tadsiox.h

documentation
 #charset "us-ascii"
 
 /* 
  *   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.  
  */
 
 #ifndef TADSIOX_H
 #define TADSIOX_H
 
 /*
  *   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)
 
 
 #endif /* TADSIOX_H */
TADS 3 Library Manual
Generated on 9/15/2006 from TADS version 3.0.12