Introduction
go to top
DCXML is a way to make the creation and managing of dialogs more easy. Everything in DCX has to do with hierarchy:
- Child controls of container controls:
Having to manage and keep track of what control is a child control is quite a task even for the most seasoned DCX user, however it's a totally essential skill to master if you want to take full advantage of DCX's awesome possibilities.
- Cell layout algorithm:
On top of keeping track of all those ID's flying around if you really want to create full fletched dialogs that take advantage of CLA you'll have to keep track of an hierarchy that's not physical at all. For instance you can create virtual panes to display 1 or more controls. These visual panes only exist within the CLA's hierarchy.
Confused yet? Don't worry a lot of people are, that's probably why CLA and DCX in general right now only has a select group of people that truly understand how to fully take advantage of how to create proper DCX dialogs.
This is where DCXML steps in. DCXML is a term for a way to describe how dialogs should look and act in XML. For those of you familiar with HTML it's almost the same principle. DCXML can be best viewed as a wrapper for all those /xdialog and /xdid calls you otherwise had to do in the on dialog init event. DCXML handles creation of controls and where/how they are positioned by automatically applying CLA.
In short: DCXML seperates design from code. Code in mIRC, design in DCXML.
Getting Started go to top
DCXML should only be used with DCX 1.4 and higher, DCXML is defined in a seperate file and not within your script. You load DCXML by calling the dcxml file in the on init event of the dialog.
example:
dialog mydialog {
size 200 200 200 200
}
on *:dialog:mydialog:init:*:{
dcx Mark $dname events
;dcxml -d [DNAME] [Name of dialog element you wish to load] [path to dcxml file]
dcxml -d $dname mydialog $qt($scriptdirdc.xml)
}
alias events {
;mydialog event handling goes here
}
alias dcxt dialog -m mydialog mydialog
Although it might be easier to use the following if your familiar with dialog tables:
alias dcxml.spawn dialog -m dcx. $+ $1 dcx
dialog dcx {
size 0 0 0 0
}
on *:dialog:dcx.*:init:*:{
tokenize 46 $dname
dcx Mark $dname $2 $+ .events
dcxml -d $dname $2 $qt($scriptdirdc.xml)
}
alias mydialog.events {
;mydialog event handling goes here
}
alias myotherdialog.events {
;mydialog event handling goes here
}
/dcxml.spawn [dialog name as defined in the dcxml file]
You can specify width height and caption of the dialog instance in DCXML so you only really need 1 dialog declaration in your mIRC script.
Some things you should know about XML go to top
XML is built up using what is call Nodes, there are several Nodes but these are the ones you should know about because I will address them in this documentation.
- Document Node :
In XML there is one single element that has all the other elements in it. The highest in the hierarchy as it were. Much like in HTML where <html> contains the entire page including <head> and <body>
- Element Node
Think of an element Node as a way to describe something. For instance: <element></element> is a way to define an element, this element can have other elements inside of it like so
<element1> <element2> </element2> </element1> You can also define an element that has nothing inside of it like so:
<element />
- Attribute Node
An attribute is a property you can set on an element like so:
<element attribute="value"></element> or
<element attribute="value" />
- Text Node
Text Node is text inside an element:
<element attribute="value">
This text is considered a Text Node
</element>
- Comment Node A Comment Node is an element that is not part of the hierarchy and is only there to place a comment of some sort. <!--- This is a comment -->
So an XML file always looks like this or any variation thereof:
<documentNode>
<element1 attribute="value1">
<element2 />
</element1>
<element1 attribute="value2">
<element2 />
</element1>
</documentNode>
DCXML markup rules go to top
The beauty of XML lies in the fact that you can freely name all your elements and attributes to suit your situation. However as the name DCXML implies it differs from XML a bit. The only difference is that we've already defined all the Elements and Attributes that the parser understands. Much like XHTML has defined <h1> to be a header and <hr> to be a horizontal ruler DCXML has defined <control> to be a control for instance.
A DCXML file always starts with this:
<dialogs>
...
</dialogs>
Which will make more sense later, a DCXML file describes one or more dialogs. It (hopefully) won't be a surprise the next step is as followed:
<dialogs>
<dialog>
...
</dialog>
</dialogs>
As you can see we are defining 1 dialog in this DCXML file now, you'll HAVE to give dialog elements a name attribute to distinguish between them the reason why becomes apparent when you define multiple dialogs. note: this value of name doesn't have to equal $dname.
<dialogs>
<dialog name="mydialog">
...
</dialog>
<dialog name="myotherdialog">
...
</dialog>
</dialogs>
This is the basic setup of a DCXML file which is pretty straightforward. Now it's up to you to define your dialogs within the dialog elements! How? Keep on reading!
Insert and layout dcx controls go to top
Forget what you know about creating dialogs! No more painstaikingly aligning controls to just the right x or h, no more calculating
control sizes for resizeable dialogs, no more keeping track of ID's, never again trace your xdialog and xdid's to what they're exactly doing! DCXML handles all of this.
ok so lets take it a step at a time shall we?
No more ID's?
Thats right, only id those controls you are going to work with the rest will be assigned an id (2000+number of parsed controls so avoid control id's >= 2000)
<control type="panel">
<control type="text">
</control>
This will create a text control on a panel without having to remember the id of the pane to insert the text inside it. There is no limitation
to how deep you can nest controls. This makes creating complex control structures a breeze.
<control type="panel">
<control type="check" id="2">
<control type="text">
<control />
ID only those controls you are planning to script with in mIRC.
No more XYWH!
DCXML will place and size controls for you, you just tell DCXML that something should be smaller or bigger.
<dialog name="somedialog">
<control type="panel" cascade="h">
<control type="check" id="2" />
<control type="text"/>
</control>
</dialog>
In this example the panel will take all the available space on the dialog because its the only child of the dialog. Inside
the panel the check and text will take 50% of the space inside the panel because 100% space devided by 2 controls that want to take
it is 50%. The controls will appear next to eachother due to the cascade attribute on the panel ( see cascade attribute ).
All very handy but what if you want the text to take only 25% of the available space ? Is that possible ? Yes it is !
<dialog name="somedialog">
<control type="panel" cascade="h">
<control type="check" id="2" weight="3"/>
<control type="text" weight="1"/>
</control>
</dialog>
As you noticed we've added an attribute called weight this hints the parser how to size the controls inside the pane.
The space inside the panel is 100% we already know this, of this space the check wants to take 3 parts and the text
wants to take 1 part. So to give them both what they
want 3+1 has to equal 100%. So 4 equals 100% and the check takes 3/4th so 75% and the text takes 1/4th or 25%.
To check if you understood weights have a look at this DCXML and think for yourself how much space the check and text take inside
the panel
<dialog name="somedialog">
<control type="panel" weight="3">
<control type="check" id="2" cascade="h" weight="10"/>
<control type="text" weight="5"/>
</control>
</dialog>
If you thought that the check takes 2/3rd (10/15th) and the text 1/3rd (5/15th) you know your stuff! Finally lets take a look another
case:
<dialog name="somedialog">
<control type="panel" cascade="h" weigth="9">
<control type="check" id="2" weight="10"/>
<control type="text" weight="5"/>
</control>
<control type="panel" cascade="h" weigth="10">
<control type="check" id="2" weight="10"/>
<control type="text" weight="5"/>
</control>
</dialog>
Here there's 2 panels on the dialog, they will not be placed next to eachother but they will be stacked vertically. This because there
is no cascade attribute set on the dialog element and stacking vertically is the default behaviour. The top panel
will take 9/19th of the space on the dialog and the bottom one 10/19th.
Ok so hopefully by now you grasp how you can manipulate the layout by modifying the weight and cascade attributes. But what if you dont want a control to size
vertically, horizontally or both ? and what if you want to specify a width/height in pixels ?
All you have to do is either specify the height and/or width:
<dialog name="somedialog">
<control type="panel" cascade="h" height="120">
<control type="check" id="2" width="20"/>
<control type="text" />
</control>
<control type="panel" cascade="h" weigth="1">
<control type="check" id="2" heigth="20" width="20"/>
<control type="text" weight="5"/>
</control>
</dialog>
In this example the top panel is 120px in height, this control will not size vertically when resized but WILL resize horizontally. The 2nd panel will take the remaining space.
The check inside the first panel is 20px wide and will not resize in width but will in height. The check inside the 2nd panel is 20px wide and 20px high and will never resize.
The power of pane go to top
A very powerful element to help you layout your dialog the way you want is the <pane>
A pane can be best viewed as a panel control without actually creating a control on the dialog.
<dialog name="somedialog">
<pane cascade="h" weight="3">
<control type="check" id="2" width="20"/>
<control type="text" />
</pane>
<pane cascade="h" weight="1">
<control type="check" id="2" heigth="20" width="20"/>
<control type="text" weight="5"/>
</pane>
</dialog>
This is the same as using a panel control in the above section but no control is actually created a <pane> virtually groups controls so is performence wise best to use. Of course <pane> doesn't replace a panel control as you can't style a pane.
Note: a <pane> cannot have a fixed width or heigth!
Cascading Control Styles
go to top
One of the major benefits of using DCXML is that you can define a multiple controls styles in one easy definition. You can style per ID, Class & Type. On top of that you can set global and local style definitions.
Style definitions are grouped in the <styles> element. This <styles> element can be a child of <dialogs> which will effect ALL dialogs or <dialog> to only style a certain dialog. You can also style directly on the <control>.
<dialogs>
<styles>
<style type="text" fontname="Trebuchet MS"/>
</styles>
<dialog>
<styles>
<style type="text" fontname="Tahoma" />
</styles>
<control type="text" fontname="Verdana">
This text is in Verdana
</control>
...
In the above example the text control will appear in Verdana because the most explicit style will always be applied.
If we remove the fontname attribute on the control the text will be in Tahoma because that's more explicit then the definition in the global styles definition.
<dialogs>
<styles>
<style type="text" fontname="Trebuchet MS" />
<style class="TahomaText" fontname="Tahoma" />
<style id="10" fontname="Verdana" />
</styles>
<dialog>
<control class="TahomaText" type="text" id="10">
This text is in Verdana
</control>
...
In the above example the text will be in Verdana because id is more explicit then class and text.
The exact order of precedence is: id, class, type. If DCXML can't match id it will try to match class and then match on type.
In addition to <style> there's also an <all> element which is the exact same but will apply to every control on the dialog(s). Note: This element has the lowest precedence and will only be applied if DCXML cant match on id, class or text.
Cascading Icon Definitions go to top
Icon libraries for controls are applied in a similar way as style definitions.
<dialogs>
<icons>
<icon type="treeview" indexmax="40" src="$_scriptdir $+ controls.icl" />
<icon class="Pastel" indexmax="40" src="$_scriptdir $+ pastel.icl" />
<icon id="10" index="20" src="$_scriptdir $+ pastel.icl" />
<icon type="listview" indexmax="40" src="$_scriptdir $+ controls.icl" />
</icons>
..
Like styles icons can appear as child of <dialogs> and <dialog>.
DCXML will first try to match in the <dialog> icons definition. When unsuccessful it will parse the <dialogs> icons definition.
Use the index attribute if you want to load up a single icon, for multiple icons you can use indexmin and indexmax. DCXML will loop from indexmin and indexmax and load up those icons. Indexmin and indexmax default to zero and min has to be smaller then max.
Templating
go to top
DCXML allows you to template dialog elements you use really often like alot of your dialogs will have a header of some sort, to prevent you from defining the header
everytime you create a new dialog you can template it.
<dcxml>
<dialogs>
<templates>
<template name="header">
<control type="panel" cascade="h" height="70">
<control width="253" height="70" type="image" eval="1" src="$+($_scriptdir,dcx.jpg)" />
<control width="547" height="70" type="image" eval="1" src="$+($_scriptdir,top_bg.jpg)" />
<control type="panel" bgcolour="16318463" />
</control>
</template>
</templates>
<dialog name="somedialog">
<calltemplate name="header" />
<control type="panel">
...
<template> can only be defined in the <templates> section of <dialogs>. You call a template using the <calltemplate> element.
calltemplate can not have any children but can be called as many times as you like.
Here's another use for templates
<template name="OkCancel">
<control type="panel" styles="vgradient" cascade="h" margin="0 5 0 5" height="35">
<pane cascade="v" weight="1" />
<control type="button" styles="vgradient" eval="1" id="1" bgcolour="$rgb(255,255,255)"
caption="Cancel" width="100" height="25" />
<control type="button" caption="Ok" id="2" width="100" height="25" />
</control>
</template>
This will define Ok and Cancel button's that are always right alligned on the dialog and will resize properly. The Cancel button has id 1 and OK button 2. Now
all you need to do to add this to a dialog is
<calltemplate name="OkCancel" />
Element Reference
go to top
There are only a few different Elements in DCXML, this is to hopefully keep the markup simple.
Another big reason a treeview for instance is created like this:
<control type="treeview" />
instead of
<treeview />
is because this way dcx can grow without having to add new dcxml elements each time a new control is made.
An element can not just exist anywhere you like, here's a complete list of elements and where they may be placed:
if they have dialog listed as parent node but not icons that means that you can't specify the element inside an icons element.
If you do so it will be ignored
Attribute Reference
go to top
| eval |
|---|
| Applies to: |
every element |
| Description: |
Specifies wheter to evaluate identifiers in the attributes and textNode of the element. Please note when set the DCXML parser will send the command to mIRC and then recieve it back in DCX this is slightly slower then normal because when this attribute is not set the DCXML parser calls the appropiate function internally. |
| Default value: |
not applicable. |
| Valid values: |
as soon as this attribute is set it will evaluate identifiers. so eval="" is enough to make it evaluate. |
| Example: |
<control type="text" eval="1" caption="$me" /> |
| w & h |
|---|
| Applies to: |
<dialog> |
| Description: |
Sets the width or height of the dialog |
| Default value: |
not applicable. |
| Valid values: |
|
| Example: |
<dialog w="200" h="400" > |
| center |
|---|
| Applies to: |
<dialog> |
| Description: |
Centers the dialog when created. |
| Default value: |
not applicable. |
| Valid values: |
any |
| Example: |
<dialog w="200" h="400" center=""> |
| type |
|---|
| Applies to: |
<control> |
| Description: |
Tells the DCXML parser what kind of control you want to create. Name as supplied to /xdialog -c or /xdid -c |
| Default value: |
Panel |
| Valid values: |
pbar, treeview, toolbar, statusbar, listview, trackbar, rebar, colorcombo, button, richedit, ipaddress, updown, webctrl, line, box, radio, check, edit, scroll, image, list, link, text, divider, panel, tab, window, dialog |
| Example: |
<control type="listview" /> |
| weight |
|---|
| Applies to: |
<control> <pane> |
| Description: |
Give's a control or pane a weight value so that the CLA can determine it's size against it's siblings. |
| Default value: |
0 |
| Valid values: |
Any numerical value greater then zero. |
| Example: |
<control type="listview" weight="4" /> |
| height |
|---|
| Applies to: |
<control> <pane> |
| Description: |
Give's a control or pane a fixed height in pixels. The control will not size vertically when this attribute is set on an element |
| Default value: |
0 |
| Valid values: |
Any numerical value greater then zero to indicate height in pixels |
| Example: |
<control type="listview" /> |
| width |
|---|
| Applies to: |
<control> <pane> |
| Description: |
Give's a control or pane a fixed width in pixels. The control will not size horizontally when this attribute is set on an element |
| Default value: |
0 |
| Valid values: |
Any numerical value greater then zero to indicate width in pixels |
| Example: |
<control type="listview" /> |
| margin |
|---|
| Applies to: |
<pane><dialog> |
| Description: |
Give's a dialog or pane a margin. All the childs will be placed at the offset specifed |
| Default value: |
0 0 0 0 |
| Valid values: |
LEFT TOP RIGHT BOTTOM as integers. |
| Example: |
<pane margin="20 20 20 20" /> |
| styles |
|---|
| Applies to: |
<control> |
| Description: |
Sets the control styles |
| Default value: |
|
| Valid values: |
Any valid style on the control |
| Example: |
<control type="listview" styles="report grid subitemimage fullrow" /> |
| caption |
|---|
| Applies to: |
<control> <dialog> |
| Description: |
If control allows text to be added this will set the text. For <dialog> this sets the dialog title. |
| Default value: |
|
| Valid values: |
Any valid XML character for instance using "&" can result in text to be cut off. |
| Example: |
<control type="text" caption="This is a text control!" />
<control type="text">This is a text control!</control> |
| Notes: |
- You don't have to use the caption attribute if you set the Text Node on the element (see above) it will do the exact same.
- When you use the Text Node method there's no limit on how much text you want to input.
- For some controls \c and \b are shortcuts to mIRC's colour and bold code respectively.
- mIRC identifiers WILL be evaluated if the eval attribute is set on the element.
|
| tooltip |
|---|
| Applies to: |
<control> |
| Description: |
Sets the control's tooltip |
| Default value: |
|
| Valid values: |
Any valid tooltip control |
| Example: |
<control type="text" tooltip="some description" /> |
| cascade |
|---|
| Applies to: |
<pane><dialog> |
| Description: |
Sets the direction in which the child <panes><controls> are placed. Specify "h" and all the children will appear next to each other. "v" makes them appear underneath each other. |
| Default value: |
v |
| Valid values: |
h v |
| Example: |
<control type="text" tooltip="some description" /> |
| textcolour |
|---|
| Applies to: |
<control><style><item> |
| Description: |
Sets text colour |
| Default value: |
|
| Valid values: |
Numeric greater then zero. |
| Example: |
<item caption="redtext" textcolour="255" /> |
| textbgcolour |
|---|
| Applies to: |
<control><style><item> |
| Description: |
Sets text background colour |
| Default value: |
|
| Valid values: |
Numeric greater then zero. |
| Example: |
<item caption="redbgtext" textcolour="255" /> |
| bgcolour |
|---|
| Applies to: |
<control><style><item> |
| Description: |
Sets background colour |
| Default value: |
|
| Valid values: |
Numeric greater then zero. |
| Example: |
<item caption="redbgt" bgcolour="255" /> |
| icon |
|---|
| Applies to: |
<control><item> |
| Description: |
Sets the icon index to be used by the control or item. |
| Default value: |
|
| Valid values: |
Numeric greater then or equal to zero. |
| Example: |
<item icon="0" /> |
| iconsize |
|---|
| Applies to: |
<control><style> |
| Description: |
Sets the icon size. |
| Default value: |
|
| Valid values: |
Numeric greater then or equal to zero. |
| Example: |
<item icon="0" /> |
| integral |
|---|
| Applies to: |
<control type="treeview"> |
| Description: |
Sets icon spacing in the treeview |
| Default value: |
|
| Valid values: |
Numeric greater then zero. |
| Example: |
<control type="treeview" integral="1"> |
| fontstyle |
|---|
| Applies to: |
<control><style> |
| Description: |
Sets the fontstyle |
| Default value: |
|
| Valid values: |
Any valid fontstyle switch |
| Example: |
<control type="text" fontstyle="b"> |
| charset |
|---|
| Applies to: |
<control><style> |
| Description: |
Sets the character set of the font |
| Default value: |
|
| Valid values: |
Any valid character set |
| Example: |
<control type="text" charset="ansii"> |
| fontsize |
|---|
| Applies to: |
<control><style> |
| Description: |
Sets the font size |
| Default value: |
|
| Valid values: |
Any font size |
| Example: |
<control type="text" fontsize="16"> |
| fontname |
|---|
| Applies to: |
<control><style> |
| Description: |
Sets the font |
| Default value: |
|
| Valid values: |
Any font |
| Example: |
<control type="text" font="Trebuchet MS"> |
| border |
|---|
| Applies to: |
<control><dialog> |
| Description: |
Sets the border on a control dialog |
| Default value: |
|
| Valid values: |
Any valid border switch |
| Example: |
<dialog name="mydialog" border="btmnzy"> |
| cursor |
|---|
| Applies to: |
<control><style> |
| Description: |
Sets the default cursor for a control |
| Default value: |
|
| Valid values: |
Any valid cursor name |
| Example: |
<control type="text" cursor="wait"> |
| indent |
|---|
| Applies to: |
<item> |
| Description: |
Sets the indentation of comboex items. In future this will support more controls and integral will be synonymous with this attribute. |
| Default value: |
|
| Valid values: |
0 or greater |
| Example: |
<item indent="5" > |
| flags |
|---|
| Applies to: |
<control><item><icon> |
| Description: |
Allows you to pass flags when creating controls, items, icons. |
| Default value: |
|
| Valid values: |
Any valid flag |
| Example: |
<item caption="these" icon="20" flags="v" />
creates a toolbar button with a dropdown arrow if this item is child of a toolbar. |
| src |
|---|
| Applies to: |
<control><item><icon> |
| Description: |
Pointer to files, for instance icon resources,a bitmap, or an URL for link controls. |
| Default value: |
|
| Valid values: |
Any valid pathname |
| Example: |
<icon type="treeview" indexmax="40" src="$_scriptdir $+ controls.icl" /> |
| cells |
|---|
| Applies to: |
<control type="statusbar"> |
| Description: |
Special attribute to tell DCX how many cells there are and how big they're going to be |
| Default value: |
|
| Valid values: |
N [N N N ...] |
| Example: |
<control type="statusbar" cells="100 200 300 400 -1"> |
| minheight |
|---|
| Applies to: |
<control> |
| Description: |
Special attribute to tell direct child controls of the rebar the minimal height the bar of the rebar band. |
| Default value: |
|
| Valid values: |
0 or greater. |
| Example: |
<control type="panel" minheight="100"> |
| minwidth |
|---|
| Applies to: |
<control> |
| Description: |
Special attribute to tell direct child controls of the rebar the minimal width the bar of the rebar band. |
| Default value: |
|
| Valid values: |
0 or greater. |
| Example: |
<control type="panel" minwidth="100"> |
|
