Part XIII: Reports, Scoring, and Location States

This section of the tutorial continues to explain the new features of TQS 2.5. The most substantial new features are the reporting, scoring, and location state tracking capabilities, which are all interrelated and provide you, the author, with numerous options for configuring your application.

TQS 2.0 introduced scoring capabilities with the SHOWSCORE attribute of the QUESTIONS element. Now, scoring is available to all location types. Add the SHOWSCORE attribute to the HANGMAN element to keep track of Hangman scores in the same manner. Also, you can even use this attribute to show the scoring table in your own custom locations (more on this in the next part of the tutorial).

Not only can scores be displayed while you are in a specific location; now TQS can keep track of all locations' scores and present them in the score report. Let's add this functionality to the TQS application we've been working with throughout parts I through X of this tutorial. Add the REPORT element to the document, as shown below:

<?xml version="1.0"?>
<TQS VERSION="2.5" EDITABLE="1">
  <TITLE>My TQS Application</TITLE>
  <AUTHORINFO ... />
  <TQSWINDOW ... />
  <REPORT
    SHOWBUTTON="1"/>
  <GLOBAL>...</GLOBAL>
  <LOCATIONS START="0">...</LOCATIONS>
  <CUSTOM>
  </CUSTOM>
</TQS>

In order for the "Report" button to be displayed at the bottom of the window, the SHOWBUTTON attribute must be set to "1". However, upon clicking this button, you will notice that only the table column heading is shown: no location data is displayed. In order to do this, we have to specify which location types are to be included in the score report. This is accomplished by adding the INCLUDETYPES element to the REPORT element, as shown.

<REPORT
  SHOWBUTTON="1">
  <INCLUDETYPES>
    <TYPE>QUESTIONS</TYPE>
    <TYPE>HANGMAN</TYPE>
  </INCLUDETYPES>
</REPORT>

Run the application, and click the Report button right away. Notice how the four locations are now in the table, all displaying scores of zero. Play each of the locations for a bit and check the report periodically, noting how the scores are updated. Also, note that the scores will be displayed on the report window despite whether they are shown via the SHOWSCORE attribute.

A TYPE element is added for each location type that we want to include in our report. For instance, if we only wanted to list the scores for questions locations, not hangman, then we would omit the <TYPE>HANGMAN</TYPE> element.

TQS supports showing the total score at the bottom of the chart. Try this by adding the SHOWTOTAL attribute to the REPORT element and setting it equal to "1".

At this point, you can tell that TQS is indenting the four locations in the table. This is due to the fact that they are nested one level in the location hierarchy. By default, TQS indents all entries according to their level in the hierarchy. Turn off indenting, temporarily, by adding the INDENT attribute and setting it to "0". For applications that use an location hierarchy, but do not want the report to reflect this, indenting should be turned off. However, we will turn it back on and use it to demonstrate a few more capabilities of TQS reporting.

Add the following TYPE element to the REPORT element, as shown:

<REPORT
  SHOWBUTTON="1"
  SHOWTOTAL="1">
  <INCLUDETYPES>
    <TYPE>NULL</TYPE>
    <TYPE>QUESTIONS</TYPE>
    <TYPE>HANGMAN</TYPE>
  </INCLUDETYPES>
</REPORT>

Now, the report table is including the two container locations (whose types are "NULL"), but not displaying any scores for them. However, they are currently labelled in the table using their location IDs. By default, the report table gets the title from the location's HEADING element, if it exists. However, for the NULL locations, the HEADING element is not supported. Instead, the REPORTTITLE element can be used within a LOC element to specify the text that should be displayed in the report table. This does not just apply to NULL locations; locations with a HEADING element can also have a REPORTTITLE element that overrides the heading text for use in the report.

Add REPORTTITLE elements to make your locations look as follows:

<LOCATIONS START="0">
  <LOC ID="0" TYPE="MENU">
    ...
  </LOC>
  <LOC ID="1" TYPE="NULL">
    <REPORTTITLE>United States</REPORTTITLE>
    <LOC ID="0" TYPE="MENU">
      ...
    </LOC>
    <LOC ID="1" TYPE="HANGMAN">
      <HEADING>United States Hangman</HEADING>
      <REPORTTITLE>Hangman</REPORTTITLE>
    </LOC>
    <LOC ID="2" TYPE="QUESTIONS">
      <HEADING>United States Trivia</HEADING>
      <REPORTTITLE>Trivia</REPORTTITLE>
    </LOC>
  </LOC>
  <LOC ID="2" TYPE="NULL">
    <REPORTTITLE>Europe</REPORTTITLE>
    <LOC ID="0" TYPE="MENU">
      ...
    </LOC>
    <LOC ID="1" TYPE="HANGMAN">
      <HEADING>Europe Hangman</HEADING>
      <REPORTTITLE>Hangman</REPORTTITLE>
      ...
    </LOC>
    <LOC ID="2" TYPE="QUESTIONS">
      <HEADING>Europe Trivia</HEADING>
      <REPORTTITLE>Trivia</REPORTTITLE>
      ...
    </LOC>
  </LOC>
