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

Please see Primitives Overview for a high-level description.

what-is-a-primitive

What is a primitive

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

In general, each Primitive 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

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.

import Scenic.Primitives

@graph Scenic.Graph.build()
       |> rect({100, 50}, stroke: {1, :yellow})
       |> rectangle({100, 50}, stroke: {1, :yellow})

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

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.

See the documentation for each primitive's module for details on it's data type.

HelperPrimitive ModuleDescription
arc/3Scenic.Primitive.ArcDraw an arc around a circle
circle/3Scenic.Primitive.CircleDraw a full circle
ellipse/3Scenic.Primitive.EllipseDraw an ellipse
group/3Scenic.Primitive.GroupCreate a group
line/3Scenic.Primitive.LineDraw a line
path/3Scenic.Primitive.PathDraw a complicated path
quad/3Scenic.Primitive.QuadDraw a quad
rect/3Scenic.Primitive.RectangleDraw a rectangle
rrect/3Scenic.Primitive.RoundedRectangleDraw a rounded rectangle
script/3Scenic.Primitive.ScriptRun a referenced draw script
sector/3Scenic.Primitive.SectorA boolean toggle control.
sprites/3Scenic.Primitive.SpritesDraw a sector
text/3Scenic.Primitive.TextDraw a string of text
triangle/3Scenic.Primitive.TriangleDraw 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

@type t() :: %Scenic.Primitive{
  data: any(),
  default_pin: Scenic.Math.vector_2(),
  id: any(),
  module: atom(),
  opts: list(),
  parent_uid: integer(),
  styles: map(),
  transforms: map()
}

Link to this section Callbacks

Link to this callback

compile(primitive, styles)

View Source
@callback compile(primitive :: t(), styles :: Scenic.Primitive.Style.t()) ::
  script :: Scenic.Script.t()
@callback valid_styles() :: list()
@callback validate(data :: any()) :: {:ok, data :: any()} | {:error, String.t()}

Link to this section Functions

Link to this function

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

View Source
@spec 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
@spec 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
@spec 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
@spec 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.

@spec 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
@spec 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.

@spec 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
@spec 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
@spec 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
@spec 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
@spec 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
@spec 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
@spec 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
@spec 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
@spec 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.