Gtoolbar
--------

Gtoolbar is an Inform bi-platform library contribution, designed
specifically for Glulx Inform games.  It adds a graphical toolbar,
like those found in most Windows and KDE applications, to the top of
the display window, when the game is run in a graphical Glulx
interpreter.

The default toolbar appearance has icons for many common Inform game
actions.  Toolbar appearance can be customized specifically for a
game.

Using Gtoolbar is simple.  For a default toolbar, used with an Inform
game that uses no special library tricks, all that is required is a
single additional Include statement in the Inform game source.

Gtoolbar insinuates itself into the Inform library's input routines,
and catches Glk events and other entry points to manage itself without
needing any other interactions.  Games compiled with Gtoolbar may be
played on non-graphical interpreters, and will behave exactly as they
would if Gtoolbar were not compiled into the game.

Gtoolbar offers tools for the following common actions:

    o Compass point movement (north, south, northwest, etc.).
    o Up, down, in and out.
    o Look, inventory, wait, and again.
    o Examine, take, drop, open, close, and read.
    o Game control: save, restore, restart, and quit.
    o Toolbar control: hide and restore the toolbar itself.

Gtoolbar adds approximately 27Kb to the size of a built game.  Of
this, about 19Kb is icon images, and the remaining 8Kb is the toolbar
management code itself.

For a screenshot, showing Advent.inf built for Glulx and running under
Linux Glulxe, see the "screenshot.gif" file in the Demo subdirectory.


Starting Gtoolbar
-----------------

Gtoolbar consists of two basic files:

    Gtoolbar.inf       - The Inform code to manage to toolbar
    Gtbicons.zip       - Zip archive of the toolbar icon images

To add a Gtoolbar to your game, first arrange for Gtoolbar.inf to be
included in your game source.  There are at least three ways of doing
this:

    o Copy Gtoolbar.inf into the directory containing your other game
      source, rename it Gtoolbar.h, and add a line to include this file
      somewhere shortly after the standard library parser inclusion,
      for example:

        ...
        Include "Parser";
        Include ">Gtoolbar.h";        ! Addition for Gtoolbar
        ...

    o Copy Gtoolbar.inf into the directory containing the other Inform
      bi-platform libraries, rename it to Gtoolbar.h, and include the
      file in your game source with something like:

        ...
        Include "Parser";
        Include "Gtoolbar";           ! Addition for Gtoolbar

    o Copy Gtoolbar.inf into the directory containing the other Inform
      bi-platform libraries, rename it to Gtoolbar.h, and edit the
      library file Parser.h so that it always includes Gtoolbar.h
      as part of normal operation, for example:

        ...
        Include "parserm";
        Include "Gtoolbar.h";         ! Addition for Gtoolbar
        ENDIF;
        <end of file>

      If you do this, every game you build with this library will
      include Gtoolbar automatically.

Now compile the game source as normal.

The second step in adding Gtoolbar is to arrange for the icon images
to be available to the interpreter.  If your interpreter can read
image resources from external files, all that you need to do is to
unzip Gtbicons.zip into the game directory.  This creates files PIC1
to PIC31, and interpreters such as Glulxe for Linux can use these
files directly.

If you run your game with a graphical Glulxe interpreter, you should
now see the toolbar at the top of the screen display.  (If you see a
very small window above the status line, with no tool icons displayed,
then your interpreter has not found the image resources.)

For better performance, and for more convenient game distribution, you
will probably want to bundle up the executable game file and the icon
images into a single Blorb file.  A couple of Blorb tools exist for
various platforms; choose the most convenient for your system.  Please
refer to later notes below for details specific to Blorbtar and
Iblorb.

This is all that is required to add the basic Gtoolbar to a game.
However, Gtoolbar is customizable, to an extent, and if you wish to
change its appearance, the strings it substitutes when icon tools are
used, or if you want to add your own tools and icons, see below.


Changing toolbar appearance
---------------------------

By default, Gtoolbar starts fully visible.  Your game can arrange for
it to start instead in hidden (collapsed) mode, with a call to

    gtb_set_visible (false);

placed in the game's Initialise() function.  The game can also call
gtb_set_visible() at any other point, if you need to force the toolbar
to be either visible, or hidden, for some reason.

Your game can check toolbar visibility with

    gtb_get_visible ();

which returns true if the toolbar is visible, and false if it has been
hidden.

