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.

Helper	Primitive Module	Description
`arc/3`	`Scenic.Primitive.Arc`	Draw an arc around a circle
`circle/3`	`Scenic.Primitive.Circle`	Draw a full circle
`ellipse/3`	`Scenic.Primitive.Ellipse`	Draw an ellipse
`group/3`	`Scenic.Primitive.Group`	Create a group
`line/3`	`Scenic.Primitive.Line`	Draw a line
`path/3`	`Scenic.Primitive.Path`	Draw a complicated path
`quad/3`	`Scenic.Primitive.Quad`	Draw a quad
`rect/3`	`Scenic.Primitive.Rectangle`	Draw a rectangle
`rrect/3`	`Scenic.Primitive.RoundedRectangle`	Draw a rounded rectangle
`script/3`	`Scenic.Primitive.Script`	Run a referenced draw script
`sector/3`	`Scenic.Primitive.Sector`	A boolean toggle control.
`sprites/3`	`Scenic.Primitive.Sprites`	Draw a sector
`text/3`	`Scenic.Primitive.Text`	Draw a string of text
`triangle/3`	`Scenic.Primitive.Triangle`	Draw a triangle

Link to this section Summary

Types

t()

Callbacks

compile(primitive, styles)

valid_styles()

validate(data)

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.

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(primitive, 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(primitive, transforms)

Update the transforms map in a primitive.

Link to this section Types

t()

@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

compile(primitive, styles)

@callback compile(primitive :: t(), styles :: Scenic.Primitive.Style.t()) ::
  script :: Scenic.Script.t()

valid_styles()

@callback valid_styles() :: list()

validate(data)

@callback validate(data :: any()) :: {:ok, data :: any()} | {:error, String.t()}

Link to this section Functions

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

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

contains_point?(primitive, point)

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

delete_style(primitive, type)

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

delete_transform(primitive, tx_type)

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

get(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.

get_style(primitive, type, default \\ nil)

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

get_styles(primitive)

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

get_transform(primitive, tx_type, default \\ nil)

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

get_transforms(primitive)

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

merge_opts(primitive, opts)

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

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

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

put_style(p, type, data)

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

put_styles(primitive, styles)

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

put_transform(p, tx_type, data)

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

put_transforms(primitive, transforms)

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

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

what-is-a-primitive What is a primitive

how-to-use-primitives How to use primitives

standard-primitives Standard Primitives

Link to this section Summary

Types

Callbacks

Functions

Link to this section Types

t()

Link to this section Callbacks

compile(primitive, styles)

valid_styles()

validate(data)

Link to this section Functions

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

contains_point?(primitive, point)

delete_style(primitive, type)

delete_transform(primitive, tx_type)

get(primitive)

get_style(primitive, type, default \\ nil)

get_styles(primitive)

get_transform(primitive, tx_type, default \\ nil)

get_transforms(primitive)

merge_opts(primitive, opts)

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

put_style(p, type, data)

put_styles(primitive, styles)

put_transform(p, tx_type, data)

put_transforms(primitive, transforms)

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

what-is-a-primitive
What is a primitive

how-to-use-primitives
How to use primitives

standard-primitives
Standard Primitives