Class: Toybox.Graphics.Dc

Inherits:
Toybox.Lang.Object show all

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 collapse

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:

Since:

API Level 1.0.0

Throws:

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:

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.

Supported Devices:

Since:

API Level 4.0.0

Throws:

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

Draw a point on the screen.

Parameters:

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.

Supported Devices:

Since:

API Level 4.0.0

Throws:

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:

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:

Since:

API Level 1.0.0

getHeight() as Lang.Number

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

Returns:

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:

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:

Returns:

Since:

API Level 1.0.0

getWidth() as Lang.Number

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

Returns:

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:

Since:

API Level 3.2.0

Throws:

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.

Supported Devices:

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:

Supported Devices:

Since:

API Level 4.0.0

setPenWidth(width as Lang.Numeric) as Void

Set the width of a line.

Parameters:

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:

Supported Devices:

Since:

API Level 4.0.0

Generated Sep 1, 2022 11:27:02 AM