Class: Toybox.Graphics.Dc

Inherits:

Toybox.Lang.Object

• Toybox.Lang.Object
• Toybox.Graphics.Dc

Overview

This class represents a device context.

It provides methods to perform drawing operations on the device.

Note:

You should never directly instantiate a Dc object, or attempt to render to the screen outside of an onUpdate call.

Example:

Draws a blue rectangle using direct pixel parameters.

using Toybox.Graphics;
function onUpdate(dc) {
    dc.setColor(Graphics.COLOR_BLUE, Graphics.COLOR_BLACK);
    dc.fillRectangle(100, 100, 100, 100);
}

Example:

Draws a red circle using direct pixel parameters.

using Toybox.Graphics;
function onUpdate(dc) {
    dc.setColor(Graphics.COLOR_RED, Graphics.COLOR_BLACK);
    dc.fillCircle(50, 100, 75);
}

Example:

Draws "Hello World" in the center of the screen using calls to the Device Context (dc).

using Toybox.Graphics;
function onUpdate(dc) {
    dc.setColor(Graphics.COLOR_BLACK, Graphics.COLOR_TRANSPARENT);
    dc.drawText(
        dc.getWidth() / 2,                      // gets the width of the device and divides by 2
        dc.getHeight() / 2,                     // gets the height of the device and divides by 2
        Graphics.FONT_LARGE,                    // sets the font size
        "Hello World",                          // the String to display
        Graphics.TEXT_JUSTIFY_CENTER            // sets the justification for the text
                );
}

Example:

Clears the screen of device with background color (Graphics.COLOR_BLACK).

using Toybox.Graphics;
function onUpdate(dc) {
    dc.setColor(Graphics.COLOR_BLACK, Graphics.COLOR_BLACK);
    dc.clear();
}

Since:

API Level 1.0.0

Instance Method Summary

• clear() as Void

  Erase the screen using the background color.

• clearClip() as Void

  Reset the drawable area to the full area of the Dc.

• drawArc(x as Lang.Numeric, y as Lang.Numeric, r as Lang.Numeric, attr as Graphics.ArcDirection, degreeStart as Lang.Numeric, degreeEnd as Lang.Numeric) as Void

  Draw an arc.

• drawBitmap(x as Lang.Numeric, y as Lang.Numeric, bitmap as Graphics.BitmapType) as Void

  Draw a bitmap to the screen.

• drawCircle(x as Lang.Numeric, y as Lang.Numeric, radius as Lang.Numeric) as Void

  Draw a circle around a point.

• drawEllipse(x as Lang.Numeric, y as Lang.Numeric, a as Lang.Numeric, b as Lang.Numeric) as Void

  Draw an ellipse around a point.

• drawLine(x1 as Lang.Numeric, y1 as Lang.Numeric, x2 as Lang.Numeric, y2 as Lang.Numeric) as Void

  Draw a line between two points.

• drawOffsetBitmap(x as Lang.Numeric, y as Lang.Numeric, bitmapX as Lang.Numeric, bitmapY as Lang.Numeric, bitmapWidth as Lang.Numeric, bitmapHeight as Lang.Numeric, bitmap as Graphics.BitmapType) as Void

  Draw a bitmap to the screen with an offset.

• drawPoint(x as Lang.Numeric, y as Lang.Numeric) as Void

  Draw a point on the screen.

• drawRectangle(x as Lang.Numeric, y as Lang.Numeric, width as Lang.Numeric, height as Lang.Numeric) as Void

  Draw a rectangle.

• drawRoundedRectangle(x as Lang.Numeric, y as Lang.Numeric, width as Lang.Numeric, height as Lang.Numeric, radius as Lang.Numeric) as Void

  Draw a rounded rectangle.

• drawScaledBitmap(x as Lang.Numeric, y as Lang.Numeric, width as Lang.Numeric, height as Lang.Numeric, bitmap as Graphics.BitmapType) as Void

  Draw a scaled bitmap to a surface.

• drawText(x as Lang.Numeric, y as Lang.Numeric, font as Graphics.FontType, text as Lang.String, justification as Graphics.TextJustification or Lang.Number) as Void

  Draw text at the given location.

• fillCircle(x as Lang.Numeric, y as Lang.Numeric, radius as Lang.Numeric) as Void

  Fill a circle with the foreground color.

• fillEllipse(x as Lang.Numeric, y as Lang.Numeric, a as Lang.Numeric, b as Lang.Numeric) as Void

  Fill an ellipse with the foreground color.

• fillPolygon(pts as Lang.Array<Lang.Array<Lang.Numeric>>) as Void

  Fill a polygon with the foreground color.

