Inside TQS

This document will give you describe the basics of how TQS operates and will describe its file format.

• TQS Application Architecture
• File Format
• Designing Locations
• Location Types and Features
• General Application Capabilities
• Global Settings
• Advanced Customization
• Embedded Files
• File Format Summary

TQS Application Architecture

From the beginning, TQS was designed to be a robust application to be used by other people to create customized solutions. The actual program is very small, built for 32-bit Microsoft Windows with Microsoft Visual C++ 2005. The application itself, currently, only is responsible for handling command-line parameters, shell registration, displaying the HTML-based main window, handling embedded files, and performing HTML isolation.

Once the main window is displayed, the program uses HTML, JScript, and XML to control the rest of the application. The data file, which contains all of the information for your custom application, is either specified to the application as a command-line parameter, run directly by the Windows Shell, or selected in the File Open dialog box that appears if no file is specified.

At all times, the program displays two buttons on the bottom of the screen: About and Quit. The About button brings up a screen which tells information about TQS itself, along with any custom information you may provide about your application. The Quit button exits the program.

File Format

The TQS file format (*.tqs) is based on XML and must be a valid XML document in order to be opened by TQS. Currently under development is the TQS Editor, which will allow you to easily create TQS applications without writing any code. However, at this time, all code must be written by you, either by hand or by using a program such as Microsoft XML Notepad.

XML documents, and thus TQS documents, are simple text files using special "tags" for marking up the data. The following are some simple rules to remember when coding TQS documents:

• First line of file must read:

  <xml version="1.0"?>

• Main document tag must be:

  <TQS VERSION="x.x">
  ...
  </TQS>
  

• All element and attribute names must be capitalized correctly; TQS always uses capital letters.
• Each element tag must have a closing tag, whether it be separate or within the tag.

  <AUTHORINFO ....></AUTHORINFO>
  

  or

  <AUTHORINFO ..../>

• All attributes must have their values enclosed in quotation marks. This applies to strings as well as numbers.

  <TQSWINDOW WIDTH="720" FONT="Arial"/>

  not

  <TQSWINDOW WIDTH=720 FONT=Arial/>

• Greater than signs, less than signs, and ampersands used within text or attributes must be coded as follows to avoid problems with the XML parser:

  < is coded as &lt;
  > is coded as &gt;
  & is coded as &amp;

• All special characters must be encoded using their numerical value. For example, to display the Ü character, you must use Ü instead of Ü. See the Reference for more information.

It is not very difficult to learn how to author TQS documents; reading through the TQS Tutorial on this site and looking at sample applications helps greatly.

Designing Locations

Before you can begin to write your TQS file, you must understand the TQS location system and plan the structure of your application.

You need to separate your application into "locations" based on what different things you want to do. For instance, if you are making a set of trivia questions on just one subject and want TQS to load right into those questions, and not do anything besides those questions, you only need one "location." (See figure at right)

However, it is more often the case to have multiple groupings of questions or different types of things. For example, say you want your application to contain two sets of trivia questions and two sets of hangman words, plus a menu to choose which one you want to do. To implement this, you would need to have five locations, one for each of the situations. (See figure below)

For larger programs, a Menu->Submenu->Questions format may work best. This is especially useful for organizing textbook questions by chapter, and then by topic within each chapter. (See figure below)

Every location has has a unique location ID. This ID can be a single number, as shown in figure 2 (Location 0, Location 1, ...), or it can be a series of numbers separated by commas, as shown in figure 3 (Location 0, Location 1,0, Location 1,1, ...). Inside a TQS file, the tags must be nested appropriately to produce nested locations.

A location ID can be a text string instead of a number. For example, instead of having Location 1,2 (Location 1 inside of Location 2), you could have Location usa,wisconsin (Location wisconsin inside of location usa). (Note: some advanced situations work best when numbers are used.)

Besides in the actual XML implementation of the location data, the location may be referred to in several other places, to determine which location to invoke in certain situations. These situations include:

• The loading of the application
• The selection of a menu item
• The clicking of a navigation button
• The building of the score report (TQS 2.5)

Also, HTML locations and custom scripts can manually swich to a different location. For more information, see the Reference.

Location Types and Features

TQS 2.0 has built-in support for three types of locations: menus, questions, and hangman. TQS 2.1 adds support for the HTML location type.

The first, the menu, displays a list of items from which the user can choose. Upon clicking on a menu item, a target location will be invoked. There are several visual options avaiable for the menu, including number of columns, centering of items, and numbering items.

