Part III: A Single-Location Application: Hangman

In this section of the Tutorial, we will use TQS to play hangman. We will use one location and will give it the location ID of zero.

All of the locations that you create will go in the LOCATIONS element, which itself goes inside the TQS element. An attribute of the LOCATIONS element, START, specifies the ID of the location which TQS is to invoke upon loading. For this, we will specify "0".

<LOCATIONS START="0">
</LOCATIONS>

Thus so far, our document looks like this:

<?xml version="1.0"?>
<TQS VERSION="2.0" EDITABLE="1">
  <TITLE>My First TQS Application</TITLE>
  <AUTHORINFO
  ...
  />
  <LOCATIONS START="0">
  </LOCATIONS>
</TQS>

Running the program at this point will generate an error, because the START attribute refers to a location that does not yet exist. Next, we will add the following LOC (location) element to the LOCATIONS element:

<LOC ID="0" TYPE="HANGMAN">
</LOC>

The ID attribute matches the START attribute of the LOCATIONS element; thus, this location will be invoked when this application is started. The location ID can be anything you want, but it is best to keep it to a single number or word. More information on location IDs will come later in the tutorial.

The TYPE attribute specifies that the location type is a hangman game. The other built-in types include "MENU" and "QUESTIONS", which will be discussed later in the tutorial. Also, TQS 2.1 adds the "HTML" type, which is covered in Part XI of this tutorial.

Before we can run our application, we need to add the hangman data to the LOC element, or else an error will be generated. But first, we'll touch on some general location options.

TQS allows any location, regardless of type, to display a heading across the top of the window, along with graphics on either side. Let's display the title My Hangman Game. Add the following element to the existing LOC element:

<HEADING>My Hangman Game</HEADING>

Although we will not include it in this example, TQS allows you to specify images on each side of the heading, through the LIMG (left image) and RIMG (right image) attributes. The values of these attributes refer to graphic files (such as GIF or JPEG). By default, these must exist in the same folder as your .tqs file; the Reference describes how to change this in TQS 2.1 or later. The syntax for specifying images is as follows:

<HEADING LIMG="leftimg.gif"
  RIMG="rightimg.gif">My Hangman Game</HEADING>

At this time, we will add the information that TQS uses to run the hangman game. All of the data for the hangman location type goes in a HANGMAN element inside of the LOC element, just as we will later see that the "MENU" type uses a MENU element and the "QUESTIONS" type uses a QUESTIONS element.

The HANGMAN element contains a series of WORD elements, the text of which specify the words or phrases to be displayed. In TQS 2.0, hangman only allows capital letters to be used; all other characters will be displayed on screen and not replaced by a hyphen. Thus, the word TRIVIA QUIZ SHELL becomes ------ ---- ----- while 3 Blind Mice?! shows up as 3 -lind -ice?!. Thus, you may use numbers and punctuation and they will appear in the hidden word.

Note: In TQS 2.1 or later, you can specify what characters can be guessed. See the Reference for more information.

With the addition of the three sample hangman words, the entire location element will look as follows:

<LOC ID="0" TYPE="HANGMAN">
  <HEADING>My Hangman Game</HEADING>
  <HANGMAN>
    <WORD>HANGMAN SAMPLE WORD ONE</WORD>
    <WORD>HANGMAN SAMPLE WORD TWO</WORD>
    <WORD>HANGMAN SAMPLE WORD THREE</WORD>
  </HANGMAN>
</LOC>

Notice that the text of a WORD element does not have to be a single word but can be a phrase or sentence.

By default, TQS will cycle through your hangman words in random order; to specify them to go in the order found in the TQS document, add this attribute to the HANGMAN element:

INORDER="1"

For this tutorial, we will have words presented in random order, so we will not specify the INORDER attribute. The entire TQS document so far should be as follows:

<?xml version="1.0"?>
<TQS VERSION="2.0" EDITABLE="1">
  <TITLE>My First TQS Application</TITLE>
  <AUTHORINFO
    AUTHOR="Your Name Here"
    EMAIL="address@example.com"
    WEBSITE="http://www.example.com"
  />
  <LOCATIONS START="0">
    <LOC ID="0" TYPE="HANGMAN">
      <HEADING>My Hangman Game</HEADING>
      <HANGMAN>
        <WORD>HANGMAN SAMPLE WORD ONE</WORD>
        <WORD>HANGMAN SAMPLE WORD TWO</WORD>
        <WORD>HANGMAN SAMPLE WORD THREE</WORD>
      </HANGMAN>
    </LOC>
  </LOCATIONS>
</TQS>

Upon running this application, the hangman game will start right away; however, once the words are done there is no way to restart besides quitting and reloading the document. In later parts of the tutorial, we will add a means to do so.

Part III of the tutorial has introduced you to the LOCATIONS and LOC elements, as well as how to define a hangman game. In the next section, we will add a menu to our program which will let us choose between several hangman games.

Part IV: Adding and Customizing a Menu