Scenic.Primitive behaviour (Scenic v0.10.3) View Source

Please see Primitives Overview for a high-level description.

What is a primitive

A primitive is the simplest thing Scenic knows how to draw on the screen. There is is only a small, fixed set of them, but they can be combined in a graph to draw very complicated images.

In general, each Primitive type has a piece of data that it expects to operate on. For example, Primitive.Text requires a bitstring. Primitive.Circle requires a radius. Please see the documentation for each primitive for details.

How to use primitives

By far, the easiest way to use primitives is to import the helper functions in Scenic.Primitives. These helpers can both add primitives to a scene you are building and modify later as you react to events.

Once you get a primitive out of a graph via functions such as Graph.modify, or Graph.get, You can use the generic helpers in this module to access or manipulate them.

Standard primitives

The set of primitives supported in Scenic is fixed in any given version. They have been chosen to provide the maximum flexibility when combined together, while still requiring the minimal amount of code and maintenance.

If required, new primitives can be added in the future, but they will not work with older versions of the drivers.

  • Arc draws an arc. This would be a line cut out of a part of the edge of a circle. If you want a shape that looks like a piece of pie, then you should use the Sector.
  • Circle draws a circle.
  • Ellipse draws an ellipse.
  • Group doesn't draw anything. Instead, it creates a node in the graph that you can insert more primitives into. Any styles or transforms you apply to the Group are inherited by all the primitives below it.
  • Line draws a line.
  • Path is sort of an escape valve for complex shapes not covered by the other primitives. You supply a list of instructions, such as :move_to, :line_to, :bezier_to, etc. to generate a complex shape.
  • Quad draws polygon with four sides.
  • Rectangle draws a rectangle.
  • RoundedRectangle draws a rectangle with the corners rounded by a given radius.
  • SceneRef doesn't draw anything by itself. Instead it points to another scene/graph and tells the driver to draw that here.
  • Sector draws a shape that looks like a piece of pie. If you want to stroke just the curved edge, then combine it with an Arc.
  • Text draws a string of text.
  • Triangle draws a triangle.

Link to this section Summary

Functions

Generic builder to create a new primitive.

Determines if a point is contained within a primitive.

Deletes a specified style from a primitive.

Deletes a specified transform from a primitive.

Get the value of the primitive-specific data.

Get the value of a specific style set on the primitive.

Get the styles map from a primitive.

Get the value of a specific transform set on the primitive.

Get the transforms map from a primitive.

Merge an options-list of styles and transforms onto a primitive.

Put primitive-specific data onto the primitive.

Update the value of a specific style set on the primitive.

Update the styles map in a primitive.

Update the value of a specific transform set on the primitive.

Update the transforms map in a primitive.

Link to this section Types

Specs

t() :: %Scenic.Primitive{
  data: any(),
  id: any(),
  module: atom(),
  parent_uid: integer(),
  styles: map(),
  transforms: map()
}

Link to this section Functions

Link to this function

build(module, data, opts \\ [])

View Source

Specs

build(module :: atom(), data :: any(), opts :: keyword()) :: t()

Generic builder to create a new primitive.

This function is used internally. You should almost always use the helpers in Scenic.Primitives instead.

Parameters:

  • module - The module of the primitive you are building
  • data - the primitive-specific data being set into the primitive
  • opts - a list of style and transform options to apply to the primitive

Returns the built primitive.

Link to this function

contains_point?(primitive, point)

View Source

Specs

contains_point?(primitive :: t(), point :: Scenic.Math.point()) :: map()

Determines if a point is contained within a primitive.

The supplied point must already be projected into the local coordinate space of the primitive. In other words, this test does NOT take into account any transforms that have been applied to the primitive.

The input mechanism takes care of this for you by projecting incoming points by the inverse-matrix of a primitive before calling this function...

Note that some primitives, such as Group, do not inherently have a notion of containing a point. In those cases, this function will always return false.

Parameters:

  • primitive - The primitive
  • point - The point to test

Returns true or false.

Link to this function

delete_style(primitive, type)

View Source

Specs

delete_style(primitive :: t(), type :: atom()) :: t()

Deletes a specified style from a primitive.

Does nothing if the style is not set.

Parameters:

  • primitive - The primitive
  • type - atom representing the style to delete.

Returns the updated primitive.

Link to this function

