Glimmr Graphic Hyperlinks

version 1/100805 by Erik Temple

  • Home page
  • Beginning
  • Previous
  • Next



  • Section: Advanced usage

    There may be times where what we want from a graphlink is something other than that it enter a command on the player's behalf. For these cases, we need to write new one or more new "graphlink processing" or "clicking graphlink rules".

    The "clicking graphlink rules" are triggered when a graphlinked window receives mouse input. The rule should test to see whether the mouse input hit a graphlink, and then instruct Inform what to do about it. We can test whether a graphlink was clicked on by using the phrase "if the click hit a hot link". Here is the default rule:

        A clicking graphlink rule (this is the default command replacement by graphlinks rule):
            if the click hit a hot link:
                follow the graphlink processing rules;
                rule succeeds;
            otherwise:
                now glulx replacement command is "".
            
    We look through the table for entries that apply to the window that was clicked (the "current graphlink window"), and when we find one, we test whether the click was within the bounds of that entry's rectangle. If it was, the player has successfully hit a graphlink: we pass handling off to the graphlink processing rules. Note that, when a hot link is detected, the "candidate replacement command" variable is set to the command provided when the graphlink was set up, and the "current graphlink" is set to the identifier (these are assigned within the decide phrase).

    If the click failed to hit a link, we simply set the glulx replacement command to null. Glulx Entry Points handles the transformation of the glulx replacement command into a "typed" command. If there is any text at all in the variable, then that text will be pasted as a command. If the glulx replacement command is null, nothing will happen except that the window will once again become receptive to input.

    We will rarely need to adjust the clicking graphlink rules--most often, we would adjust them when we want to bypass the Table of Glulx Graphlink Replacement Commands altogether. More often, we will want to intervene in the graphlink processing rules. The graphlink processing rules is a rulebook that runs only after a graphlink has definitively been clicked. (Note: If we are using GGH with Glimmr Canvas-Based Drawing, the graphlink processing rules will be an object-based rulebook, with the object generally being the g-element that was clicked on to trigger the graphlink.)

    The default graphlink processing rule changes the glulx replacement command to the candidate replacement command (which was set in the clicking graphlink rules):

        A graphlink processing rule (this is the default graphlink processing rule):
            cancel input in main window;
            now the glulx replacement command is the candidate replacement command;
            now the candidate replacement command is "";
            rule succeeds.

    Because this will result in the command being printed to the window, we need to cancel input in the window (a requirement of Glk, the interface layer of Glulx). We also reset the candidate replacement command.

    There may be times when we do not want to use the glulx replacement command to communicate the outcome of a graphlink, and we do have two other options. Neither of these, however, will have any effect unless we write our own graphlink processing rule. We use variants of the "set graphlink" phrase to prepare these alternate outcomes:

        set a graphlink in the graphics-window identified as "undo button" from {10, 10} to {40, 25} as 2.

        set a graphlink in the graphics-window identified as "jump button" from {10, 10} to {40, 25} as the action of jumping.

    The first phrase sets the "alt" entry in the table to the number 2. We can later read this number and make an appropriate decision about how to respond (perhaps looking up the result in a separate table). The second phrase sets the "action" entry to a stored action (jumping, in this case), which allows us to specify an action without specifying the text of the command. This means that we can fire the command "silently," without printing the command to the screen.

    Again, we need to write our own graphlink processing rules to deal with such alternatives. Here's how we might write a rule to execute a stored action:

        First graphlink processing rule (this is the direct action firing rule):
            choose row (current graphlink row) from the Table of Graphlink Glulx Replacement Commands;
            if there is an action entry:
                try the action entry;
            rule succeeds.

    Note the use of the "current graphlink row" variable. This is set when a graphlink is clicked and can be used to quickly and accurately refer to the row containing the graphlink (from the Table of Graphlink Glulx Replacement Commands). If our linkid entries are not unique, this allows us to avoid difficulties in reselecting the proper graphlink.