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.

Go to Property Listing | Method Listing

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.

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.

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.

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.

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.