For example, you might want to arrange for the game to automatically
collapse the toolbar while in a help menu.  Since help usually uses
single-keypress navigation, a toolbar is not useful in the context of
help menus.  In this case, something like the following will collapse
the toolbar at the start of help, and restore it again afterwards:

    vis = gtb_get_visible ();
    if (vis)
        gtb_set_visible (false);

    ...help menu code...

    if (vis && ~~gtb_get_visible ())
        gtb_set_visible (true);

The game can also check whether Gtoolbar has been able to create a
toolbar at all, with

    gtb_is_available ();

This function returns true if a toolbar is being displayed (even if
collapsed), and false otherwise (for example, if the Glulxe
interpreter being used does not support graphics).  If the function
returns false, nothing else that you do to Gtoolbar matters.

If you need to know the Gtoolbar version number, you can get it by
calling

    gtb_version ();

One way to print it out might be

    ver = gtb_version ();
    print "Gtoolbar version ", ver/256, ".", ver%256, "^";

You can also use

    gtb_print_ident ();

to print out a complete Gtoolbar identification string to the current
output stream.  This prints something like "Gtoolbar v2.06".


Changing toolbar layout
-----------------------

Your game can vary the number, and position, of the toolbar icons that
are displayed, using the gtb_set_icon_list() function.  In its simplest
form, this takes a single argument that describes how you want the
toolbar to appear.  Note that this argument must _not_ be a dictionary
string, but rather an Inform "Array mumble string "..."" value.

The string argument to gtb_set_icon_list() uses the following ASCII
characters to indicate icons and control:

    >  - Compass rose     ^  - Up/down    |  - Separator (spacer)
    N  - In               O  - Out        L  - Look
    I  - Inventory        Z  - Wait       G  - Again
    T  - Take             R  - Drop       P  - Open
    C  - Close            D  - Read       S  - Save
    E  - Restore          A  - Restart    Q  - Quit

The default toolbar icon list is the string

    >^NO|LIZG|XTRPCD|SEAQ

So, for example, the following code, added to Initialise(), will set
up Gtoolbar to display just a quit icon, a separator, and then the
compass rose:

    Array my_list string "Q|>";
    ...
    gtb_set_icon_list (my_list);

If you pass null (0) to gtb_set_icon_list(), Gtoolbar will revert to
using its default toolbar icon list.

The function

    gtb_get_icon_list ();

returns the current icon list being used by Gtoolbar.


Using "virtual" toolbars
------------------------

If you find the toolbar becoming too cluttered, Gtoolbar allows you to
split it into "tiers".  Gtoolbar will then display just one of the
tiers, and will add small forward and backward arrows as necessary to
let the user move between tiers, giving the appearance of more than
one usable toolbar.  Use ":" in the icon list to separate tiers.

For example, since the default toolbar is already somewhat crowded,
you might want to split it into two tiers using the icon list string

    >^NO|LIZG|XTRPCD:SEAQ

This moves the game controls (save, restore, restart, and quit) to
their own separate "virtual" toolbar.  The initial toolbar will not
display these icons, but will instead display a small forward arrow at
its far right edge.  When you click this arrow, Gtoolbar switches to
displaying the game controls instead, this time adding a small back
arrow at the far left of the controls to allow you to return to the
prior toolbar display.

You can use as many tiers as you like, for example

    >^NO:LIZG:XTRPCD:SEAQ

breaks up the default icon list into four tiers.

When setting an icon list, you can also set the initial display tier
by passing the tier number, starting at 0, to gtb_set_icon_list() as
an optional second argument.  To start the above toolbar at the game
control tier, for example, use

    Array my_list string ">^NO:LIZG:XTRPCD:SEAQ";
    ...
    gtb_set_icon_list (my_list, 3);

The default tier number, if not supplied, is 0.

The function

    gtb_get_icon_tier ();

returns the current toolbar tier on display.  To explicitly set just
the tier from inside a game, you can use gtb_set_icon_tier(), for
example:

    gtb_set_icon_tier (3);


Changing tool strings
---------------------

You can change the strings that Gtoolbar tools add to the Inform
library input buffer, by using gtb_set_icon_string().  This takes two
main arguments, and an optional third: the icon whose string you are
changing, the new string for the icon, and for compound icons (the
compass rose, and up/down buttons), an index value indicating which
precise icon string you want to set.

As with gtb_set_icon_list(), string arguments must be Inform strings,
not dictionary strings.  They must also have one of '_', '<', or '>'
as their first character, since this controls how Gtoolbar will handle
them.

