DCX Treeview - Dialog Control Xtension DLL v3.1 by ClickHeRe, twig* & Ook

Home | Download | Forum | Bug Tracker

v3.1

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.
custom	Enable custom drawing code. (this allows mirc ctrl codes in text)
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:

Format	N N N ... N
Example	1 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:

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, or to select the last branch of a given sub-path.

Example

-1 -1

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

Note: Some commands will allow for special path items. Read the notes to make sure what the special paths are. (ie. root and 0)

/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. Use 0 to insert an item at the very top of the branch. 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. Use 0 for ICON, SICON and OVERLAY to display no icon. If you do not wish to modify ICON or SICON, use a value of -1.

/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

Note. Due to the current implementation of this feature, you cannot move an item into into its subbranch.

/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

Note. Due to the current implementation of this feature, you cannot copy an item into into its subbranch.

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

Note. You can use root as the path with the +a or +z switches.

/xdid -u
This command clears any selection.
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. Use -1 for INDEX to load all icons in 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 -A
This command lets you set a property on a specific item.
Syntax:	/xdid -A [DNAME] [ID] [PATH] [TAB] [+FLAGS] [INFO]
Example:	/xdid -A dcx 4 4 2 2 $chr(9) +M Marked text here
Parameters:
+FLAGS	Property flags.
M	Marked text property. Much like /xdid -M, this can be used to define custom data but on a per item basis.
INFO	The information to set. The usage of this parameter depends on the flags specified in FLAGS.

/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.
E	Matchtext is an exact match.
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. If T is W or R, you need to escape special characters with a \ (use \ to match a single \).

$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().markeditem
This property lets you retreive the marked (see /xdid -A +M) text for the treeview item specified.
Syntax:	$xdid(dialog, ID, [ITEMPATH]).markeditem
Example:	$xdid(dcx, 4, 1 2).markeditem

$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
Return	noedit 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.
Return	noedit 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.