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 |
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 |
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 |
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 |
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 |
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> or <object:item> |
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.
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> or <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> |
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 |
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 |
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> or <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). 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 third parameter. 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> |
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> |
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> |
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> |
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: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> |
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. |