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: BitmapReference, BitmapTexture, BoundingBox, BufferedBitmap, BufferedBitmapReference, Dc, FontReference, InvalidBitmapResourceException, InvalidPaletteException, ResourceReference

Constant Summary

FontDefinition

Since:

API Level 1.0.0

Name Value Since Description
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

ColorValue

Since:

API Level 1.0.0

Name Value Since Description
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
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

Constant representing the blending mode

Since:

API Level 4.0.0

Name Value Since Description
BLEND_MODE_DEFAULT 0

API Level 4.0.0

Default blend mode for Dc drawing

BLEND_MODE_NO_BLEND 1

API Level 4.0.0

No blending mode for Dc drawing

AlphaBlending

Constant representing alpha blending state for buffered bitmaps

Since:

API Level 4.0.0

Name Value Since Description
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.

ArcDirection

Since:

API Level 1.0.0

Name Value Since Description
ARC_COUNTER_CLOCKWISE 0

API Level 1.2.0

Counter clockwise draw

ARC_CLOCKWISE 1

API Level 1.2.0

Clockwise draw

Typedef Summary

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

Since:

API Level 1.0.0

typedef ColorType as Lang.Number or Graphics.ColorValue

Since:

API Level 1.0.0

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

Since:

API Level 1.0.0

Instance Method Summary collapse

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 — (Lang.Number) —

      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.Number, height as Lang.Number, 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.Number) —

    The width of the area to fit within

  • height — (Lang.Number) —

    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

Generated May 31, 2023 8:48:50 AM