Graphic customization objects¶

These objects provide the ability to customize the appearance of user-interface controls before they are drawn:

ScriptUIGraphics object
ScriptUIBrush object
ScriptUIFont object
ScriptUIImage object
ScriptUIPath object
ScriptUIPen object

In addition, the Custom element class (if supported by the Adobe application you are using) allows you to define completely customized UI elements that are rendered by the application in a manner you define.

ScriptUIGraphics Object¶

Most types of user-interface elements have a graphics property which contains an object of this type, which allows you 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.

ScriptUIGraphics Class Attributes¶

These static properties provide color type constants with which to create Pen and Brush objects.

BrushType¶

Description¶

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

SOLID_COLOR
THEME_COLOR

Type¶

Object

PenType¶

Description¶

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

SOLID_COLOR
THEME_COLOR

Type¶

Object

ScriptUIGraphics Object Attributes¶

The object contains the following properties:

backgroundColor¶

controlObj.graphics.backgroundColor

Description¶

The background color of a container, or the parent background color for a control element.

Type¶

ScriptUIBrush object

currentPath¶

controlObj.graphics.currentPath

Description¶

The current drawing path for this object.

Type¶

ScriptUIPath object

currentPoint¶

controlObj.graphics.currentPoint

Description¶

The current position in the drawing path for this object

Type¶

Point object

disabledBackgroundColor¶

controlObj.graphics.disabledBackgroundColor

Description¶

The background color for the disabled state of a container, or the parent background color for the disabled state of a control element.

Type¶

ScriptUIBrush object

disabledForegroundColor¶

controlObj.graphics.disabledForegroundColor

Description¶

The foreground color for the disabled state of a container, or the parent foreground color for the disabled state of a control element.

Type¶

ScriptUIPen object

font¶

controlObj.graphics.font

Description¶

The default font to use in writing text.

Type¶

ScriptUIFont object

foregroundColor¶

controlObj.graphics.foregroundColor

Description¶

The foreground color for a container, or the parent foreground color of a control element.

Type¶

ScriptUIPen object

ScriptUIGraphics Object Methods¶

These functions directly customize the appearance of the associated element by drawing on the screen, or create the Pen and Brush objects used to populate the graphics object or pass to the drawing methods:

closePath()¶

controlObj.graphics.closePath()

Description¶

Defines a line from the current position to the start point of the current path (the value of currentPath), which closes the path.

Returns¶

Nothing

drawFocusRing()¶

controlObj.graphics.drawFocusRing(left, top[, width, height])

Description¶

Draws a focus ring within the given rectangular region. This is a visual indicator showing that a given control has the keyboard focus (accepts keyboard input).

In Mac OS, this is typically a light blue ring around the control.

In Windows, it is typically a dashed-line rectangle around some part of the control.

Parameters¶

Parameter	Type	Description
`left`, `top`	Number	Defines the top left corner of the region, in the coordinate system of the control that contains this graphics object.
`width`, `height`	Number	Optional. The width and height of the region in pixels.

Returns¶

Nothing

drawImage()¶

controlObj.graphics.drawImage(image, left, top[, width, height])

Description¶

Draws an image within the given rectangular region, using the image file from the given image object that is appropriate to the control's current state.

Parameters¶

Parameter	Type	Description
`image`	ScriptUIImage object	The ScriptUIImage object containing the images to be drawn.
`left`, `top`	Number	Defines the top left corner of the drawing region, in the coordinate system of the control that contains this graphics object.
`width`, `height`	Number	Optional. The width and height of the drawing region in pixels. If specified, the image is stretched or shrunk to fit into the given rectangular area. If omitted, the image's original width or height is used.

Returns¶

Nothing

drawOSControl()¶

controlObj.graphics.drawOSControl()

Description¶

Draws the platform-specific control associated with this element.

Returns¶

Nothing

drawString()¶

controlObj.graphics.drawString(text, pen, x, y, font)

Description¶

Draws a string of text starting at a given point, using the given pen and font.

Parameters¶

Parameter	Type	Description
`text`	String	The text string.
`pen`	ScriptUIPen object	The ScriptUIPen object for the drawing pen to use.
`x`, `y`	Number	The origin point of the drawn text, in the coordinate system of the control that contains this graphics object.
`font`	ScriptUIFont object	Optional. The ScriptUIFont object for the font to use. Default is the font value in this object.

Returns¶

Nothing

ellipsePath()¶

controlObj.graphics.ellipsePath(left, top[, width, height])

Description¶

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.

Parameters¶

Parameter	Type	Description
`left`, `top`	Number	Defines the top left corner of the region, in the coordinate system of the control that contains this graphics object.
`width`, `height`	Number	The width and height of the region in pixels.

Returns¶

Point object

fillPath()¶

controlObj.graphics.fillPath(brush[, path])

Description¶

Fills a path using a given painting brush.

