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; 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: 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 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 14th Nov 2002