• fillRectangle(x as Lang.Numeric, y as Lang.Numeric, width as Lang.Numeric, height as Lang.Numeric) as Void

  Fill a rectangle with the foreground color.

• fillRoundedRectangle(x as Lang.Numeric, y as Lang.Numeric, width as Lang.Numeric, height as Lang.Numeric, radius as Lang.Numeric) as Void

  Fill a rounded rectangle with the foreground color.

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

  Get the height of a font.

• getHeight() as Lang.Number

  Get the height of the display region that is available to the app.

• getTextDimensions(text as Lang.String, font as Graphics.FontType) as Lang.Array<Lang.Number>

  Get the width and height of a String.

• getTextWidthInPixels(text as Lang.String, font as Graphics.FontType) as Lang.Number

  Get the width of a String.

• getWidth() as Lang.Number

  Get the width of the display region that is available to the app.

• setAntiAlias(enabled as Lang.Boolean) as Void

  Enable anti-aliased drawing for primitives This method is not supported for a BufferedBitmap that has a palette.

• setBlendMode(mode as Graphics.BlendMode) as Void

  Set blend mode for drawing.

• setClip(x as Lang.Numeric, y as Lang.Numeric, width as Lang.Numeric, height as Lang.Numeric) as Void

  Apply a clipping region to the Dc.

• setColor(foreground as Graphics.ColorType, background as Graphics.ColorType) as Void

  Set the current foreground and background colors.

• setFill(fill as Lang.Number or Graphics.BitmapTexture) as Void

  Set fill tool for drawing primitives.

• setPenWidth(width as Lang.Numeric) as Void

  Set the width of a line.

• setStroke(stroke as Lang.Number or Graphics.BitmapTexture) as Void

  Set draw tool for drawing primitives.

Instance Method Details

clear() as Void

Erase the screen using the background color.

Note:

Starting form version 3.1.0, COLOR_TRANSPARENT will also be honored as background color, which will cause the value of pixels in the clip region to be replaced by COLOR_TRANSPARENT. For example, this can be used to clear the transparent overlay layer so animation background is visible.

Since:

API Level 1.0.0

clearClip() as Void

Reset the drawable area to the full area of the Dc.

Since:

API Level 2.3.0

drawArc(x as Lang.Numeric, y as Lang.Numeric, r as Lang.Numeric, attr as Graphics.ArcDirection, degreeStart as Lang.Numeric, degreeEnd as Lang.Numeric) as Void

Draw an arc.

• 0 degrees: 3 o'clock position.

• 90 degrees: 12 o'clock position.

• 180 degrees: 9 o'clock position.

• 270 degrees: 6 o'clock position.

Parameters:

• x — (Lang.Number) —

  The x location of the arc center

• y — (Lang.Number) —

  The y location of the arc center

• r — (Lang.Number) —

  The radius of the arc

• attr — (Lang.Number) —

  Arc drawing attributes. (ARC_COUNTER_CLOCKWISE or ARC_CLOCKWISE)

• degreeStart — (Lang.Number) —

  The start angle of the arc by degrees.

• degreeEnd — (Lang.Number) —

  The end angle of the arc by degrees.

Since:

API Level 1.2.0

drawBitmap(x as Lang.Numeric, y as Lang.Numeric, bitmap as Graphics.BitmapType) as Void

Draw a bitmap to the screen.

Note:

BitmapReference is only supported in CIQ 4.0.0 and later

Parameters:

• x — (Lang.Number) —

  The top left x coordinate to begin the draw

• y — (Lang.Number) —

  The top left y coordinate to begin the draw

• bitmap — (BitmapResource, Graphics.BufferedBitmap, Graphics.BitmapReference) —

  The object to draw. The source color palette must be a subset of the destination color palette.

Since:

API Level 1.0.0

Throws:

• (Graphics.InvalidPaletteException) —

  Thrown if the source color palette is not a subset of the destination palette

drawCircle(x as Lang.Numeric, y as Lang.Numeric, radius as Lang.Numeric) as Void

Draw a circle around a point.

Parameters:

• x — (Lang.Number) —

  The x location of the circle center

• y — (Lang.Number) —

  The y location of the circle center

• radius — (Lang.Number) —

  The radius of the circle

Since:

API Level 1.0.0

drawEllipse(x as Lang.Numeric, y as Lang.Numeric, a as Lang.Numeric, b as Lang.Numeric) as Void

Draw an ellipse around a point.

Parameters:

• x — (Lang.Number) —

  The x location of the ellipse center