For example, to change the quit icon to add "q" instead of "Quit" to
the input buffer, use

    Array my_quit string "_q";
    ...
    gtb_set_icon_string ('Q', my_quit);

The gtb_set_icon_string() function returns true if the string was set
correctly, and false if it could not be set (for example, incorrect or
invalid arguments).

If the first character of the string is '_', Gtoolbar will delete any
partially typed input on icon press, and return the rest of the string
to the Inform parser as if it had been typed as a single line of
input.  Use this for self contained commands, such as "Quit", "North",
and "Look".

If the first character of the string is '<', Gtoolbar will search the
input buffer for any partially typed input.  If there is input already
present, it will prepend the rest of the string to the data already
present, and return it to the Inform parser.  If however there is no
input already present, Gtoolbar will insert the rest of the string
into the input buffer, then allow the user to type after or edit it.
Use this for commands that have a target noun, such as "Examine" or
"Open".

If the first character of the string is '>', Gtoolbar will search for
partially typed input, the same as for '<' prepend.  If there is input
already present, it will add the rest of the string to it, and return
it to the Inform parser.  If there is no input already present,
Gtoolbar will siimply reissue the line read, in effect, doing nothing.
Typical use for this would be icons that represent nouns.  There are
no icon strings of this type in the default Gtoolbar configuration.

If the string is null (0), this disables the tool icon, but leaves it
visible.  Use this for separators, placeholders, or to allow
context-sensitive toolbars.  Note that Gtoolbar gives no visual
indication that an icon is inactive -- it is simply not clickable.

To change compass rose and up/down icon strings, you need to reprogram
the strings for several icons (eight for the compass rose, two for the
up/down buttons).  To do this, use the optional third argument to
gtb_set_icon_string() to indicate which precise icon string you wish
to change.  Values are 1 to 8, representing, in order, NW, N, NE, W,
E, SW, S, and SE, for the compass rose, and 1 or 2, for up and down
icons.

So, for example, if your game only uses the four main cardinal compass
directions, you could disable the other four compass points with

    gtb_set_icon_string ('>', 0, 1);           ! Set NW to NULL
    gtb_set_icon_string ('>', 0, 3);           ! Set NE to NULL
    gtb_set_icon_string ('>', 0, 6);           ! Set SW to NULL
    gtb_set_icon_string ('>', 0, 8);           ! Set SE to NULL

Your game can retrieve icon strings with a call to the function
gtb_get_icon_string().  This takes one main argument, and an optional
second: the icon whose string you are retrieving, and for compound
icons (the compass rose, and up/down buttons), an index value
indicating which precise icon string you want to retrieve.

So, to obtain the string for the quit icon, call:

    gtb_get_icon_string ('Q');

For compass rose and up/down icons, you need to supply a second
argument to gtb_get_icon_string(), so that it knows which particular
string you are requesting.  The value is 1 to 8 for compass rose
queries, representing, in order, NW, N, NE, W, E, SW, S, and E, and 1
or 2, for up and down icons, as with gtb_set_icon_string().  For
example

    gtb_get_icon_string ('>', 2);

returns the string for compass rose North.  If gtb_get_icon_string()
doesn't understand the arguments passed to it, it returns -1 (because
0 is a valid, null, icon string).


Removing Gtoolbar altogether
----------------------------

If your game calls

    gtb_destroy ();

then the toolbar is completely removed from the display, as if it had
never existed.

A call to

    gtb_create ();

will create a new toolbar.  In order to give the display the same
arrangement as when it is created automatically (that is, to get the
toolbar placed above the status window), Gtoolbar must destroy the
existing status window, create the toolbar window, and then recreate
the status window again.  In doing this, Gtoolbar makes a few
assumptions about the way the display is laid out, and it's probably
best if you can avoid using this function where possible.

In particular, for gtb_create() calls, Gtoolbar assumes a totally
standard display layout, placing the toolbar at the display top, the
status window next, and the main window after.  It does not make any
entry point calls while rearranging windows, assuming that the game
knows about the window shuffling since it made the call to
gtb_create().  If your game does something special with windows
layout, you will probably need to replace this function with a version
tailored more to your needs.


Gtoolbar icon numbers
---------------------

If you want to add your own icons and tools, or program Gtoolbar at a
lower level, you need to know about icon numbers.

