I might as well admit it: I'm a TADS partisan.

I've dabbled in Hugo. I've written a reasonable amount of Inform code.
I still use TADS for all of my released adventures. Call it familiarity;
call it laziness, if you wish.

One of the few things I wish TADS had was a simple way of doing
Inform-esque menus, where topics are printed at the top of the screen
for you to choose from.

Oh, sure, TADS has that nifty adaptive hints module by Dave Allen and
modified by yours truly. Still, there are times when you don't want to
go through all the trouble of setting up adaptive hints, or you want
to present some introductory material in an organized manner.

With the advent of HTML TADS, all of this is now possible.

Using the HTML TADS banner feature, you can create a menu just like
those ol' Informers do. Better yet, you can select items from the menu
using your mouse, if you like those new-fangled devices.

Don't worry about people who play your game under a standard TADS
interpreter, either. This module checks to see what kind of interpreter
the player is running. If it doesn't support HTML formatting, this
module will adjust accordingly.

Enough introductory blather. You came here to find out how to make
menus. The instructions for menus.t are divided into two sections.
The first section explains the basics of making a menu. If all you want
to do is add a menu and use the default interface, you need read no
further than that section. If you want to change the menu's color, keys,
or modify how the menu is displayed, you can then read the second section,
which explains the details of menus.t.


===========
Basic Menus
===========

The first thing I have to do is explain the menu hierarchy. There are
four objects which make up a menu: the menuItem, the submenuItem, the
topicItem, and the longTopicItem.

The menuItem is the topmost layer of a menu. Ideally it should be the
theme which all submenus and topics follow. In addition, the menuItem
is responsible for defining the keys used to navigate the menus--not
that you need bother with that right now.

The submenuItem is just like a menuItem, only it's a sub-menu. You
use them to offer the player further choices.

The topicItem and longTopicItem are really two versions of the same
beast. The topicItem presents a sequential list of strings, one at
a time, and prints it in the banner which holds the menu. It's intended
to be used to give gradual hints to the player. The longTopicItem spits
out a huge chunk of text to the main window, *not* the banner. You
should use it to present, say, your game's copyright information.

If you're confused, try thinking of your menu as an outline. Let's
make a simple hint menu. In outline form, it would look something like
this:

I. Hints [menuItem]
   A. Inside [submenuItem]
      1. How do I do this? [topicItem]
      2. How do I do that? [topicItem]
   B. Outside [submenuItem]
      1. Can I go there? [topicItem]
   C. About these hints [longTopicItem]

If you drew a tree of the above menu, with the menuItem at the top and
the submenus and topics below it, it would look like this:


                              -------
                             | Hints |
                              ------- - - - - - -
                             /    \               \
                  -------- /        \ ---------     -------------------
                 | Inside |          | Outside |   | About these hints |
                  --------            ---------     -------------------
                   /     \                      \
 -------------------    -------------------       -----------------
| How do I do this? |  | How do I do that? |     | Can I go there? |
 -------------------    -------------------       -----------------

You'll notice that at most a menu has to contain a menuItem and either
a topicItem or a longTopicItem.

Let's create the above menu to give you an idea of how this works.
The first thing to do is to create the menuItem. It will have a title
(in this case, "Hints") and a contents list (which will contain the
submenuItems "Inside" and "Outside" and the longTopicItem "About
these hints").


hints_menu: menuItem
    title = "Hints"
    myContents = [ inside_menu, outside_menu, about_topic ]
;


The contents of the menu are put into the myContents list. Add them
in the order you want them to appear in the menu.

Next we make the sub-menus. The title of a sub-menu is what is printed
in the main menu; it's contents are the (optional) sub-menus and topics
it contains.


inside_menu: submenuItem
    title = "Inside"
    myContents = [ how_this_topic, how_that_topic ]
;

outside_menu: submenuItem
    title = "Outside"
    myContents = [ go_there_topic ]
;


Finally, we have to define the topics themselves. Again, topics have
a title and a myContents, though they use myContents differently. For
a topicItem, myContents is a list of strings which are printed one by
one. For a longTopicItem, myContents is either a single-quoted string,
a double-quoted string, or a block of code which gets called by menus.t.


how_this_topic: topicItem
    title = "How do I do this?"
    myContents = [
'Have you tried pressing the button?'
'If it didn\'t work, you probably haven\'t pulled the lever.'
'PULL LEVER THEN PUSH BUTTON.'
    ]
;

how_that_topic: topicItem
    title = "How do I do that?"
    myContents = [
'The same way you did this.'
'See the "How do I do this?" hint for more information.'
    ]
;

go_there_topic: topicItem
    title = "Can I go there?"
    myContents = [
'No.'
'I mean it. Don\'t ask me again.'
    ]
;

about_hints_topic: longTopicItem
    title = "About these hints"
    myContents = {
        "This is just an example set of hints. It doesn't do much now,
            other than demonstrate a little bit of what's possible. ";
    }
;


There are at least two other ways that I could have coded the myContents
part of about_hints_topic. I'll leave what those ways are as an exercise
for you.

And that's about it. If you're satisfied with how the standard menu
looks, you need read no further.


==================
Not-So-Basic Menus
==================

There are several changes you can make to your menus. I'll start with the
simpler ones and work up to the more complex.

The background and foreground colors of the menu are controlled through
the "bgcolor" and "fgcolor" properties. These properties are present in
menuItems, submenuItems, and topicItems, and are strings which hold
the name of the color you want the background or foreground color to
be. By default, the bgcolor is set to 'statusbg' and the fgcolor is set
to 'statustext'. Note that these properties are strings because they
are printed inside HTML <body> tags.

You can also control the number of spaces by which sub-menus and topics
(in menuItems and submenuItmes) and strings (in topicItems) are indented
by changing the "indent" property. The indent property is a string which
holds the number of spaces by which the sub-items are indented. By
default, indent is '10' for menuItems and submenuItems and is '30' for
topicItems.

The final string which is printed at the end of all the hints in a
topicItem and at the end of a longtopicItem is held in the "goodbye"
property. By default, this string is set to '[The end]'.

Also, you can modify the "chunkSize" property of topicItems to change the
maximum number of strings the topic will display in the banner at one
time. This property is necessary because the user cannot scroll text in a
banner, and HTML TADS will let you put as much text as you want in a
banner, potentially filling up the screen. The default chunkSize is
6, which means that at most the last six strings will be displayed at
once.

Finally, modifying the navigation keys. This is the most complex of
the menu's features. The keys used to navigate a menu are held in the
"keyList" property of the menuItem. keyList is a list of strings which
match keys with menu operations.

At the top of menus.t, you will find a list of #defined constants. These
constants are for accessing the keys associated with the navigation
operations. These operations are, in order: quit, previous menu, up a
selection, down a selection, and select a menu item.

You'll notice that the constants are all odd numbers. This is because
each operation is bound to two keys. For instance, you can move up a
selection by pressing either 'u' or the up arrow ('[up]'). The first
key for each operation (the ones at position 1, 3, 5, 7, and 9 of keyList)
is the one that is printed in the top banner of the menu to tell people
how to get around.

I actually lied about there being two keys bound to each navigation
operation. There are more than that bound to the "select a menu item"
operation. This is because there are many ways of selecting an item: press
ENTER, press the space bar, press the right arrow.... The reason that this
operation is last in the keyList is so that all items in the list which
are after the 8th one, no matter how many there are, are bound to this
operation.

To tell the truth, the best way for you to figure out how this works is
to experiment on your own. Copy the keyList from menus.t in your own
menu, then change a couple of keys.

