ScriptUIGraphics (SUI)

An object used to draw custom graphics, found in the graphics property of window, container, and control objects.

Allows a script to customize aspects of the element’s appearance, such as the color and font. Use an onDraw callback function to set these properties or call the functions.All measurements are in pixels.

Methods:

closePath, drawFocusRing, drawImage, drawOSControl, drawString, ellipsePath, fillPath, lineTo, measureString, moveTo, newBrush, newPath, newPen, rectPath, strokePath

Objects:

Point (SUI), ScriptUIBrush (SUI), ScriptUIFont (SUI), ScriptUIPath (SUI), ScriptUIPen (SUI)

Property Listing

Property

Type

Access

Description

backgroundColor

ScriptUIBrush (SUI)

read/write

The background color for containers; for non-containers, the parent background color.

The paint color and style is defined in this brush object.This property is only supported for controls like dropdownlist, edittext, and listbox.

currentPath

ScriptUIPath (SUI)

readonly

The current drawing path, encapsulated in a path object.

currentPoint

Point (SUI)

readonly

The current position in the current drawing path.

disabledBackgroundColor

ScriptUIBrush (SUI)

read/write

The background color for containers when disabled or inactive; for non-containers, the parent background color.

The paint color and style is defined in this brush object.This property is only supported for controls like dropdownlist, edittext, and listbox.

disabledForegroundColor

ScriptUIPen (SUI)

read/write

The text color when the element is disabled or inactive.

The paint color and style is defined in this pen object.

font

ScriptUIFont (SUI)

read/write

The default font to use for displaying text.

foregroundColor

ScriptUIPen (SUI)

read/write

The text color.

The paint color and style is defined in this pen object.

Property Listing

Name

Type

Access

Description

BrushType

Object

readonly

Contains the enumerated constants for the type argument of newBrush().

Type constants are: SOLID_COLOR, THEME_COLOR.

PenType

Object

readonly

Contains the enumerated constants for the type argument of newPen().

Type constants are: SOLID_COLOR, THEME_COLOR.

Method Listing

undefined closePath ()

Closes the current path.

Defines a line from the current postion (currentPoint) to the start point of the current path (the value of currentPath).

undefined drawFocusRing (left:Number, top:Number, width:Number, height:Number)

Draws a focus ring within a region of this element.

Parameter

Type

Description

left

Number

The left coordinate of the region.

Value is relative to the origin of this element.

top

Number

The top coordinate of the region.

Value is relative to the origin of this element.

width

Number

The width of the region in pixels.

height

Number

The height of the region in pixels.

undefined drawImage (image:ScriptUIImageSUI, left:Number, top:Number, [width:Number], [height:Number])

Draws an image within a given region of the element.

Uses the version of the image that is appropriate to the element's current state.

Parameter

Type

Description

image

ScriptUIImage (SUI)

The image to draw.

This object contains different versions of an image appropriate to various element states, such as a dimmed version for the disabled state.

left

Number

The left coordinate of the region, relative to the origin of this element.

top

Number

The top coordinate of the region, relative to the origin of this element.

width

Number

The width in pixels. If provided, the image is stretched or shrunk to fit. If omitted, uses the original image width.

height

Number

The height in pixels. If provided, the image is stretched or shrunk to fit. If omitted, uses the original image height.

undefined drawOSControl ()

Draw the platform-specific control associated with this element.

undefined drawString (text:String, pen:ScriptUIPenSUI, x:Number, y:Number, [font:ScriptUIFontSUI])

Draw a string of text starting at a given point in this element, using a given drawing pen and font.

Parameter

Type

Description

text

String

The text string.

pen

ScriptUIPen (SUI)

The drawing pen to use.

x

Number

The left coordinate, relative to the origin of this element.

y

Number

The top coordinate, relative to the origin of this element.

font

ScriptUIFont (SUI)

The font to use. Default is the  font value in this object.

Point (SUI) ellipsePath (left:Number, top:Number, width:Number, height:Number)

Defines an elliptical path within a given rectangular area in the currentPath object, which can be filled using fillPath() or stroked using strokePath().

Returns a Point object for the upper left corner of the area, which is the new currentPoint.

Parameter

Type

Description

left

Number

The left coordinate of the region, relative to the origin of this element.

top

Number

The top coordinate of the region, relative to the origin of this element.

width

Number

The width of the region in pixels.

height

Number

The height of the region in pixels.

undefined fillPath (brush:ScriptUIBrushSUI, [path:ScriptUIPathSUI])

