Scenic

v0.10.2

Scenic v0.10.2 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

Types

t()

Functions

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

Generic builder to create a new primitive

contains_point?(primitive, point)

Determines if a point is contained within a primitive

delete_style(primitive, type)

Deletes a specified style from a primitive

delete_transform(primitive, tx_type)

Deletes a specified transform from a primitive

do_put(p, data)
get(primitive)

Get the value of the primitive-specific data

get_style(primitive, type, default \\ nil)

Get the value of a specific style set on the primitive

get_styles(primitive)

Get the styles map from a primitive

get_transform(primitive, tx_type, default \\ nil)

Get the value of a specific transform set on the primitive

get_transforms(primitive)

Get the transforms map from a primitive

merge_opts(primitive, opts)

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

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

Put primitive-specific data onto the primitive

put_style(p, type, data)

Update the value of a specific style set on the primitive

put_styles(primitve, styles)

Update the styles map in a primitive

put_transform(p, tx_type, data)

Update the value of a specific transform set on the primitive

put_transforms(primitve, transforms)

Update the transforms map in a primitive

Callbacks

add_to_graph(map, any, opts)
contains_point?(any, {})
default_pin(any)
expand(any)
filter_styles(map)
info(data)
valid_styles()
verify(any)

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

do_put(p, data) View Source

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 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 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_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_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()