Part IV: Adding and Customizing a Menu

A menu is simply a location specified with the type as "MENU". In this section of the tutorial, we will add a menu location which will enable the user to choose between two hangman locations.

We want our program to load into our menu right away, so we could add a LOC element for the menu, give it an ID of 1 and change the LOCATIONS element's START attribute to 1. However, for best organization, we will simply rename our hangman location to an ID of 1, and add a menu location above it with ID of zero.

The MENU element of the LOC element contains menu-specific settings. At this time, we will leave this empty; our LOCATIONS element will look like this:

<LOCATIONS START="0">
  <LOC ID="0" TYPE="MENU">
    <HEADING>My Main Menu</HEADING>
    <MENU>
    </MENU>
  </LOC>
  <LOC ID="1" 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>

Running the program at this time will bring up an empty menu, as we have not yet specified any menu items. Before we do so, we'll add another hangman location, with an ID of 2. And, we'll change the words to some with a little more meaning.

<LOCATIONS START="0">
  <LOC ID="0" TYPE="MENU">
    <HEADING>My Main Menu</HEADING>
    <MENU>
    </MENU>
  </LOC>
  <LOC ID="1" TYPE="HANGMAN">
    <HEADING>United States Hangman</HEADING>
    <HANGMAN>
      <WORD>ALABAMA</WORD>
      <WORD>ALASKA</WORD>
      <WORD>ARIZONA</WORD>
      ...
    </HANGMAN>
  </LOC>
  <LOC ID="2" TYPE="HANGMAN">
    <HEADING>European Hangman</HEADING>
    <HANGMAN>
      <WORD>SPAIN</WORD>
      <WORD>FRANCE</WORD>
      <WORD>GREAT BRITAIN</WORD>
      ...
    </HANGMAN>
  </LOC>
</LOCATIONS>

Note: It is not necessary to have the LOC elements in any kind of order within the LOCATIONS element, since they are always referred to by the ID attribute. However, each LOC element must have a unique ID; that is to say, the ID attribute of each LOC element must be set to a different value than those of other LOC elements at the same level.

Since the main menu will be the first thing the user sees when running this document, it serves as a good place to display a welcome message. So, let's change the HEADING element of Location 0 to Welcome to My Hangman Games!.

We are now ready to begin implementing the MENU element. The purpose of a menu is to show choices to the user, which upon being clicked will invoke a different location. The element name is MENUITEM, and it contains two attributes, TITLE and TARGET.

The TITLE attribute specifies the text that appears for this menu item, and the TARGET attribute contains the ID of the target location. At this point, the target ID is merely a single number; however, later in the tutorial we will deal with compound location IDs.

Add the following MENUITEM elements so that your Location 0 looks like this:

<LOC ID="0" TYPE="MENU">
  <HEADING>Welcome to My Hangman Games!</HEADING>
  <MENU>
    <MENUITEM
      TITLE="United States Hangman"
      TARGET="1"
    />
    <MENUITEM
      TITLE="European Hangman"
      TARGET="2"
    />
  </MENU>
</LOC>

Remember that you are free to put the entire MENUITEM element and its attributes one one line, if desired.

Run the program to see that, by default, TQS has placed your menu in a single column along the left side of the window. By adding attributes to the MENU element, you can center the menu, divide it into mutiple columns, and number each item, if desired.

Experiment with the following attributes to see their effect.

To specify that the items should appear in two columns, add the following attribute to the MENU element:

NUMCOLUMNS="2"

When menus include more items, such as 20, it may be better to split the items into two or more columns. Simply specify the number of columns desired in the value of the NUMCOLUMNS attribute.

To center the menu items within their column(s), add this attribute to the MENU element:

CENTER="1"

TQS can number the menu items, in order of the placement of the MENUITEM elements. To do so, add this attribute to the MENU element:

NUBMERS="1"

For our simple menu of two items, it is not worth it to number the items or to split them into multiple columns. However, for some programs it may be useful or even necessary.

We will change our menu to center the items, though. The MENU element should then look like this:

<MENU CENTER="1">
  <MENUITEM
    TITLE="United States Hangman"
    TARGET="1"
  />
  <MENUITEM
    TITLE="European Hangman"
    TARGET="2"
  />
</MENU>

The last feature of TQS menu locations is the ability to specify instructions to the user. This is accomplished by adding an INSTR element to the MENU element, as follows:

<MENU>
  <INSTR>Select an item from the menu.</INSTR>
  <MENUITEM ... />
  ...
</MENU>

We will not add this to our sample application, but you may wish to use it in your own applications.

In Part IV of the tutorial we have added another hangman location and implemented a menu to allow the user to choose which hangman game to play. In the next part, we will add navigation buttons to allow the user to restart a hangman game or return to the main menu.

Part V: Implementing Navigation Buttons