Fills a path using a given painting brush.

Parameter

Type

Description

brush

ScriptUIBrush (SUI)

The brush object that defines the fill color.

path

ScriptUIPath (SUI)

The path object. Default is the currentPath.

Point (SUI) lineTo (x:Number, y:Number)

Adds a path segment to the currentPath.

The line is defined from the currentPoint to the specified destination point. Returns the Point object for the destination point, which becomes the new value of currentPoint.

Parameter

Type

Description

x

Number

The X coordinate for the destination point, relative to the origin of this element.

y

Number

The Y coordinate for the destination point, relative to the origin of this element.

Dimension (SUI) measureString (text:String, [font:ScriptUIFontSUI], [boundingWidth:Number])

Calculates the size needed to display a string using the given font.

Returns a Dimension object that contains the height and width of the string in pixels.

Parameter

Type

Description

text

String

The text string to measure.

font

ScriptUIFont (SUI)

The font to use. Default is the font value in this object.

boundingWidth

Number

The bounding width.

Point (SUI) moveTo (x:Number, y:Number)

Adds a given point to the currentPath, and makes it the current drawing position.

Returns the Point object which is the new value of currentPoint.

Parameter

Type

Description

x

Number

The X coordinate for the new point, relative to the origin of this element.

y

Number

The Y coordinate for the new point, relative to the origin of this element.

ScriptUIBrush (SUI) newBrush (type:Number, color:Array of Number String)

Creates a new painting brush object.

Parameter

Type

Description

type

Number

The brush type, solid or theme.

One of the constants ScriptUIGraphics.BrushType.SOLID_COLOR or ScriptUIGraphics.BrushType.THEME_COLOR.

color

Array of Number

String

The brush color.

If type is SOLID_COLOR, the color expressed as an array of three or four values, in the form [R, B, G, A] specifying the red, green, and blue values of the color and, optionally, the opacity (alpha channel). All values are numbers in the range [0.0..1.0]. An opacity of 0 is fully transparent, and an opacity of 1 is fully opaque. If the type is THEME_COLOR, the name string of the theme. Theme colors are defined by the host application.

ScriptUIPath (SUI) newPath ()

Creates a new, empty path object.

Replaces any existing path in currentPath.

ScriptUIPen (SUI) newPen (type:Number, color:Array of Number String, width:Number)

Creates a new drawing pen object.

Parameter

Type

Description

type

Number

The pen type, solid or theme.

One of the constants ScriptUIGraphics.PenType.SOLID_COLOR or ScriptUIGraphics.PenType.THEME_COLOR.

color

Array of Number

String

The pen color.

If type is SOLID_COLOR, the color expressed as an array of three or four values, in the form [R, B, G, A] specifying the red, green, and blue values of the color and, optionally, the opacity (alpha channel). All values are numbers in the range [0.0..1.0]. An opacity of 0 is fully transparent, and an opacity of 1 is fully opaque. If the type is THEME_COLOR, the name string of the theme. Theme colors are defined by the host application.

width

Number

The width of the pen line in pixels.

The line is centered around the current point. For example, if the value is 2, drawing a line from (0, 10) to (5, 10) paints the two rows of pixels directly above and below y-position 10.

Point (SUI) rectPath (left:Number, top:Number, width:Number, height:Number)

Defines a rectangular path in the currentPath object.

The rectangle can be filled using fillPath() or stroked using strokePath().Returns the Point object for the upper left corner of the rectangle, which becomes the new value of currentPoint.

Parameter

Type

Description

left

Number

The left coordinate relative to the origin of this element.

top

Number

The top coordinate relative to the origin of this element.

width

Number

The width in pixels.

height

Number

The height in pixels.

undefined strokePath (pen:ScriptUIPenSUI, [path:ScriptUIPathSUI])

Strokes the path segments of a path with a given drawing pen.

Parameter

Type

Description

pen

ScriptUIPen (SUI)

The drawing pen that defines the color and line width.

path

ScriptUIPath (SUI)

The path object. Default is the currentPath.

Object of

StaticText (SUI).graphics

Button (SUI).graphics

IconButton (SUI).graphics

EditText (SUI).graphics

ListBox (SUI).graphics

DropDownList (SUI).graphics

Checkbox (SUI).graphics

Scrollbar (SUI).graphics

Slider (SUI).graphics

Progressbar (SUI).graphics

TreeView (SUI).graphics

Group (SUI).graphics

Panel (SUI).graphics

RadioButton (SUI).graphics

Window (SUI).graphics