The questions type cycles through a series of multiple choice questions, which can include any number of answers and a graphic. When the user selects an answer, the program will report if it is correct or not, and can keep and display the score, if you, the author, specify. The questions and/or answers may be displayed in random order or in the order listed in your file. TQS 2.5 adds support for different types of question sets, including true-false and type-in-answer questions, as well as question sets made up of multiple types of questions.

Thirdly, the hangman type presents a series of hangman words to the user. As of TQS 2.1, you can specify what characters the user can choose, removing the former limitation of English-language capital letters. Also, version 2.1 lets you replace the graphics that are displayed when the user is hanged, and change the number of incorrect letters allowed before death (defaults to 8).

The HTML location type, available beginning in TQS 2.1, lets you display any HTML code, as long as you enter it in XML-compatible form. This allows you to create rich, interactive data presentations, without having to expose your HTML pages for anyone to see.

Several features are available to any location regardless of its type: heading, heading images, and navigation buttons. The heading is a text string that is displayed at the top of the window. Images may be specified to be placed on either side of the heading. Lastly, navigation buttons may be placed on the bottom, next to the About button; these buttons invoke locations when clicked. Commonly this is used to allow the user to return to previous menus; however, it may also be used to reinvoke the current location or travel to a related location.

Navigation buttons can also be specified in the Global Settings, discussed later in this document.

General Application Capabilities

TQS allows you, the developer, to customize many aspects of the main window, including size and colors, and lets you add your own author information to the about window. This section describes the general things you can do; more information can be found in the Reference.

When TQS loads up, it gets a number of attributes from your data file which are placed in the about screen. These include:

• Title of your application
• Author name
• Your e-mail address
• Your web site address
• Program description/about section (TQS 2.5)

Visually, the TQS main window is yours to do with as you please. You may specify the both the horizontal and vertical sizes of the window; it will automatically be centered on screen. All locations will function correctly regardless of window size; scroll bars will be displayed if there is not enough room in the window for the current location.

By default, the background color of the window is dark blue, with white text and a yellow highlight color (used when hovering over menu items, answers, and hangman letters). You are free to change any of these colors, as well as add a background image which will be tiled across the back of the window. Also, you may specify a font to be used instead of the default, Verdana.

Additionally, if you specify one in your data file, TQS will play an audio file while your program is running. Control over looping the background sound is supported in TQS 2.5.

New to TQS 2.5 is the ability to generate a score report. If you specify this, a "Report" button will be added next to the "About" button at the bottom of the window. Upon clicking this button, TQS will display a table of locations and the following score information: Number tried, correct, incorrect, and percentage, for each location. Locations are added to the table in the order they are listed in your TQS file; you have control over which location types are included and how to handle nested locations. More information on using the report features of TQS 2.5 is available in Part 12 of the Tutorial.

The figure below shows TQS's general, non-location-related capabilities.

Global Settings

A special section of the TQS file may be used to specify settings which will become defaults for all locations, unless a specific location overrides it. Each location type has its own special global settings which are described in more detail in the Reference. Also, any custom location types you design can store their own global settings.

The Global Settings section is ideal for the placement of navigation buttons. If you are developing a program to model a textbook with 20 chapters, for example, it is impractical to specify a "Main Menu" button in each location; it is better placed in Global Settings. You, the developer, can specify exactly when to display buttons, using a variety of rules. For instance, tell the program to display a button in all locations except 1,1 and 3,2. Or, to display a button only when the second position of the location (i.e. 2 in 3,2) is greater than a certain number. TQS allows great power and flexibility in the placing of navigation buttons, through Global Settings.

The diagram below shows the organization of various global settings.

Advanced Customization

TQS allows you to create your own location types, using Dynamic HTML and JScript. For more information, see Part X of the Tutorial, read through the Reference, or take a look at the code for some sample applications.

Embedded Files

Prior to TQS 2.6, you would have to distribute any image and sound files that your application uses alongside the TQS document itself. Now, you can use the TQS Embed Utility to embed these files within your TQS document.

The actual contents of the files are encoded into Base64 so that the XML document remains valid. You should not modify the embedded files section yourself; always use the TQS Embed Utility.

The figure below shows how embedded files are represented in the TQS document.

File Format Summary

The following diagram shows how a complete TQS document would be laid out, including general settings, global settings, locations, and customization.

Tutorial
Reference