When you pass an icon id, such as 'Q' (for "Quit"), to functions like
gtb_set_icon_string(), Gtoolbar will convert this into a number for
its own internal use.

The icon numbers for the standard Gtoolbar icons are:

    Compass rose                           - 6 to 13, representing, in
                                             order, NW, N, NE, W, E, SW,
                                             S, and SE
    Up/down                                - 14 and 15
    In, out                                - 16, 17
    Look, inventory, wait, again           - 18, 19, 20, 21
    Examine, take, drop, open, close, read - 22, 23, 24, 25, 26, 27
    Save, restore, restart, quit           - 28, 29, 30, 31

Icon number 1 is reserved for the vertical control separator, and
numbers 2 and 3 for the horizontal control separator and the vertical
spacer separator.  Icon numbers 4 and 5 are reserved for the next and
prior tier arrows.

Gtoolbar defines constants for these, or uses constants for them that
may have already been defined by your Blorb tool.  You should always
refer to the icon numbers by Gtoolbar constants, since the actual
Blorb image resource values may vary depending on how your Blorb tool
puts together a Blorb file.

The constant defintions are simply the numbers prefixed with GTB_PIC,
so that for example, the Quit button is

    GTB_PIC31

and is a constant which may, or may not, have the value 31 (see below).


Using Gtoolbar with Blorbtar
----------------------------

Blorbtar numbers Blorb resources by looking at the name of each file
that it is handed to package.

Since the game's executable code must always be resource 0, this means
that you need to copy the game .ulx file to a file called "STORY0",
unpack the Gtoolbar icons into the same directory, then call Blorbtar
with the command

    blorbtar c mygame.blb STORY0 PIC1 PIC2 PIC3 PIC4 PIC5 PIC6 PIC7 \
        PIC8 PIC9 PIC10 PIC11 PIC12 PIC13 PIC14 PIC15 PIC16 PIC17   \
        PIC18 PIC19 PIC20 PIC21 PIC22 PIC23 PIC24 PIC25 PIC26 PIC27 \
        PIC28 PIC29 PIC30 PIC31

The resulting file 'mygame.blb' has the executable story as Blorb
resource number 0, and the Gtoolbar icons as Blorb resources 1 to 31.

Where the constants GTB_PIC1 to GTB_PIC57 are not already defined
before Gtoolbar is included in your game, Gtoolbar will automatically
define them with the values 1 to 57.  So in this case, the value of
GTB_PIC1 will be be 1, GTB_PIC2 will be 2, and so on, and the GTB_PIC
constant values will exactly match their internal Gtoolbar icon
numbering.


Using Gtoolbar with Iblorb
--------------------------

If you want to use Gtoolbar with Iblorb, you will need to do a little
extra work.

First of all, you need an additional Include statement in your game,
to obtain the Blorb resource numbers that Iblorb outputs.  This is
something like

    #Include ">mygame.bli";

and needs to be included _before_ including Gtoolbar itself.

Secondly, you need to rename all of the Gtoolbar icon image files so
that they have a .png extension, since Iblorb requires this:

    $ cp PIC1 PIC1.png ..., or
    % ren PIC1 PIC1.png ...

Thirdly, you need to add all of the Gtoolbar icon images to the
Iblorb resources file.  For example, mygame.res:

    CODE                    mygame.ulx
    PICTURE GTB_PIC1        PIC1.png
    PICTURE GTB_PIC2        PIC2.png
    ...
    PICTURE GTB_PIC31       PIC31.png

Now, when you compile your game with Iblorb's 'front', it creates a
.bli file that contains definitions like these:

    Constant GTB_PIC1 3;    !Blorb Pict:PIC1.png
    Constant GTB_PIC2 4;    !Blorb Pict:PIC2.png
    ...
    Constant GTB_PIC31 33;  !Blorb Pict:PIC31.png

Because it is included after 'mygame.bli', Gtoolbar is able to use
these constants to find its icon images.  Note however that the actual
GTB_PIC constant values do not match Gtoolbar's internal numbering;
GTB_PIC1 is 3 in this case, whereas it was 1 with Blorbtar.  This is
why it's important to always use the GTB_PIC constants when referring
directly to icon numbers.

Finally, on the topic of Iblorb, here is a complete resources file
section for Gtoolbar that you can cut and paste, to save a bit of
time creating an Iblorb resources file:

