Toddy.Canvas.Shape (Toddy v0.3.0)

Copy Markdown View Source

Convenience builders for canvas shape descriptors.

Every function produces a plain map with string keys, ready for the wire protocol. These are optional helpers -- raw maps work identically.

Basic shapes

rect(10, 20, 100, 50, fill: "#ff0000")
circle(50, 50, 25, stroke: stroke("#000", 2))
line(0, 0, 100, 100, stroke: stroke("#333", 1, cap: "round"))
text(10, 10, "Hello", fill: "#000", size: 16)

Paths

path([move_to(0, 0), line_to(100, 0), line_to(50, 80), close()],
  fill: "#0088ff",
  stroke: stroke("#000", 2)
)

Transforms

Transform commands are interleaved with shapes in a layer's shape list:

[
  push_transform(),
  translate(100, 100),
  rotate(:math.pi() / 4),
  rect(0, 0, 50, 50, fill: "#f00"),
  pop_transform()
]

Clipping

Clip regions restrict drawing to a rectangular area:

[
  push_clip(10, 10, 100, 80),
  rect(0, 0, 200, 200, fill: "#ff0000"),
  pop_clip()
]

Clip regions nest -- inner clips are intersected with outer clips.

Per-shape opacity

All shapes accept an :opacity option (0.0-1.0) that multiplies into the fill and stroke color alpha channels:

rect(0, 0, 100, 100, fill: "#ff0000", opacity: 0.5)
circle(50, 50, 25, stroke: stroke("#000", 2), opacity: 0.3)

Text alignment

The text/4 builder accepts :align_x and :align_y options:

text(100, 50, "Centered", fill: "#000", align_x: "center", align_y: "center")

Valid values for :align_x: "left", "center", "right". Valid values for :align_y: "top", "center", "bottom".

Gradients

Use linear_gradient/3 as a fill value:

rect(0, 0, 200, 100,
  fill: linear_gradient({0, 0}, {200, 0}, [{0.0, "#ff0000"}, {1.0, "#0000ff"}])
)

Summary

Functions

arc(cx, cy, r, start_angle, end_angle)

Arc path command (center, radius, start and end angles in radians).

arc_to(x1, y1, x2, y2, radius)

Tangent arc path command.

bezier_to(cp1x, cp1y, cp2x, cp2y, x, y)

Cubic bezier curve path command.

circle(x, y, r, opts \\ [])

Builds a circle shape descriptor.

close()

Close path command.

ellipse(cx, cy, rx, ry, rotation, start_angle, end_angle)

Ellipse path command.

image(source, x, y, w, h, opts \\ [])

Draws a raster image on the canvas at the given position and size.

line(x1, y1, x2, y2, opts \\ [])

Builds a line shape descriptor.

line_to(x, y)

Line-to path command.

linear_gradient(arg1, arg2, stops)

Builds a linear gradient descriptor, usable as a fill value.

move_to(x, y)

Move-to path command.

path(commands, opts \\ [])

Builds an arbitrary path shape descriptor.

pop_clip()

Pops the most recent clipping rectangle.

pop_transform()

Pop (restore) the previously saved transform state from the stack.

push_clip(x, y, w, h)

Pushes a clipping rectangle. All shapes until the matching pop_clip are clipped to this region.

push_transform()

Push (save) the current transform state onto the stack.

quadratic_to(cpx, cpy, x, y)

Quadratic bezier curve path command.

rect(x, y, w, h, opts \\ [])

Builds a rectangle shape descriptor.

rotate(angle)

Rotate the coordinate system (angle in radians).

rounded_rect(x, y, w, h, radius)

Rounded rectangle path command.

scale(x, y)

Scale the coordinate system.

stroke(color, width, opts \\ [])

Builds a stroke descriptor.

svg(source, x, y, w, h)

Draws an SVG on the canvas at the given position and size.

text(x, y, content, opts \\ [])

Builds a text shape descriptor.

translate(x, y)

Translate the coordinate origin.

Functions

arc(cx, cy, r, start_angle, end_angle)

@spec arc(
  cx :: number(),
  cy :: number(),
  r :: number(),
  start_angle :: number(),
  end_angle :: number()
) :: list()

Arc path command (center, radius, start and end angles in radians).

arc_to(x1, y1, x2, y2, radius)

@spec arc_to(
  x1 :: number(),
  y1 :: number(),
  x2 :: number(),
  y2 :: number(),
  radius :: number()
) :: list()

Tangent arc path command.

bezier_to(cp1x, cp1y, cp2x, cp2y, x, y)