• y — (Lang.Number) —

  The y location of the ellipse center

• a — (Lang.Number) —

  The radius of the ellipse along the x axis

• b — (Lang.Number) —

  The radius of the ellipse along the y axis

Since:

API Level 1.0.0

drawLine(x1 as Lang.Numeric, y1 as Lang.Numeric, x2 as Lang.Numeric, y2 as Lang.Numeric) as Void

Draw a line between two points.

Parameters:

• x1 — (Lang.Number) —

  The first x coordinate

• y1 — (Lang.Number) —

  The first y coordinate

• x2 — (Lang.Number) —

  The second x coordinate

• y2 — (Lang.Number) —

  The second y coordinate

Since:

API Level 1.0.0

drawOffsetBitmap(x as Lang.Numeric, y as Lang.Numeric, bitmapX as Lang.Numeric, bitmapY as Lang.Numeric, bitmapWidth as Lang.Numeric, bitmapHeight as Lang.Numeric, bitmap as Graphics.BitmapType) as Void

Draw a bitmap to the screen with an offset.

Parameters:

• x — (Lang.Number) —

  The top left x coordinate to begin the draw

• y — (Lang.Number) —

  The top left y coordinate to begin the draw

• bitmapX — (Lang.Number) —

  The x offset of the upper left corner of pixels to copy from the bitmap.

• bitmapY — (Lang.Number) —

  The y offset of the upper left corner of pixels to copy from the bitmap.

• bitmapWidth — (Lang.Number) —

  The width of the area to copy pixels from the bitmap.

• bitmapHeight — (Lang.Number) —

  The height of the area to copy pixels from the bitmap

• bitmap — (Lang.Object) —

  The BitmapResource or BufferedBitmap to render. The source color palette must be a subset of the destination color palette.

Since:

API Level 4.0.0

Throws:

• (Graphics.InvalidPaletteException) —

  Thrown if the source color palette is not a subset of the destination palette

drawPoint(x as Lang.Numeric, y as Lang.Numeric) as Void

Draw a point on the screen.

Parameters:

• x — (Lang.Number) —

  The x location of the point

• y — (Lang.Number) —

  The y location of the point

Since:

API Level 1.0.0

drawRectangle(x as Lang.Numeric, y as Lang.Numeric, width as Lang.Numeric, height as Lang.Numeric) as Void

Draw a rectangle.

Parameters:

• x — (Lang.Number) —

  The x location of the upper corner

• y — (Lang.Number) —

  The y location of the upper corner

• width — (Lang.Number) —

  The width value of the rectangle

• height — (Lang.Number) —

  The height value of the rectangle

Since:

API Level 1.0.0

drawRoundedRectangle(x as Lang.Numeric, y as Lang.Numeric, width as Lang.Numeric, height as Lang.Numeric, radius as Lang.Numeric) as Void

Draw a rounded rectangle.

Parameters:

• x — (Lang.Number) —

  The x location of the upper corner

• y — (Lang.Number) —

  The y location of the upper corner

• width — (Lang.Number) —

  The width value of the rectangle

• height — (Lang.Number) —

  The height value of the rectangle

• radius — (Lang.Number) —

  The radius of the rounding.

Since:

API Level 1.0.0

drawScaledBitmap(x as Lang.Numeric, y as Lang.Numeric, width as Lang.Numeric, height as Lang.Numeric, bitmap as Graphics.BitmapType) as Void

Draw a scaled bitmap to a surface.

Parameters:

• x — (Lang.Number) —

  The top left x coordinate to begin the draw

• y — (Lang.Number) —

  The top left y coordinate to begin the draw

• width — (Lang.Number) —

  The width of the bitmap drawn on the destination surface

• height — (Lang.Number) —

  The height of the bitmap drawn on the destination surface

• bitmap — (Lang.Object) —

  The BitmapResource or BufferedBitmap to render. The source color palette must be a subset of the destination color palette.

Since:

API Level 4.0.0

Throws:

• (Graphics.InvalidPaletteException) —

  Thrown if the source color palette is not a subset of the destination palette

drawText(x as Lang.Numeric, y as Lang.Numeric, font as Graphics.FontType, text as Lang.String, justification as Graphics.TextJustification or Lang.Number) as Void

Draw text at the given location.

This method is not supported for anti-aliased fonts (including most built in fonts) for a BufferedBitmap that has a palette.

Note:

FontReference is only supported in CIQ 4.0.0 and later

Parameters:

• x — (Lang.Number) —

  The x location of the text

• y — (Lang.Number) —

  The y location of the text