<cut here>
PICTURE GTB_PIC1        PIC1.png
PICTURE GTB_PIC2        PIC2.png
PICTURE GTB_PIC3        PIC3.png
PICTURE GTB_PIC4        PIC4.png
PICTURE GTB_PIC5        PIC5.png
PICTURE GTB_PIC6        PIC6.png
PICTURE GTB_PIC7        PIC7.png
PICTURE GTB_PIC8        PIC8.png
PICTURE GTB_PIC9        PIC9.png
PICTURE GTB_PIC10       PIC10.png
PICTURE GTB_PIC11       PIC11.png
PICTURE GTB_PIC12       PIC12.png
PICTURE GTB_PIC13       PIC13.png
PICTURE GTB_PIC14       PIC14.png
PICTURE GTB_PIC15       PIC15.png
PICTURE GTB_PIC16       PIC16.png
PICTURE GTB_PIC17       PIC17.png
PICTURE GTB_PIC18       PIC18.png
PICTURE GTB_PIC19       PIC19.png
PICTURE GTB_PIC20       PIC20.png
PICTURE GTB_PIC21       PIC21.png
PICTURE GTB_PIC22       PIC22.png
PICTURE GTB_PIC23       PIC23.png
PICTURE GTB_PIC24       PIC24.png
PICTURE GTB_PIC25       PIC25.png
PICTURE GTB_PIC26       PIC26.png
PICTURE GTB_PIC27       PIC27.png
PICTURE GTB_PIC28       PIC28.png
PICTURE GTB_PIC29       PIC29.png
PICTURE GTB_PIC30       PIC30.png
PICTURE GTB_PIC31       PIC31.png
<cut here>


Using Gtoolbar with some other Blorb packager
---------------------------------------------

If you use Gtoolbar with some other Blorb packaging tool, here are the
rules for defining the GTB_PIC constants.

If your Blorb packager allows you to control the precise Blorb
resource numbers it uses, arrange for Gtoolbar's PIC1 to be Blorb
resource number 1, PIC2 to be resource number 2, and so on.  In this
case, Gtoolbar's default values for the GTB_PIC constants will be fine
for use with the output Blorb file.

If your Blorb packager assigns Blorb resource numbers to image files
automatically, you will need to define the constants GTB_PIC1 to
GTB_PIC31 before you include Gtoolbar in your game.  The values to
assign are the Blorb resource numbers that your Blorb packager has
assigned to each image file.  For example, if it assigned Gtoolbar's
PIC31 to Blorb resource number 123, then you need to define GTB_PIC31
to be 123.  When Gtoolbar sees prior definitions of the GTB_PIC
constants, it will use them in preference to its default values.


Adding your own tools and icons
-------------------------------

Gtoolbar supports up to 26 user defined icons, allowing your game to
add to, or even entirely replace, the default toolbar.

User defined icon numbers begin at GTB_PIC32, and end at GTB_PIC57.
User defined icons are represented by the lower case letters 'a' to
'z' in icon list strings, and in calls to set and get icon strings.

To add an icon, you will need to create the icon image, add a call in
your game to set a string for the icon, and alter Gtoolbar's icon list
to include your new icon.

For example, to create an "undo" icon, take the following steps:

    o Using your favorite icon editor (or at least one you can get
      along with), create a PNG file containing a 32x32 pixel icon.
      Gtoolbar uses $DCDCDC as its background color, $FFFFFF for
      light shading, and $9A9A9A for dark shading.

    o Decide on a letter to assign to the tool.  For "undo", 'u' seems
      like a good choice.  This is the 21st letter of the alphabet, so
      this means that the corresponding Gtoolbar icon number is 52
      (calcuated as 32 + 21 - 1).

    o Copy the PNG icon file to PIC52 if you are using Blorbtar, or
      PIC52.png if using Iblorb.

    o Add code to your game's Initialise() function to associate a
      string with the new icon, and ensure that the new icon appears
      in the list of tools that Gtoolbar displays.  For example:

        Array my_list string "uQ";
        Array my_undo string "_Undo";
        ...
        gtb_set_icon_string ('u', my_undo);
        gtb_set_icon_list (my_list);

    o Rebuild the game, taking care to include PIC52 in any Blorb
      file that gets created with the build.  For Blorbtar, this
      means remembering to add "PIC52" to the arguments list.  For
      Iblorb, it means adding a "PICTURE GTB_PIC52 PIC52.png" line
      to the game's .res file.

