BUTTON Element

Specifies a button to be displayed.

Syntax

<BUTTON
  TITLE="title"
  TARGET="target"
  SUBST="subst"
  APPLIESTO="appliesto"
  INCLUDE="include"
  EXCLUDE="exclude"
  GREATER="greater"
  LESS="less"
/>

Attributes

TITLE

The text of the button.

TARGET

The location that should be invoked when the button is clicked. If the button is a global button, a LOCPOS dynamic value can be used in place of any location digit.

SUBST

TQS 2.0, 2.1 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 "string,LOCPOS:x".

TQS 2.5 Substitution is supported for local, global, and finish buttons. All TQS dynamic values are supported. The attribute must be in the form of "string,dynval"; multiple substitutions can be specified by joining them with a semicolon (;).

APPLIESTO

Only 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:

"NONE": The button will never be displayed. This is the default if no APPLIESTO attribute exists.
"ALL": The button will be displayed in every location.
"ONLY": The button will be only be displayed in locations explicitly specified in the INCLUDE attribute.
"ALLBUT": The button will be only be displayed in all locations except those explicitly specified in the EXCLUDE attribute.
"GREATER": The button will be only be displayed in locations which pass the test specified in the GREATER attribute.
"LESS": The button will be only be displayed in locations which pass the test specified in the LESS attribute.

INCLUDE

Only applies to global and global finish buttons with the APPLIESTO attribute set to "ONLY". Contains a list of locations, separated by semicolons (;). Only these locations will display this button.

EXCLUDE

Only applies to global and global finish buttons with the APPLIESTO attribute set to "ALLBUT". Contains a list of locations, separated by semicolons (;). Every location except these will display this button.

GREATER

Only applies to global and global finish buttons with the APPLIESTO 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>value2". When value1 is greater than value2, the button is displayed. In TQS 2.0 and 2.1, value1 must be a LOCPOS dynamic value; in TQS 2.5 and greater it can be any dynamic value. value2 must be a number.

LESS

Only applies to global and global finish buttons with the APPLIESTO 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<value2". When value1 is less than value2, the button is displayed. In TQS 2.0 and 2.1, value1 must be a LOCPOS dynamic value; in TQS 2.5 and greater it can be any dynamic value. value2 must be a number.

Placement

The BUTTON element can be used in the following places: As a child of the BUTTONS element, to specify a global button; as a child of the FINISH element, to specify a global or local button to be displayed when a location is finished; or as a child of a LOC element, to specify a location-specific button.

Children

No children are supported within the BUTTON element.

Remarks

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 BUTTON element.

Note that in the GREATER and LESS attributes, the rules must contain > and < respectively, and not > and <.

Examples

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 X 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&gt;0"
/>

This global finish button uses the 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>