Module: Toybox.Graphics

Overview

The Graphics module provides a set of tools that allow developers to use basic drawing functionality.

This provides the ability to draw shapes, lines, fill shapes, and use dynamic layouts for graphic elements based on specific device contexts. The Device Context (Dc) is useful for developers who are interested in creating content for multiple device platforms with differing screen shapes, sizes, and color palettes.

Since:

API Level 1.0.0

App Types:

  • Watch App

  • Audio Content Provider

  • Data Field

  • Watch Face

  • Widget

Classes Under Namespace

Classes: AffineTransform, BitmapReference, BitmapTexture, BoundingBox, BufferedBitmap, BufferedBitmapReference, Dc, FontReference, InvalidBitmapResourceException, InvalidPaletteException, OutOfGraphicsMemoryException, ResourceReference, VectorFont

Constant Summary

FontDefinition

Since:

API Level 1.0.0

Name Value Since Description See Also
FONT_XTINY 0

API Level 1.0.0

Extra tiny Connect IQ font

FONT_TINY 1

API Level 1.0.0

Tiny Connect IQ font

FONT_SMALL 2

API Level 1.0.0

Small Connect IQ font

FONT_MEDIUM 3

API Level 1.0.0

Medium Connect IQ font

FONT_LARGE 4

API Level 1.0.0

Large Connect IQ font

FONT_NUMBER_MILD 5

API Level 1.0.0

Normal size number only Connect IQ font

FONT_NUMBER_MEDIUM 6

API Level 1.0.0

Medium size number only Connect IQ font

FONT_NUMBER_HOT 7

API Level 1.0.0

Large size number only Connect IQ font

FONT_NUMBER_THAI_HOT 8

API Level 1.0.0

Huge size number only Connect IQ font

FONT_SYSTEM_XTINY 9

API Level 1.3.0

Extra tiny system font

FONT_SYSTEM_TINY 10

API Level 1.3.0

Tiny system font

FONT_SYSTEM_SMALL 11

API Level 1.3.0

Small system font

FONT_SYSTEM_MEDIUM 12

API Level 1.3.0

Medium system font

FONT_SYSTEM_LARGE 13

API Level 1.3.0

Large system font

FONT_SYSTEM_NUMBER_MILD 14

API Level 1.3.0

Normal size number only system font

FONT_SYSTEM_NUMBER_MEDIUM 15

API Level 1.3.0

Medium size number only system font

FONT_SYSTEM_NUMBER_HOT 16

API Level 1.3.0

Large size number only system font

FONT_SYSTEM_NUMBER_THAI_HOT 17

API Level 1.3.0

Huge size number only system font

FONT_GLANCE 18

API Level 3.1.8

Glance text font

FONT_GLANCE_NUMBER 19

API Level 3.1.8

Glance number only font

FONT_AUX1 20

API Level 4.2.2

Auxiliary Font 1

FONT_AUX2 21

API Level 4.2.2

Auxiliary Font 2

FONT_AUX3 22

API Level 4.2.3

Auxiliary Font 3

FONT_AUX4 23

API Level 4.2.3

Auxiliary Font 4

FONT_AUX5 24

API Level 4.2.3

Auxiliary Font 5

FONT_AUX6 25

API Level 4.2.3

Auxiliary Font 6

FONT_AUX7 26

API Level 4.2.3

Auxiliary Font 7

FONT_AUX8 27

API Level 4.2.3

Auxiliary Font 8

FONT_AUX9 28

API Level 4.2.3

Auxiliary Font 9

ColorValue

Since:

API Level 1.0.0

Name Value Since Description See Also
COLOR_WHITE 0xFFFFFF

API Level 1.0.0

White

COLOR_LT_GRAY 0xAAAAAA

API Level 1.0.0

Light Gray

COLOR_DK_GRAY 0x555555

API Level 1.0.0

Dark Gray

COLOR_BLACK 0x000000

API Level 1.0.0

Black

COLOR_RED 0xFF0000

API Level 1.0.0

Red

COLOR_DK_RED 0xAA0000

API Level 1.0.0

Dark Red

COLOR_ORANGE 0xFF5500

API Level 1.0.0

Orange

COLOR_YELLOW 0xFFAA00

API Level 1.0.0

Yellow

COLOR_GREEN 0x00FF00

API Level 1.0.0

Green

COLOR_DK_GREEN 0x00AA00

API Level 1.0.0

Dark Green

COLOR_BLUE 0x00AAFF

