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.

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
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.

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.

value

string or
bool or
int 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:

  • 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.
     

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>]

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.

You can also pass a DialogListItem object obtained from another control.
 

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>

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>

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
GetItemByName

<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>
<string:name>
[<int:value>]

[<int:groupid>]

or

 

<int:position>
<object:item>

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.
 

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

MoveItem

<int:position>
or
<object:item>

<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>
or
<object:item>

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
<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>

 

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>
<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.