@spec bezier_to(
  cp1x :: number(),
  cp1y :: number(),
  cp2x :: number(),
  cp2y :: number(),
  x :: number(),
  y :: number()
) :: list()

Cubic bezier curve path command.

circle(x, y, r, opts \\ [])

@spec circle(x :: number(), y :: number(), r :: number(), opts :: keyword()) :: map()

Builds a circle shape descriptor.

close()

@spec close() :: String.t()

Close path command.

ellipse(cx, cy, rx, ry, rotation, start_angle, end_angle)

@spec ellipse(
  cx :: number(),
  cy :: number(),
  rx :: number(),
  ry :: number(),
  rotation :: number(),
  start_angle :: number(),
  end_angle :: number()
) :: list()

Ellipse path command.

image(source, x, y, w, h, opts \\ [])

@spec image(
  source :: String.t(),
  x :: number(),
  y :: number(),
  w :: number(),
  h :: number(),
  opts :: keyword()
) :: map()

Draws a raster image on the canvas at the given position and size.

Options

  • :rotation -- rotation angle in radians.
  • :opacity -- opacity multiplier (0.0-1.0).

line(x1, y1, x2, y2, opts \\ [])

@spec line(
  x1 :: number(),
  y1 :: number(),
  x2 :: number(),
  y2 :: number(),
  opts :: keyword()
) :: map()

Builds a line shape descriptor.

line_to(x, y)

@spec line_to(x :: number(), y :: number()) :: list()

Line-to path command.

linear_gradient(arg1, arg2, stops)

@spec linear_gradient(
  from :: {number(), number()},
  to :: {number(), number()},
  stops :: [{number(), String.t()}]
) :: map()

Builds a linear gradient descriptor, usable as a fill value.

Stops are {offset, color} tuples where offset is 0.0..1.0.

move_to(x, y)

@spec move_to(x :: number(), y :: number()) :: list()

Move-to path command.

path(commands, opts \\ [])

@spec path(commands :: [map() | list() | String.t()], opts :: keyword()) :: map()

Builds an arbitrary path shape descriptor.

Commands are produced by move_to/2, line_to/2, bezier_to/6, quadratic_to/4, arc/5, arc_to/5, ellipse/7, rounded_rect/5, and close/0.

pop_clip()

@spec pop_clip() :: map()

Pops the most recent clipping rectangle.

pop_transform()

@spec pop_transform() :: map()

Pop (restore) the previously saved transform state from the stack.

push_clip(x, y, w, h)

@spec push_clip(x :: number(), y :: number(), w :: number(), h :: number()) :: map()

Pushes a clipping rectangle. All shapes until the matching pop_clip are clipped to this region.

push_transform()

@spec push_transform() :: map()

Push (save) the current transform state onto the stack.

quadratic_to(cpx, cpy, x, y)

@spec quadratic_to(cpx :: number(), cpy :: number(), x :: number(), y :: number()) ::
  list()

Quadratic bezier curve path command.

rect(x, y, w, h, opts \\ [])

@spec rect(
  x :: number(),
  y :: number(),
  w :: number(),
  h :: number(),
  opts :: keyword()
) :: map()

Builds a rectangle shape descriptor.

rotate(angle)

@spec rotate(angle :: number()) :: map()

Rotate the coordinate system (angle in radians).

rounded_rect(x, y, w, h, radius)

@spec rounded_rect(
  x :: number(),
  y :: number(),
  w :: number(),
  h :: number(),
  radius :: number()
) :: list()

Rounded rectangle path command.

scale(x, y)

@spec scale(x :: number(), y :: number()) :: map()

Scale the coordinate system.

stroke(color, width, opts \\ [])

@spec stroke(color :: String.t(), width :: number(), opts :: keyword()) :: map()

Builds a stroke descriptor.

Options

  • :cap -- line cap: "butt", "round", or "square". Default: "butt".
  • :join -- line join: "miter", "round", or "bevel". Default: "miter".
  • :dash -- dash pattern as {segments, offset} where segments is a list of numbers and offset is the starting offset.

svg(source, x, y, w, h)

@spec svg(
  source :: String.t(),
  x :: number(),
  y :: number(),
  w :: number(),
  h :: number()
) :: map()

Draws an SVG on the canvas at the given position and size.

text(x, y, content, opts \\ [])

@spec text(x :: number(), y :: number(), content :: String.t(), opts :: keyword()) ::
  map()

Builds a text shape descriptor.

translate(x, y)

@spec translate(x :: number(), y :: number()) :: map()

Translate the coordinate origin.