</LOCATIONS>

Notice how the REPORTTITLE element gives you much control over the report.

TQS also has the ability to keep track of subtotals for each container (NULL) location, and can display this data in several different ways. Add the SUMCHILDLOCS attribute to the REPORT element and set it to "INLINE". Run the application, then change the attribute to "SUBTOTAL". Also, add the BOLDSUMS attribute and set it to "1" to have these subtotals displayed in bold. When writing your own TQS application, one type of displaying child totals may be more appropriate than the other, or you may wish to not display them at all.

Another feature related to reporting is the ability to get the user's name when they start the application. Set the REPORT element's GETNAME attribute to "1" and run the application. Right away, you are prompted to enter your name. This name will be displayed at the top of the report screen and can be used in other places via the USERNAME dynamic value. In addition, you can customize the prompt that is displayed to the user by setting the GETNAMEPROMPT to a string of your choice.

The last attribute we will discuss at this time is the PRINTABLE attribute. When set to "1", the "Print" button will appear on the report screen, allowing the user to print out the score report. Try this now to see how this feature works.

In addition to the new reporting subsystem, TQS 2.5 introduces the concept of location states. A location state is a value that is associated with each location, including NULL container locations. Initially, each location's state is "EMPTY"; when you visit a location it is set to "PARTIAL".

When you complete a location (by answering all questions or guessing all Hangman words), the location's state will change to "DONE", or "DONE100" if the score is 100 percent correct. NULL container locations will have a state that is the minimum combination of all child locations that are listed in the REPORT element's INCLUDETYPES element. For instance, in our example, when we visit the "United States" menu, container Location 1 (for U.S. items) will have a state of "PARTIAL". Until we complete both U.S. Hangman and U.S. Trivia, it will remain "PARTIAL". Once those two locations are completed, the U.S. container location will have the "DONE" state, unless both sublocations were completed with "DONE100", in which case that state will be assigned to the container.

Associated with each possible state is a state image. To the REPORT element, add the SHOWSTATES attribute and set it to "1". Run your application and notice how the state images are shown in the report and how they change when you complete locations.

One thing you will notice is that if you complete both child locations, then look at the report, the container location state will be "DONE" or "DONE100". However, if you go back to the menu, it will change to "PARTIAL" despite the fact that both child locations that are supposed to count are completed. In order to prevent this, the DEFERSTATE attribute must be added to the U.S. and Euope menu location elements:

<LOC ID="0" TYPE="MENU" DEFERSTATE="PARENT">
  ...
</LOC>

This attribute tells TQS that the state of the location will be determined by looking at the state of the parent (container) LOC element. This is not required for the main menu because it is an immediate child location of the LOCATIONS element.

In addition to being used in the report, state images can be displayed on menus to show the state of the menu item's target location. The MENU element's SHOWSTATES attribute, either within a location or global settings, controls whether to show state images. Set this attribute as follows:

<GLOBAL>
  <MENU SHOWSTATES="1" .../>
  ...
</GLOBAL>

Using state images in menus makes it easy for the user to tell where he or she has been. However, if a questions or hangman location is visited after it is completed, its scores will be reset to zero and its state reset to "PARTIAL". TQS allows you to disable or remove items from menus once their target locations have been completed by using the MENU element's DONEITEMS attribute:

<GLOBAL>
  <MENU SHOWSTATES="1" DONEITEMS="DISABLE" .../>
  ...
</GLOBAL>

Now, menu items are disabled after they have been completed. To have completed items not displayed on the menu, set the DONEITEMS attribute to "HIDE".

TQS also allows you to replace the built-in state images with ones of your own that match your application's color scheme. For information on how to do this, see the STATEIMG element reference.

Part XIII of the tutorial has presented you with a wealth of information on TQS's reporting and scoring capabilities. More information on these features is available in the Reference. The next section of the tutorial is for advanced developers who use the customization features first presented in Part X. It will cover how to use TQS 2.5's new features from within custom location types. Or, skip to Part XV to read about new features in TQS 2.6.

Part XIV: New Customization Features
Part XV: Embedding Files in TQS Applications