Parameters¶

Parameter	Type	Description
`brush`	ScriptUIBrush object	The ScriptUIBrush object that defines the fill color.
`path`	ScriptUIPath object	Optional, the ScriptUIPath object for the path. If not supplied, operates on the currentPath.

Returns¶

Nothing

lineto()¶

controlObj.graphics.lineto(x, y)

Description¶

Adds a path segment to the currentPath, from the currentPoint to the specified point.

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

Parameters¶

Parameter	Type	Description
`x`, `y`	Number	The destination point of the line, in the coordinate system of the control that contains this graphics object.

Returns¶

Point object

measureString()¶

controlObj.graphics.measureString(text, font[, boundingWidth])

Description¶

Calculates the size needed to draw a text string in a given font.

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

Parameters¶

Parameter	Type	Description
`text`	Text	The text string to measure.
`font`	ScriptUIFont object	Optional. The ScriptUIFont object for the font to use. Default is the font value in this object.
`boundingWidth`	Number	Optional. A number that specifies the maximum width in pixels of the area in which the text might be placed. Use when wrapping a long string of text across multiple lines.

Returns¶

Dimension object

moveto()¶

controlObj.graphics.moveto(x, y)

Description¶

Adds a given point to the currentPath, and makes it the currentPoint.

Parameters¶

Parameter	Type	Description
`x`, `y`	Number	The new coordinates, in the coordinate system of the control that contains this graphics object.

Returns¶

Point object

newBrush()¶

controlObj.graphics.newBrush(type, color);

Description¶

Creates a new painting brush.

Parameters¶

Parameter

Type

Description

type

BrushType

The brush type, one of these constants:

ScriptUIGraphics.BrushType.SOLID_COLOR
ScriptUIGraphics.BrushType.THEME_COLOR

color

Array of Numbers

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.

Returns¶

ScriptUIBrush object.

newPath()¶

controlObj.graphics.newPath();

Description¶

Creates a new, empty drawing path in currentPath, replacing any existing path.

Returns¶

ScriptUIPath object.

newPen()¶

controlObj.graphics.newPen(type, color, lineWidth);

Description¶

Creates a new drawing pen.

Parameters¶

Parameter

Type

Description

type

PenType

The pen type, one of these constants:

ScriptUIGraphics.PenType.SOLID_COLOR
ScriptUIGraphics.PenType.THEME_COLOR

color

Array of Numbers

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.

lineWidth

Pixels

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

Returns¶

ScriptUIPen object.

rectPath()¶

controlObj.graphics.rectPath(left, top[, width, height])

Description¶

Defines a rectangular path 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 rectangle, which is the new currentPoint.

Parameters¶

Parameter	Type	Description
`left`, `top`	Number	Defines the top left corner of the region, in the coordinate system of the control that contains this graphics object.
`width`, `height`	Number	The width and height of the region in pixels.

Returns¶

Point object

strokePath()¶

controlObj.graphics.fillPath(pen[, path])

Description¶

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

Parameters¶

Parameter	Type	Description
`pen`	ScriptUIPen object	The ScriptUIPen object that defines the color and line width.
`path`	ScriptUIPath object	Optional, the ScriptUIPath object for the path. If not supplied, operates on the currentPath.

Returns¶

Nothing

ScriptUIBrush Object¶

A helper object that encapsulates the qualities of a brush used to paint fill into a path in a control. Create with the newBrush() method of the ScriptUIGraphics object.

Used as a value of backgroundColor and disabledBackgroundColor.

Passed as an argument to fillPath().

ScriptUIBrush Object Attributes¶

The object contains the following properties:

Property

Type

Description

color

Array of Number

The paint color to use when the type is SOLID_COLOR. An array in the form [R, B, G, A] specifying the red, green, blue values of the color and the opacity (alpha channel) value as numbers in the range [0.0...1.0]. An opacity of 0 is fully transparent, and an opacity of 1 is fully opaque.

theme

String

The name of a color theme to use as a painting texture when the type is THEME_COLOR. Theme colors are defined by the host application.

type

Number

The brush type, one of these constants:

ScriptUIGraphics.BrushType.SOLID_COLOR
ScriptUIGraphics.BrushType.THEME_COLOR

ScriptUIFont Object¶

A helper object that encapsulates the qualities of a font used to draw text into a control. Create with the newFont() method of the ScriptUI class.

Used as a value of font.

Passed as an argument to drawString() and measureString().

ScriptUIFont Object Attributes¶

The object contains the following properties:

Property	Type	Description
`family`	String	The font family name.
`name`	String	The complete font name, consisting of the family and style, if specified.
`size`	Number	The font point size.
`style`	Object	The font style. One of these constants: `ScriptUI.FontStyle.REGULAR` `ScriptUI.FontStyle.BOLD` `ScriptUI.FontStyle.ITALIC` `ScriptUI.FontStyle.BOLDITALIC`
`substitute`	String	The name of a substitution font, a fallback font to substitute for this font if the requested font family or style is not available.

