DCX - Dialog Control Xtension
v1.4.0
Treeview
This control enables you to create a treeview.

Control Styles
These control styles are available when creating a Treeview control. Remember that the general styles disabled, group, hidden, notheme, tabstop and transparent apply to all DCX controls except the embedded Dialog and Window controls.
alpha Control is alpha blended.
autohscroll Remove the horizontal scrollbar and auto-scroll depending on mouse position. (Vista)
balloon The treeview and treeview item tooltips will use the balloon style.
checkbox Enables Checkbox support in the treeview.
doublebuffer Specifies how the background is erased or filled. (Vista)
editlabel Makes the treeview items editable.
fadebuttons Fade expand buttons in or out when the mouse moves away or into a state of hovering over the control. (Vista)
fullrow Selection highlight is the full row of the item. Cannot be used with haslines.
hasbuttons Enables ± buttons on the side of items containing child items for expand/collapse operations.
haslines Items are linked with lines.
linesatroot Enables lines to be connected to the root item (needs the haslines style to work).
nohscroll Disables horizontal scrolling in the treeview.
noident Does not indent the tree view for the expand buttons. (Vista)
noscroll Disables scrolling in the treeview.
notooltips Disables tooltip popup on items.
richtooltip Allow rich tooltips in the tree view (custom drawn with icon and text). (Vista)
showsel Selection is always visible, even when control loses focus.
singleexpand Causes the item being selected to expand and the item being unselected to collapse upon selection in the tree view. If the user holds down the CTRL key while selecting an item, the item being unselected will not be collapsed.

TreeView Item Path
The treeview control has an engine that parses the given item "path" data to know where to insert/delete/modify a given item in the control. The parameters you supply are a space separated numerical token list of the treeview branches that lead to the item position:

FormatN N N ... N
Example1 2 3

This position represents the 3rd child branch of the 2nd child branch of the first branch as shown by the selected item in the picture below:

Treeview Branches

You can also use the value -1 for any of the values to indicate the parser that you want to insert the item at the end of the branch (if used as the last path number) or to select the last branch of a given sub-path (if not used as last path number).

Example-1 -1
This would add the item at the end of the last branch in the first column of branches.

Note: If you specify a path that does not exist the engin will reverse to the last valid path encoutered during parsing.
/xdid flags
Control commands are input to the control with the /xdid command.
/xdid -a
This command lets you add an item to the treeview.
Syntax:
/xdid -a [DNAME] [ID] [PATH] [TAB] [+FLAGS] [ICON] [SICON] [OVERLAY] [STATE] [INTEGRAL] [COLOR] [BGCOLOR] (TEXT) [TAB] (Tooltip Text)
Example:
/xdid -a dcx 4 $+(-1 2 4,$chr(9),+bc 1 1 0 0 0 $rgb(0,0,255) $rgb(255,0,255) Item Text,$chr(9),Tooltip)
Parameters:
+FLAGS Item flags.
b Item text is bold.
c Item text is colored (COLOR is the text color).
g Background is colored (BGCOLOR is the background color).
H Allows you to load an item from a hash table by name. Cannot be used with +n
e Item is expanded.
i The item is italic.
n Allows you to load an item from a hash table by index. Cannot be used with +h
s Item appears selected.
u Item text is underlined.
x Adds items from DCXML file, where TEXT is [XML_DATASET] [FILENAME]. Refer to note for additional information on the DCXML format.
ICON Icon index number from the normal icon list.
SICON Selected Icon index number from the normal icon list.
OVERLAY Icon index number from the normal icon list that was marked as an overlay icon.
STATE Icon index number from the state icon list.
0 No check.
1 Unchecked.
2 Checked
INTEGRAL Multiple of the regular treeview item height.
COLOR Item text color of the treeview item in $rgb() format. (Needs to add flag +c to work)
BGCOLOR Background color of the treeview item in $rgb() format. (Needs to add flag +g to work)
TEXT The text to display on the item.
If used with +h or +n +FLAGS, then this is either HASHTABLE ITEM or HASHTABLE INDEX respectively.
 
Note.
  • You can use 0 for the #ICON, #SICON, and #OVERLAY values if you wish to use no icon.
  • You need to use checkbox style in order to use checkboxes in the treeview.
  • INTEGRAL is calculated in this manner.
    0 = normal height,
    1 = twice the height,
    2 = 3X height, etc.

/xdid -c
This command lets you select a treeview item.
Syntax:
/xdid -c [DNAME] [ID] [PATH]
Example:
/xdid -c dcx 4 1 3 5

