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:

• Audio Content Provider

• Background (supported since API Level 5.1.0)

• Data Field

• Glance

• Watch App

• 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

• BitmapType as WatchUi.BitmapResource or Graphics.BufferedBitmap or Graphics.BitmapReference or Graphics.BufferedBitmapReference
• ColorType as Lang.Number or Graphics.ColorValue
• FontType as WatchUi.FontResource or Graphics.FontDefinition or Graphics.FontReference or Graphics.VectorFont
• Point2D as [ Lang.Numeric, Lang.Numeric ]

  Type alias for an Array of length 2.

• VectorFontOptions as { :face as Lang.String or Lang.Array<Lang.String>, :size as Lang.Numeric, :font as Graphics.FontDefinition or Graphics.VectorFont, :scale as Lang.Float }

Instance Method Summary

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

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

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

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

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

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

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

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

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

• getVectorFont(options as Graphics.VectorFontOptions) as Graphics.VectorFont or Null

  Get a font for this device.

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

VectorFontOptions as { :face as Lang.String or Lang.Array<Lang.String>, :size as Lang.Numeric, :font as Graphics.FontDefinition or Graphics.VectorFont, :scale as Lang.Float }

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:

• Toybox::Graphics::BufferedBitmapReference A reference to BufferedBitmap object

Since:

API Level 4.0.0

Throws:

• (Graphics.InvalidPaletteException) —

  Thrown if the palette size exceeds the number of system colors.

• (Graphics.InvalidPaletteException) —

  Thrown if the palette size exceeds 256 colors.

• (Graphics.InvalidBitmapResourceException) —

  Thrown if the BitmapResource provided has an alpha channel.

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:

• font — (Graphics.FontType) —

  The font to use

Returns:

• Lang.Number —

  The ascent of the font

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:

• font — (Graphics.FontType) —

  The font to use

Returns:

• Lang.Number —

  The descent of the font

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:

• font — (Graphics.FontType) —

  The font to use

Returns:

• Lang.Number —

  The height of the font

Since:

API Level 1.2.0

getVectorFont(options as Graphics.VectorFontOptions) as Graphics.VectorFont or Null

Get a font for this device

Note:

The :font and :scale options are only supported in CIQ 5.1.0 and later.

Parameters:

• options — (Lang.Dictionary, Graphics.FontDefinition) —

  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.

  • :font — (Graphics.FontDefinition, Graphics.VectorFont) —

    The font to apply a scale to.

  • :scale — (Lang.Float) —

    The amount to scale the font.

Supported Devices:

• Approach® S70 42mm
• Approach® S70 47mm
• D2™ Mach 1
• Descent™ Mk3 43mm / Mk3i 43mm
• Descent™ Mk3i 51mm
• Enduro™ 3
• epix™ (Gen 2) / quatix® 7 Sapphire
• epix™ Pro (Gen 2) 42mm
• epix™ Pro (Gen 2) 47mm / quatix® 7 Pro
• epix™ Pro (Gen 2) 51mm / D2™ Mach 1 Pro / tactix® 7 – AMOLED Edition
• fēnix® 7 / quatix® 7
• fēnix® 7 Pro - Solar Edition (no Wi-Fi)
• fēnix® 7 Pro
• fēnix® 7S Pro
• fēnix® 7S
• fēnix® 7X / tactix® 7 / quatix® 7X Solar / Enduro™ 2
• fēnix® 7X Pro - Solar Edition (no Wi-Fi)
• fēnix® 7X Pro
• fēnix® 8 43mm
• fēnix® 8 47mm / 51mm / tactix® 8 47mm / 51mm
• fēnix® 8 Solar 47mm
• fēnix® 8 Solar 51mm / tactix® 8 Solar 51mm
• fēnix® E
• Forerunner® 165 Music
• Forerunner® 165
• Forerunner® 265
• Forerunner® 265s
• Forerunner® 570 42mm
• Forerunner® 570 47mm
• Forerunner® 955 / Solar
• Forerunner® 965
• Forerunner® 970
• MARQ® (Gen 2) Athlete / Adventurer / Captain / Golfer / Carbon Edition / Commander - Carbon Edition
• MARQ® (Gen 2) Aviator
• Venu® 3
• Venu® 3S
• vívoactive® 6

Returns:

• Graphics.VectorFont —

  if a font can be created for the given parameters, otherwise null

See Also:

• Reference Guides - Devices Reference

Since:

API Level 4.2.1

Throws:

• (Lang.UnexpectedTypeException) —

  Thrown if options is not a supported type.

• (Lang.UnexpectedTypeException) —

  Thrown if the provided :size or :scale are not a supported type.

• (Lang.UnexpectedTypeException) —

  Thrown if the provided :face is not a supported type.

• (Lang.InvalidValueException) —

  Thrown if the provided :face value is out of range.

• (Lang.InvalidValueException) —

  Thrown if the provided :size or :scale value is not positive.