API Level 1.0.0

Blue

COLOR_DK_BLUE 0x0000FF

API Level 1.0.0

Dark Blue

COLOR_PURPLE 0xAA00FF

API Level 1.0.0

Purple. Not valid on fenix 3 or D2 Bravo. Use 0x5500AA instead.

COLOR_PINK 0xFF00FF

API Level 1.0.0

Pink

COLOR_TRANSPARENT -1

API Level 1.0.0

Transparent

TextJustification

Since:

API Level 1.0.0

Name Value Since Description See Also
TEXT_JUSTIFY_RIGHT 0

API Level 1.0.0

Right justify the text at the x/y coordinates

TEXT_JUSTIFY_CENTER 1

API Level 1.0.0

Center justify the text at the x/y coordinates

TEXT_JUSTIFY_LEFT 2

API Level 1.0.0

Left justify the text at the x/y coordinates

TEXT_JUSTIFY_VCENTER 4

API Level 1.0.0

Center the text vertically

BlendMode

Blend mode

Specifies how colors of a source pixel will be blended with the colors of a destination pixel.

In the below descriptions 

   S is source pixel
   D is destination pixel
   a is the alpha component

Since:

API Level 4.0.0

Name Value Since Description See Also
BLEND_MODE_DEFAULT 0

API Level 4.0.0

Alias for BLEND_MODE_SOURCE_OVER

BLEND_MODE_NO_BLEND 1

API Level 4.0.0

Alias for BLEND_MODE_SOURCE

BLEND_MODE_SOURCE_OVER 0

API Level 4.2.1

S + (1 - S.a) * D

BLEND_MODE_SOURCE 1

API Level 4.2.1

S, i.e. no blending.

BLEND_MODE_MULTIPLY 2

API Level 4.2.1

(S * (1 - D.a)) + (D * (1 - S.a)) + (S * D)

BLEND_MODE_ADDITIVE 3

API Level 4.2.1

S + D

AlphaBlending

Constant representing alpha blending state for buffered bitmaps

Since:

API Level 4.0.0

Name Value Since Description See Also
ALPHA_BLENDING_FULL 0

API Level 4.0.0

Default surface for buffered bitmap with maximum alpha blending support

ALPHA_BLENDING_PARTIAL 1

API Level 4.0.0

Surface for buffered bitmap with at least a 1-bit alpha channel. The actual number of bits may vary by device.

RadialTextDirection

Orientation for radial text

Since:

API Level 4.2.1

Name Value Since Description See Also
RADIAL_TEXT_DIRECTION_CLOCKWISE 0

API Level 4.2.1

Top of text is further from center. Typically used for upright text along the top of a circle.

RADIAL_TEXT_DIRECTION_COUNTER_CLOCKWISE 1

API Level 4.2.1

Bottom of text is further from center. Typically used for upright text along the bottom of a circle.

FilterMode

Filter mode

Specifies how many pixels to sample

Since:

API Level 4.2.1

Name Value Since Description See Also
FILTER_MODE_POINT 0

API Level 4.2.1

Point filter

FILTER_MODE_BILINEAR 1

API Level 4.2.1

Biliniear filter

ArcDirection

Since:

API Level 1.0.0

Name Value Since Description See Also
ARC_COUNTER_CLOCKWISE 0

API Level 1.2.0

Counter clockwise draw

ARC_CLOCKWISE 1

API Level 1.2.0

Clockwise draw

Typedef Summary collapse

Instance Method Summary collapse

Typedef Details

BitmapType as WatchUi.BitmapResource or Graphics.BufferedBitmap or Graphics.BitmapReference or Graphics.BufferedBitmapReference

Since:

API Level 1.0.0

ColorType as Lang.Number or Graphics.ColorValue

Since:

API Level 1.0.0

FontType as WatchUi.FontResource or Graphics.FontDefinition or Graphics.FontReference or Graphics.VectorFont

Since:

API Level 1.0.0

Point2D as [ Lang.Numeric, Lang.Numeric ]

Type alias for an Array of length 2

Since:

API Level 1.0.0

Instance Method Details

createBufferedBitmap(options as { :width as Lang.Number, :height as Lang.Number, :palette as Lang.Array<Graphics.ColorType>, :colorDepth as Lang.Number, :bitmapResource as WatchUi.BitmapResource or Graphics.BitmapReference, :alphaBlending as Graphics.AlphaBlending }) as Graphics.BufferedBitmapReference