ScriptUIImage Object¶

A helper object that encapsulates a set of images that can be drawn into a control. Alternate versions of an image can reflect the state, such as a dimmed version for a disabled control.

An object of this type is created automatically when a script uses a pathname or File object to set the image property of an Image, IconButton, or ListItem object; the new object becomes the value of that property.

You can create this object explicitly using the newImage() method of the ScriptUI class. When you do this, you can specify alternate versions of the image to be used for different control states, such as enabled, disabled, and rollover.

This object is passed as an argument to drawImage().

ScriptUIImage Object Attributes¶

The object contains the following read-only properties:

Property	Type	Description
`format`	String	The image format. Scripts can define images in `JPEG` and `PNG` format. Applications can define images in the `resource` format.
`name`	String	The image name, either a file name or resource name.
`pathname`	String	The full path to the file that contains the image.
`size`	Dimension	A Dimension object that defines the size of the image in pixels.

ScriptUIPath Object¶

A helper object that encapsulates a drawing path for a figure to be drawn into a control. Create the object the newPath() method and define path segments with the moveto(), lineto(), rectPath(), and ellipsePath() methods of the ScriptUIGraphics object.

Used as a value of currentPath, where it is acted upon by closePath() and other methods.

Can be passed as an optional argument to fillPath() and strokePath() (which otherwise act upon the currentPath).

The class defines no properties or methods.

ScriptUIPen Object¶

A helper object that encapsulates the qualities of a pen used to stroke path segments in a control. Create with the newPen() method of the ScriptUIGraphics object.

Used as a value of foregroundColor and disabledForegroundColor.

Passed as an argument to drawString() and strokePath().

ScriptUIPen Object Attributes¶

The object contains the following properties:

Property	Type	Description
`color`	Array of Number	The paint color to use when the type is SOLID_COLOR. An array in the form [R, B, G, A] specifying the red, green, blue values of the color and the opacity (alpha channel) value as numbers in the range [0.0...1.0]. An opacity of 0 is fully transparent, and an opacity of 1 is fully opaque.
`lineWidth`	Number	The pixel width of the drawing line.
`theme`	String	The name of a color theme to use for drawing when the type is `THEME_COLOR`. Theme colors are defined by the host application.
`type`	Number	The pen type, one of these constants: `ScriptUIGraphics.PenType.SOLID_COLOR` `ScriptUIGraphics.PenType.THEME_COLOR`

Custom element class¶

Elements of the Custom class differ from typical UI elements in that they have no default appearance; the script which creates a custom element is responsible for drawing it by defining the element's onDraw event handler function. This allows scripts to create any appearance for custom elements that can be rendered via the drawing functions defined for a UI element's graphics object.

Custom elements have the same common properties that other types of control elements have (see Common properties). The different types of custom elements have additional properties.

The Custom element class has the following types of elements:

Element

Description

customBoundedValue

Can be used to implement controls whose 'value' can vary within minimum and maximum bounds, like the Progressbar, Slider, and Scrollbar. Has the same additional properties as those controls:

value
minvalue
maxvalue
shortcutKey

If the value property is changed, the control receives an onChange event notification, followed by an onDraw event notification, so the element can redraw itself with the changed state.

customButton

Can be used to implement various types of button controls, like the Button, IconButton with text, Checkbox, and so on. Additional properties are:

image
shortcutKey
text
value

customView

Has an image property that allows a script to define an image to display.

If no onDraw function is defined and the image property is set, the default appearance is simply the specified image, rendered centered in the bounds of the element.

A custom element's onDraw event handler function is not called when the mouse enters or leaves the screen region occupied by the element.

If you need to force a drawing update in such cases, you must call notify("onDraw") for the element, in response to a mouseOver or mouseout event for the element.

In the following example, the script forces a visual update for a customButton element when the mouse enters or leaves the button, by handling mouseover or mouseout events for the custom button:

var res =
"""palette {
    text:'Custom elements demo',
    properties:{ closeOnKey:'OSCmnd+W', resizeable:true },
    customBtn: Custom {
        type:'customButton',
        text:'Redraw original image'
    },
    customImageViewer: Custom {
        type:'customView',
        alignment:['fill','fill']
    }
}""";

var w = new Window (res);
w.customBtn.onDraw = drawButton;
w.customBtn.addEventListener ("mouseover", btnMouseEventHandler, false);
w.customBtn.addEventListener ("mouseout", btnMouseEventHandler, false);

// ...

function btnMouseEventHandler (event) {
    try {
        //
        Redraw the button on mouseover and mouseout
        event.target.notify("onDraw");
    } catch (e) {
        ...
    }
}

function drawButton (drawingState) {
    ...
}