• font — (Graphics.FontType) —

  The font to use. This can be a custom font loaded from resources or a Graphics.FONT_* value.

• text — (Lang.String) —

  The String to render. This can be a String loaded from resources or a hard coded String

• justification —

  Mask of Graphics.TEXT_JUSTIFY_* constants. This may either be a single Graphics.TEXT_JUSTIFY_* constant, or a combination of one vertical and one horizontal justification value as a bit mask (e.g., Graphics.TEXT_JUSTIFY_CENTER | Graphics.TEXT_JUSTIFY_VCENTER).

Since:

API Level 1.0.0

Throws:

• (Graphics.InvalidPaletteException) —

  Thrown if an anti-aliased font is used on a paletted bitmap

fillCircle(x as Lang.Numeric, y as Lang.Numeric, radius as Lang.Numeric) as Void

Fill a circle with the foreground color.

Parameters:

• x — (Lang.Number) —

  The x location of the circle center

• y — (Lang.Number) —

  The y location of the circle center

• radius — (Lang.Number) —

  The radius of the circle

Since:

API Level 1.0.0

fillEllipse(x as Lang.Numeric, y as Lang.Numeric, a as Lang.Numeric, b as Lang.Numeric) as Void

Fill an ellipse with the foreground color.

Parameters:

• x — (Lang.Number) —

  The x location of the ellipse center

• y — (Lang.Number) —

  The y location of the ellipse center

• a — (Lang.Number) —

  The radius of the ellipse along the x axis

• b — (Lang.Number) —

  The radius of the ellipse along the y axis

Since:

API Level 1.0.0

fillPolygon(pts as Lang.Array<Lang.Array<Lang.Numeric>>) as Void

Fill a polygon with the foreground color.

Parameters:

• pts — (Lang.Array) —

  Array of coordinates with a 64 point limit

Since:

API Level 1.0.0

fillRectangle(x as Lang.Numeric, y as Lang.Numeric, width as Lang.Numeric, height as Lang.Numeric) as Void

Fill a rectangle with the foreground color.

Parameters:

• x — (Lang.Number) —

  The x location of the upper corner

• y — (Lang.Number) —

  The y location of the upper corner

• width — (Lang.Number) —

  The width value of the rectangle

• height — (Lang.Number) —

  The height value of the rectangle

Since:

API Level 1.0.0

fillRoundedRectangle(x as Lang.Numeric, y as Lang.Numeric, width as Lang.Numeric, height as Lang.Numeric, radius as Lang.Numeric) as Void

Fill a rounded rectangle with the foreground color.

Parameters:

• x — (Lang.Number) —

  The x location of the upper corner

• y — (Lang.Number) —

  The y location of the upper corner

• width — (Lang.Number) —

  The width value of the rectangle

• height — (Lang.Number) —

  The height value of the rectangle

• radius — (Lang.Number) —

  The radius of the rounding

Since:

API Level 1.0.0

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

Get the height of a font.

Parameters:

• font — (FontType) —

  The font to measure

Returns:

• Lang.Number —

  The height of the font in pixels

Since:

API Level 1.0.0

getHeight() as Lang.Number

Get the height of the display region that is available to the app.

Returns:

• Lang.Number —

  The height of display in pixels

Since:

API Level 1.0.0

getTextDimensions(text as Lang.String, font as Graphics.FontType) as Lang.Array<Lang.Number>

Get the width and height of a String.

This takes new lines into account when determining the height. The width is the maximum width for a given line of the String. If a String has two newline characters (\\n) in it, the height would be for three lines and the width would be the width of the longest String.

Parameters:

• text — (Lang.String) —

  The text to get the width for

• font — (Graphics.FontType) —

  The font of the text to measure.

Returns:

• Lang.Array —

  The [width, height] of the String in pixels

Since:

API Level 1.0.0

getTextWidthInPixels(text as Lang.String, font as Graphics.FontType) as Lang.Number

Get the width of a String.

Parameters:

• text — (Lang.String) —

  The text to get width for

• font — (Graphics.FontType) —

  The font of the text to measure.

Returns:

• Lang.Number —

  The width of String in pixels

Since:

API Level 1.0.0

getWidth() as Lang.Number

Get the width of the display region that is available to the app.

Returns:

• Lang.Number —

  The width of display in pixels

Since:

API Level 1.0.0

setAntiAlias(enabled as Lang.Boolean) as Void

Enable anti-aliased drawing for primitives This method is not supported for a BufferedBitmap that has a palette.

Parameters:

• enabled — (Lang.Boolean) —

  true if AA is to be enabled, false otherwise.

Supported Devices:

