#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)
Adv3Lite Library Reference Manual
Generated on 03/07/2024 from adv3Lite version 2.1