Tool icons do not need to be 32x32 pixels, but this is a comfortable
size and fits well inside the Gtoolbar graphical window.  Shorter
icons will probably look okay, depending on how short they are.
Taller ones will most likely be clipped at the bottom.  Wider or
narrower icons are fine, but unorthodox (except for separators).

If you need a different toolbar height, you will need to alter the
standard Gtoolbar images, since they are all currently designed to fit
the window.  The toolbar display height is set by Gtoolbar by reading
the height of GTB_PIC1, the control vertical separator.

There is currently no method to create user defined icons that behave
like the compass rose and up/down buttons; that is, are composed of
many smaller icons.  This would be too complex for the simple icon
list method used by Gtoolbar.

If you are adding icons without deleting any of the standard ones, you
might consider splitting the toolbar into tiers, since the default
toolbar display is already pretty full.


Tuneable constants
------------------

Gtoolbar allows you to override a few of its internal constants, to
provide for some limited tuning.  You do this by defining selected
Gtoolbar constants before including Gtoolbar in your game.

You can set values for the following tuning constants:

  GTB_PRESS_TIMEOUT, GTB_TIMER_GRANULARITY

    The delay in milliseconds used by Gtoolbar to give the appearance
    of button presses, and the period of Glk timeouts to implement
    this delay.  The default is to produce a 200 mS delay, at a
    granularity of 50 mS.  Gtoolbar uses multiple shorter Glk timeouts
    to create the delay because Glk timeouts are not guaranteed to be
    accurate.  This way, the effect of Glk timeout jitter is limited
    to +/- GTB_TIMER_GRANULARITY (that is, the default 200 mS delay
    will in actuality be between 150 mS and 250 mS).  Both values must
    be greater than zero, and the minimum useable will depend on the
    specifics of a particular Glk library.  A minimim of 10 mS, with
    10 mS granularity, is typical.

  GTB_MAXIMUM_ICONS

    The maximum number of tool icons that Gtoolbar will display on a
    single toolbar, or toolbar tier.  Gtoolbar will silently refuse to
    display any more icons than this number.  Note that the compass
    rose consumes eight separate icons, and the up and down buttons
    two icons.  The default is 50 icons displayable at a time.  Each
    displayable icon requires 20 bytes of memory, so the default
    configuration uses 1000 bytes to save icon positions.  You can
    increase this value if you have an extreme need for lots of icons
    all displayable at once, or decrease it if you really need to
    shave bytes from memory usage.

  GTB_BACKGROUND, GTB_LIGHT_SHADE, GTB_DARK_SHADE

    The background color for the toolbar graphical window, and the
    top/left and bottom/right shading colors used in producing 3d
    effects.  Default values are $DCDCDC for background, and $FFFFFF
    and $9A9A9A for light and dark shading respectively.  If you
    redefine a complete icon set for Gtoolbar, and use a background
    color for the graphics other than #DCDCDC, you will probably want
    to redefine GTB_BACKGROUND.

  GTB_TOOLBARWIN_ROCK

    The Glk rock value associated with the toolbar graphical window.
    The default value is 5001.  Unless this clashes with some other
    window rock in use by your game or by something included by your
    game, there should be no need to change this.

For example, to set a much longer button press time (the time between
clicking on the icon, and Gtoolbar making changes to the games input
buffer), you could use:

    ...
    Constant GTB_PRESS_TIMEOUT 1500;
    Include ">Gtoolbar.h";
    ...

In practice, the default values for all of the above should be fine
for pretty much every Gtoolbar use.


Entry points
------------

Gtoolbar takes control of a handful of the bi-platform library's entry
points, namely

    o HandleGlkEvent
    o InitGlkWindow
    o IdentifyGlkObject
    o AfterPrompt

The first three are specific to Glk entry points, and it's not likely
that your game will use them.  The fourth is generic to Inform, and is
used only by games that try to achieve special behaviors.  A typical
Inform game does not any of these entry points.

If, however, you do need to make use of these, then you will need to
make a few small changes to your code to interact with Gtoolbar.
Because Gtoolbar takes control of these, it passes on calls to the
entry points via a new function name:

    o GtbHandleGlkEvent
    o GtbInitGlkWindow
    o GtbIdentifyGlkObject
    o GtbAfterPrompt

So, if your game needed AfterPrompt(), and Gtoolbar is using it, you
can alter your code to define a function GtbAfterPrompt(), and
Gtoolbar will call it for you when it receives a call to the entry
point AfterPrompt().