Create a buffered bitmap object. This function will return a Toybox::Graphics::BufferedBitmapReference object which can be used to reference the Toybox::Graphics::BufferedBitmap object.

Note:

The result of a draw/fill operation to a BufferedBitmap created with ALPHA_BLENDING_PARTIAL may produce inconsistent results between devices and the ConnectIQ simulator if the drawn pixels are not fully opaque or fully transparent.

Parameters:

  • options — (Lang.Dictionary) —

    Dictionary of options. Must contain width and height, with optional palette, or a BitmapResource. This resource is not allowed to have an alpha channel.

    • :width — (Lang.Number) —

      The width of the surface in pixels. Must be a positive integer value.

    • :height — (Lang.Number) —

      The height of the surface in pixels. Must be a positive integer value.

    • :palette — (Lang.Array) —

      The colors used in this surface. Using less will reduce the bitmap size. The bitmap will use the system default if not provided. The maximum palette size allowed is 256 colors. If a palette is provided, the number of colors must also be <= to the number of system colors.

    • :colorDepth — (Lang.Number) —

      Color depth in terms of bits/pixel, when missing, default to system value.

    • :bitmapResource — (WatchUi.BitmapResource) —

      A BitmapResource or BitmapReference to initialize

    • :alphaBlending — (Graphics.AlphaBlending) —

      A AlphaBlending enum to specify the level of alpha blending support for this buffered bitmap object.

Returns:

Since:

API Level 4.0.0

Throws:

createColor(alpha as Lang.Number, red as Lang.Number, green as Lang.Number, blue as Lang.Number) as Lang.Number

Create a color with the individual channel values passed in

Parameters:

  • alpha — (Lang.Number) —

    Number value ranging from 0-255 representing alpha channel

  • red — (Lang.Number) —

    Number value ranging from 0-255 representing red channel

  • green — (Lang.Number) —

    Number value ranging from 0-255 representing green channel

  • blue — (Lang.Number) —

    Number value ranging from 0-255 representing blue channel

Returns:

  • color [Toybox::Lang::Number] 32-bit value representing the created color that can be used with Toybox.Graphics functions.

Since:

API Level 4.0.0

fitTextToArea(text as Lang.String, font as Graphics.FontType, width as Lang.Numeric, height as Lang.Numeric, truncate as Lang.Boolean) as Lang.String or Null

Get a text string to fit in a specified area

Note:

FontReference is only supported in CIQ 4.0.0 and later

Parameters:

  • text — (Lang.String) —

    The text to fit into the given area, which may include newlines

  • font — (Graphics.FontType) —

    The font to use when determining line break placement

  • width — (Lang.Numeric) —

    The width of the area to fit within

  • height — (Lang.Numeric) —

    The height of the area to fit within

  • truncate — (Lang.Boolean) —

    If true, the resulting string may be truncated to fit within the provided area using the provided font

Returns:

  • Returns a String suitable for display in the given area. The String will be truncated if the 'truncate' parameter is true and the String cannot fit into the specified area. Otherwise, null will be returned.

Since:

API Level 3.1.0

getFontAscent(font as Graphics.FontType) as Lang.Number

Get the recommended distance above the baseline for single spaced text.

The base line is the line on which the text sits.

Note:

FontReference is only supported in CIQ 4.0.0 and later

Parameters:

Returns:

Since:

API Level 1.2.0

getFontDescent(font as Graphics.FontType) as Lang.Number

Get the recommended distance below the baseline for single spaced text.

The base line is the line on which the text sits.

Note:

FontReference is only supported in CIQ 4.0.0 and later

Parameters:

Returns:

Since:

API Level 1.2.0

getFontHeight(font as Graphics.FontType) as Lang.Number

Get the height (ascent plus descent) of the given font.

Note:

FontReference is only supported in CIQ 4.0.0 and later

Parameters:

Returns:

Since:

API Level 1.2.0

getVectorFont(options as { :face as Lang.String or Lang.Array<Lang.String>, :size as Lang.Numeric }) as Graphics.VectorFont or Null

Get a font for this device

Parameters:

  • options — (Lang.Dictionary) —

    A description of the font to retrieve.

    • :face — (Lang.String, Lang.Array) —

      A String representing the face name requested, or an Array of face names that are acceptable.

    • :size — (Lang.Numeric) —

      The height of the font requested in pixels as a positive number.

Supported Devices:

Returns:

See Also:

Since:

API Level 4.2.1

Throws:

Generated Dec 11, 2024, 8:58:43 AM