Understanding the config.xml file from ExQueues Shell Queue GPL by Slain Jamison Wilde<p/>

ExQueues uses a relatively complicated method for storing its configuration data, namely in an xml-style configuration file called 'config.xml'.  This file should be located in the user's application data folder under ExQueues, to allow for multiple users on the same machine to have different settings.<p/>

This file is both read (and when complete written) by pugxml (the Pug XML Parser).  <p/>


In the text below, there will be discussion of attributes and &lt;Attribute&gt; tags.  'attributes' are the key="value" we are all familiar with in XML.  The &lt;Attribute&gt;s are ExQueues specific tags used to indicate values and options for particular task and task queue types.<p/>


***********************************<p/>
XML Attributes<p/>
***********************************<p/>
The XML tags can have various attributes which will be described here:<p/>

display="Display this in the config control"  <p/>
********************************************<p/>
	Generally used in a section tag, such as &lt;General&gt;, this will be used instead of (overriding) the tag name in the Tree control used to display and modify the config data.  So for example, &lt;General display="General Settings"&gt;<p/>
<p/>

name="MyName"<p/>
*************<p/>
	Generally used to indicate a particular instance of a tag, such as &lt;Option name="ExtractVIDEO_TStoFolder"&gt; to indicate which setting this option is referring to.  In most cases, you may also use a sub tag &lt;Name value="MyName"/&gt; or &lt;Name&gt;MyName&lt;/Name&gt; to indicate this information.  This alternate formatting may not remain once resaved after editing in the config tree control, though. <p/>

<p/>
value="MyValue"<p/>
***************<p/>
	Used to indicate the value of a particular tag, whether it is a string, number, or boolean.  For example, &lt;Option ... value="true"&gt; indicates a boolean true is the value.  In some cases, you may also use a sub tag &lt;Value value="MyValue"/&gt; or &lt;Value&gt;MyValue&lt;/Value&gt; to indicate this information.  This alternate formatting may not remain once resaved after editing in a the config tree control, though. Values will often times indicate lists of values, separarated by commas, such as lists of directories, or lists of extensions.  When indicating lists of directories, if a path contains a space then that path should be surrounded by double quotes. Ex.: c:\firstpath, "c:\second path", c:\thirdpath <p/>

<p/>

type="MyDataType"<p/>
*****************<p/>
MyDataType must be one of (string, int, bool).  Inidcates that the data should be interpreted as a string, a boolean or an integer.  This is most useful in helping determine how to display the control for a value in the config control, whether as an editbox for a string, a checkbox for a boolean, or a number edit box for an integer.<p/>

<p/>
default="MyDefaultValue"<p/>
************************<p/>
Used in &lt;Option&gt; and &lt;Attribute&gt; tags, this indicates the default value for an option setting or ExQueues attibute, such as &lt;UseRecylceBin type="bool" default="true"&gt; for the &lt;UseRecycleBin&gt; option setting.<p/>
<p/>

show="MyBoolValue"<p/>
******************<p/>
Used to determine if a section or tag will appear in the config tree control.  This is for settings that shouldn't change, such as the ExQueues &lt;Attribute&gt; tags which describe the other data in the document.  Changes to these would need to be made by hand in the xml document. <p/>
<p/>

number="MyNumber"<p/>
*****************<p/>
Not really used by the application at this time, these simply indicate and differentiate between tags that would otherwise be identical, but contain desparate data.  For example, &lt;Task number="1"&gt; and &lt;Task number="2"&gt; indicate that these are different tasks (xml-wise), but this isn't really used by ExQueues at this time and may go away.<p/>
<p/>

PCDATA<p/>
******<p/>
As indicated in name= and vaue= above, sometimes PCDATA (data in between two tags) is allowed.  For example, &lt;Name&gt;MyName&lt;/Name&gt;, where MyName is the PCDATA.<p/>

<p/>


***********************************<p/>
XML Section Tags<p/>
***********************************<p/>


The file contains various sections which will be described in further detail here.<p/>

&lt;Config&gt;<p/>
********<p/>
The containing tag for the document is the &lt;Config&gt; tag, in which all other relevant section and data tags will be found.<p/>

&lt;General&gt;<p/>
*********<p/>
The section for general settings for the application are contained in the &lt;General&gt; section.  Within this section, the actual data for the settings is contained in &lt;Option&gt; tags.<p/>
<p/>
All of the options are self-explanatory, if one also looks at the &lt;Tips&gt; tags inside each &lt;Option&gt;.  These options are editable within the config tree control.  Developers adding additional options should make sure that the option name is unique, that a default is provided and that the type is set.<p/>