One particular case where there is a clash over entry points is if you
combine Gtoolbar with JustEnoughGlulx.h.  In this case, you will need
to edit JustEnoughGlulx.h so that its definitions of InitGlkWindow()
and IdentifyGlkObject() are instead definitions of GtbInitGlkWindow
and GtbIdentifyGlkObject.  For the current JustEnoughGlulx.h, this
means renaming the functions at lines 51 and 73 respectively.

To avoid splitting Gtoolbar into several source files, or making
changes to grammar.h, Gtoolbar will define stubs for all of its entry
points unless you tell it not to by defining a constant before you
include the Gtoolbar code.  The constants are the name of the entry
point, prepended with "Replace_".  So, if your code implements the
GtbAfterPrompt entry point, you should ensure that your code contains

    Constant Replace_GtbAfterPrompt;

before statements or directives that include Gtoolbar.  This is
slightly different from standard Inform library stubs, but it does
keep the simple cases simple, at the cost of slight inconvenience for
complex games.

As well as standard Glk entry point calls, Gtoolbar makes a call

    GtbInitGlkWindow (GTB_TOOLBARWIN_ROCK)

just before it creates the toolbar window.  If you want to take over
toolbar window creation for yourself, you need to create a graphical
window, store its reference in gtb_toolbarwin, then return 1.  If you
have not created the graphical window, and you want Gtoolbar to do
this as normal, return 0.

Gtoolbar also defines a new entry point, that you can use to receive
information about toolbar events:

    o GtbToolbarEvent (pic, context, arg)

This entry point has three arguments: pic is the icon number involved,
context indicates how the call arose, and arg is auxiliary data
specific to the call.  The icon numbers are as defined above (for
example, GTB_PIC31 is the quit icon), and context has the following
values:

    o 0 if the user has just clicked on the toolbar, with pic
      indicating the icon.  This call occurs for normal icons, for the
      separators (the ones that collapse and reinstate the toolbar and
      the spacer, icon numbers GTB_PIC1, GTB_PIC2 and GTB_PIC3), and
      the tier control arrows (icon numbers GTB_PIC4 and GTB_PIC5).
      It also occurs if the user clicked on the toolbar, but clicked
      outside of any icon, in which case pic is 0.

      On context 0 calls, arg contains 0 if the toolbar was clicked
      inside Inform line input (KeyboardPrimitive), and 1 if clicked
      inside Inform character input (KeyCharPrimitive).

      Returning -1 indicates that the entry point has completely
      handled the event, and Gtoolbar need do no more.  Returning 2
      indicates that the entry point handled the event, and Gtoolbar
      should now go ahead with displaying the button as pressed, and
      waiting for a timeout (except for the separators and tier
      control arrows, which never delay their operation, and pic 0,
      which does nothing), even if the icon has no substitution string
      associated with it.

      Returning any other value, for example true or false, indicates
      that the entry point is happy for Gtoolbar to continue to handle
      the icon tool event as normal, that is, display the button as
      pressed and wait for a timeout if the icon has a substitution
      string associated with it, otherwise do nothing further.

    o 1 if Gtoolbar has seen a timeout, and is just about to work on
      the Inform input buffer, with arg set to the Inform input buffer
      address as received by HandleGlkEvent.  This call only occurs
      for "normal" toolbar icons (that is, not GTB_PIC1 to GTB_PIC5,
      and not 0).

      Returning -1 or 2 indicates that the entry point has handled
      Inform input buffer changes, or done whatever other work it
      wanted to do for that icon, and that Gtoolbar need do no more.

      Returning any other value, for example true or false, indicates
      that the entry point is happy for Gtoolbar to continue to handle
      the timeout as normal, that is, alter the Inform input buffer
      according to the rules of the icon's substitution string.

    o 2 after Gtoolbar has altered the Inform input buffer for the
      icon clicked, again with arg set to the Inform input buffer
      address, and again only for "normal" toolbar icons.

      Gtoolbar ignores the entry point return value for this value of
      context.

This entry point should allow you to attach toolbar icons to more or
less any game action that you wish, rather than being restricted to
the standard input buffer changes provided by Gtoolbar.  (It's also
likely to be slightly tricky to use in a general purpose way.  For
example, when called, there is normally either a line or a character
input request outstanding on the main window.  This means that your
game cannot print to it without first canceling that request.)

