This header defines the tads-io-ext function sets, which provides optional extensions to the standard input/output set.
These functions are defined in a separate function set from the basic tads-io set, because the features defined here are available only on certain platforms. Be aware that using this function set will limit your program to interpreters that support it, and will prevent your program from running on some systems.
By default, when the player selects this sort of menu command, the interpreter sends it to the game by stuffing the literal text of the command into the command line, and returning it from the command-line input function (inputLine(), typically). This was traditionally the only way for the interpreter to send this sort of command to the game. In particular, there was no way to send this kind of command via the "event input" mechanism (as in inputEvent()).
This function allows the game to control (1) which commands are enabled for normal command-line input, and (2) whether or not the commands are enabled for inputEvent(). By default, all commands are enabled for inputLine(), and all are disabled for inputEvent().
When a command is enabled for inputLine(), it's returned from inputLine() as the command-line string corresponding to the command. The SAVE command is returned as the text "save", for example.
When a command is enabled for inputEvent(), it's returned as an InEvtSysCommand event, with the command ID in the second element of the event record's list.
'id' is the ID of the command to enable/disable, or a list or vector of IDs to set. If a list or vector is used, all of the commands listed are set to the same new status. Command IDs are given by the XxxCommand values defined in tadsio.h.
'stat' is the new status to send. This is a combination of the MenuStatXxxEnable and MenuStatXxxDisable flags defined below. For any Xxx, only one of Enable or Disable can be used - if both are specified together, the Enable flag takes precedence. If you don't specify either the Enable or Disable flag for an Xxx, then the command is unaffected in that context - that is, its previous value is left in effect. For example, if you specify MenuStatEventEnable, then the command is enabled for inputEvent(), and its previous status for inputLine() is left unchanged.
'x' and 'y' give the location of the top left corner of the new window. The coordinates are given in pixels relative to the top left of the game window. If these are nil (note that *both* must be nil if either one is), the popup is shown at a suitable local default position for a context menu. On Windows, the default position is the current mouse position.
This function doesn't return until the user either makes a selection from the menu or cancels the menu. If the user clicks the mouse outside of the popup menu, or switches to a different window, the popup is canceled - this means that the popup menu will automatically disappear, and the function will return the 'canceled' status code. If the user makes a selection from the popup menu by clicking on a hyperlink shown within the menu, the menu disappears and the function returns the 'href' status code and the HREF text of the selected hyperlink.
(Note that some systems might have different local conventions for operating a popup menu, so the actual user actions involved in selecting or canceling might differ from system to system. In these cases, the local conventions apply.)
The return value is a list. The first element of the list is one of the PopMenuXxx status codes, indicating what happened. If the status code is PopMenuHRef, the list will have a second element, containing a string giving the HREF of the hyperlink the user clicked on. For any other status codes, the list will have no further elements.
(0x0001 | 0x0000)
(0x0001 | 0x0002)
(0x0004 | 0x0000)
(0x0004 | 0x0008)
MenuStatLineEnable and MenuStatLineDisable let you control the inputLine() status of a command. If neither is specified, the old status is left unchagned for inputLine().
MenuStatEventEnable and MenuStatEventDisable control the inputEvent() status of a command. If neither is specified, the old status is left unchagned for inputEvent().