Scenic v0.9.0 Scenic.Primitive behaviour 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

put_style(p, list) deprecated

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

Link to this type t() View Source
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
build(module :: atom(), data :: any(), opts :: keyword()) ::
  Scenic.Primitive.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
contains_point?(primitive :: Scenic.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
delete_style(primitive :: Scenic.Primitive.t(), type :: atom()) ::
  Scenic.Primitive.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
delete_transform(primitive :: Scenic.Primitive.t(), type :: atom()) ::
  Scenic.Primitive.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.

Link to this function get(primitive) View Source
get(primitive :: Scenic.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
get_style(primitive :: Scenic.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.

Link to this function get_styles(primitive) View Source
get_styles(primitive :: Scenic.Primitive.t()) :: map()

Get the styles map from a primitive.

Parameters:

  • primitive - The primitive

Returns the a 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
get_transform(
  primitive :: Scenic.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
get_transforms(primitive :: Scenic.Primitive.t()) :: map()

Get the transforms map from a primitive.

Parameters:

  • primitive - The primitive

Returns the a 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
merge_opts(primitive :: Scenic.Primitive.t(), opts :: keyword()) ::
  Scenic.Primitive.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
put(primitive :: Scenic.Primitive.t(), data :: any(), opts :: list()) ::
  Scenic.Primitive.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_opts(primitive, opts) View Source
put_opts(primitive :: Scenic.Primitive.t(), opts :: keyword()) ::
  Scenic.Primitive.t()
This function is deprecated. Use Primitive.merge_opts instead..
This function is deprecated. Use Primitive.merge_opts instead.
Link to this function put_style(p, type, data) View Source
put_style(primitive :: Scenic.Primitive.t(), type :: atom(), data :: any()) ::
  Scenic.Primitive.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(primitve, styles) View Source
put_styles(primitive :: Scenic.Primitive.t(), styles :: map()) ::
  Scenic.Primitive.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_list) View Source
This function is deprecated. Use Primitive.merge_opts instead.
Link to this function put_transform(p, tx_type, data) View Source
put_transform(
  primitive :: Scenic.Primitive.t(),
  type :: atom(),
  transform :: any()
) :: Scenic.Primitive.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(primitve, transforms) View Source
put_transforms(primitive :: Scenic.Primitive.t(), transforms :: map()) ::
  Scenic.Primitive.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
add_to_graph(map(), any(), opts :: keyword()) :: map()
Link to this callback contains_point?(any, {}) View Source
contains_point?(any(), {float(), float()}) :: true | false
Link to this callback default_pin(any) View Source
default_pin(any()) :: {float(), float()}
Link to this callback expand(any) View Source
expand(any()) :: any()
Link to this callback filter_styles(map) View Source
filter_styles(map()) :: map()
Link to this callback info(data) View Source
info(data :: any()) :: bitstring()
Link to this callback valid_styles() View Source
valid_styles() :: list()
Link to this callback verify(any) View Source
verify(any()) :: any()