Hyperlinks

Hyperlinks are images or pieces of text which, when clicked, will pass a message to HandleGlkEvent() saying that they've been clicked, allowing you to run special code if you'd like. You might, for instance, want to insert clickable footnotes into your game, or allow players to move about by clicking on items in the room's list of exits... there and endless possibilities. Hyperlinks are set up much the same way as mouse input in text grid or graphics windows. First you have to alert the program to be on the lookout for a clicked hyperlink:

   glk_request_hyperlink_event(gg_mainwin); 

(Swap in the name of the window where hyperlinks will be appearing if it's not gg_mainwin. If you want links in multiple windows, you'll need to make this call multiple times.) Now that the program is ready to respond to a link, you need to build the links themselves. This is done with the glk_set_hyperlink() command. This is called with one argument, a unique non-zero number. You'll probably want to make constants for the link values you choose: "GO_NORTH_LINK" makes for more readable code than, say, "67". Any text or image that follows a glk_set_hyperlink() call will become part of the link, until it reaches a "glk_set_hyperlink(0);" call. (You can also go straight from one link to another, if you wish -- the first link will be completed and the second started with the same call.)

Now your links are ready, and all you need is to customize HandleGlkEvent() to respond to them when the player clicks on them. It should look something like this:

   [ HandleGlkEvent ev context abortres newcmd cmdlen;
      switch (ev-->0) {
         evtype_Hyperlink:
            glk_request_hyperlink_event(gg_mainwin);
            ! Put code here the same way you did with mouse input.
            ! The only difference is that now ev-->1 stores the
            ! source window and ev-->2 the link value.
      }
   ];

And just as in the previous section, note that after responding to one clicked hyperlink, the program won't respond to another unless you explicitly tell it to.