<p/>
&lt;AttributesInfo&gt;<p/>
****************<p/>
This section contains all of the various possible attributes that can be used to describe a task or task queue in ExQueues such as Repair or Extract.  The value types and default values for these task attributes are also established in this section, including tooltip text describing the function of each attrribute for display in the config tree control.<p/>
<p/>
Examples of attributes are MenuText, MenuShow, UseRecycleBin, DeleteSources, MenuDestinations.  Each &lt;Attribute&gt;, like an &lt;Option&gt; has a name attribute, a type (string, bool, int) attribute, a default attribute to indicate the default value in the absence of other information, and a sub-tag &lt;Tip&gt; used to show tooltips in the config property tree control. <p/>
<p/>

&lt;Vars&gt;<p/>
******<p/>
The &lt;Vars&gt; section contains sub-tag &lt;Var&gt;s, that can be used as substitution variables for frequently used values.  For example, many times the &lt;MenuDestinations&gt; &lt;Attribute&gt; uses the same directories in most of the &lt;Task&gt; types.  You could use a &lt;Var&gt; to represent those destination paths that repeat in most tasks.  You would then use :: (colon colon) in front of the name= attribute you chose for your &lt;Var&gt;, to have the variable name substituted with its value.  For example, by default in the config.xml file there is a &lt;Var name="varDests"&gt;.  Set this variables value to be your most common destinations.  You could then use the value of varDests in a &lt;MenuDestinations&gt; &lt;Attribute&gt; by writing '::varDests'.  If you wanted to add additional paths after, you could use '::varDests, c:\My\Other\Path' for example (w/o quotes). <p/>
<p/>

&lt;Tasks&gt;<p/>
*******<p/>
Contains all of the Task Specific information for a single task (not a task queue, with the exception that deleteing the source files after successful completeion of a task can create a secondary task when requested).  Examples of atomic tasks are Repair, Move, Copy, Extract, Delete. &lt;Task&gt; tags contain several tags (derived from &lt;Attribute&gt; tags listed in &lt;AttributesInfo&gt; section).  The only mandatory &lt;Attribute&gt; tag is the Name tag (or name= attribute in the &lt;Task&gt; tag). Refer to the tips in the config.xml file regarding specific information about various &lt;Attribute&gt;s.<p/>
<p/>

&lt;Queues&gt;<p/>
********<p/>
Contains all of the task queue (sequential tasks triggered by one action). The current example is "Repair then Extract", where two atomic tasks (Repair, Extract) are chained together in sequence.  Queues contain many of the same Attributes as tasks.  <p/>
<p/>
Queues contain an ordered list of &lt;Task&gt;s to indicate which tasks should be used and in what order they will be executed.  Default values for these atomic &lt;Task&gt;s can be overridden as well in the &lt;Queue&gt; &lt;Task&gt; tag.<p/>
<p/>

&lt;DDE&gt;<p/>
*****<p/>
This section describes how a DDE request is converted into a Task or Task Queue when recieved, based on the file extension(s) of the data.  For example, if a user drags and drops one or more repair (.par2) files in Directory Opus into another folder, the default action for ExQueues is to begin a "Repair Then Extract" Task Queue for each file.  If a repair file and an archive file (.rar) are dragged and dropped to the same folder, then a "Repair Then Extract" Queue is created for the .par2 file and an "Extract" Task is created for the .rar file.  If an NFO file is also dragged at the same time as the other .par and .rar, then instead of Repairing or Extracting, ExQueues will simply move all of the selected files.<p/>
<p/>
The &lt;DDE&gt; section contains &lt;Command&gt;s that represent a single DDE action, such as a drag and drop DDE command or ctrl-delete.  Each DDE command has a specific name, such as 'delete' or 'queue' (which are built-in) or whatever the user decides to create. Each &lt;Command&gt; then has one or more &lt;CommandGroup&gt;s, representing groupings of Tasks/Queues that could be used to process that command.  For example, the 'queue' &lt;Command&gt; has two &lt;CommandGroup&gt;s.  One is for handling if all of the file are .par2's or .rar's, so that the files would be Repair Then Extract if they were par2, or simply Extract if they were rar's.  However, what if you wanted to accomodate the situation where you grab all of the files (.nfo, .sfv, .rar's, .par2's, etc.) for drag and drop them to a different destination, with the objective being to Move or Copy the files, in a queued manner.  Because you included nfo, sfv, etc files along with the par2 and rar files, the first &lt;CommandGroup&gt; would not be chosen because there were files that did not fit its list of extensions, therefore the second &lt;CommandGroup&gt; would be tested.  SInce it accepts all files, it would be the one chosen to execute (in the default case this is a Move &lt;Task&gt;).<p/>
<p/>
Each &lt;CommandTask&gt; subtag under the &lt;CommandGroup&gt; represents an ordered extensions filter for the file list.  So if two &lt;CommandTask&gt;s had overlapping extensions, the one first would be chosen to process that file.<p/>
<p/>