• Captain Marvel
• D2™ Air
• D2™ Air X10
• D2™ Mach 1
• Darth Vader™
• Descent™ Mk2 / Descent™ Mk2i
• Descent™ Mk2 S
• Edge® 1030
• Edge® 1030 Plus
• Edge® 530
• Edge® 830
• Enduro™
• epix™ (Gen 2) / quatix® 7 Sapphire
• First Avenger
• Forerunner® 245
• Forerunner® 245 Music
• Forerunner® 645 Music
• Forerunner® 745
• Forerunner® 945
• Forerunner® 945 LTE
• fēnix® 5 Plus
• fēnix® 5S Plus
• fēnix® 5X Plus
• fēnix® 6 / 6 Solar / 6 Dual Power
• fēnix® 6 Pro / 6 Sapphire / 6 Pro Solar / 6 Pro Dual Power / quatix® 6
• fēnix® 6 Pro System 5 Preview
• fēnix® 6S / 6S Solar / 6S Dual Power
• fēnix® 6S Pro / 6S Sapphire / 6S Pro Solar / 6S Pro Dual Power
• fēnix® 6X Pro / 6X Sapphire / 6X Pro Solar / tactix® Delta Sapphire / Delta Solar / Delta Solar - Ballistics Edition / quatix® 6X / 6X Solar / 6X Dual Power
• fēnix® 7 / quatix® 7
• fēnix® 7S
• fēnix® 7X / tactix® 7 / quatix® 7X Solar
• MARQ® Adventurer
• MARQ® Athlete
• MARQ® Aviator
• MARQ® Captain / MARQ® Captain: American Magic Edition
• MARQ® Commander
• MARQ® Driver
• MARQ® Expedition
• MARQ® Golfer
• Montana® 7 Series
• Rey™
• Venu™
• Venu™ 2
• Venu™ 2 Plus
• Venu™ 2 System 5 Preview
• Venu™ 2S
• Venu™ Mercedes-Benz® Collection
• Venu® Sq
• Venu® Sq. Music Edition
• vívoactive® 3 Music
• vívoactive® 3 Music LTE
• vívoactive® 4
• vívoactive® 4S

Since:

API Level 3.2.0

Throws:

• (Graphics.InvalidPaletteException) —

  Thrown if antialiasing is enabled for a paletted bitmap.

setBlendMode(mode as Graphics.BlendMode) as Void

Set blend mode for drawing.

Note:

BLEND_MODE_NO_BLEND is only supported while drawing bitmaps

Parameters:

• mode — (Lang.Number) —

  Graphics.BLEND_MODE_* constant.

Since:

API Level 4.0.0

setClip(x as Lang.Numeric, y as Lang.Numeric, width as Lang.Numeric, height as Lang.Numeric) as Void

Apply a clipping region to the Dc.

Pixels outside of the region will not be affected by any operations.

Parameters:

• x — (Lang.Number) —

  The x coordinate of the top left corner of the clipping region

• y — (Lang.Number) —

  The y coordinate of the top left corner of the clipping region

• width — (Lang.Number) —

  The width of the clipping region in pixels.

• height — (Lang.Number) —

  The height of the clipping region in pixels.

Since:

API Level 2.3.0

setColor(foreground as Graphics.ColorType, background as Graphics.ColorType) as Void

Set the current foreground and background colors.

Parameters:

• foreground — (Lang.Number) —

  Graphics.COLOR_* constant or 24-bit integer of the form 0xRRGGBB.

• background — (Lang.Number) —

  Graphics.COLOR_* constant or 24-bit integer of the form 0xRRGGBB.

Since:

API Level 1.0.0

setFill(fill as Lang.Number or Graphics.BitmapTexture) as Void

Set fill tool for drawing primitives.

Note:

this function takes precedence over setColor(). If fill tool is not set, the foreground color will be used.

Parameters:

• fill — (Lang.Object) —

  The BitmapTexture or Color 32-bit integer in the format 0xAARRGGBB to use for fill draws.

Since:

API Level 4.0.0

setPenWidth(width as Lang.Numeric) as Void

Set the width of a line.

Parameters:

• width — (Lang.Number) —

  The pen width in pixels

Since:

API Level 1.0.0

setStroke(stroke as Lang.Number or Graphics.BitmapTexture) as Void

Set draw tool for drawing primitives.

Note:

this function takes precedence over setColor(). If draw tool is not set, the foreground color will be used.

Parameters:

• stroke — (Lang.Object) —

  The BitmapTexture or Color 32-bit integer in the format 0xAARRGGBB to use for draws.

Since:

API Level 4.0.0