/xdid -d
This command lets you delete a treeview item (and it's sub-items if any).
Syntax:
/xdid -d [DNAME] [ID] [PATH]
Example:
/xdid -d dcx 4 1 3 5

/xdid -g
This command lets you set the treeview item height (in pixels).
Syntax:
/xdid -g [DNAME] [ID] [HEIGHT]
Example:
/xdid -g dcx 4 15
 
Note. You can use the value -1 to reset to the default height.

/xdid -i
This command lets you change treeview colors.
Syntax:
/xdid -i [DNAME] [ID] [+FLAGS] [COLOR]
Example:
/xdid -i dcx 4 +b $rgb(0,255,0)
Parameters:
+FLAGS Color flags.
b Background color.
l Line color.
s Selection background color.
t Text color.
COLOR Color in $rgb() format.
 
Note. Use -1 to revert to default color.

/xdid -j
This command lets you change the icon, selected icon and overlay icon for a treeview item.
Syntax:
/xdid -j [DNAME] [ID] [PATH] [TAB] [ICON] [SICON] (OVERLAY)
Example:
/xdid -j dcx 4 1 2 $chr(9) 3 3
/xdid -j dcx 4 2 $chr(9) -1 -1 2
 
Note.

/xdid -k
This command lets you change the check state on a treeview item.
Syntax:
/xdid -k [DNAME] [ID] [STATE] [PATH]
Example:
/xdid -k dcx 4 2 1 3 5
Parameters:
STATE Check State
0 No check.
1 Unchecked.
2 Checked
COLOR Color in $rgb() format.
 
Note. If you are not using the checkbox style, this function can also change the state icon of an item. Be sure to insert the state icons before you use them.

/xdid -l
This command lets you change the size of the treeview icons.
Syntax:
/xdid -l [DNAME] [ID] [SIZE]
Example:
/xdid -l dcx 4 24
 
Note.
  • You need to use this command before adding icons to a treeview.
  • Values can be 16 (default), 24, or 32.

/xdid -m
This command lets you move a treeview item and its sub-items. The first path is the item to be moved to the second path.
Syntax:
/xdid -m [DNAME] [ID] [PATH1] {TAB} [PATH2]
Example:
/xdid -m dcx 4 1 2 $chr(9) 1

/xdid -n
This command lets you copy a treeview item and its sub-items. The first path is the item to be copied to the second path.
Syntax:
/xdid -n [DNAME] [ID] [PATH1] {TAB} [PATH2]
Example:
/xdid -n dcx 4 1 2 $chr(9) 1

/xdid -o
This command lets you change the tooltip text of a treeview item.
Syntax:
/xdid -o [DNAME] [ID] [PATH] [TAB] (TipText)
Example:
/xdid -o dcx 4 1 2 $chr(9) Blah

/xdid -r
This command lets you clear all the treeview items.
Syntax:
/xdid -r [DNAME] [ID]
Example:
/xdid -r dcx 4

/xdid -t
This command lets you toggle/expand/collapse treeview items. You can use root as the path with the +a and +z switches.
Syntax:
/xdid -t [DNAME] [ID] [+FLAGS] [PATH]
Example:
/xdid -t dcx 4 +a root
Parameters:
+FLAGS Toggle flags.
a Expands the branch and all sub-branches.
c Collapses the branch.
e Expands the branch.
p Expands partially the branch.
r Collapses and deletes the branches children.
t Toggles opposite action on branch.
z Collapses the branch and all sub-branches.

/xdid -u
This command makes the currently selected treeview item unselected.
Syntax:
/xdid -u [DNAME] [ID]
Example:
/xdid -u dcx 4

/xdid -v
This command lets you change the text of a treeview item.
Syntax:
/xdid -v [DNAME] [ID] [PATH] [TAB] (ItemText)
Example:
/xdid -v dcx 4 1 2 $chr(9) Blah

/xdid -w
This command lets you add an icon to the treeview image lists.
Syntax:
/xdid -w [DNAME] [ID] [+FLAGS] [INDEX] [FILENAME]
Example:
/xdid -w dcx 4 +n 113 shell32.dll
/xdid -w dcx 4 +no2 29 shell32.dll
Parameters:
+FLAGS Image list flags.
n Normal icon list.
s State icon list.
o Overlay icon list. The overlay index is declared immediately after the +o flag. Must be used with +n.
a Uses the icon associated with the given file (as shown in Windows Explorer).
Note: File must exist.
f Uses the icon associated with the given filetype.
Note: Filename is the extension (eg. BMP, PNG, AVI, etc).
g Convert to grayscale icon.
P If GDI+ is enabled, this will use GDI+ to extract the icon.
INDEX Icon index in icon archive
FILENAME Icon archive filename
 
Note.
  • Use 0 for INDEX if the file is a single icon file.
  • For readability and ease of indexing, it is suggested you declare your overlay icons AFTER the normal icons. Overlay icons are also added to the normal icon list, so it will mess up your existing icon indexes.
  • There is a limit of 15 overlay icons you may use, indexes from 1 to 15.

/xdid -y
This command lets you clear the treeview image lists.
Syntax:
/xdid -y [DNAME] [ID] [+FLAGS]
Example:
/xdid -y dcx 4 +ns
Parameters:
+FLAGS Image list flags
n Normal icon list.
s State icon list.

/xdid -z
This command lets you sort the data in the treeview control.
Syntax:
/xdid -z [DNAME] [ID] [+FLAGS] [PATH] [TAB] (ALIAS)
Example:
/xdid -z dcx 4 +tab root $chr(9) tvsort
Parameters:
+FLAGS Sort flags.
a Ascendant order sorting. (Default)
b Sorts only the given branch.
c Custom sorting provided by ALIAS.
d Descendant order sorting.
n Numerical sorting.
r Sorts recursively all sub-branches.
s Case-sensitive sorting. (With Alpha-numeric)
t Alpha-numeric sorting. (Default)
ALIAS Alias name to be called in the case of custom sorting.
 
Note.
  • ALIAS is not needed if not using a custom sorting algorithm.
  • When using +c, sorted values given by $1 and $2 into ALIAS.
  • The custom alias must return the following values for the comparison of custom values. The ascendant or descendant order is managed by the DLL with the given values returned.
    $1 < $2 return -1
    $1 > $2 return 1
    $1 == $2 return 0

/xdid -B
This command lets you force label editing on a treeview item.
Syntax:
/xdid -B [DNAME] [ID] [PATH]
Example:
/xdid -B dcx 4 1 3 5

/xdid -G
This command lets you set the treeview background image.
Syntax:
/xdid -G [DNAME] [ID] [+FLAGS] [X] [Y] [FILENAME]
Example:
/xdid -G dcx 4 +r 0 0 treeview_bg.bmp
Parameters:
+FLAGS Background flags.
a Anti-alias image.
b Image alpha blending.
h High quality rendering.
t Tile image.
r Resize image to match control area.
X X position image offset.
Y Y position image offset.

/xdid -Q
This command lets you change the font styles and color on a treeview item.
Syntax:
/xdid -Q [DNAME] [ID] [+FLAGS] [COLOR] [PATH]
Example:
/xdid -Q dcx 4 +bcu $rgb(128,0,255) 1 2
Parameters:
+FLAGS Check State
b Item text is bold.
u Item text is underlined.
c Item text is colored. (COLOR is the text color).
i The item is italic.
COLOR Item text color of the treeview item in $rgb() format. (Needs to add flag +c to work)
 
Note. Use -1 as COLOR value if you omit the +c switch.

/xdid -S
This command saves the contents specified by the range within the treeview into a file.
Syntax:
/xdid -S [DNAME] [ID] [N (N ...)] [TAB] [+FLAGS] [XML_DATASET] [FILENAME]
Example:
/xdid -S dcx 4 1 3 $chr(9) + setup_tv config.xml
Parameters:
N (N ...) Range of items to save.
+FLAGS This is required but not used.

$xdid() Properties
The $xdid identifier is a given mIRC alias that communicates with the DCX DLL to extract information in DCX controls.
$xdid().expand
This property lets you retreive whether a treeview item is expanded or not.
Syntax:
$xdid(dialog, ID, [ITEMPATH]).expand
Example:
$xdid(dcx, 4, 1 2).expand

$xdid().find
This property lets you retreive a treeview Item Path that leads to the Nth found treeview item matching the input search patern. If N is 0, returns the total number of matching items. SUBPATH is an optional parameter to start the search at a desired branch.
Syntax:
$xdid(dialog, ID, [TAB]Matchtext[TAB], T, N, SUBPATH).find
Example:
$xdid(dcx, 4, $chr(9) $+ hello * $+ $chr(9), W, 0, 1 2).find
Parameters:
MATCHTEXT String composed of wildcards or regex paterns used for the search.
T Value indicating if the search is using a regex patern or wildcard string.
W Matchtext is a wildcard string.
R Matchtext is a regex patern.
N Parameter indicating to return the Nth match.
SUBPATH Optional parameter to start the search at a specific branch.
 
Note.
  • If N is 0, returns the total number of matching items.
  • The [TAB] characters surrounding the matchtext are mandatory or else it wont work.
  • If SUBPATH is blank, searches at root of treeview.

$xdid().icon
This property lets you retreive the treeview item icon.
Syntax:
$xdid(dialog, ID, [ITEMPATH]).icon
Example:
$xdid(dcx, 4, 1 2).icon

$xdid().mouseitem
This property lets you retreive the treeview Item Path over which the mouse pointer is hovering over.
Syntax:
$xdid(dialog, ID).mouseitem
Example:
$xdid(dcx, 4).mouseitem
 
Note. Returns 0 if mouse is not over any item.

$xdid().num
This property lets you retreive the number of child items of a treeview item. You can use the value root as ITEMPATH to get the number of childs of the root item.
Syntax:
$xdid(dialog, ID, [ITEMPATH]).num
Example:
$xdid(dcx, 4, 1 2).num

$xdid().selpath
This property lets you retreive the Item Path that leads to the selected item in the treeview.
Syntax:
$xdid(dialog, ID).selpath
Example:
$xdid(dcx, 4).selpath

$xdid().seltext
This property lets you retreive the selected treeview item text.
Syntax:
$xdid(dialog, ID).seltext
Example:
$xdid(dcx, 4).seltext

$xdid().state
This property lets you retreive the check item state of an item.
Syntax:
$xdid(dialog, ID, [ITEMPATH]).state
Example:
$xdid(dcx, 4, 1 2).state
 
Note. If you are not using the checkbox style, the value returned is the state icon value. Otherwise, returns 2 (checked), 1 (unchecked), or 0 (no check).

$xdid().text
This property lets you retreive a treeview item text.
Syntax:
$xdid(dialog, ID, PATH).text
Example:
$xdid(dcx, 4, 1 2).text

$xdid().tooltip
This property lets you retreive the treeview item tooltip.
Syntax:
$xdid(dialog, ID, [ITEMPATH]).tooltip
Example:
$xdid(dcx, 4, 1 2).tooltip

Treeview Events
These events are fired when activity occurs in the Treeview control.
buttonclick
When a ± button is clicked.
Syntax:
/cb_alias DNAME buttonclick ID PATH
Example:
/cb_alias dcx buttonclick 4 4 2
Parameters:
PATH Path leading to the item that had his ± button clicked.

collapse
When a branch is collapsed.
Syntax:
/cb_alias DNAME collapse ID PATH
Example:
/cb_alias dcx collapse 4 4 2
Parameters:
PATH Path leading to the item that was collapsed.

dclick
When an item is double clicked.
Syntax:
/cb_alias DNAME dclick ID PATH
Example:
/cb_alias dcx dclick 4 4 2
Parameters:
PATH Path leading to the item that triggered the event.
 
Note. You cant use $xdid().tvseltext to get item text, you need to use $xdid().tvtext with item path given.

expand
When a branch is expanded.
Syntax:
/cb_alias DNAME expand ID PATH
Example:
/cb_alias dcx expand 4 4 2
Parameters:
PATH Path leading to the item that was expanded.

help
Launched when you click on a control using the ? contexthelp button.
Syntax:
/cb_alias DNAME help ID
Example:
/cb_alias dcx help 4

labelbegin
When item text label editing begins.
Syntax:
/cb_alias DNAME labelbegin ID
Example:
/cb_alias dcx labelbegin 4
Returnnoedit to block label editing.
 
Note. Use $xdid().selpath to determine which path is being edited.

labelcancel
When the user presses ESC while editing or clicks somewhere else without editing the text.
Syntax:
/cb_alias DNAME labelcancel ID
Example:
/cb_alias dcx labelcancel 4

labelend
When the user clicks elsewhere or presses RETURN while editing or clicks somewhere else but edited the text.
Syntax:
/cb_alias DNAME labelend ID VALUE
Example:
/cb_alias dcx labelend 4 New Item Text
Parameters:
VALUE Edited text label.
Returnnoedit to cancel label editing (for example if string is NULL or invalid to your application).
 
Note. Use $xdid().selpath to determine which path is being edited.

rclick
When the treeview is right clicked.
Syntax:
/cb_alias DNAME rclick ID PATH
Example:
/cb_alias dcx rclick 4 4 2
Parameters:
PATH Path leading to the item that triggered the event.
 
Note.
  • You cant use $xdid().tvseltext to get item text, you need to use $xdid().tvtext with item path given.
  • This event does not require an item to be clicked on to be triggered. If no item was right clicked, no path is returned.

sclick
When an item is single clicked.
Syntax:
/cb_alias DNAME sclick ID PATH
Example:
/cb_alias dcx sclick 4 1 4 2
Parameters:
PATH Path leading to the item that triggered the event.
 
Note. You cant use $xdid().tvseltext to get item text, you need to use $xdid().tvtext with item path given.

selchange
When the selected item changes.
Syntax:
/cb_alias DNAME selchange ID PATH
Example:
/cb_alias dcx selchange 4 4 2
Parameters:
PATH Path leading to the item which triggered the event.

stateclick
When a checkbox is clicked.
Syntax:
/cb_alias DNAME stateclick ID STATE PATH
Example:
/cb_alias dcx stateclick 4 1 4 2
Parameters:
STATE New item check state (checkbox style) or state icon value.
PATH Path leading to the item that triggered the event.

Contact 2005-2007 Last Updated: 25th December, 07

Valid XHTML 1.0 Transitional Valid CSS!