DCX - Dialog Control Xtension
v1.4.0
DCXML
  1. Introduction
  2. Getting started
  3. Some things you should know about XML
  4. DCXML markup rules
  5. Insert and layout dcx controls.
  6. The power of pane
  7. Cascading Control Styles
  8. Cascading Icon Definitions
  9. Templating
  10. Elements Refference
  11. Attributes Refference


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

<dialogs>
dialogs is the document node this means it has to be at the top of the hierarchy see "DCXML markup rules" for more information.
Child nodes: <dialog>, <icons> and <styles>
Parent Nodes: none
<dialog>
The dialog element is where you can define your dialog in.
Child nodes: <control>, <pane>, <icons> and <styles>
Parent Nodes: none
<control>
The control element creates as you might expect a control on your dialog, you can specify which by setting the type attribute: <control type="listview" /> creates a listview etc.
Child nodes: <control> (If the parent control element is a Container type)
<pane> (if control is of type Panel or Box)
<item> (Control specific allows you to add items to toolbars, lists, treeview's etc)
Parent Nodes: <control>, <pane>
<item>
Control specific allows you to add items to toolbars, lists, treeview's etc
Child nodes: <item>
Parent Nodes: <control>
<pane>
Pane is a way to group controls and manage their display in a grouped manner.
Child nodes: <control>, <pane>
Parent Nodes: <control> (if control has CLA such as PANE and BOX controls), <pane>
<styles>
styles is an element that groups style elements.
Child nodes: <style>
Parent Nodes: <dialogs>(global), <dialog>(local)
<style>
style allows you to style a control/class or id.
Child nodes: none
Parent Nodes: <styles>
<all>
Handy element to style EVERYTHING on your dialog.
Child nodes: none
Parent Nodes: <styles>
<icons>
icons groups icon elements
Child nodes: <icon>
Parent Nodes: <dialogs>(global), <dialog>(local)
<icon>
icon allows you to specify a control/class or id's image list
Child nodes: none
Parent Nodes: <icons>
<templates>
Container for templates
Child nodes: <template>
Parent Nodes: <dialogs>
<template>
icon allows you to specify a control/class or id's image list
Child nodes: Any valid child of <dialog> except for <calltemplate>
Parent Nodes: <templates>
<calltemplate>
Applies a certain template
Child nodes: None
Parent Nodes: Any valid <dialog> child element except for <calltemplate>

Attribute Refference 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">
Contact 2005-2007 Last Updated: 25th December, 07

Valid XHTML 1.0 Transitional Valid CSS!