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. |
columns |
object: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). |
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. |
label |
string or |
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. |
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 |
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. |
value |
string or object:DialogListItem or object:Vector |
Set or query the control's value. The meaning of this property depends on the type of the control:
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 |
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: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. 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"; |
DeselectItem |
<int:position> |
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> |
object: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> |
object:DialogListItem |
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. |
GetItemByLabel |
<string:name> |
object:DialogListItem |
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). |
InsertItemAt |
<int:position> [<int:groupid>]
<int:position> |
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).
The return value indicates the position in the list of the new item. |
MoveItem |
<int:position> <int:newposition> |
int |
Moves an existing item to a new location (list box, combo box or list view). 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> |
none |
Removes an item from the control (list box, combo box or list view). 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. |
SelectItem |
<int:position> 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>
or
<object:item1> <object:item2> |
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. |
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> |
none |
Sets the position of this control. The x and y coordinates are specified in pixels. |
SetPosAndSize |
<int:x> |
none |
Sets the position and size of the control, in a single operation. All coordinates are specified in pixels. |
SetSize |
<int:cx> |
none |
Sets the size of this control. The cx (width) and cy (height) values are specified in pixels. |