reference:scripting_reference:scripting

Control

The Control object represents a control on a script dialog; it lets you read and modify a control's value (and contents). Use the Dialog.Control method to obtain a Control object.

Property Name	Return Type	Description
bg	string	Set or query the color used for the background (fill) of this control. This is in the format #RRGGBB (hexadecimal) or RRR,GGG,BBB (decimal). Currently only static text and list view controls are supported for this property.
charcase	string	For an edit control, gets or sets the control's case setting. Values are upper, lower and normal.
columns	DialogListColumns	For a list view control, returns a DialogListColumns object that lets you query or modify the columns in Details mode.
count	int	Returns the number of items contained in the control (e.g. in a combo box, list box or list view, returns the number of items in the list).
cuetext	string	Get or set the cue text of a single-line edit control. This is the text shown to help the user when the edit control is empty.
cx	int	Set or query the width of the control, in pixels.
cy	int	Set or query the height of the control, in pixels.
enabled	bool	Set or query the enabled state of the control. Returns True if the control is enabled, False if it's disabled. You can set this property to change the state.
fg	string	Set or query the color used for the text (foreground) of this control. This is in the format #RRGGBB (hexadecimal) or RRR,GGG,BBB (decimal). Currently only static text and list view controls are supported for this property.
focus	bool	Set or query the input focus state of the control. Returns True if the control currently has input focus, False if it doesn't. Set to True to give the control input focus.
image	string or object:Image	For a button or static control set to image mode, this assigns an image to the control. You can either provide a filename (or internal icon name - e.g. #about for the internal about icon), or an Image object that you obtained from the DOpus.LoadImage or Script.LoadImage methods.
label	string or object:Image	Set or query the control's label or title. Not all controls have labels - this will have no effect on controls (like the list view) that don't. Note that for combo box controls, this property is only valid for an editable combo - that is, one that you can type your own text into. You can use this property to set or query the current value of the editable text. For a static control set to "image" mode, you can also provide an Image object that you obtained from the DOpus.LoadImage or Script.LoadImage methods. This is the same as using the image property. For a tab control, you can set or query the labels of the individual tabs by specifying an index; e.g. Control.label(0) would reference the label of the first tab.
mode	string	For a list view control, lets you change or query the current view mode. Valid values are icon, details, smallicon, list.
readonly	bool	Set or query the read only state of an edit control.
redraw	bool	Set or query the redraw state of the control. Some controls let you turn off redrawing in order to make multiple changes without visible flicker (for example, adding a large number of items to a list view). Set to False to turn off redraw, or True to turn redraw back on after changing the control.
rotate	int	For a static text control set to "image" mode, you can set this property to rotate the displayed image. The value provided is the number of degrees from the image's initial orientation.
style	string	Set or query the font styles used to display this control's label. The string consists of zero or more characters; valid characters are b for bold and i for italics. Currently only static text controls are supported for this property.
textbg	string	Set or query the color used for the text background (fill) of this control. This is in the format #RRGGBB (hexadecimal) or RRR,GGG,BBB (decimal). Currently only list view controls are supported for this property.
title	string or object:Image	Alternative name for the label property. The term title is used in the dialog editor and XML resources, and can also be used here as a convenience.
type	string	Returns a string indicating the type of the control.
userdata	anything	Lets you associate a data value with the control. Opus makes no use of this value, it's only for your own use.
value	string or bool or int or DialogListItem or Vector or Date	Set or query the control's value. The meaning of this property depends on the type of the control: Edit control: Returns or accepts a string representing the current contents of the edit control. Check box: For a simple on/off check box, returns or accepts a bool - True for checked and False for unchecked. For a tri-state check box, returns or accepts an int - 0 for unchecked, 1 for checked and 2 for the indeterminate state. Radio button: Returns or accepts a bool - True for checked and False for unchecked. Tab: Returns or accepts an int indicating the currently selected page in the tab control. List box / combo box / list view: Returns or accepts a DialogListItem representing the selected item. When setting the value it also accepts an int representing the 0-based index of the selected item. Palette control: Returns the current color value. The color string is prefixed with a ! character if the palette button's checkbox is disabled. You can set the color this way as well. You can also set the value to "enable" or "disable" to change the checkbox state without affecting the color. Date/Time control: Returns a Date object if a valid date or time is chosen. If the "Show None" property is enabled and the control has been turned off, returns the string "none". Note that for a multiple-selection list box or list view, this value will return a Vector of DialogListItem objects, representing all currently selected items.
visible	bool	Set or query the visible state of the control. Returns True if the control is visible and False if it's hidden. You can set this property to hide or show the control.
x	int	Set or query the left (x) position of the control, in pixels.
y	int	Set or query the top (y) position of the control, in pixels.

Method Name

Arguments

Return Type

Description

AddGroup

<string:name>
<int:id>
[<string:flags>]

int

Adds a new group to a list view control. Items you add to the list can optionally be placed in groups. Each group must have a unique ID.

The optional flags are "c" (group is collapsible) and "d" (group starts out collapsed). E.g. AddGroup("Unimportant", 100, "cd") would add a group called Unimportant that is initially collapsed.

AddItem

<string:name>
[<int:value>]
[<int:groupid>]

int

Adds a new item to the control (list box, combo box or list view). The first parameter is the item's name, and the optional second parameter is a data value to associate with the item.

When adding to a grouped list view, the optional third parameter provides the ID of the group you want to add the item to (the second parameter must be provided in this case, and can be set to 0 if no value is required).

The item is added to the end of the list.

Instead of the name and value you can also pass a DialogListItem object obtained from another control. This will copy the name and value from the existing item, but won't copy its group (since the new list may have different groups). You can assign the new item to a group with the optional second parameter.

The return value indicates the position in the list of the new item.

If you are adding to a listview control and need to add an item with multiple columns, you can do it like this (JScript):

var i = listview.AddItem("This is col 1");
listview.GetItemAt(i).subitems(0) = "This is col 2";
listview.GetItemAt(i).subitems(1) = "This is col 3";

For a tab control, this lets you add back a tab that you've previously removed via the RemoveItem method. Only the name argument is used, which indicates the name of the child dialog to add back to the control.

AddText

<Map:text>

int

Adds a text string as an overlay on a static control in image mode (i.e. lets you overlay text on images).

The text parameter must be a Map object (created via the DOpusFactory.Map method, with the following member values to define the text. All values are optional.

text	The text to display
color	RGB string that specifies the text color
back	RGB string that specifies the background color, or "none" for transparent
shadow	RGB string that specifies the shadow color
x	x coordinate offset (relative to the anchor)
y	y coordinate offset (relative to the anchor)
anchor	anchor position; one of tl (top-left), tm (top-middle), tr (top-right), ml (middle-left), m (middle), mr (middle-right), bl (bottom-left), bm (bottom-middle), br (bottom-right)
font	font ID to specify the font to use; must have been previously added via Dialog.CreateFont
multiline	set to True to enable multiline text (line-break is a cr/lf character pair)
html	set to True to enable simple HTML markup
justify	specify text justification for multiline (not supported by html). One of l (left), r (right), m (middle).

This method returns a numeric ID for the text which lets you modify and remove it.

AutoSize

[<bool:height>]

bool

Autosizes the control, if the control type supports autosize. Returns True if the control was autosized.

If the optional height parameter is set to true, the control will be autosized vertically as well as horizontally.

DeselectItem

<int:position>

<object:item>

int

This method is mainly for use with multiple-selection list box and list view controls. It lets you deselect individual items in the control while leaving other items selected (or unaffected).

You can specify either the index of the item to select (0 means the first item, 1 means the second and so on) or a DialogListItem object obtained from the GetItemAt or GetItemByName methods.

You can also specify -1 to deselect all items in the list box.

EnableGroupView

<bool:enable>

none

Only applies to list view controls. By default group view is off; after adding groups with the AddGroup method, use EnableGroupView to turn group view on.

GetGroupById

<int:id>

DialogListGroup

Returns a DialogListGroup object representing the group with the specified ID that you've previous added to a list view control using the AddGroup method.

GetItemAt

<int:position>

DialogListItem
or <string>

Returns a DialogListItem object representing the item contained in the control at the specified index (list box, combo box or list view). Item 0 represents the first item in the list, item 1 the second, and so on. For a tab control, this returns the name of the dialog whose tab is at the specified index.

GetItemByLabel
GetItemByName

<string:name>

DialogListItem
or <int>

Returns a DialogListItem object representing the item contained in the control with the specified name (list box, combo box or list view). This method has two names (…Label and …Name) for historical reasons, you can use either method name interchangeably). For a tab control, this returns the index of the dialog within the tab.

InsertItemAt

<int:position>
<string:name>
[<int:value>]
[<int:groupid>]

<int:position>
<object:item>
[<int:groupid>]

int

Inserts a new item in the control (list box, combo box or list view). The first parameter is the position to insert the item at (0 means the beginning of the list, 1 means the second position and so on). The second parameter is the item's name, and the optional third parameter is a data value to associate with the item.

When adding to a grouped list view, the optional fourth parameter provides the ID of the group you want to add the item to (the third parameter must be provided in this case, and can be set to 0 if no value is required).

For a tab control, this lets you add back a tab that you've previously removed via the RemoveItem method. Only the position and name arguments are used. The name argument indicates the name of the child dialog to add back to the control.

The return value indicates the position in the list of the new item.

ModifyText

<Map:text>
<int:id>

none

Modifies an existing text element in a static control. The id argument indicates the text element to modify, this is returned by the AddText method. See the AddText method for a description of the text argument.

MoveItem

<int:position>
or
<object:item>
<int:newposition>

int

Moves an existing item to a new location (list box, combo box, list view or tab). The first parameter is the item to move (you can pass either its index or a DialogListItem object), and the second parameter is the new position the item should be moved to.

The return value indicates the position in the list of the moved item.

RemoveGroup

<int:id>

none

Removes the specified group from a list view control.

RemoveItem

<int:position>
or
<object:item>

none

Removes an item from the control (list box, combo box, list view or tab). You can provide either the index of the item to remove (0 means the first item, 1 means the second and so on) or a DialogListItem object obtained from the GetItemAt or GetItemByName methods.

You can also specify -1 to completely clear the contents of the control, removing all items at once.

RemoveText

<int:id>

none

Removes a text element from a static control. The id argument indicates the text element to remove, this is returned by the AddText method.

SelectItem

<int:position>
or
<object:item>
or
<string:tab>

int

Selects an item in the control. For a list box, combo box or list view, you can specify either the index of the item to select (0 means the first item, 1 means the second and so on) or a DialogListItem object obtained from the GetItemAt or GetItemByName methods.

For a multiple-selection list box or list view you can also specify -1 to select all items in the control.

For a tab control, you can change which page is visible by specifying the name of the page (i.e. the name of the child dialog) to show.

The return value indicates the new selected index.

SelectRange

<int:start>
<int:end>

object:Vector

Selects text within an edit control (or the edit field in a combo box control). The two parameters represent the start and end position of the desired selection. To select the entire contents, use 0 for the start and -1 for the end.

The return value is a Vector with two members that provide the current start and end of the selection. To query the range without changing it, simply call the SelectRange method with no arguments.

In a list box or list view control, this method selects a range of items.

SetFont

<int:id>

none

Sets the font used by the control to the specified font. The id parameter must have come from a previous call to Dialog.CreateFont. You can use 0 to reset the font to its default.

SetItemWidth

<int:width>

none

Sets the width in pixels of items in a list view control that's set to list or smallicon mode. Specify -1 to automatically size the items.

SetPos

<int:x>
<int:y>

none

Sets the position of this control. The x and y coordinates are specified in pixels.

SetPosAndSize

<int:x>
<int:y>
<int:cx>
<int:cy>

none

Sets the position and size of the control, in a single operation. All coordinates are specified in pixels.

SetSize

<int:cx>
<int:cy>

none

Sets the size of this control. The cx (width) and cy (height) values are specified in pixels.