# tadsiox.h | documentation

    #charset "us-ascii"
    #pragma once

    /*
     *   Copyright (c) 1999, 2006 Michael J. Roberts
     *
     *   This file is part of TADS 3
     *
     *   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.
     */

    /*
     *   The TADS input/output extensions function set.
     */
    intrinsic 'tads-io-ext/030000'
    {
        /*
         *   Show a popup menu.  This opens a temporary window, drawn in a style
         *   consistent with the local conventions for popup menus.  The new
         *   window is shown in the foreground, in front of the active game
         *   window.  'txt' gives HTML text that's used for the contents of the
         *   new window.
         *
         *   '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.
         */
        showPopupMenu(x, y, txt);

        /*
         *   Enable/disable a system menu command.  Some interpreters offer a set
         *   of common system-level game commands via menus, toolbars, or similar
         *   UI widgets, depending on local conventions - commands such as SAVE,
         *   RESTORE, UNDO, and QUIT that most games offer.
         *
         *   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.
         */
        enableSystemMenuCommand(id, stat);
    }

    /* ------------------------------------------------------------------------ */
    /*
     *   showPopupMenu status codes.  The function returns a list whose first
     *   element is one of these codes.
     */

    /*
     *   Failed: the popup menu could not be shown.  This could indicate a
     *   resource problem (low memory, for example) or another system problem.
     */
    #define PopMenuFail    0

    /*
     *   HRef: the user clicked on a hyperlink shown in the menu.  The list will
     *   contain a second element giving a string with the HREF of the hyperlink
     *   the user selected.
     */
    #define PopMenuHRef    1

    /*
     *   Canceled: the user canceled the menu.  This usually means that the user
     *   clicked outside of the menu, or switched to a different application.
     */
    #define PopMenuCancel  2

    /*
     *   "End of file": this indicates that the application is being terminated,
     *   so it's not possible to obtain any further input from the user.
     */
    #define PopMenuEof     3

    /* ------------------------------------------------------------------------ */
    /*
     *   enableSystemMenuCommand() status codes.  You can control the inputLine()
     *   and inputEvent() status of a command independently - simply specify the
     *   flags for the context you want to change, and leave the others
     *   unspecified.
     *
     *   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().
     */
    #define MenuStatLineEnable   (0x0004 | 0x0008)
    #define MenuStatLineDisable  (0x0004 | 0x0000)

    #define MenuStatEventEnable  (0x0001 | 0x0002)
    #define MenuStatEventDisable (0x0001 | 0x0000)

TADS 3 Library Manual
Generated on 5/16/2013 from TADS version 3.1.3