Trivia Quiz Shell ReferenceThis reference describes how to use various elements and functions when writing your own applications for Trivia Quiz Shell 2.8.TQS ReferenceThe Trivia Quiz Shell reference contains detailed information on all of the elements and functions that TQS supports. Each reference page describes the syntax of the element or function and all accompanying information, such as attributes, children, placement, and parameters. Also, each page provides one or more examples of how the element or function is used. In addition, the version of TQS that an element requires is displayed in the top left corner; any version-dependent additions are also noted.%IMGNEW% indicates a new feature in TQS version 2.8.TQS ElementThis element is the root element of the TQS file, containing all data.<pre><<b>TQS</b>
<b>VERSION</b>="<i>version</i>"
<b>EDITABLE</b>="<i>editable</i>"
<b>DATAROOT</b>="<i>dataroot</i>"
<b>USESSOUNDS</b>="<i>usessounds</i>">
...
</<b>TQS</b>></pre>
VERSIONSpecifies the version of Trivia Quiz Shell that the user must have in order to run this application. The minimum value is "2.0"; however, if your application uses features that are only available in a newer version, you must specify the version. This value must be set to "2.0", "2.1", "2.5", "2.6", "2.7", or "2.8".EDITABLEOptional. Specifies whether this file can be edited using the TQS Embed Utility or the future TQS Editor. "1" means it can, "0" means it cannot. Defaults to "0".DATAROOTThe path that all data files (such as images and sounds) are contained in. This defaults to the path of the .TQS file. A trailing slash is required. This can be the URL of a web directory.USESSOUNDSIf any sounds are to be played, besides any background sound specified by the %REFTO:BGSOUND% element, this attribute must be set to "1". This includes those specified to respond to correct and incorrect answers, and sounds played in custom locations via the %REFTO:playSound% or %REFTO:playSoundFile% functions. Defaults to "0".<p><b>TQS 2.8</b> <span style="color:#ff0000; font-weight:bold">Deprecated.</span> This attribute is ignored if your <b>TQS</b> element's <i>VERSION</i> attribute is 2.8 or higher; sounds can be played without this attribute.The <b>TQS</b> element must be the root element, following the XML declaration.The <b>TQS</b> element, and the <i>VERSION</i> attribute, are necessary for the TQS application to be executed.<?xml version="1.0"?>
<TQS
VERSION="2.1"
EDITABLE="1"
DATAROOT="http://www.example.com/tqsdata/">
<TITLE>...</TITLE>
<LOCATIONS ...>
...
</LOCATIONS>
</TQS>
<?xml version="1.0"?>
<TQS
VERSION="2.5"
EDITABLE="1"
USESSOUNDS="1">
<TITLE>...</TITLE>
<REPORT ...>...</REPORT>
<GLOBAL>
<CORRECT SOUND="correct.wav">Correct!</CORRECT>
<INCORRECT SOUND="wrong.wav">Wrong!</INCORRECT>
</GLOBAL>
<LOCATIONS ...>
...
</LOCATIONS>
</TQS>
TITLE ElementSpecifies the title of the TQS application.<pre><<b>TITLE</b>><i>title</i></<b>TITLE</b>></pre>
The <b>TITLE</b> element must be a child of the %REFTO:TQS% element.The text specified is displayed in the title bar of the application, and in the About screen.<TITLE>World Literature Trivia</TITLE>ABOUT ElementSpecifies additional text to be displayed in the About screen.<pre><<b>ABOUT</b>><i>about</i></<b>ABOUT</b>></pre>
The <b>ABOUT</b> element must be a child of the %REFTO:TQS% element.The contents of the <b>ABOUT</b> element can contain HTML markup and special characters. The text will be displayed in the About screen beneath the application title and any author information.<TITLE>Les Miserables Trivia</TITLE>
<ABOUT>The first in the series of <b>Victor Hugo Trivia
</b> games. © 2001 Bot Productions.</ABOUT>AUTHORINFO ElementContains information about the author of the TQS application.<pre><<b>AUTHORINFO</b>
<b>AUTHOR</b>="<i>author</i>"
<b>EMAIL</b>="<i>email</i>"
<b>WEBSITE</b>="<i>website</i>"
/></pre>
AUTHORThe name of the author, such as an individual or company name.EMAILThe e-mail address of the author or company.WEBSITEThe complete URL of the author's web site, or the site that should be associated with this TQS application.The <b>AUTHORINFO</b> element must be a child of the %REFTO:TQS% element.This information is displayed in the About screen. The values for e-mail and web site will be displayed as hyperlinks, allowing the user to click on them. For the e-mail address, the <i>mailto:</i> prefix will be added; for the web site URL, you must include the protocol prefix (<i>http://</i>).<p>Use of the <b>AUTHORINFO</b> element is optional. Additionally, each attribute is optional.<AUTHORINFO
AUTHOR="Bot Productions"
EMAIL="mail@botproductions.com"
WEBSITE="http://www.botproductions.com"
/>TQSWINDOW ElementContains specifications regarding the appearance of the TQS application window.<pre><<b>TQSWINDOW</b>
<b>WIDTH</b>="<i>width</i>"
<b>HEIGHT</b>="<i>height</i>"
<b>FONT</b>="<i>font</i>"
<b>BGIMG</b>="<i>bgimg</i>"
<b>BGCOLOR</b>="<i>bgcolor</i>"
<b>BGGRADIENTCOLOR</b>="<i>bggradientcolor</i>"
<b>BGGRADIENTSTYLE</b>="<i>bggradientstyle</i>"
<b>TEXTCOLOR</b>="<i>textcolor</i>"
<b>SELCOLOR</b>="<i>selcolor</i>"
<b>BGCOLOR3D</b>="<i>bgcolor3d</i>"
<b>BORDERCOLOR3D</b>="<i>bordercolor3d</i>"
<b>TEXTCOLOR3D</b>="<i>textcolor3d</i>"
<b>SBUSE3DCOLORS</b>="<i>sbuse3dcolors</i>"
<b>BGSTYLE</b>="<i>bgstyle</i>"
<b>BGIMGREPEAT</b>="<i>bgimgrepeat</i>"
<b>BGIMGPOS</b>="<i>bgimgpos</i>"
<b>ADJUSTDPI</b>="<i>adjustdpi</i>"
<b>SIZEINCLNC</b>="<i>sizeinclnc</i>"
<b>RESIZABLE</b>="<i>resizable</i>"
/></pre>
WIDTHThe width of the TQS window, in pixels. This attribute is only used by the main <b>TQSWINDOW</b> element; it is ignored for child locations.HEIGHTThe height of the TQS window, in pixels. This attribute is only used by the main <b>TQSWINDOW</b> element; it is ignored for child locations.FONTThe name of the font used throughout the application window. Additional fonts, separated by commas, can be specified to be used if the previous is not installed on the system. Defaults to "Verdana, Arial, sans-serif".BGIMGThe filename of an image to be displayed in the background. Defaults to no image.BGCOLORThe background color of the application window. Defaults to "#000033".BGGRADIENTCOLORThe color to use with the <i>BGCOLOR</i> to make a gradient.BGGRADIENTSTYLESpecifies the type of gradient to display. Currently, it must be one of the following values:<dl><dt><b>"HORIZ"</b></dt><dd>The gradient is displayed horizontally from left to right.</dd><dt><b>"VERT"</b></dt><dd>The gradient is displayed vertically from top to bottom.</dd></dl>TEXTCOLORThe color used to display text. Defaults to "white".SELCOLORThe color used to display selected items. When the mouse hovers over a menu item, a question answer, or a letter in the hangman letter table, this color is used. Defaults to "yellow".BGCOLOR3DThe color of 3D objects, such as buttons. Defaults to current Windows color settings.BORDERCOLOR3DThe highlight color of 3D objects, such as buttons. To make it look 3D, use a color a few shades lighter than the <i>BGCOLOR3D</i> color. Windows will automatically choose a darker shade for the button shadow. Defaults to current Windows color settings.TEXTCOLOR3DThe color of text drawn on 3D objects, such as buttons. Defaults to current Windows color settings.SBUSE3DCOLORSWhen set to "1", specifies that if the content of the TQS window needs to be scrolled, the scroll bar color will be that specified by the various <i>xxCOLOR3D</i> attributes. Defaults to "0", meaning they will use current Windows color settings despite any <i>xxCOLOR3D</i> attributes. Colored scroll bars require Internet Explorer 5.5 or newer.BGSTYLEControls how the background image is displayed. It can be set to one of the following values:<dl><dt><b>"SCROLL"</b></dt><dd>The background image will move with the window contents if the TQS window is scrolled. This is the default if no value is specified.</dd><dt><b>"FIXED"</b></dt><dd>The background image will not move if the TQS window is scrolled.</dd><dt><b>"STRETCH"</b></dt><dd><b>TQS 2.7</b> The background image is stretched to cover the entire dimensions of the window. In this case, the image will not repeat, and the <i>BGIMGREPEAT</i> and <i>BGIMGPOS</i> attributes are ignored.</dd><dt><b>"HIDEIMG"</b></dt><dd><b>TQS 2.7</b> Only applies when the <b>TQSWINDOW</b> element is located inside of a %REFTO:LOC% or %REFTO:REPORT% element. This causes the background image that would be displayed (i.e. one specified in the main <b>TQSWINDOW</b> element or in a parent location's <b>TQSWINDOW</b> element) to be hidden for this location.</dd></dl>BGIMGREPEATSpecifies whether the background image should be repeated (tiled) if it is smaller than the size of the window, and in which directions. This attribute can be set to one of the following values:<dl><dt><b>"BOTH"</b></dt><dd>The image is repeated both horizontally and vertically. This is the default value if this attribute is not specified.</dd><dt><b>"HORIZ"</b></dt><dd>The image is only repeated horizontally.</dd><dt><b>"VERT"</b></dt><dd>The image is only repeated vertically.</dd><dt><b>"NONE"</b></dt><dd>The image is displayed but not repeated in either direction.</dd></dl>BGIMGPOSSpecifies the initial position of the background image within the window. If the image is to be repeated, its initial position is specified by this attribute, and the repetition is based on this position. This attribute must be set to one of the following values:<dl><dt><b>"1"</b></dt><dd>Bottom left.</dd><dt><b>"2"</b></dt><dd>Bottom, centered horizontally.</dd><dt><b>"3"</b></dt><dd>Bottom right.</dd><dt><b>"4"</b></dt><dd>Centered vertically, left.</dd><dt><b>"5"</b></dt><dd>Centered vertically and horizontally.</dd><dt><b>"6"</b></dt><dd>Centered vertically, right.</dd><dt><b>"7"</b></dt><dd>Top left. This is the default if no value is specified.</dd><dt><b>"8"</b></dt><dd>Top, centered horizontally.</dd><dt><b>"9"</b></dt><dd>Top right.</dd></dl>ADJUSTDPISpecifies whether to adjust the <i>WIDTH</i> and <i>HEIGHT</i> automatically based on the user's screen resolution (DPI). This attribute is only used by the main <b>TQSWINDOW</b> element; it is ignored for child locations. By default for applications marked as version 2.8 or newer, the dimensions are adjusted; set this attribute to "0" to disable the adjustment. Applications marked for previous versions are never adjusted.SIZEINCLNCSpecifies whether the specified <i>WIDTH</i> and <i>HEIGHT</i> values include the size of the window's nonclient area (title bar and borders). Defaults to <b>"1"</b> to include the nonclient area; set to <b>"0"</b> to specify that the dimensions refer only to the main client area of the window. In TQS 2.7 and prior versions, the default includes the nonclient version when Internet Explorer 6 or prior is installed; with Internet Explorer 7 the default refers to just the client version.RESIZABLESpecifies whether the window can be resized. The default value is <b>"1"</b>, allowing the window to be resized. Set this attribute to <b>"0"</b> to prevent the window from being resized.The main <b>TQSWINDOW</b> element must be a child of the %REFTO:TQS% element.<p><b>TQS 2.7</b> <b>TQSWINDOW</b> elements can also be children of %REFTO:LOC% elements, in order to override global styles with location-specific styles. In addition, it can be a child of the %REFTO:REPORT% element, in order to customize the report screen.Use of the <b>TQSWINDOW</b> element is optional. Additionally, each attribute is optional.<p>When setting the width and height of the window, the size of the title bar and window border are included. There is currently no way to specify the specific size of the client area. If the window contents do not fit in the window size, scroll bars are displayed.<p>Color values can either be words ("white", "blue") or hexadecimal values ("#FFFFFF", "#0000FF"). View the list of Internet Explorer's <a href="http://msdn2.microsoft.com/en-us/library/ms531197.aspx">named colors</a>.<p>If you specify an image file in the <i>BGIMG</i> attribute, it must reside in the data root folder. This is, by default, the folder containing the .TQS file.<ul><li><b>TQS 2.1</b> The data root folder can be set with the %REFTO:TQS% element's <i>DATAROOT</i> attribute. To specify an absolute path, such as an Internet address, precede the path with <b>NOROOT?</b>.</li><li><b>TQS 2.6</b> To specify an embedded file, precede the path with <b>EMBED?</b>.</li></ul><p>To display gradients, the <i>BGCOLOR</i>, <i>BGCOLORGRADIENT</i>, and <i>BGGRADIENTSTYLE</i> attributes must each be set.<p>If the background image contains any transparency, the background color (or gradient) will be visible through the transparent areas.<p>In a nested location hierarchy, TQS will walk the hierarchy, looking at the <b>TQSWINDOW</b> elements attached to each %REFTO:LOC% element, in order to put together the composite visual appearance of the location. Read the <a href="http://www.botproductions.com/tqs/tutorial.html?index=16">TQS Tutorial, Part XVI</a> for a more detailed explanation.<TQSWINDOW
WIDTH="720"
HEIGHT="520"
BGIMG="bgimg.gif"
BGSTYLE="FIXED"
FONT="Times New Roman"
/><TQSWINDOW
BGCOLOR="#FFFFFF"
WIDTH="600"
HEIGHT="460"
FONT="Impact, Arial"
TEXTCOLOR="#000000"
SELCOLOR="#097894"
TEXTCOLOR3D="#FFFFFF"
BGCOLOR3D="#097894"
BORDERCOLOR3D="#88CBDC"
SBUSE3DCOLORS="1"
/><TQSWINDOW
BGCOLOR="#000080"
BGGRADIENTCOLOR="#0000FF"
BGGRADIENTSTYLE="VERT"
TEXTCOLOR="#FFFFFF"
...
/><TQSWINDOW
BGIMG="bgimg.gif"
BGSTYLE="STRETCH"
...
/><TQSWINDOW
BGIMG="EMBED?samplebk.gif"
BGIMGREPEAT="NONE"
BGIMGPOS="1"
...
/>BGSOUND ElementSpecifies the name of an audio file to be played in the background while the application is running.<pre><<b>BGSOUND</b>
<b>LOOP</b>="<i>loop</i>"><i>bgsound</i></<b>BGSOUND</b>></pre>
LOOPSpecifies the number of times to loop through the sound file. If set to "-1", the file will loop infinitely.The <b>BGSOUND</b> element must be a child of the %REFTO:TQS% element.The sound file must reside in the data root folder. This is, by default, the folder containing the .TQS file.<ul><li><b>TQS 2.1</b> The data root folder can be set with the %REFTO:TQS% element's <i>DATAROOT</i> attribute. To specify an absolute path, such as an Internet address, precede the path with <b>NOROOT?</b>.</li><li><b>TQS 2.6</b> To specify an embedded file, precede the path with <b>EMBED?</b>.</li></ul><p>Depending on the version of Windows Media Player and the codecs installed, different audio formats are supported, such as MIDI, WAVE, and MP3.<BGSOUND>bksong.mp3</BGSOUND><BGSOUND>NOROOT?http://www.example.com/song.mid</BGSOUND><BGSOUND LOOP="-1">shortsong.wav</BGSOUND>REPORT ElementSpecifies how TQS should collect and display score report data.<pre><<b>REPORT</b>
<b>SHOWBUTTON</b>="<i>showbutton</i>"
<b>SHOWSTATES</b>="<i>showstates</i>"
<b>SHOWTOTAL</b>="<i>showtotal</i>"
<b>SUMCHILDLOCS</b>="<i>sumchildlocs</i>"
<b>BOLDSUMS</b>="<i>boldsums</i>"
<b>INDENT</b>="<i>indent</i>"
<b>BORDERCOLOR</b>="<i>bordercolor</i>"
<b>BGSTYLE</b>="<i>bgstyle</i>"
<b>PRINTABLE</b>="<i>printable</i>"
<b>GETNAME</b>="<i>getname</i>"
<b>GETNAMEPROMPT</b>="<i>getnameprompt</i>">
...
</<b>REPORT</b>></pre>
SHOWBUTTONIf set to "1", the "Report" button will be displayed at the bottom of the window, next to the "About" button. Clicking on this button is the only way to display the report screen. Defaults to not displayed.SHOWSTATESIf set to "1", the report screen will display the image corresponding to the state of the location item. To change the default images, add a %REFTO:STATEIMG% element to the %REFTO:GLOBAL% element. Defaults to not displaying state images.SHOWTOTALIf set to "1", grand total score values will be displayed at the end of the report table.SUMCHILDLOCSSpecifies how to display sums of child locations. For instance, the entry for location 2,0 would sum the score values for 2,0,1; 2,0,2; etc. Two values are supported: <b>"INLINE"</b> will display the sums on the same line of the table as the location, while child locations are listed below. <b>"SUBTOTAL"</b> will display the location, then the child locations, followed by a line called "Subtotal" which lists the sums. Defaults to not displaying any sums.BOLDSUMSIf set to "1", sums of child locations will be displayed in bold. Defaults to not bold.INDENTIf set to "0", entries in the report table will not be indented according to the location's entry in the location hierarchy. Defaults to indenting.BORDERCOLORSpecifies the color of the lines and borders of the report table. Defaults to "#808080".<p>Color values can either be words ("white", "blue") or hexadecimal values ("#FFFFFF", "#0000FF"). View the list of Internet Explorer's <a href="http://msdn2.microsoft.com/en-us/library/ms531197.aspx">named colors</a>.BGSTYLEIf set to <b>"HIDEIMG"</b>, the current background image will be hidden when the report is displayed. Defaults to not hiding the background image.<p><b>TQS 2.7</b> <span style="color:#ff0000; font-weight:bold">Deprecated.</span> This attribute is ignored if your %REFTO:TQS% element's <i>VERSION</i> attribute is 2.7 or higher. Use a child %REFTO:TQSWINDOW% element instead.PRINTABLEIf set to "1", the "Print" button will be displayed at the bottom of the report screen. Clicking on this button allows the user to print the score report. Defaults to not displaying the button.GETNAMEIf set to "1", the TQS application will ask the user for their name immediately, before switching to the starting location. Defaults to not asking for a user name.GETNAMEPROMPTSpecifies the prompt to display when asking for the user's name. Defaults to "Please enter your name:".The <b>REPORT</b> element must be a child of the %REFTO:TQS% element.There is no way for the score report to be displayed at all unless the <i>SHOWBUTTON</i> attribute is set to "1". If you do not want to support the score report, you can still use the <b>REPORT</b> element to get the user's name; just omit the <i>SHOWBUTTON</i> attribute. Most of the remaining attributes are used only if the report is shown.Use the <b>REPORT</b> element only to get the user's name:<REPORT
GETNAME="1"
GETNAMEPROMPT="What is your name?"
/><REPORT
SHOWBUTTON="1"
PRINTABLE="1"
SHOWSTATES="1"
SHOWTOTAL="1"
SUMCHILDLOCS="SUBTOTAL"
BOLDSUMS="1">
<INCLUDETYPES>
<TYPE>NULL</TYPE>
<TYPE>QUESTIONS</TYPE>
<TYPE>HANGMAN</TYPE>
</INCLUDETYPES>
<TQSWINDOW BGSTYLE="HIDEIMG"/>
</REPORT>INCLUDETYPES ElementSpecifies which location types should be displayed in the score report.<pre><<b>INCLUDETYPES</b>>
...
</<b>INCLUDETYPES</b>></pre>
The <b>INCLUDETYPES</b> element must be a child of the %REFTO:REPORT% element.By default, no location types are included in the score report.<REPORT ...>
<INCLUDETYPES>
<TYPE>QUESTIONS</TYPE>
<TYPE>HANGMAN</TYPE>
<TYPE>CUSTOM_FOO</TYPE>
</INCLUDETYPES>
</REPORT>TYPE ElementSpecifies that a location type should be displayed in the score report.<pre><<b>TYPE</b>><i>type</i></<b>TYPE</b>></pre>
The <b>TYPE</b> element must be a child of the %REFTO:INCLUDETYPES% element.By default, no location types are included in the score report. If a location type is included, a specific location can remove itself from the report by setting the location's %REFTO:LOC% element's <i>REPORT</i> attribute to "0".<REPORT ...>
<INCLUDETYPES>
<TYPE>QUESTIONS</TYPE>
<TYPE>HANGMAN</TYPE>
<TYPE>CUSTOM_FOO</TYPE>
</INCLUDETYPES>
</REPORT>GLOBAL ElementContains default settings that apply to all locations.<pre><<b>GLOBAL</b>>
...
</<b>GLOBAL</b>></pre>
The <b>GLOBAL</b> element must be a child of the %REFTO:TQS% element.The <b>GLOBAL</b> element and its children are only used to override TQS defaults. Usage of this element is optional.<p>While global settings will become the default settings for all locations, if an individual location explicitly specifies settings, the local settings will override the global ones.<GLOBAL>
<BUTTONS>
...
</BUTTONS>
<MENU ...>
...
</MENU>
<QUESTIONS ...>
...
</QUESTIONS>
</GLOBAL>STATEIMG ElementSpecifies image files or colors that are used to display the state of a location.<pre><<b>STATEIMG</b>
<b>EMPTY</b>="<i>empty</i>"
<b>PARTIAL</b>="<i>partial</i>"
<b>DONE</b>="<i>done</i>"
<b>DONE100</b>="<i>done100</i>"
<b>BGCOLOR</b>="<i>bgcolor</i>"
<b>FRAMECOLOR</b>="<i>framecolor</i>"
<b>EMPTYCOLOR</b>="<i>emptycolor</i>"
<b>PARTIALCOLOR</b>="<i>partialcolor</i>"
<b>DONECOLOR</b>="<i>donecolor</i>"
<b>DONE100COLOR</b>="<i>done100color</i>"
/></pre>
EMPTYThe name of the image file representing the "EMPTY" state, where a location has not been visited.PARTIALThe name of the image file representing the "PARTIAL" state, where a location has been visited but not completed.DONEThe name of the image file representing the "DONE" state, where a location has been completed.DONE100The name of the image file representing the "DONE100" state, where a location has been completed with a score of 100%.BGCOLORThe color to use for the inner background of state images. Defaults to <b>"#000033"</b>.FRAMECOLORThe color to use for the one-pixel frame around the state image background. Defaults to <b>"white"</b>.EMPTYCOLORThe color to use for the "EMPTY" state image. Currently, no image is displayed for this state, so this attribute is ignored.PARTIALCOLORThe color to use for the "PARTIAL" state image, which is currently an image of the letter P. Defaults to <b>"white"</b>.DONECOLORThe color to use for the "DONE" state image, which is currently an image of a check mark. Defaults to <b>"yellow"</b>.DONE100COLORThe color to use for the "DONE100" state image, which is currently an image of a star. Defaults to <b>"yellow"</b>.The <b>STATEIMG</b> element must be a child of the %REFTO:GLOBAL% element.If images are specified, they take precedence over any specified colors.<p>Color values can either be words ("white", "blue") or hexadecimal values ("#FFFFFF", "#0000FF"). Also, you may use the empty string "" to signify that the particular portion of the state image should not be drawn. View the list of Internet Explorer's <a href="http://msdn2.microsoft.com/en-us/library/ms531197.aspx">named colors</a>.<p>Currently, when printing a report, any specified color values are ignored and the default state images are used instead.<p>Image files must reside in the data root folder. This is, by default, the folder containing the .TQS file.<ul><li>The data root folder can be set with the %REFTO:TQS% element's <i>DATAROOT</i> attribute. To specify an absolute path, such as an Internet address, precede the path with <b>NOROOT?</b>.</li><li><b>TQS 2.6</b> To specify an embedded file, precede the path with <b>EMBED?</b>.</li></ul><p>State images can be displayed in menus and/or in the report screen.<p>For more information on TQS's state tracking and scoring capabilities, read the <a href="http://www.botproductions.com/tqs/tutorial.html?index=13">TQS Tutorial, Part XIII</a>.<STATEIMG
EMPTY="custom_empty.gif"
PARTIAL="custom_partial.gif"
DONE="custom_done.gif"
DONE100="custom_done100.gif"
/><STATEIMG
BGCOLOR=""
FRAMECOLOR="blue"
PARTIALCOLOR="white"
DONECOLOR="red"
DONE100COLOR="#ff1192"
/>LOCATIONS ElementContains the application's location definitions.<pre><<b>LOCATIONS</b>
<b>START</b>="<i>start</i>">
...
</<b>LOCATIONS</b>></pre>
STARTThe location that should be loaded when the TQS application is started.The <b>LOCATIONS</b> element must be a child of the %REFTO:TQS% element.All %REFTO:LOC% elements must be specified within the <b>LOCATIONS</b> element, either directly or as sublocations of other %REFTO:LOC% elements.<LOCATIONS START="1,2">
...
<LOC ID="1" TYPE="NULL">
<LOC ID="2" TYPE="MENU">
<HEADING>Starting Location</HEADING>
...
</LOC>
</LOC>
...
</LOCATIONS>LOC ElementContains the definition of a location.<pre><<b>LOC</b>
<b>ID</b>="<i>id</i>"
<b>TYPE</b>="<i>type</i>"
<b>BGCOLOR</b>="<i>bgcolor</i>"
<b>BGIMG</b>="<i>bgimg</i>"
<b>BGSTYLE</b>="<i>bgstyle</i>"
<b>REPORT</b>="<i>report</i>"
<b>REPORTCHILDREN</b>="<i>reportchildren</i>"
<b>DEFERSTATE</b>="<i>deferstate</i>"
<b>STATE</b>="<i>state</i>"
<b>TRIED</b>="<i>tried</i>"
<b>CORRECT</b>="<i>correct</i>"
<b>WRONG</b>="<i>wrong</i>">
...
</<b>LOC</b>></pre>
IDThe ID of this location. Note that this ID must be unique among all <b>LOC</b> elements grouped at the same level.TYPEThe type of location. This can be one of the current built-in values or the name of a custom location type defined in the %REFTO:CUSTOM% element:<dl><dt><b>"NULL"</b></dt><dd>The location cannot be navigated to and is used only to hold other <b>LOC</b> elements.</dd><dt><b>"MENU"</b></dt><dd>The location is a menu; data is loaded from the %REFTO:MENU% subelement.</dd><dt><b>"QUESTIONS"</b></dt><dd>The location is a set of trivia questions; data is loaded from the %REFTO:QUESTIONS% subelement.</dd><dt><b>"HANGMAN"</b></dt><dd>The location is a hangman game; data is loaded from the %REFTO:HANGMAN% subelement.</dd><dt><b>"HTML"</b></dt><dd><b>TQS 2.1</b> The location is HTML code, which is loaded from the %REFTO:HTML% subelement.</dd><dt><b>"CUSTOM_*"</b></dt><dd>Substitute * with the name of your custom location type. Data is loaded from the subelement with that name.</dd></dl>BGCOLORBackground color for this location; overrides any background color specified in the main %REFTO:TQSWINDOW% element. Color values can either be words ("white", "blue") or hexadecimal values ("#FFFFFF", "#0000FF"). View the list of Internet Explorer's <a href="http://msdn2.microsoft.com/en-us/library/ms531197.aspx">named colors</a>.<p><b>TQS 2.7</b> <span style="color:#ff0000; font-weight:bold">Deprecated.</span> This attribute is ignored if your %REFTO:TQS% element's <i>VERSION</i> attribute is 2.7 or higher. Use a child %REFTO:TQSWINDOW% element instead.BGIMGBackground image for this location; overrides any background image specified in the main %REFTO:TQSWINDOW% element.<p><b>TQS 2.7</b> <span style="color:#ff0000; font-weight:bold">Deprecated.</span> This attribute is ignored if your %REFTO:TQS% element's <i>VERSION</i> attribute is 2.7 or higher. Use a child %REFTO:TQSWINDOW% element instead.BGSTYLEWhen set to <b>"HIDEIMG"</b>, no background image will be shown; the background color either specified by this <b>LOC</b> element's <i>BGCOLOR</i> attribute or within %REFTO:TQSWINDOW% will be used.<p><b>TQS 2.7</b> <span style="color:#ff0000; font-weight:bold">Deprecated.</span> This attribute is ignored if your %REFTO:TQS% element's <i>VERSION</i> attribute is 2.7 or higher. Use a child %REFTO:TQSWINDOW% element instead.REPORTIf the location type is specified in the %REFTO:REPORT% element's %REFTO:INCLUDETYPES% element, it will be included in the score report. To exclude it, set this attribute to <b>"0"</b>.REPORTCHILDRENBy default, the children of all "NULL" locations will be in the score report according to their inclusion in the %REFTO:INCLUDETYPES% element, regardless of whether the "NULL" location is itself included. Setting this attribute to <b>"0"</b> will exclude this NULL location's child locations from the report.DEFERSTATEIf set to <b>"PARENT"</b>, this location's state will be mapped to the state of the parent location. For instance, the state of a "MENU" location should be set to its parent location's state, because a "MENU" location cannot be "completed." This attribute cannot be set when the <b>LOC</b> element is an immediate child of the %REFTO:LOCATIONS% element.STATESpecifies the current state of the location. If this attribute is set, it will specify the initial state of the location. It is recommended that this attribute not be set; TQS will manage all location states.TRIEDSpecifies the number of questions or words that the user has tried.CORRECTSpecifies the number of questions or words that the user has gotten correct.WRONGSpecifies the number of questions or words that the user has gotten incorrect.The <b>LOC</b> element must be a child of the %REFTO:LOCATIONS% element or a child of a <b>LOC</b> element whose <i>TYPE</i> is <b>"NULL"</b>.All <b>LOC</b> elements must be specified within the %REFTO:LOCATIONS% element, either directly or as sublocations of other <b>LOC</b> elements. All of the type-specific data (questions, hangman words, etc.) is contained in a subelement of the <b>LOC</b> element. The name of this element has to be the same as the <b>LOC</b>'s <i>TYPE</i> attribute.<p>Note that if a location type is excluded from the report because it is not listed in the %REFTO:INCLUDETYPES% element, setting the <i>REPORT</i> attribute to <b>"1"</b> will NOT include it.<p>The <i>TRIED</i>, <i>CORRECT</i>, and <i>INCORRECT</i> attributes will be created and used by TQS to keep track of the location's score, if the location type is included in the %REFTO:REPORT% element's %REFTO:INCLUDETYPES% element list. If the attributes are specified in your TQS file, they will provide initial values, but these values will be overwritten when the location is invoked. Thus, it is recommended that you not include these attributes; TQS will manage all scoring values.<p>For more information on TQS's state tracking and scoring capabilities, read the <a href="http://www.botproductions.com/tqs/tutorial.html?index=13">TQS Tutorial, Part XIII</a>.<p>In a nested location hierarchy, TQS will walk the hierarchy, looking at the %REFTO:TQSWINDOW% elements attached to each <b>LOC</b> element, in order to put together the composite visual appearance of the location. Read the <a href="http://www.botproductions.com/tqs/tutorial.html?index=16">TQS Tutorial, Part XVI</a> for a more detailed explanation.<LOCATIONS START="0">
<LOC ID="0" TYPE="HANGMAN">
<HANGMAN>...</HANGMAN>
</LOC>
</LOCATIONS><TQSWINDOW ... BGIMG="img.gif"/>
<LOCATIONS START="0">
<LOC ID="0" TYPE="MENU">
<MENU>...</MENU>
</LOC>
<LOC ID="1" TYPE="NULL">
<LOC ID="0" TYPE="MENU" DEFERSTATE="PARENT">
<MENU>...</MENU>
</LOC>
<LOC ID="1" TYPE="CUSTOM_MATCHING">
<TQSWINDOW
BGCOLOR="#003300"
BGSTYLE="HIDEIMG"
/>
<CUSTOM_MATCHING>...</CUSTOM_MATCHING>
</LOC>
</LOC>
...
</LOCATIONS>REPORTTITLE ElementContains text used to represent this location in the report table.<pre><<b>REPORTTITLE</b>><i>reporttitle</i></<b>REPORTTITLE</b>></pre>
The <b>REPORTTITLE</b> element must be a child of the %REFTO:LOC% element.The %REFTO:HEADING% element's text will be used in the report table to represent the location; use the <b>REPORTTITLE</b> element to specify a different title for use in the report. If neither the <b>REPORTTITLE</b> nor %REFTO:HEADING% elements exist, the %REFTO:LOC% element's <i>ID</i> attribute will be displayed instead.<p>Use of the <b>REPORTTITLE</b> element is necessary to specify a title for "NULL" locations.<LOC ID="2001" TYPE="NULL">
<REPORTTITLE>2001 Hangman Series</REPORTTITLE>
<LOC ID="Jan" TYPE="HANGMAN">
<HEADING>Welcome to January Hangman</HEADING>
<REPORTTITLE>January</REPORTTITLE>
</LOC>
...
</LOC>HEADING ElementContains the text of the heading to be displayed at the top of the TQS window, along with optional graphics.<pre><<b>HEADING</b>
<b>LIMG</b>="<i>limg</i>"
<b>RIMG</b>="<i>rimg</i>"><i>heading</i></<b>HEADING</b>></pre>
LIMGFile name of a graphic to be displayed to the left of the heading.RIMGFile name of a graphic to be displayed to the right of the heading.The <b>HEADING</b> element must be a child of the %REFTO:LOC% element.The image files specified by the <i>LIMG</i> and/or <i>RIMG</i> attributes, if any, must reside in the data root folder. This is, by default, the folder containing the .TQS file.<ul><li><b>TQS 2.1</b> The data root folder can be set with the %REFTO:TQS% element's <i>DATAROOT</i> attribute. To specify an absolute path, such as an Internet address, precede the path with <b>NOROOT?</b>.</li><li><b>TQS 2.6</b> To specify an embedded file, precede the path with <b>EMBED?</b>.</li></ul><p>The heading will be used in the report table to represent its location; use the %REFTO:REPORTTITLE% element to specify a different title for use in the report. If neither the <b>HEADING</b> nor %REFTO:REPORTTITLE% elements exist, the %REFTO:LOC% element's <i>ID</i> attribute will be displayed instead.<HEADING>My Main Menu</HEADING><HEADING LIMG="img.gif"
RIMG="img.gif">Heading With Same Graphics</HEADING><HEADING
LIMG="NOROOT?http://www.example.com/limg.gif"
>Heading With One Graphic</HEADING><HEADING
LIMG="EMBED?limg.gif"
RIMG="EMBED?rimg.gif">Heading With Embedded Graphics</HEADING>BUTTONS ElementContains buttons that are defined for the entire application.<pre><<b>BUTTONS</b>>
...
</<b>BUTTONS</b>></pre>
The <b>BUTTONS</b> element must be a child of the %REFTO:GLOBAL% element.The <b>BUTTONS</b> element groups together application-wide %REFTO:BUTTON% definitions.<BUTTONS>
<BUTTON .../>
<BUTTON .../>
...
</BUTTONS>BUTTON ElementSpecifies a button to be displayed.<pre><<b>BUTTON</b>
<b>TITLE</b>="<i>title</i>"
<b>TARGET</b>="<i>target</i>"
<b>SUBST</b>="<i>subst</i>"
<b>APPLIESTO</b>="<i>appliesto</i>"
<b>INCLUDE</b>="<i>include</i>"
<b>EXCLUDE</b>="<i>exclude</i>"
<b>GREATER</b>="<i>greater</i>"
<b>LESS</b>="<i>less</i>"
/></pre>
TITLEThe text of the button.TARGETThe location that should be invoked when the button is clicked. If the button is a global button, a %REFTO:LOCPOS% dynamic value can be used in place of any location digit.SUBST<b>TQS 2.0, 2.1</b> Only applies to global buttons. Allows you to substitute, in the button title, a location position. The contents of the attribute must be in the form of "<i>string</i>,LOCPOS:<i>x</i>".<p><b>TQS 2.5</b> Substitution is supported for local, global, and finish buttons. All TQS dynamic values are supported. The attribute must be in the form of "<i>string,dynval</i>"; multiple substitutions can be specified by joining them with a semicolon (;).APPLIESTOOnly applies to global and global finish buttons. Specifies what rules are used when determining whether to display the button. It can be set to one of the following values:<dl><dt><b>"NONE"</b></dt><dd>The button will never be displayed. This is the default if no <i>APPLIESTO</i> attribute exists.</dd><dt><b>"ALL"</b></dt><dd>The button will be displayed in every location.</dd><dt><b>"ONLY"</b></dt><dd>The button will be only be displayed in locations explicitly specified in the <i>INCLUDE</i> attribute.</dd><dt><b>"ALLBUT"</b></dt><dd>The button will be only be displayed in all locations except those explicitly specified in the <i>EXCLUDE</i></i> attribute.</dd><dt><b>"GREATER"</b></dt><dd>The button will be only be displayed in locations which pass the test specified in the <i>GREATER</i> attribute.</dd><dt><b>"LESS"</b></dt><dd>The button will be only be displayed in locations which pass the test specified in the <i>LESS</i> attribute.</dd></dl>INCLUDEOnly applies to global and global finish buttons with the <i>APPLIESTO</i> attribute set to "ONLY". Contains a list of locations, separated by semicolons (;). Only these locations will display this button.EXCLUDEOnly applies to global and global finish buttons with the <i>APPLIESTO</i> attribute set to "ALLBUT". Contains a list of locations, separated by semicolons (;). Every location except these will display this button.GREATEROnly applies to global and global finish buttons with the <i>APPLIESTO</i> attribute set to "GREATER". Contains a rule which defines the locations that will display this button. The rule must be in the form of "value1&gt;value2". When <i>value1</i> is greater than <i>value2</i>, the button is displayed. In TQS 2.0 and 2.1, <i>value1</i> must be a %REFTO:LOCPOS% dynamic value; in TQS 2.5 and greater it can be any dynamic value. <i>value2</i> must be a number.LESSOnly applies to global and global finish buttons with the <i>APPLIESTO</i> attribute set to "LESS". Contains a rule which defines the locations that will display this button. The rule must be in the form of "value1&lt;value2". When <i>value1</i> is less than <i>value2</i>, the button is displayed. In TQS 2.0 and 2.1, <i>value1</i> must be a %REFTO:LOCPOS% dynamic value; in TQS 2.5 and greater it can be any dynamic value. <i>value2</i> must be a number.The <b>BUTTON</b> element can be used in the following places: As a child of the %REFTO:BUTTONS% element, to specify a global button; as a child of the %REFTO:FINISH% element, to specify a global or local button to be displayed when a location is finished; or as a child of a %REFTO:LOC% element, to specify a location-specific button.Using global buttons makes it easier to implement menu buttons for programs that have complex nested locations. Specifying a common button as a global button saves from having to add the button twenty times to twenty different locations. The examples below illustrate common uses of the <b>BUTTON</b> element.<p>Note that in the <i>GREATER</i> and <i>LESS</i> attributes, the rules must contain <b>&gt;</b> and <b>&lt;</b> respectively, and not > and <.One use of a button is to restart the current hangman game or trivia question set, by setting the target equal to that location (in this case, 1,1):<BUTTON
TITLE="Restart"
TARGET="1,1"
/>This global button defines a "Main Menu" button, which appears in every location but the main menu itself (location 0):<BUTTON
TITLE="Main Menu"
TARGET="0"
APPLIESTO="ALLBUT"
EXCLUDE="0"
/>This global button defines a button that appears only in locations "3,4,5" and "4,5,6" that take the user to "3,4,2" and "4,5,2" respectively:<BUTTON
TITLE="Special button"
TARGET="LOCPOS:0,LOCPOS:1,2"
APPLIESTO="ONLY"
INLUDE="3,4,5;4,5,6"
/>In this example, the program is divided into chapters, and each chapter has a menu and several other sublocations. This global button defines a "Chapter <i>X</i> Menu" button to appear in each of the chapter's sublocations but not the chapter's menu (that is, when the second digit of the location is greater than zero):<BUTTON
TITLE="Chapter %s Menu"
SUBST="%s,LOCPOS:0"
TARGET="LOCPOS:0,0"
APPLIESTO="GREATER"
GREATER="LOCPOS:1>0"
/>This global finish button uses the %REFTO:USERNAME% dynamic value to congratulate the user and go back to a menu:<FINISH>
<BUTTON
TITLE="Good job, %U! Back to Chapter %C menu."
SUBST="%U,USERNAME;%C,LOCPOS:0"
TARGET="LOCPOS:0,0"
APPLIESTO="ALL"
/>
</FINISH>MENU ElementContains the data for a location of type <b>"MENU"</b>.<pre><<b>MENU</b>
<b>NUMCOLUMNS</b>="<i>numcolumns</i>"
<b>CENTER</b>="<i>center</i>"
<b>NUMBERS</b>="<i>numbers</i>"
<b>HOVER</b>="<i>hover</i>"
<b>SHOWSTATES</b>="<i>showstates</i>"
<b>DONEITEMS</b>="<i>doneitems</i>">
...
</<b>MENU</b>></pre>
NUMCOLUMNSThe number of columns which the menu items should be displayed in. Defaults to 1.CENTERIf set to "1", the menu items will be centered within their column. Defaults to not centered.NUMBERSIf set to "1", the menu items will be numbered. Defaults to not displaying numbers.HOVERIf set to "U", a menu item will be underlined when the mouse hovers over it. Defaults to not underlining.SHOWSTATESIf set to "1", each menu item will have the state image for the target location displayed next to it.DONEITEMSSpecifies how to handle menu items whose target locations' states are <b>"DONE"</b> or <b>"DONE100"</b>. Defaults to <b>"SHOW"</b>, where menu items are displayed as normal on the menu. Other values include <b>"HIDE"</b>, where such items are not displayed, and <b>"DISABLE"</b>, where items are displayed but cannot be selected.The <b>MENU</b> element must be a child of a %REFTO:LOC% element whose <i>TYPE</i> attribute is set to <b>"MENU"</b>, or of the %REFTO:GLOBAL% element when specifying settings for all MENU locations.In TQS 2.0 global settings, only the element's %REFTO:INSTR% subelement is used; attributes are ignored. In version 2.1 and later, all <b>MENU</b> attributes are supported under global settings.<p>For more information on TQS's state tracking and scoring capabilities, read the <a href="http://www.botproductions.com/tqs/tutorial.html?index=13">TQS Tutorial, Part XIII</a>.<GLOBAL>
<MENU
CENTER="1"
HOVER="U">
<INSTR>Instructions for all menus here</INSTR>
</MENU>
</GLOBAL><LOC TYPE="MENU">
<MENU
CENTER="0"
NUMCOLUMNS="2"
NUMBERS="1">
<INSTR>Choose a chapter from below.</INSTR>
<MENUITEM .../>
<MENUITEM .../>
<MENUITEM .../>
...
</MENU>
</LOC>INSTR ElementSpecifies instructions to be displayed above a set of menu items.<pre><<b>INSTR</b>><i>instr</i></<b>INSTR</b>></pre>
The <b>INSTR</b> element must be a child of the %REFTO:MENU% element, either inside of an individual location element or within global settings.There is no default if no <b>INSTR</b> element is specified.<INSTR>Select an item from the menu below.</INSTR>MENUITEM ElementContains specifications for an individual item of a menu.<pre><<b>MENUITEM</b>
<b>TITLE</b>="<i>title</i>"
<b>TARGET</b>="<i>target</i>"
<b>SHOWSTATE</b>="<i>showstate</i>"
/></pre>
TITLEThe text of the menu item.TARGETThe location to invoke when the menu item is chosen.SHOWSTATEAllows state image display to be toggled on or off for a specific menu item. If set to <b>"1"</b>, the image for the target location state will be displayed next to the menu item; if <b>"0"</b>, it will not. This attribute will override any other setting, either from the parent or global %REFTO:MENU% element's <i>SHOWSTATES</i> attribute.The <b>MENUITEM</b> element must be a child of the %REFTO:MENU% element within an individual location element.If the menu is set to display numbers, the text of the menu item will be the number, followed by a period and a space, then the contents of the <i>TITLE</i> attribute.<p>For more information on TQS's state tracking and scoring capabilities, read the <a href="http://www.botproductions.com/tqs/tutorial.html?index=13">TQS Tutorial, Part XIII</a>.<MENU>
<MENUITEM
TITLE="Chapter 3 Trivia"
TARGET="3,1"
/>
<MENUITEM
TITLE="Chapter 3 Hangman"
TARGET="3,2"
/>
</MENU><MENU SHOWSTATES="1">
<MENUITEM TITLE="Trivia #1" TARGET="1"/>
<MENUITEM TITLE="Trivia #2" TARGET="2"/>
<MENUITEM TITLE="Trivia #3 Without State Image"
TARGET="3" SHOWSTATE="0"/>
</MENU>QUESTIONS ElementContains the data for a location of type <b>"QUESTIONS"</b>, in which the user is presented with a series of trivia questions.<pre><<b>QUESTIONS</b>
<b>INORDER</b>="<i>inorder</i>"
<b>SCRAMBLEANS</b>="<i>scrambleans</i>"
<b>SHOWSCORE</b>="<i>showscore</i>"
<b>HOVER</b>="<i>hover</i>"
<b>TYPE</b>="<i>type</i>"
<b>CASESENSITIVE</b>="<i>casesensitive</i>">
...
</<b>QUESTIONS</b>></pre>
INORDERIf set to "1", the questions will be presented to the user in the order that the %REFTO:QUESTION% elements are listed in the file. Defaults to random order.SCRAMBLEANSApplies to multiple-choice questions. If set to "1", the answers will be listed in a random order. Defaults to the order that the %REFTO:ANSWER% elements are listed in the file.SHOWSCOREIf set to "1", TQS will display score statistics for the current location, such as number tried, correct, wrong, and percent correct. Defaults to being hidden.HOVERIf set to "U", an answer will be underlined when the mouse hovers over it. Defaults to not underlining.TYPESpecifies the type of questions contained in this question set; does not apply to global settings. Can be one of the following values:<dl><dt><b>"MC"</b> (default)</dt><dd>Multiple-choice questions.</dd><dt><b>"TF"</b></dt><dd>True-false questions.</dd><dt><b>"BLANKS"</b></dt><dd>Type-in-answer questions.</dd><dt><b>"MIXED"</b></dt><dd>Questions of various types; each %REFTO:QUESTION% element's <i>TYPE</i> attribute specifies the type of each individual question.</dd></dl>CASESENSITIVEApplies to type-in-answer questions. If set to "1", answers are case-sensitive, where capitalization counts. Defaults to not case sensitive.The <b>QUESTIONS</b> element must be a child of a %REFTO:LOC% element whose <i>TYPE</i> attribute is set to <b>"QUESTIONS"</b>, or of the %REFTO:GLOBAL% element when specifying settings for all QUESTIONS locations.In TQS 2.0, the <i>SHOWSCORE</i> attribute is only used in global settings; <i>INORDER</i> and <i>SCRAMBLEANS</i> apply to both local and global settings. In version 2.1 and later, all <b>QUESTIONS</b> attributes are supported under both global settings and local settings.<GLOBAL>
<QUESTIONS
SHOWSCORE="1"
SCRAMBLEANS="1"
HOVER="U">
<CORRECT>Correct answer!</CORRECT>
<INCORRECT>Wrong answer!</INCORRECT>
</QUESTIONS>
</GLOBAL><LOC TYPE="QUESTIONS">
<QUESTIONS
INORDER="1"
SHOWSCORE="0">
<QUESTION>
...
</QUESTION>
<QUESTION>
...
</QUESTION>
...
</QUESTIONS>
</LOC>CORRECT ElementSpecifies text to be displayed when a question is answered correctly (%REFTO:QUESTIONS% location type only). Specifies a sound to be associated with a correct answer (all location types).<pre><<b>CORRECT</b>
<b>SOUND</b>="<i>sound</i>"><i>correct</i></<b>CORRECT</b>></pre>
SOUNDThe file name of a sound to be played when the answer or word is guessed correctly.<b>TQS 2.0, 2.1</b> The <b>CORRECT</b> element must be a child of the %REFTO:QUESTIONS% element, either inside of an individual location element or within global settings.<p><b>TQS 2.5</b> The <b>CORRECT</b> element can be a direct child of the %REFTO:GLOBAL% element, or can be used within these elements within a location or global settings: %REFTO:QUESTIONS% and %REFTO:HANGMAN%; or within these elements within global settings only: %REFTO:HTML% and %REFTO:CUSTOM_*%.By default, the string "Correct!" is displayed. There is no default sound.<p>When used as a direct child of the %REFTO:GLOBAL% element, the <b>CORRECT</b> element is only used to retrieve the <i>SOUND</i> attribute. The %REFTO:QUESTIONS% location retrieves the display text only when the <b>CORRECT</b> element is located within a %REFTO:QUESTIONS% element, either within a location or global settings.<p>The %REFTO:HANGMAN% location type will play sounds as specified by the <i>SOUND</i> attribute, but will not display any text.<p>With the %REFTO:HTML% and %REFTO:CUSTOM_*% location types, the sounds will not be used; you may invoke them by calling the %REFTO:playSound% function.<p>In order for any sounds to be played, the %REFTO:TQS% element's <i>USESSOUNDS</i> element must be set to "1".<p><b>TQS 2.5</b> The sound file must reside in the data root folder. This is, by default, the folder containing the .TQS file.<ul><li>The data root folder can be set with the %REFTO:TQS% element's <i>DATAROOT</i> attribute. To specify an absolute path, such as an Internet address, precede the path with <b>NOROOT?</b>.</li><li><b>TQS 2.6</b> To specify an embedded file, precede the path with <b>EMBED?</b>.</li></ul><CORRECT>Right answer!</CORRECT><GLOBAL>
<CORRECT SOUND="defcorrect.wav"/>
<INCORRECT SOUND="defincorrect.wav"/>
<QUESTIONS ...>
<CORRECT>Right answer!</CORRECT>
<INCORRECT>Wrong answer!</CORRECT>
</QUESTIONS>
<HANGMAN ...>
<CORRECT SOUND="hangcorrect.wav"/>
<INCORRECT SOUND="hangdead.wav"/>
</HANGMAN>
</GLOBAL>Use the %REFTO:playSound% function within your %REFTO:SCRIPT% code to invoke your custom correct and incorrect sounds.<GLOBAL>
...
<CUSTOM_FOO ...>
<CORRECT SOUND="foocorrect.wav"/>
<INCORRECT SOUND="fooincorrect.wav"/>
...
</CUSTOM_FOO>
</GLOBAL>INCORRECT ElementSpecifies text to be displayed when a question is answered incorrectly (%REFTO:QUESTIONS% location type only). Specifies a sound to be associated with an incorrect answer (all location types).<pre><<b>INCORRECT</b>
<b>INSERT</b>="<i>insert</i>"
<b>SOUND</b>="<i>sound</i>"><i>incorrect</i></<b>INCORRECT</b>></pre>
INSERTA sequence of characters that exists within the main incorrect string that will be replaced with the correct answer.SOUNDThe file name of a sound to be played when the answer or word is guessed incorrectly.<b>TQS 2.0, 2.1</b> The <b>INCORRECT</b> element must be a child of the %REFTO:QUESTIONS% element, either inside of an individual location element or within global settings.<p><b>TQS 2.5</b> The <b>INCORRECT</b> element can be a direct child of the %REFTO:GLOBAL% element, or can be used within these elements within a location or global settings: %REFTO:QUESTIONS% and %REFTO:HANGMAN%; or within these elements within global settings only: %REFTO:HTML% and %REFTO:CUSTOM_*%.By default, the string "Incorrect!" is displayed, without any correct answer. For multiple-choice questions, the correct answer will be the letter, not the answer string. There is no default sound.<p>When used as a direct child of the %REFTO:GLOBAL% element, the <b>INCORRECT</b> element is only used to retrieve the <i>SOUND</i> attribute. The %REFTO:QUESTIONS% location retrieves the display text only when the <b>INCORRECT</b> element is located within a %REFTO:QUESTIONS% element, either within a location or global settings.<p>The %REFTO:HANGMAN% location type will play sounds as specified by the <i>SOUND</i> attribute, but will not display any text.<p>With the %REFTO:HTML% and %REFTO:CUSTOM_*% location types, the sounds will not be used; you may invoke them by calling the %REFTO:playSound% function.<p>In order for any sounds to be played, the %REFTO:TQS% element's <i>USESSOUNDS</i> element must be set to "1".<p><b>TQS 2.5</b> The sound file must reside in the data root folder. This is, by default, the folder containing the .TQS file.<ul><li>The data root folder can be set with the %REFTO:TQS% element's <i>DATAROOT</i> attribute. To specify an absolute path, such as an Internet address, precede the path with <b>NOROOT?</b>.</li><li><b>TQS 2.6</b> To specify an embedded file, precede the path with <b>EMBED?</b>.</li></ul>In the following example, if the correct answer is <b>A</b> and the user selects <b>B</b>, TQS will display the following:<br><b>Wrong! The correct answer is A.</b><INCORRECT
INSERT="%s">Wrong! The correct answer is %s.</INCORRECT><GLOBAL>
<CORRECT SOUND="defcorrect.wav"/>
<INCORRECT SOUND="defincorrect.wav"/>
<QUESTIONS ...>
<CORRECT>Right answer!</CORRECT>
<INCORRECT>Wrong answer!</CORRECT>
</QUESTIONS>
<HANGMAN ...>
<CORRECT SOUND="hangcorrect.wav"/>
<INCORRECT SOUND="hangdead.wav"/>
</HANGMAN>
</GLOBAL>Use the %REFTO:playSound% function within your %REFTO:SCRIPT% code to invoke your custom correct and incorrect sounds.<GLOBAL>
...
<CUSTOM_FOO ...>
<CORRECT SOUND="foocorrect.wav"/>
<INCORRECT SOUND="fooincorrect.wav"/>
...
</CUSTOM_FOO>
</GLOBAL>QUESTION ElementContains the data for an individual question, either a multiple-choice, true-false, or type-in-answer question.<pre><<b>QUESTION</b>
<b>SOUND</b>="<i>sound</i>"
<b>TYPE</b>="<i>type</i>">
...
</<b>QUESTION</b>></pre>
SOUNDThe file name of a sound to be played when presenting this question.TYPESpecifies the type of question; is used when the <i>TYPE</i> attribute of the parent %REFTO:QUESTIONS% element is set to <b>"MIXED"</b>. Can be one of the following values:<dl><dt><b>"MC"</b> (default)</dt><dd>A multiple-choice question.</dd><dt><b>"TF"</b></dt><dd>A true-false question.</dd><dt><b>"BLANKS"</b></dt><dd>A type-in-answer question.</dd></dl>The <b>QUESTION</b> element must be a child of the %REFTO:QUESTIONS% element within an individual location element.The actual data for the question itself is stored within its child elements.<p>In order for any sounds to be played, the %REFTO:TQS% element's <i>USESSOUNDS</i> element must be set to "1".<p>The sound file must reside in the data root folder. This is, by default, the folder containing the .TQS file.<ul><li>The data root folder can be set with the %REFTO:TQS% element's <i>DATAROOT</i> attribute. To specify an absolute path, such as an Internet address, precede the path with <b>NOROOT?</b>.</li><li><b>TQS 2.6</b> To specify an embedded file, precede the path with <b>EMBED?</b>.</li></ul>Multiple-choice questions (default):<LOC TYPE="QUESTIONS">
<QUESTIONS>
<QUESTION>
<Q>What is the answer?</Q>
<ANSWER>Not this.</ANSWER>
<ANSWER>Not this either.</ANSWER>
<ANSWER CORRECT="1">This.</ANSWER>
</QUESTION>
...
</QUESTIONS>
</LOC>True-false questions:<LOC TYPE="QUESTIONS">
<QUESTIONS TYPE="TF">
<QUESTION>
<Q>Detroit is the capitol of Michigan.</Q>
<ANSWER>FALSE<ANSWER>
</QUESTION>
...
</QUESTIONS>
</LOC>Type-in-answer questions:<LOC TYPE="QUESTIONS">
<QUESTIONS TYPE="BLANKS">
<QUESTION>
<Q>What is the capitol of Michigan?</Q>
<ANSWER>Lansing<ANSWER>
</QUESTION>
...
</QUESTIONS>
</LOC>Mixed question types:<LOC TYPE="QUESTIONS">
<QUESTIONS TYPE="MIXED">
<QUESTION TYPE="MC">
<Q>What is the answer?</Q>
<ANSWER>Not this.</ANSWER>
<ANSWER>Not this either.</ANSWER>
<ANSWER CORRECT="1">This.</ANSWER>
</QUESTION>
<QUESTION TYPE="TF">
<Q>Detroit is the capitol of Michigan.</Q>
<ANSWER>FALSE<ANSWER>
</QUESTION>
<QUESTION TYPE="BLANKS">
<Q>What is the capitol of Michigan?</Q>
<ANSWER>Lansing<ANSWER>
</QUESTION>
...
</QUESTIONS>
</LOC><QUESTION SOUND="moo.wav">
<Q>What animal makes this sound?</Q>
<ANSWER CORRECT="1">Cow.</ANSWER>
<ANSWER>Horse.</ANSWER>
<ANSWER>Bird.</ANSWER>
</QUESTION>Q ElementContains the question that is presented to the user.<pre><<b>Q</b>><i>q</i></<b>Q</b>></pre>
The <b>Q</b> element must be a child of the %REFTO:QUESTION% element.The question can contain HTML tags, using proper XML notation.<QUESTION>
<Q>What is the answer?</Q>
<ANSWER>Not this.</ANSWER>
<ANSWER>Not this either.</ANSWER>
<ANSWER CORRECT="1">This.</ANSWER>
</QUESTION>The following question will be displayed as:<br>Is that your <i>final</i> answer?<Q>Is that your <i>final</i> answer?</Q>ANSWER ElementContains an individual answer for the question (multiple-choice); contains the correct answer (true-false, type-in-answer).<pre><<b>ANSWER</b>
<b>CORRECT</b>="<i>correct</i>"><i>answer</i></<b>ANSWER</b>></pre>
CORRECTApplies only to multiple-choice questions. If set to "1", specifies that this answer is the correct answer. For each question, one answer should be correct. Defaults to not correct.The <b>ANSWER</b> element must be a child of the %REFTO:QUESTION% element.Multiple-choice answers can contain HTML tags, using proper XML notation.<p>For true-false questions, the contents of this element should be <b>TRUE</b> or <b>FALSE</b>. For fill-in-answer questions, it must contain the correct answer. The %REFTO:QUESTIONS% element's <i>CASESENSITIVE</i> attribute can be set to "1" to indicate that answers are case-sensitive.Multiple-choice questions:<QUESTION>
<Q>What is the answer?</Q>
<ANSWER>Not this.</ANSWER>
<ANSWER>Not this either.</ANSWER>
<ANSWER CORRECT="1">This.</ANSWER>
</QUESTION>The following multiple-choice answer will be displayed as:<br>My <i>final</i> answer.<ANSWER>My <i>final</i> answer.</ANSWER>True-false questions:<QUESTIONS TYPE="TF">
<QUESTION>
<Q>Detroit is the capitol of Michigan.</Q>
<ANSWER>FALSE<ANSWER>
</QUESTION>
...
</QUESTIONS>Type-in-answer questions:<QUESTIONS TYPE="BLANKS">
<QUESTION>
<Q>What is the capitol of Michigan?</Q>
<ANSWER>Detroit<ANSWER>
</QUESTION>
...
</QUESTIONS>LIMG ElementSpecifies that this question has an accompanying image, which should appear to the left of the question.<pre><<b>LIMG</b>
<b>SRC</b>="<i>src</i>"
/></pre>
SRCThe name of the image file.The <b>LIMG</b> element must be a child of the %REFTO:QUESTION% element.The image file must reside in the data root folder. This is, by default, the folder containing the .TQS file.<ul><li><b>TQS 2.1</b> The data root folder can be set with the %REFTO:TQS% element's <i>DATAROOT</i> attribute. To specify an absolute path, such as an Internet address, precede the path with <b>NOROOT?</b>.</li><li><b>TQS 2.6</b> To specify an embedded file, precede the path with <b>EMBED?</b>.</li></ul><p>A question can have a left-side image (<b>LIMG</b>), a right-side image (%REFTO:RIMG%), both images, or neither.<QUESTION>
<Q>What animal is this?</Q>
<LIMG SRC="horse.gif"/>
<ANSWER CORRECT="1">Horse</ANSWER>
<ANSWER>Cow</ANSWER>
...
</QUESTION><LIMG
SRC="NOROOT?http://www.example.com/horse.gif"
/><LIMG
SRC="EMBED?horse.gif"
/>RIMG ElementSpecifies that this question has an accompanying image, which should appear to the right of the question.<pre><<b>RIMG</b>
<b>SRC</b>="<i>src</i>"
/></pre>
SRCThe name of the image file.The <b>RIMG</b> element must be a child of the %REFTO:QUESTION% element.The image file must reside in the data root folder. This is, by default, the folder containing the .TQS file.<ul><li><b>TQS 2.1</b> The data root folder can be set with the %REFTO:TQS% element's <i>DATAROOT</i> attribute. To specify an absolute path, such as an Internet address, precede the path with <b>NOROOT?</b>.</li><li><b>TQS 2.6</b> To specify an embedded file, precede the path with <b>EMBED?</b>.</li></ul><p>A question can have a left-side image (%REFTO:LIMG%), a right-side image (<b>RIMG</b>), both images, or neither.<QUESTION>
<Q>Where might you find these animals?</Q>
<LIMG SRC="horse.gif"/>
<RIMG SRC="cow.gif"/>
<ANSWER CORRECT="1">On a farm</ANSWER>
<ANSWER>In an office</ANSWER>
...
</QUESTION><RIMG
SRC="NOROOT?http://www.example.com/cow.gif"
/><RIMG
SRC="EMBED?cow.gif"
/>HANGMAN ElementContains the data for a location of type <b>"HANGMAN"</b>, in which the user is presented with the Hangman game and a series of words or phrases to guess.<pre><<b>HANGMAN</b>
<b>INORDER</b>="<i>inorder</i>"
<b>REPLACEIMG</b>="<i>replaceimg</i>"
<b>IMGPOS</b>="<i>imgpos</i>"
<b>CHARSET</b>="<i>charset</i>"
<b>SHOWSCORE</b>="<i>showscore</i>"
<b>IMGBASECOLOR</b>="<i>imgbasecolor</i>"
<b>IMGBODYCOLOR</b>="<i>imgbodycolor</i>">
...
</<b>HANGMAN</b>></pre>
INORDERIf set to "1", the words/phrases will be presented to the user in the order that the %REFTO:WORD% elements are listed in the file. Defaults to random order.REPLACEIMGIf set to "1", TQS will not use its built-in hangman graphics. Instead, it will use the images specified by the child %REFTO:IMG% elements. There must be at least two child %REFTO:IMG% elements for this setting to take effect.<p><b>TQS 2.8</b> If set to "0", the built-in graphics will be used. This can be used in a location to override <i>REPLACEIMG</i> specified at the global level.IMGPOSIf set to <b>"LEFT"</b>, TQS will display the hangman graphics to the left of the word and letter table. If set to <b>"RIGHT"</b> or if not specified, graphics will be on the right.CHARSETThe set of characters that the user can guess. These characters are choices in the table of letters, and all occurrences of these characters in hangman words will be replaced with a "-". The default character set is the 26-letter English alphabet, capital letters only.SHOWSCOREIf set to "1", TQS will display score statistics for the current location, such as number tried, correct, wrong, and percent correct. Defaults to being hidden.IMGBASECOLORThe color to use when drawing the hangman gallows. Defaults to "white". Ignored if replacement images are specified.IMGBODYCOLORThe color to use when drawing the hangman body. Defaults to "red". Ignored if replacement images are specified.The <b>HANGMAN</b> element must be a child of a %REFTO:LOC% element whose <i>TYPE</i> attribute is set to <b>"HANGMAN"</b>, or of the %REFTO:GLOBAL% element when specifying settings for all HANGMAN locations.In TQS 2.0, there are no global settings for the hangman location type. In versions 2.1 and later, all attributes, as well as the %REFTO:IMG% subelements, are supported in global settings.<p>Regardless of the characters specified by the <i>CHARSET</i> attribute, only the 26 letters of the English alphabet can be selected from the letter table using the keyboard.<p><b>Note:</b> In TQS, all special characters must be encoded using their numerical value. For example, to display the <b>Ü</b> character, you must use <b>&#220;</b> instead of <b>&Uuml;</b>.<GLOBAL>
<HANGMAN
REPLACEIMG="1">
<IMG SRC="hang1.gif"/>
<IMG SRC="hang2.gif"/>
...
</HANGMAN>
</GLOBAL><LOC TYPE="HANGMAN">
<HANGMAN
INORDER="1"
IMGPOS="LEFT"
CHARSET="ABCDEFGHIJKLMNOPQRSTUVWXYZÄÖÜ">
<WORD>ICH HÄTTE DAS GERN</WORD>
</HANGMAN>
</LOC><HANGMAN
IMGBASECOLOR="blue"
IMGBODYCOLOR="green">
...
</HANGMAN>
WORD ElementContains an individual hangman phrase, which is presented to the user.<pre><<b>WORD</b>><i>word</i></<b>WORD</b>></pre>
The <b>WORD</b> element must be a child of the %REFTO:HANGMAN% element within an individual location element.The contents of this element is not limited to a single word, but can be a phrase or sentence.<p>TQS will display the guessable characters of this word/phrase as hyphens; when the user selects a letter that is in the phrase, that letter will be displayed. In TQS 2.0, the set of guessable letters is the standard 26-letter English alphabet. In versions 2.1 and later, the <i>CHARSET</i> attribute of the %REFTO:HANGMAN% element may be used to specify an alternative character set.The following will be displayed as <b><nobr>-----</nobr> <nobr>-----</nobr> <nobr>----</nobr></b><HANGMAN>
<WORD>THREE BLIND MICE</WORD>
...
</HANGMAN>The following will be displayed as <b>3 <nobr>-lind</nobr> <nobr>-ice</nobr></b><HANGMAN>
<WORD>3 Blind Mice</WORD>
...
</HANGMAN>In TQS 2.1 and later, the following will be displayed as <b><nobr>----</nobr> <nobr>------------</nobr> <nobr>---</nobr></b><HANGMAN
CHARSET="ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789">
<WORD>1600 PENNSYLVANIA AVE</WORD>
...
</HANGMAN>IMG ElementSpecifies a replacement hangman image.<pre><<b>IMG</b>
<b>SRC</b>="<i>src</i>"
/></pre>
SRCThe name of the image file.An <b>IMG</b> element must be a child of the %REFTO:HANGMAN% element, either within a location or within global settings.By default, TQS uses eight hangman images to show the player's errors. This means that the seventh mistake brings death. When you use replacement images, you may use as many as you want; if you have <i>n</i> <b>IMG</b> elements, death will occur on the <i>n-1</i> mistake.<p>The parent %REFTO:HANGMAN% element must have its <i>REPLACEIMG</i> attribute set to <b>"1"</b> in order for the <b>IMG</b> elements to be used.<p>The image files must reside in the data root folder. This is, by default, the folder containing the .TQS file.<ul><li>The data root folder can be set with the %REFTO:TQS% element's <i>DATAROOT</i> attribute. To specify an absolute path, such as an Internet address, precede the path with <b>NOROOT?</b>.</li><li><b>TQS 2.6</b> To specify an embedded file, precede the path with <b>EMBED?</b>.</li></ul>The user will lose upon a fourth mistake:<HANGMAN REPLACEIMG="1">
<IMG SRC="hangnormal.gif"/>
<IMG SRC="hangbody.gif"/>
<IMG SRC="hanglegs.gif"/>
<IMG SRC="hangarms.gif"/>
<IMG SRC="hangdead.gif"/>
<WORD>...</WORD>
...
</HANGMAN><IMG
SRC="NOROOT?http://www.example.com/dead.gif"
/><IMG
SRC="EMBED?dead.gif"
/>HTML ElementContains the HTML code for a location of type <b>"HTML"</b>, in which you present data to the user with HTML.<pre><<b>HTML</b>
<b>SUBST</b>="<i>subst</i>"
<b>STATEONLOAD</b>="<i>stateonload</i>"
<b>SHOWSCORE</b>="<i>showscore</i>"
<b>ONLOAD</b>="<i>onload</i>">
...
</<b>HTML</b>></pre>
SUBST<b>TQS 2.1</b> Allows you to substitute the dynamic value %REFTO:DATAROOT% in the HTML code. The contents of the attribute must be in the form of "<i>string</i>,DATAROOT".<p><b>TQS 2.5</b> All TQS dynamic values are supported. The attribute must be in the form of "<i>string,dynval</i>"; multiple substitutions can be specified by joining them with a semicolon (;).STATEONLOADSpecifies the state that the location should be set to when it is invoked. The default is to set the state to <b>"PARTIAL"</b>; other values include <b>"EMPTY"</b>, <b>"DONE"</b>, and <b>"DONE100"</b>.SHOWSCOREIf set to "1", TQS will display score statistics for the current location, such as number tried, correct, wrong, and percent correct. You must use the scoring functions to manipulate the scores. Defaults to being hidden.ONLOADSpecifies JavaScript to be executed when TQS switches to the location. Can be set both within global settings and within individual location's <b>HTML</b> elements. If the location's <i>ONLOAD</i> attribute is present, its code will be executed instead of the code within global settings (that is, they are not both executed).<p>This attribute is analagous to the %REFTO:ONLOAD% element used by custom location types.The <b>HTML</b> element must be a child of a %REFTO:LOC% element whose <i>TYPE</i> attribute is set to <b>"HTML"</b>, or of the %REFTO:GLOBAL% element when specifying settings for all HTML locations.<b>TQS 2.7 and earlier</b> All <i>id</i> names, as well as any custom JavaScript variables or functions specified in event handlers, must begin with <b>"S_"</b>. This is not required as of TQS 2.8.<p>The entire contents, between <b><HTML></b> and <b></HTML></b>, will be inserted as HTML into the TQS window. This code must be XML compliant, meaning that:<ul><li>Every tag has a closing tag, whether or not it is required by HTML. For example, <b><BR></b> in HTML must be entered as <b><BR/></b>.</li><li>All attributes must be in quotes.</li></ul><p>For more information on TQS's state tracking and scoring capabilities, read the <a href="http://www.botproductions.com/tqs/tutorial.html?index=13">TQS Tutorial, Part XIII</a>.<HTML SUBST="%data%,DATAROOT">
<div align="center">
This is a HTML location.<br/>
<img src="%data%myimage.jpg" width="40"
height="30"/>
</div>
</HTML><HTML
STATEONLOAD="DONE"
SUBST="%data%,DATAROOT;%name%,USERNAME">
...
</HTML><HTML SUBST="%embed%,EMBEDROOT">
<div align="center">
Below is an embedded image.<br/>
<img src="%embed%myimage.jpg" width="40"
height="30"/>
</div>
</HTML>CUSTOM_* ElementContains all type-specific data for a location of type <b>"CUSTOM_*"</b>.<p>Note: "CUSTOM_*" is not the specific name of an element; it represents any custom-defined location type, such as <b>CUSTOM_FOO</b>, <b>CUSTOM_BAR</b>, etc.<p>Dependent upon the format you choose.
Dependent upon the format you choose.<br><br><b>TQS 2.5</b> The <i>SHOWSCORE</i> attribute is supported. If set to "1", TQS will display score statistics for the current location, such as number tried, correct, wrong, and percent correct. You must use the scoring functions to manipulate the scores. Defaults to being hidden.<b>CUSTOM_*</b> elements are used within the %REFTO:LOC% element to provide location-specific data, and may be used within the %REFTO:GLOBAL% element to provide global settings.All data specific to a particular location, but for a given <b>CUSTOM_*</b> type, goes under the <b>CUSTOM_*</b> element. How this data is organized and used is up to you, the author of the custom location type.<LOC
ID="1"
TYPE="CUSTOM_FOO">
<CUSTOM_FOO>
<FOOHOLDER>
<FOO BAR="Foo 1"/>
<FOO BAR="Foo 2"/>
</FOOHOLDER>
</CUSTOM_FOO>
</LOC><GLOBAL>
<CUSTOM_FOO COLOR="#FF00FF">
<BAR COLOR="#00FF00"/>
</CUSTOM_FOO>
</GLOBAL>FINISH ElementContains text and/or one or more buttons that are displayed when the user "completes" a location.<pre><<b>FINISH</b>
<b>PROMPT</b>="<i>prompt</i>">
...
</<b>FINISH</b>></pre>
PROMPTText string to display to the user.The <b>FINISH</b> element must be a child of the %REFTO:LOC% element, or of the %REFTO:GLOBAL% element when specifying settings for all locations.Built-in location types, such as Questions and Hangman, display a button after each question or word which takes the user to the next question or word. When no questions or words remain, TQS will, by default, not display anything. Any buttons and/or text specified in the <b>FINISH</b> element will be displayed.<p>The <i>PROMPT</i> string can contain HTML markup.<FINISH PROMPT="You have finished my Hangman game!
<br>Use the Main Menu button to continue."/><LOC ID="1">
<FINISH>
<BUTTON TITLE="Play again" TARGET="1"/>
<BUTTON TITLE="Return to menu" TARGET="0"/>
...
</FINISH>
...
</LOC><GLOBAL>
<FINISH>
<BUTTON
TITLE="Restart"
TARGET="LOCPOS:0,LOCPOS:1"
APPLIESTO="GREATER"
GREATER="LOCPOS:1&gt;0"
/>
<BUTTON
TITLE="Back to Menu"
TARGET="LOCPOS:0,0"
APPLIESTO="GREATER"
GREATER="LOCPOS:1&gt;0"
/>
</FINISH>
...
</GLOBAL>CUSTOM ElementContains definitions of all custom location types.<pre><<b>CUSTOM</b>>
...
</<b>CUSTOM</b>></pre>
The <b>CUSTOM</b> element must be a child of the %REFTO:TQS% element.<CUSTOM>
<CUSTOMDIV ...>
...
</CUSTOMDIV>
<CUSTOMDIV ...>
...
</CUSTOMDIV>
...
</CUSTOM>CUSTOMDIV ElementContains the definition of a custom location type.<pre><<b>CUSTOMDIV</b>
<b>NAME</b>="<i>name</i>">
...
</<b>CUSTOMDIV</b>></pre>
NAMEThe name of this location type; must begin with <b>"CUSTOM_"</b>.The <b>CUSTOMDIV</b> element must be a child of the %REFTO:CUSTOM% element.A %REFTO:LOC% element that has its <i>TYPE</i> attribute set to this name contains all of its data inside its subelement of this name.<CUSTOMDIV NAME="CUSTOM_FOO">
...
</CUSTOMDIV>A location of this type would look as following:<LOC
ID="1"
TYPE="CUSTOM_FOO">
<CUSTOM_FOO>
...
</CUSTOM_FOO>
</LOC>DIVCODE ElementSpecifies the HTML code that visually makes up the custom location type.<pre><<b>DIVCODE</b>
<b>XMLCOMPLIANT</b>="<i>xmlcompliant</i>">
...
</<b>DIVCODE</b>></pre>
XMLCOMPLIANTIf set to "1", means that the HTML code is valid XML code. This means:<ul><li>Every tag has a closing tag, whether or not it is required by HTML. For example, <b><BR></b> in HTML must be entered as <b><BR/></b>.</li><li>All attributes must be in quotes.</li></ul><p>Defaults to not compliant.The <b>DIVCODE</b> element must be a child of the %REFTO:CUSTOMDIV% element.No child elements will be interpreted by TQS.<b>TQS 2.7 and earlier</b> All <i>id</i> and <i>class</i> names, as well as any JavaScript variables or functions specified in event handlers, must begin with <b>"S_"</b>. This is not required as of TQS 2.8.<p>To avoid potential display problems, you should break to a new line only within an HTML beginning or ending tag.<p>Unless the code is XML compliant as stated above, the script contents must use <b>&gt;</b> and <b>&lt;</b> instead of <b>></b> and <b><</b>, respectively, in all cases.<p>It is recommended that you test your HTML code in a standard web page before using it in a TQS application. Then, once it works, you can use find and replace to perform the above step (if non-XML compliant), and you can put the line breaks where they work for you.The following shows how to use non-XML compliant code:<DIVCODE>
<SPAN ID="matchingChoicesSpan"></SPAN
><H3 ID="matchingQuestionSpan"
></H3><H3 ID="matchingStatus"
> </H3><SPAN ID="bottomButtons"
><BR><BUTTON ID="matchNextButton"
onclick="loadMatchQuestion(0);"
STYLE="visibility:hidden"
>Next Question</BUTTON></SPAN>
</DIVCODE>The following code is equivalent, but XML compliant:<DIVCODE XMLCOMPLIANT="1">
<SPAN ID="matchingChoicesSpan"></SPAN
><H3 ID="matchingQuestionSpan"
></H3><H3 ID="matchingStatus"
> </H3><SPAN ID="bottomButtons"
><BR><BUTTON ID="matchNextButton"
onclick="loadMatchQuestion(0);"
STYLE="visibility:hidden"
>Next Question</BUTTON></SPAN>
</DIVCODE>ONLOAD ElementSpecifies JavaScript to be executed when TQS switches to a location of this type.<pre><<b>ONLOAD</b>>
...
</<b>ONLOAD</b>></pre>
The <b>ONLOAD</b> element must be a child of the %REFTO:CUSTOMDIV% element.Script within this element and the %REFTO:SCRIPT% element may use the script variables and functions described in the reference.<p>It is recommended that the <b>ONLOAD</b> script calls a function defined in the %REFTO:SCRIPT% element.<p><b>TQS 2.7 and earlier</b> All variables, functions, and any other identifiers must begin with <b>"S_"</b>. This is not required as of TQS 2.8.<p>The script contents must use <b>&gt;</b> and <b>&lt;</b> instead of <b>></b> and <b><</b>, respectively.<p>Only JavaScript may be used.<ONLOAD>
loadFirstQuestion();
</ONLOAD>SCRIPT ElementSpecifies JavaScript that contains functions and variables that implement the custom location type.<pre><<b>SCRIPT</b>>
...
</<b>SCRIPT</b>></pre>
The <b>SCRIPT</b> element must be a child of the %REFTO:CUSTOMDIV% element.Script within this element and the %REFTO:ONLOAD% element may use the script variables and functions described in the reference.<p><b>TQS 2.7 and earlier</b> All variables, functions, and any other identifiers must begin with <b>"S_"</b>. In multiple custom location types, you can use the same variable, S_foo, but they will not be the same; each location type's variables are specific to it. This is not required as of TQS 2.8; TQS will automatically manage the separation of location types' identifiers.<p>Applications marked to require TQS 2.1 can use the variable <b>dataRoot</b> within the script to refer to the data root path. Version 2.5 and newer applications should use the %REFTO:getDynVal% function.<p>The script contents must use <b>&gt;</b> and <b>&lt;</b> instead of <b>></b> and <b><</b>, respectively.<p>Only JavaScript may be used.This sample shows some of the basics of how to use a custom script.<SCRIPT>
var numCorrect = 0;
var numWrong = 0;
var curQuestion = 0;
var questionsUsed = new Array();
// more variables as needed
function loadFirstQuestion()
{
numQuestionsSpan.innerText =
"Number of questions: " +
xmlNumChildOf(xmlLocData, "QUEST");
// remainder of implementation
}
function loadQuestion()
{
imgEl.src = getDynVal("DATAROOT")+"img.gif";
// remainder of implementation
}
function handleMouseEvent(evt)
{
switch(evt)
{
// handle different events
}
}
// more functions as needed
</SCRIPT>STYLES ElementContains style sheet definitions that apply to this custom location type.<pre><<b>STYLES</b>
<b>SUBST</b>="<i>subst</i>">
...
</<b>STYLES</b>></pre>
SUBSTSpecifies a semicolon-deliminated list of substitution values. A substitution value is in the form of <i>string,dynval</i> where all instances of <i>string</i> are replaced with the specified dynamic value.The <b>STYLES</b> element must be a child of the %REFTO:CUSTOMDIV% element.<STYLES>
<STYLE .../>
<STYLE .../>
</STYLES>Using the <i>SUBST</i> attribute is useful for specifying graphics for bulleted lists.<STYLES SUBST="%DATA%,DATAROOT">
<STYLE
NAME="#myClass UL"
STYLEENTRY="list-style-image:url(%DATA%bullet.gif)"
/>
...
</STYLES><STYLES SUBST="%EMBED%,EMBEDROOT">
<STYLE
NAME="#myClass UL"
STYLEENTRY="list-style-image:url(%EMBED%bullet.gif)"
/>
...
</STYLES>STYLE ElementContains a specific cascading style sheet (CSS) entry for this custom location type.<pre><<b>STYLE</b>
<b>NAME</b>="<i>name</i>"
<b>STYLEENTRY</b>="<i>styleentry</i>"
/></pre>
NAMEThe name of the CSS selector. TQS allows you to specify an individual element by using <b>"#elementID"</b> or a class of elements by using <b>".elementClass"</b>.STYLEENTRYThe rule to be applied to the element or class specified in <i>NAME</i>.The <b>STYLE</b> element must be a child of the %REFTO:STYLES% element.<b>TQS 2.7 and earlier</b> The <b>"S_"</b> prefix is required in the <i>NAME</i> attribute. This is not required as of TQS 2.8.<STYLES>
<STYLE
NAME="#questionSpan"
STYLEENTRY="font-size:larger; color:green"
/>
<STYLE
NAME=".answerHover"
STYLEENTRY="cursor:hand; color:#00FFFF"
/>
</STYLES>FILES ElementContains files that are embedded within the TQS XML document.<pre><<b>FILES</b>>
...
</<b>FILES</b>></pre>
The <b>FILES</b> element must be a child of the %REFTO:TQS% element.Do not create or edit this element directly. Use the TQS Embed Utility to add and remove files from TQS applications.<FILES>
<FILE NAME="file1.gif">/9j/4AAQSkZJ ...</FILE>
<FILE NAME="file2.gif">2wBDAQMEBAUE ...</FILE>
...
</FILES>FILE ElementContains an embedded file.<pre><<b>FILE</b>
<b>NAME</b>="<i>name</i>">
...
</<b>FILE</b>></pre>
NAMESpecifies the name assigned to the embedded file.The <b>FILE</b> element must be a child of the %REFTO:FILES% element.The text content of a <b>FILE</b> element is the contents of the embedded file itself, encoded in Base64 format.<p>Do not create or edit this element directly. Use the TQS Embed Utility to add and remove files from TQS applications, and to rename existing files.<p>TQS can automatically load graphics and sounds from embedded files by prefixing the file name with <b>EMBED?</b>. For use in HTML or custom locations, use the dynamic value %REFTO:EMBEDROOT% to retrieve the necessary URL prefix.<FILE NAME="new.gif">R0lGODlhHwAMALMAAP//AP///wAAMwAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
AAAAAAAAAAAAAAAAAAAAACH5BAEAAAEALAAAAAAfAAwAAAQ+MMhJq7046y2F
/2AIbmJpah7wqUDLgqqACm1Kw7ic2a/LvzqMjQZMuWrBy/AWWy1nTZbvRk1a
TNjRLFuyRAAAOw==</FILE>LOCPOS Dynamic ValueSpecifies a specific position of the current location.<pre><b>LOCPOS</b>:<i>digit</i></pre>
The format of a location is <i>digit1</i>,<i>digit2</i>,...,<i>digitn</i>. <b>LOCPOS:0</b> is equal to <i>digit1</i>, <b>LOCPOS:1</b> is equal to <i>digit2</i>, etc.In this example, the program is divided into chapters, and each chapter has a menu and several other sublocations. This global button defines a "Chapter <i>X</i> Menu" button to appear in each of the chapter's sublocations but not the chapter's menu (that is, when the second digit of the location is greater than zero):<BUTTON
TITLE="Chapter %s Menu"
SUBST="%s,LOCPOS:0"
TARGET="LOCPOS:0,0"
APPLIESTO="GREATER"
GREATER="LOCPOS:1>0"
/>DATAROOT Dynamic ValueSpecifies the data root path.<pre><b>DATAROOT</b></pre>
The data root path defaults to the folder that contains this TQS application file, including an ending backslash. It can be changed to, for example, a web site directory through the use of the <i>DATAROOT</i> attribute of the %REFTO:TQS% element.If the currently located TQS application is:<br><b>C:\TQS Applications\My App.tqs</b><br>and no <i>DATAROOT</i> attribute exists in the %REFTO:TQS% element, then <b>DATAROOT</b> will be equal to:<br><b>C:\TQS Applications\</b><LOC TYPE="HTML">
<HTML SUBST="%DATA%,DATAROOT">
<IMG SRC="%DATA%img.jpg"/>
</HTML>
</LOC>TQS will change the HTML code into:<IMG SRC="C:\TQS Applications\img.jpg"/>Here, <b>DATAROOT</b> will be equal to:<br><b>http://www.example.com/tqsdata/</b><TQS
VERSION="2.1"
DATAROOT="http://www.example.com/tqsdata/">
...
<LOCATIONS ...>
<LOC TYPE="HTML">
<HTML SUBST="%DATA%,DATAROOT">
<IMG SRC="%DATA%img.jpg"/>
</HTML>
</LOC>
...
</LOCATIONS>
</TQS>TQS will change the HTML code into:<IMG SRC="http://www.example.com/tqsdata/img.jpg"/>USERNAME Dynamic ValueSpecifies name of the current user, as the user typed it in.<pre><b>USERNAME</b></pre>
The user name is collected when the %REFTO:REPORT% element's <i>GETNAME</i> attribute is set to <b>"1"</b>.This global finish button uses the <b>USERNAME</b> dynamic value to congratulate the user and go back to a menu:<REPORT GETNAME="1" ...>
...
</REPORT>
<GLOBAL>
...
<FINISH>
<BUTTON
TITLE="Good job, %U! Back to Main Menu."
SUBST="%U,USERNAME"
TARGET="0"
APPLIESTO="ALL"
/>
</FINISH>
</GLOBAL>EMBEDROOT Dynamic ValueSpecifies the URL prefix that must be used to reference embedded files.<pre><b>EMBEDROOT</b></pre>
Files embedded in a TQS application are accessed via a special URL protocol and a path containing a unique identifier. In order for HTML and custom locations to correctly refer to these files, they must be able to prefix the file names with the necessary URL protocol and path. The <b>EMBEDROOT</b> dynamic value contains this path, with a trailing slash.<LOC TYPE="HTML">
<HTML SUBST="%EMB%,EMBEDROOT">
<IMG SRC="%EMB%img.jpg"/>
</HTML>
</LOC>If the <b>EMBEDROOT</b> value is <b>bmwscxml://{D3A89AD6-C02C-4FDB-84C4-30A26F0C4691}/</b>, then TQS will change the HTML code into:<IMG SRC="bmwscxml://{D3A89AD6-C02C-4FDB-84C4-30A26F0C4691}/img.jpg"/>xmlNumChildOf FunctionReturns the number of child XML elements that have a given element tag name.<pre>value = <b>xmlNumChildOf</b>(el, tagName);</pre>
elXML parent object.tagNameThe element tag name.Returns the number of child elements of the specified name; zero if none exist.The variable <i>numFoos</i> will equal 2.<CUSTOM_FOO>
<FOOHOLDER>
<FOO BAR="Foo 1"/>
<FOO BAR="Foo 1"/>
</FOOHOLDER>
</CUSTOM_FOO>numFoos = xmlNumChildOf(xmlChildOf
(xmlLocData, "FOOHOLDER", 0), "FOO", 0);The HTML element <i>spanFoo</i> will contain the following:<br><b>Inside Foo 1... Inside Foo 2... Inside Foo 3... </b><CUSTOM_FOO>
<FOO>Inside Foo 1</FOO>
<FOO>Inside Foo 2</FOO>
<FOO>Inside Foo 3</FOO>
</CUSTOM_FOO>for(i = 0;
i < xmlNumChildOf(xmlLocData, "FOO");
i++)
{
foo = xmlChildOf(xmlLocData, "FOO", i);
spanFoo.insertAdjacentText("beforeEnd",
foo.text + "... ");
}xmlChildOf FunctionReturns a specific child XML element of another XML element.<pre>xmlEl = <b>xmlChildOf</b>(el, tagName, index);</pre>
elXML parent object.tagNameThe element tag name.indexZero-based index of which element to return, if multiple elements have the same tag name.Returns the specified XML element, or a null reference if it does not exist.The HTML element <i>spanBar</i> will display <b>Inside Bar</b>.<CUSTOM_FOO>
<FOO>
<BAR>Inside Bar</BAR>
</FOO>
</CUSTOM_FOO>fooEl = xmlChildOf(xmlLocData, "FOO", 0);
barEl = xmlChildOf(fooEl, "BAR", 0);
spanBar.innerText = barEl.text;The HTML element <i>spanFoo</i> will contain the following:<br><b>Inside Foo 1... Inside Foo 2... Inside Foo 3... </b><p>Both script fragments achieve the same result.<CUSTOM_FOO>
<FOO>Inside Foo 1</FOO>
<FOO>Inside Foo 2</FOO>
<FOO>Inside Foo 3</FOO>
</CUSTOM_FOO>foo = xmlChildOf(xmlLocData, "FOO", 0);
spanFoo.insertAdjacentText("beforeEnd",
foo.text + "... ");
foo = xmlChildOf(xmlLocData, "FOO", 1);
spanFoo.insertAdjacentText("beforeEnd",
foo.text + "... ");
foo = xmlChildOf(xmlLocData, "FOO", 2);
spanFoo.insertAdjacentText("beforeEnd",
foo.text + "... ");for(i = 0;
i < xmlNumChildOf(xmlLocData, "FOO");
i++)
{
foo = xmlChildOf(xmlLocData, "FOO", i);
spanFoo.insertAdjacentText("beforeEnd",
foo.text + "... ");
}xmlAttr FunctionReturns the value of an XML element's attribute.<pre>value = <b>xmlAttr</b>(el, attr, defVal);</pre>
elXML element object which contains the attribute.attrThe name of the attribute.defValThe value to return if the attribute does not exist.Returns the value of the attribute, or <i>defVal</i> if the attribute does not exist.The variable <i>center</i> will be set to "1".<CUSTOM_FOO CENTER="1">
...
</CUSTOM_FOO>var center = xmlAttr(xmlLocData, "CENTER", 0);The HTML element <i>spanFoo</i> will display <b>Foo Value</b>, while <i>spanBar</i> will display <b>No Bar specified</b>.<CUSTOM_FOO>
<FOO
FOO="Foo Value"
/>
</CUSTOM_FOO>xmlEl = xmlChildOf(xmlLocData, "FOO", 0);
spanFoo.innerText = xmlAttr(xmlEl, "FOO",
"No Foo specified");
spanBar.innerText = xmlAttr(xmlEl, "BAR",
"No Bar specified");xmlRetrieve FunctionGets data from a specified path of elements, starting at the root.<pre>value = <b>xmlRetrieve</b>(elPath, defVal, index, retrNum);</pre>
elPathThe path to the element or attribute to be retrieved. This is in the form of <i>childEl/childEl/.../childEl</i>:<i>attr</i>. Each <i>childEl</i> is an element tag name; the <i>:attr</i> portion, optional, specifies the name of the attribute of the last <i>childEl</i> that should be returned.defValThe default value to return if one of the elements in the path, or the attribute, does not exist.indexIf the more than one element at the end of the path exists with the same name, this specifies the zero-based index of which element to use.retrNumIf equal to 1, the function will return the number of elements at the end of the path with the specified element tag name.Returns either the number of elements, the contents of an element, or an attribute value, based on the parameters.An attribute can only be specified at the end of a path.<p>The %REFTO:xmlRetrieveEx% function performs the same operations, but with more flexibility.The HTML element <i>spanFoo</i> will display <b>Default Global Foo</b>, while <i>spanBar</i> will display <b>Inside Global Bar</b>.<GLOBAL>
<CUSTOM_FOO>
<BAR>Inside Global Bar</BAR>
</CUSTOM_FOO>
</GLOBAL>spanFoo.innerText = xmlRetrieve(
"GLOBAL/CUSTOM_FOO/FOO", "Default Global Foo",
0, 0);
spanBar.innerText = xmlRetrieve(
"GLOBAL/CUSTOM_FOO/BAR", "Default Global Bar",
0, 0);The HTML element <i>spanFoo</i> will have the color <b>#FF00FF</b>, while <i>spanBar</i> will have the color <b>#00FF00</b>.<GLOBAL>
<CUSTOM_FOO COLOR="#FF00FF">
<BAR COLOR="#00FF00"/>
</CUSTOM_FOO>
</GLOBAL>spanFoo.style.color = xmlRetrieve(
"GLOBAL/CUSTOM_FOO:COLOR", "#000000", 0, 0);
spanBar.style.color = xmlRetrieve(
"GLOBAL/CUSTOM_FOO/BAR:COLOR", "#FFFFFF", 0, 0);The HTML element <i>spanBar</i> will display <b>Bar 1... Default... Bar 3... </b>. Both script fragments achieve the same result.<GLOBAL>
<CUSTOM_FOO>
<BAR VALUE="Bar 1"/>
<BAR/>
<BAR VALUE="Bar 3"/>
</CUSTOM_FOO>
</GLOBAL>val = xmlRetrieve("GLOBAL/CUSTOM_FOO/BAR:VALUE",
"Default", 0, 0);
spanBar.insertAdjacentText("beforeEnd",
val + "... ");
val = xmlRetrieve("GLOBAL/CUSTOM_FOO/BAR:VALUE",
"Default", 1, 0);
spanBar.insertAdjacentText("beforeEnd",
val + "... ");
val = xmlRetrieve("GLOBAL/CUSTOM_FOO/BAR:VALUE",
"Default", 2, 0);
spanBar.insertAdjacentText("beforeEnd",
val + "... ");numBars = xmlRetrieve("GLOBAL/CUSTOM_FOO/BAR",
"", 0, 1);
for(i = 0; i < numBars; i++)
{
val = xmlRetrieve(
"GLOBAL/CUSTOM_FOO/BAR:VALUE", "Default",
i, 0);
spanBar.insertAdjacentText("beforeEnd",
val + "... ");
}xmlRetrieveEx FunctionGets the XML data from a specified element or attribute.<pre>value = <b>xmlRetrieveEx</b>(elStart, elPath, attr,
defVal, retrNum);</pre>
elStartThe XML element to start at when finding the appropriate data. The following values have special meaning:<dl><dt><b>null</b></dt><dd>Start at the root element of the document (the %REFTO:TQS% element).</dd><dt>%REFTO:xmlLocData%</dt><dd>Start at the current location's type-specific data element (the %REFTO:CUSTOM_*% element).</dd><dt>%REFTO:xmlCurLoc%</dt><dd>Start at the current location's element (the %REFTO:LOC% element).</dd></dl>elPathThe path to the element or attribute to be retrieved. This is in the form of <i>childEl[x]/childEl[y]/.../childEl[z]</i>. Each <i>childEl</i> is an element tag name; the number in brackets specifies the zero-based index of each element to use.attrThe name of the attribute of the last element of the path. To specify that the contents of the element should be returned, pass "".defValThe default value to return if one of the elements in the path, or the attribute, does not exist.retrNumIf equal to 1, the function will return the number of elements at the end of the path with the specified element tag name.Returns either the number of elements, the contents of an element, or an attribute value, based on the parameters.The %REFTO:xmlRetrieve% function performs the same operations, but with less flexibility.The HTML element <i>spanFoo</i> will display <b>Default Global Foo</b>, while <i>spanBar</i> will display <b>Inside Global Bar</b>.<GLOBAL>
<CUSTOM_FOO>
<BAR>Inside Global Bar</BAR>
</CUSTOM_FOO>
</GLOBAL>spanFoo.innerText = xmlRetrieveEx(null,
"GLOBAL[0]/CUSTOM_FOO[0]/FOO[0]", "",
"Default Global Foo", 0);
spanBar.innerText = xmlRetrieveEx(null,
"GLOBAL[0]/CUSTOM_FOO[0]/BAR[0]", "",
"Default Global Bar", 0);The HTML element <i>spanFoo</i> will have the color <b>#FF00FF</b>, while <i>spanBar</i> will have the color <b>#00FF00</b>.<GLOBAL>
<CUSTOM_FOO COLOR="#FF00FF">
<BAR COLOR="#00FF00"/>
</CUSTOM_FOO>
</GLOBAL>spanFoo.style.color = xmlRetrieveEx(null,
"GLOBAL[0]/CUSTOM_FOO[0]", "COLOR",
"#000000", 0);
spanBar.style.color = xmlRetrieveEx(null,
"GLOBAL[0]/CUSTOM_FOO[0]/BAR[0]", "COLOR",
"#FFFFFF", 0, 0);The HTML element <i>spanHead</i> will contain <b>Foo</b>; the element <i>spanBar</i> will display <b>Bar 1... Default... Bar 3... </b>. Both script fragments achieve the same result.<LOC ID="3" TYPE="CUSTOM_FOO">
<HEADING>Foo</HEADING>
<CUSTOM_FOO>
<BARS>
<BAR VALUE="Bar 1"/>
<BAR/>
<BAR VALUE="Bar 3"/>
</BARS>
</CUSTOM_FOO>
</LOC>spanHead.innerText = xmlRetrieveEx(xmlCurLoc,
"HEADING[0]", "", "No Heading", 0);
val = xmlRetrieveEx(xmlLocData,
"BARS[0]/BAR[0]", "VALUE", "Default", 0);
val += "... ";
val += xmlRetrieveEx(xmlLocData,
"BARS[0]/BAR[1]", "VALUE", "Default", 0);
val += "... ";
val += xmlRetrieveEx(xmlLocData,
"BARS[0]/BAR[2]", "VALUE", "Default", 0);
val += "... ";
spanBar.innerText = val;spanHead.innerText = xmlRetrieveEx(xmlCurLoc,
"HEADING[0]", "", "No Heading", 0);
numBars = xmlRetrieveEx(xmlLocData,
"CUSTOM_FOO[0]/BAR", "", 0, 1);
val = "";
for(i = 0; i < numBars; i++)
{
val += xmlRetrieveEx(xmlLocData,
"BARS[0]/BAR["+i+"]", "VALUE",
"Default", 0);
val += "... ";
}
spanBar.innerText = val;xmlSetAttr FunctionSets the value of an XML element's attribute.<pre><b>xmlSetAttr</b>(el, attr, val);</pre>
elXML element object which contains the attribute.attrThe name of the attribute.valThe value to which the attribute should be set.There is no return value.Use this function to manipulate your custom data, for instance to keep track of the status of questions as you present them.<CUSTOM_FOO>
<FOOQUESTION>
...
</FOOQUESTION>
<FOOQUESTION>
...
</FOOQUESTION>
...
</CUSTOM_FOO>xmlSetAttr(xmlChildOf(xmlLocData, "FOOQUESTION", 0),
"STATUS", "CORRECT");xmlGetText FunctionReturns the text contents of an XML element.<pre>value = <b>xmlGetText</b>(el, defVal);</pre>
elXML element object whose contents are to be retrieved.defValThe value to return if the element does not exist or is empty.Returns the contents of the element, or <i>defVal</i> if the element does not exist or is empty.Using this function instead of the <b>text</b> property of XML element objects allows you to handle a default value if the element does not exist.The HTML element <i>spanFoo</i> will contain <b>Custom Foo Contents</b>, while the element <i>spanBar</i> will contain <b>Default Bar Contents</b>.<CUSTOM_FOO>
<FOO>Custom Foo Contents</FOO>
</CUSTOM_FOO>spanFoo.innerText = xmlGetText(xmlChildOf(
xmlLocData, "FOO", 0), "Default FOO contents.");
spanBar.innerText = xmlGetText(xmlChildOf(
xmlLocData, "BAR", 0), "Default BAR contents.");xmlSetText FunctionSets the text contents of an XML element.<pre><b>xmlSetText</b>(el, val);</pre>
elXML element object whose contents are to be set.valThe value to which the contents should be set.There is no return value.Use this function to manipulate your custom data, for instance to keep track of the status of questions as you present them.<p>Using this function instead of the <b>text</b> property of XML element objects protects you from scripting errors if the element does not exist.<CUSTOM_FOO>
<FOOQUESTION>
<STATUS/>
</FOOQUESTION>
<FOOQUESTION>
<STATUS/>
</FOOQUESTION>
...
</CUSTOM_FOO>xmlSetText(xmlChildOf(xmlChildOf(xmlLocData,
"FOOQUESTION", 0), "STATUS", 0), "CORRECT");
xmlSetText(xmlChildOf(xmlChildOf(xmlLocData,
"FOOQUESTION", 0), "NOEXIST", 0), "CORRECT");getLocState FunctionRetrieves the state of a specific location.<pre>value = <b>getLocState</b>('<i>location</i>'.split(','));</pre>
locationThe location whose state is to be retrieved.Returns one of the following state values:<dl><dt><b>"EMPTY"</b></dt><dd>The location has not been visited.</dd><dt><b>"PARTIAL"</b></dt><dd>The location has been visited but not completed.</dd><dt><b>"DONE"</b></dt><dd>The location has been completed.</dd><dt><b>"DONE100"</b></dt><dd>The location has been completed with a score of 100%.</dd></dl>Use the %REFTO:getCurLocState% function to retrieve the state of the current location.state = getLocState("April,0".split(','));
if((state != "DONE") &&
(state != "DONE100"))
{
spanStatus.innerText =
"You must complete April Questions first.";
spanAll.style.display = "none";
} else
spanAll.style.display = "";setLocState FunctionSets the state of a specific location.<pre><b>setLocState</b>('<i>location</i>'.split(','), newState);</pre>
locationThe location whose state is to be set.newStateThe new state for the location. Can be one of the following values:<dl><dt><b>"EMPTY"</b></dt><dd>The location has not been visited.</dd><dt><b>"PARTIAL"</b></dt><dd>The location has been visited but not completed.</dd><dt><b>"DONE"</b></dt><dd>The location has been completed.</dd><dt><b>"DONE100"</b></dt><dd>The location has been completed with a score of 100%.</dd></dl>There is no return value.Use the %REFTO:setCurLocState% function to change the state of the current location.if(sectionChosen == 1)
setLocState("April,1".split(','), "DONE");
else
setLocState("April,0".split(','), "DONE");getCurLocState FunctionRetrieves the state of the current location.<pre>value = <b>getCurLocState</b>();</pre>
Returns one of the following state values:<dl><dt><b>"EMPTY"</b></dt><dd>The location has not been visited.</dd><dt><b>"PARTIAL"</b></dt><dd>The location has been visited but not completed.</dd><dt><b>"DONE"</b></dt><dd>The location has been completed.</dd><dt><b>"DONE100"</b></dt><dd>The location has been completed with a score of 100%.</dd></dl>state = getCurLocState();
if((state == "DONE") || (state == "DONE100"))
{
spanStatus.innerText =
"You have already completed this section.";
spanAll.style.display = "none";
} else
spanAll.style.display = "";setCurLocState FunctionSets the state of the current location.<pre><b>setCurLocState</b>(newState);</pre>
newStateThe new state for the location. Can be one of the following values:<dl><dt><b>"EMPTY"</b></dt><dd>The location has not been visited.</dd><dt><b>"PARTIAL"</b></dt><dd>The location has been visited but not completed.</dd><dt><b>"DONE"</b></dt><dd>The location has been completed.</dd><dt><b>"DONE100"</b></dt><dd>The location has been completed with a score of 100%.</dd></dl>There is no return value.Use this function when the user has completed your custom location.if(numWrong == 0)
setCurLocState("DONE100");
else
setCurLocState("DONE");getStateImg FunctionRetrieves the path of the image file used to represent a given state.<pre>path = <b>getStateImg</b>(state);</pre>
stateThe state whose image should be returned. Can be one of the following values:<dl><dt><b>"EMPTY"</b></dt><dd>The location has not been visited.</dd><dt><b>"PARTIAL"</b></dt><dd>The location has been visited but not completed.</dd><dt><b>"DONE"</b></dt><dd>The location has been completed.</dd><dt><b>"DONE100"</b></dt><dd>The location has been completed with a score of 100%.</dd></dl>The path of the image file is returned.Regardless of whether the image is the built-in state image, or a custom image set through the %REFTO:STATEIMG% element, the returned path name includes the required path for TQS to display the image.<p>The functions %REFTO:getLocState% and %REFTO:getCurLocState% can be used to retrieve the states of locations.myImgEl.src = getStateImg("DONE");myImgEl.src = getStateImg(getCurLocState());setScoreValue FunctionSets the value associated with a specific score value.<pre><b>setScoreValue</b>(valType, amt);</pre>
valTypeSpecifies which score value to change. Can be one of the following values:<dl><dt><b>0</b></dt><dd>The number tried.</dd><dt><b>1</b></dt><dd>The number correct.</dd><dt><b>2</b></dt><dd>The number incorrect.</dd></dl>amtThe number to assign to the score value.There is no return value.Use this function to use TQS's built-in scoring functionalities in your custom location types. The %REFTO:offsetScoreValue% is well-suited for increasing a particular score value by a given amount.numTried++;
setScoreValue(0, numTried);
if(correctAnswer)
{
numCorrect++;
setScoreValue(1, numCorrect);
} else
{
numWrong++;
setScoreValue(2, numWrong);
}offsetScoreValue FunctionIncreases or decreases the value associated with a specific score value by a certain amount.<pre><b>offsetScoreValue</b>(valType, delta);</pre>
valTypeSpecifies which score value to change. Can be one of the following values:<dl><dt><b>0</b></dt><dd>The number tried.</dd><dt><b>1</b></dt><dd>The number correct.</dd><dt><b>2</b></dt><dd>The number incorrect.</dd></dl>deltaThe number to add to the current score value. A negative number means the score value will decrease.There is no return value.Use this function to use TQS's built-in scoring functionalities in your custom location types. The %REFTO:setScoreValue% function is used for setting a particular score value to a specific number.offsetScoreValue(0, 1);
if(correctAnswer)
offsetScoreValue(1, 1);
else
offsetScoreValue(2, 1);getScoreValue FunctionRetrieves the number associated with a specific score value.<pre>value = <b>getScoreValue</b>(valType);</pre>
valTypeSpecifies which score value to retrieve. Can be one of the following values:<dl><dt><b>0</b></dt><dd>The number tried.</dd><dt><b>1</b></dt><dd>The number correct.</dd><dt><b>2</b></dt><dd>The number incorrect.</dd></dl>Returns the number assigned to the score value.Use this function to use TQS's built-in scoring functionalities in your custom location types.if(getScoreValue(2) == 10)
spanStatus.innerText =
"You have gotten ten questions incorrect." +
"Would you like some easier questions?";invokeLoc FunctionSwitches to a new location.<pre><b>invokeLoc</b>('<i>location</i>'.split(','));</pre>
locationThe location to switch to.There is no return value.The <b>invokeLoc</b> function can be called from within the %REFTO:HTML% element of a location of type <b>"HTML"</b>, or from within the %REFTO:SCRIPT% element of a custom location type.TQS will switch to location 1,3.<CUSTOMDIV NAME="CUSTOM_FOO">
...
<SCRIPT>
...
invokeLoc('1,3'.split(','));
...
</SCRIPT>
</CUSTOMDIV>This sample creates a link which will switch to location 1,1.<LOC ID="1,0" TYPE="HTML">
<HTML>
...
<a onclick="event.returnValue=false;
invokeLoc('1,1'.split(','));" href="">...</a>
...
</HTML>
</LOC>locFinished FunctionInforms TQS that a location has been finished, so any location-specific or global %REFTO:FINISH% actions can take place.<pre><b>locFinished</b>();</pre>
There is no return value.Use of this function is not required, but helps custom locations take advantage of built-in %REFTO:FINISH% functionality.if(noMoreQuestions)
locFinished();
else
loadQuestion();getDynVal FunctionRetrieves the value of a TQS dynamic value.<pre>value = <b>getDynVal</b>(dynVal);</pre>
dynValSpecifies which dynamic value to retrieve.Returns the value of the dynamic value.Use this function to use dynamic values in ways other than through <i>SUBST</i> attributes.spanStatus.innerText =
"Sorry, " + getDynVal("USERNAME") +
", that is incorrect."playSound FunctionPlays the sound associated with a correct or an incorrect answer.<pre><b>playSound</b>(id);</pre>
idSpecifies which sound to play. Can be one of the following values:<dl><dt><b>0</b></dt><dd>Correct answer.</dd><dt><b>1</b></dt><dd>Incorrect answer.</dd></dl>There is no return value.The sound files associated with correct and incorrect answers are taken from the <i>SOUND</i> attribute of the %REFTO:CORRECT% and %REFTO:INCORRECT% elements. These elements must exist either within the global settings %REFTO:HTML% or %REFTO:CUSTOM_*% element, or directly within global settings, in order to be used by this function.<p>In order for any sounds to be played, the %REFTO:TQS% element's <i>USESSOUNDS</i> element must be set to "1".<p>Use the %REFTO:playSoundFile% function to play a specific sound file.<LOC ID="3" TYPE="CUSTOM_FOO">
<CORRECT SOUND="correct.wav"/>
<INCORRECT SOUND="incorrect.wav"/>
<CUSTOM_FOO>
...
</CUSTOM_FOO>
</LOC><CUSTOMDIV NAME="CUSTOM_FOO">
...
<SCRIPT>
...
if(answerCorrect)
playSound(0);
else
playSound(1);
...
</SCRIPT>
</CUSTOMDIV><GLOBAL>
<CORRECT SOUND="correct.wav"/>
<INCORRECT SOUND="incorrect.wav"/>
...
</GLOBAL><LOC TYPE="HTML">
...
<HTML>
...
<BUTTON ID="correct"
ONCLICK="playSound(0);"/>
<BUTTON ID="incorrect"
ONCLICK="playSound(1);"/>
...
</HTML>
</LOC>playSoundFile FunctionPlays the specified sound file.<pre><b>playSoundFile</b>(fileName);</pre>
fileNameSpecifies the sound file to play.There is no return value.In order for any sounds to be played, the %REFTO:TQS% element's <i>USESSOUNDS</i> element must be set to "1".<p>The sound file must reside in the data root folder. This is, by default, the folder containing the .TQS file.<ul><li>The data root folder can be set with the %REFTO:TQS% element's <i>DATAROOT</i> attribute. To specify an absolute path, such as an Internet address, precede the path with <b>NOROOT?</b>.</li><li><b>TQS 2.6</b> To specify an embedded file, precede the path with <b>EMBED?</b>.</li></ul><p>Use the %REFTO:playSound% function to play the sound associated with a correct or an incorrect answer.<DIVCODE XMLCOMPLIANT="1">
...
<BUTTON onclick="onBtnClick(0)">Cow</BUTTON>
<BUTTON onclick="onBtnClick(1)">Horse</BUTTON>
<BUTTON onclick="onBtnClick(2)">Pig</BUTTON>
...
</DIVCODE>function onBtnClick(btnID)
{
playSoundFile("animal"+btnID+".wav");
}function onBtnClick(btnID)
{
playSoundFile("EMBED?animal"+btnID+".wav");
}xmlLocData VariableRepresents the current %REFTO:CUSTOM_*% element within the current %REFTO:LOC% element.Use this variable with the TQS XML data access functions to load data for your custom location. The variable %REFTO:xmlCurLoc% represents the current %REFTO:LOC% element.<p>The <b>xmlLocData</b> object is equivalent to the object returned by <b>xmlChildOf(xmlCurLoc, "CUSTOM_*", 0)</b> in TQS 2.5 and later.The HTML element <i>spanBar</i> will display <b>Inside Bar</b>.<CUSTOM_FOO>
<FOO>
<BAR>Inside Bar</BAR>
</FOO>
</CUSTOM_FOO>fooEl = xmlChildOf(xmlLocData, "FOO", 0);
barEl = xmlChildOf(fooEl, "BAR", 0);
spanBar.innerText = barEl.text;xmlCurLoc VariableRepresents the current %REFTO:LOC% element.Use this variable with the TQS XML data access functions to load data for your custom location. The variable %REFTO:xmlLocData% represents the current %REFTO:CUSTOM_*% element within the current %REFTO:LOC% element.The HTML element <i>spanBar</i> will display <b>April Custom Location</b>.<LOC ID="April" TYPE="CUSTOM_FOO">
...
<CUSTOM_FOO>
...
</CUSTOM_FOO>
</LOC>spanBar.innerText = xmlAttr(xmlCurLoc, "ID", "")
+ " Custom Location";ICON ElementSpecifies the icon to show in the TQS window.<pre><<b>ICON</b>
<b>SRC</b>="<i>src</i>"
/></pre>
SRCSpecifies file name of the icon to display.The <b>ICON</b> element must be a child of the %REFTO:TQS% element.If the <b>ICON</b> element is not specified, or the icon file cannot be found, the default TQS icon is displayed instead.<p>The icon file must reside in the data root folder. This is, by default, the folder containing the .TQS file.<ul><li>The data root folder can be set with the %REFTO:TQS% element's <i>DATAROOT</i> attribute. To specify an absolute path, such as an Internet address, precede the path with <b>NOROOT?</b>.</li><li>To specify an embedded file, precede the path with <b>EMBED?</b>.</li></ul><ICON SRC="EMBED?trivia.ico"/>messageBox FunctionDisplays a message box on the screen.<pre>value = <b>messageBox</b>(message, caption, flags);</pre>
messageThe text of the message box.captionThe caption to display in the message box's title bar. If not specified, the name of your TQS application is used.flagsA value composed of bit flags that control the buttons and icon displayed in the message box. Pass a number from the button flags table, optionally adding a number the icon flags table if desired.<p>Button flags:<table><tr><td>0</td><td>OK button only (default)</td></tr><tr><td>1</td><td>OK and Cancel buttons</td></tr><tr><td>2</td><td>Abort, Retry, and Ignore buttons</td></tr><tr><td>3</td><td>Yes, No, and Cancel buttons</td></tr><tr><td>4</td><td>Yes and No buttons</td></tr><tr><td>5</td><td>Retry and Cancel buttons</td></tr><tr><td>6</td><td>Cancel, Try Again, and Continue buttons<br>(Requires Windows 2000, XP, or newer)</td></tr></table><p>Icon flags:<table><tr><td>16</td><td>Error icon</td></tr><tr><td>32</td><td>Question mark icon</td></tr><tr><td>48</td><td>Exclamation icon</td></tr><tr><td>64</td><td>Information icon</td></tr></table>Returns an value corresponding to the button in the message box that the user clicked:<p><table><tr><td>1</td><td>OK</td></tr><tr><td>2</td><td>Cancel</td></tr><tr><td>3</td><td>Abort</td></tr><tr><td>4</td><td>Retry</td></tr><tr><td>5</td><td>Ignore</td></tr><tr><td>6</td><td>Yes</td></tr><tr><td>7</td><td>No</td></tr><tr><td>10</td><td>Try Again</td></tr><tr><td>11</td><td>Continue</td></tr></table>Use this function to display a custom message box to the user. The use of this function is preferred over the script functions <b>alert</b> and <b>confirm</b>.The following displays a simple message box. Since no caption is specified, the TQS application's title will be used.messageBox("That is correct!");The following example asks the user a yes/no question. The value 36 represents 6 (Yes and No buttons) + 32 (Question mark icon). The code checks for the return value 6 to indicate whether Yes was pressed.if(messageBox("Do you want to play again?",
"Matching", 36) == 6)
{
// play again
} else
{
// do something else
}
enableSpecialImg FunctionEnables an image element to receive special rendering. Used by custom location types that wish to display state images using the same colors and antialiasing that the rest of TQS uses.<pre><b>enableSpecialImg</b>(imgEl);</pre>
imgElThe HTML image element that should receive special rendering.There is no return value.TQS can display state images in the report and in menus; a custom location type can also display state images by retrieving the image URL via %REFTO:getStateImg% and assigning it to one of its image elements.<p>Starting in TQS 2.8, TQS draws these state images using antialiasing and allows you to specify the colors used. However, by default this only applies to the images displayed in reports and in menus. To apply these colors to its own state images, a custom location type must call <b>enableSpecialImg</b> for each HTML image element it wants to use to display states. It must still set the image's source to the URL returned from %REFTO:getStateImg%, as this tells TQS which state image to draw.<p><b>enableSpecialImg</b> only needs to be called once per image element, not every time its <i>src</i> attribute is changed.// During ONLOAD
enableSpecialImg(myImgEl);
// Later, to display a state image
myImgEl.src = getStateImg("DONE");