delete_transform(primitive, tx_type)

View Source

Specs

delete_transform(primitive :: t(), type :: atom()) :: t()

Deletes a specified transform from a primitive.

Does nothing if the transform is not set.

Parameters:

  • primitive - The primitive
  • type - atom representing the transform to delete.

Returns the updated primitive.

Specs

get(primitive :: t()) :: any()

Get the value of the primitive-specific data.

Parameters:

  • primitive - The primitive

Returns the value of the primitive-specific data.

Link to this function

get_style(primitive, type, default \\ nil)

View Source

Specs

get_style(primitive :: t(), type :: atom(), default :: any()) :: any()

Get the value of a specific style set on the primitive.

If the style is not set, it returns default

Parameters:

  • primitive - The primitive
  • type - atom representing the style to get.
  • default - default value to return if the style is not set.

Returns the value of the style.

Specs

get_styles(primitive :: t()) :: map()

Get the styles map from a primitive.

Parameters:

  • primitive - The primitive

Returns the map of styles set directly onto this primitive. This does not include any inherited styles.

Link to this function

get_transform(primitive, tx_type, default \\ nil)

View Source

Specs

get_transform(primitive :: t(), type :: atom(), default :: any()) :: any()

Get the value of a specific transform set on the primitive.

If the transform is not set, it returns default

Parameters:

  • primitive - The primitive
  • type - atom representing the transform to get.
  • default - default value to return if the transform is not set.

Returns the value of the transform.

Link to this function

get_transforms(primitive)

View Source

Specs

get_transforms(primitive :: t()) :: map()

Get the transforms map from a primitive.

Parameters:

  • primitive - The primitive

Returns the map of transforms set directly onto this primitive. This does not include any inherited transforms.

Link to this function

merge_opts(primitive, opts)

View Source

Specs

merge_opts(primitive :: t(), opts :: keyword()) :: t()

Merge an options-list of styles and transforms onto a primitive.

This function might go through a name-change in the future. It is really more of a merge. The supplied list of styles and transforms

Parameters:

  • primitive - The primitive

Returns the value of the primitive-specific data.

Link to this function

put(primitive, data, opts \\ [])

View Source

Specs

put(primitive :: t(), data :: any(), opts :: list()) :: t()

Put primitive-specific data onto the primitive.

Like many of the functions in the Scenic.Primitive module, you are usually better off using the helper functions in Scenic.Primitives instead.

Parameters:

  • primitive - The primitive
  • data - The data to set
  • opts - A list of style/transform options to merge

Returns the updated primitive.

Link to this function

put_style(p, type, data)

View Source

Specs

put_style(primitive :: t(), type :: atom(), data :: any()) :: t()

Update the value of a specific style set on the primitive.

Parameters:

  • primitive - The primitive
  • type - atom representing the style to get.
  • data - the value to set on the style.

Returns the updated primitive.

Link to this function

put_styles(primitive, styles)

View Source

Specs

put_styles(primitive :: t(), styles :: map()) :: t()

Update the styles map in a primitive.

Parameters:

  • primitive - The primitive
  • styles - The new styles map

Returns the primitive with the updated styles.

Link to this function

put_transform(p, tx_type, data)

View Source

Specs

put_transform(primitive :: t(), type :: atom(), transform :: any()) :: t()

Update the value of a specific transform set on the primitive.

Parameters:

  • primitive - The primitive
  • type - atom representing the transform to get.
  • data - the value to set on the transform.

Returns the updated primitive.

Link to this function

put_transforms(primitive, transforms)

View Source

Specs

put_transforms(primitive :: t(), transforms :: map()) :: t()

Update the transforms map in a primitive.

Parameters:

  • primitive - The primitive
  • transforms - The new transforms map

Returns the primitive with the updated transforms.

Link to this section Callbacks

Link to this callback

add_to_graph(map, any, opts)

View Source

Specs

add_to_graph(map(), any(), opts :: keyword()) :: map()
Link to this callback

contains_point?(any, {})

View Source

Specs

contains_point?(any(), {float(), float()}) :: true | false

Specs

default_pin(any()) :: {float(), float()}

Specs

expand(any()) :: any()

Specs

filter_styles(map()) :: map()

Specs

info(data :: any()) :: bitstring()

Specs

valid_styles() :: list()

Specs

verify(any()) :: any()