For example, the following game code implements the quit tool icon
much more directly (and in a much more cavalier fashion) than adding
the string "Quit" to the Inform input buffer:

    ...
    Constant Replace_GtbToolbarEvent;
    Include ">Gtoolbar.h";
    ...
    [ GtbToolbarEvent pic context arg;
        if (context == 1 && pic == GTB_PIC31)
           quit;
    ];

Another example GtbToolbarEvent() sets the toolbar to full size, when
collapsed, if the user clicks anywhere inside the collapsed toolbar
window (normally it would do this only for clicks on the horizontal
separator), and also arranges for the toolbar to collapse if a spacer
separator is clicked:

    [ GtbToolbarEvent pic context arg;
        if (context == 0) {
            if (~~gtb_get_visible ()) {
                gtb_set_visible (true);
                return -1;
            }
            if (pic == GTB_PIC3) {
                gtb_set_visible (false);
                return -1;
            }
        }
    ];


Notes and omissions
-------------------

The Gtoolbar icons images, with just one or two exceptions, are
largely lifted out of KDE.  The stated reason for this is that they
offer a readily understood idiom for GUI interactions.  The real
reason is that I have virtually no talent for creating or designing
icons.

Gtoolbar requires the Glulx interpreter to support graphics, mouse
input in graphical windows, and timers.

User defined icon support is limited.  In particular, the icon list
feature may be insufficient for some needs, and there is no way to
create composite icons such as the compass rose.

Prepended icon strings try to be smart about whether they do anything
or not.  For example, if Gtoolbar finds that existing buffered input
matches a toolbar icon string, it will not prepend any new text.  This
mechanism is imperfect.

Substitution icon strings simply dump any existing buffered input,
before inserting themselves in the input buffer.  This is somewhat
draconian, and might not always be what is wanted.

Appended icon strings are implemented simplistically.  They will add
themselves to existing input buffer data, and always complete input.
If there is no existing input buffer data, they do nothing.

The only way to find out what input exists already when an icon is
clicked is to cancel the Glk line request.  This means that if
Gtoolbar needs to continue with line input, the results of the line
cancel remain displayed, leaving the screen a little untidy.

When echoing an icon string as if input, Gtoolbar always prints a fake
">" prompt, even if the game or library prompt was different.  This is
because calling L__M(##Prompt) displays an unnecessary newline, and
breaks up the flow of game display even more than it already is.

Gtoolbar relies on a Glk library not complaining about a request for
mouse input from a window where one may already be outstanding.
Existing Glk libraries seem not to mind this.  The Glk specification
does not say either whether this is permitted, or whether it is a
Glk error.

Gtoolbar takes over a handful of Inform library entry points
completely.  It might be better if this could be avoided, especially
in the case of AfterPrompt().

Getting Gtoolbar icons into the right resource numbers in a Blorb file
can be awkward.  Similarly, telling Gtoolbar what resource numbers a
Blorb packager has allocated to its icon images can also be awkward.

Resizing an Xglk frame that contains graphics often results in untidy
(that is, broken) rendering of parts of the display, most notably the
nongraphical Glk windows.  This is probably an Xglk bug, and may not
occur with other Glulxe interpreters.  Use Ctrl-L to persuade Xglk to
display the resized frame correctly.


Licensing
---------

Gtoolbar is released under version 2.1 of the GNU Lesser General
Public License (LGPL):

    This program is free software; you can redistribute it and/or
    modify it under the terms of the GNU Lesser General Public License
    as published by the Free Software Foundation; either version 2 of
    the License, or (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU Lesser General Public License for more details.

    You should have received a copy of the GNU Lesser General Public
    License along with this program; if not, write to the Free
    Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
    02111-1307  USA

It's generally agreed that using the LGPL means that you can include
Gtoolbar in your game, without needing to publish the game's source
code, which might otherwise be the case if Gtoolbar used the ordinary
GPL.  The LGPL explicitly permits Gtoolbar to be used in "non-free
programs".

And just in case there's any other doubt, the LGPL includes the clause

  "14. If you wish to incorporate parts of the Library into other free
       programs whose distribution conditions are incompatible with these,
       write to the author to ask for permission."

in which case, Gtoolbar comes with express permission for its use in
Inform games for which the source is not published.  You may include
Gtoolbar freely in Glulx Inform games without needing to make any of
the rest of your game source available.

If you make additions to the internal operation of Gtoolbar, though,
please publish your changes.


--

Simon Baldwin <simon_baldwin@yahoo.com>
14th Nov 2002
