This header defines the tads-io intrinsic function set.
The TADS input/output function set provides access to the user interface. This lets you read input from the keyboard and display output on the monitor or terminal. It also provides access to windowing features (via the "banner" functions) on systems that support multiple display windows (which doesn't necessarily mean GUI-type systems: many character-mode systems support the banner operations as well, simply by dividing up the character-mode screen into rectangular regions).
'parent' is the handle of the parent window; if this is nil, the banner is split off from the main display window. 'where' is a BannerXxx value giving the list position; if this is BannerBefore or BannerAfter, 'other' is the handle of an existing banner window child of the same parent. 'windowType' is a BannerTypeXxx value giving the type of window to create. 'align' is a BannerAlignXxx value giving the alignment - that is, the edge of the parent window to which the new banner window attaches. 'size' is the size of the window, in the units given by 'sizeUnits', which is a BannerSizeXxx value. 'styleFlags' is a combination of BannerStyleXxx bit flags that specifies the desired combination of visual styles and UI behavior for the new window.
The value list is handled the same way as the arguments to tadsSay() in terms of type conversions.
Note that not all systems support this function. On systems where the function is not supported, this call has no effect. Because of this, you should always use this function in conjunction with an "advisory" call to bannerSetSize().
'buttons' can be given as an InDlgXxx constant (InDlgOk, InDlgOkCancel, etc.) to select one of the standard sets of buttons. Or, it can be a list giving a custom set of buttons, in which case each element of the list is either a string giving a custom label for the button, or one of the InDlgLblXxx values to select a standard label. The standard labels should be used when possible, as these will be automatically localized; labels given explicitly as strings will be used exactly as given. If a list of custom button labels is given, the buttons are displayed in the dialog in the order of the list (usually left to right, but this could vary according to system conventions and localization).
Each custom button label string can incorporate an ampersand ("&"). The letter immediately following the ampersand, if provided, is used as the keyboard shortcut for the button. This is particularly important on character-mode systems, where the "dialog" is typically shown merely as a text prompt, and the user responds by selecting the letter of the desired option. Typically, you should use the first character of a button label as its keyboard shortcut, but this obviously won't work when two button labels have the same first letter; in these cases, you should choose another letter from the button label, preferably something like the first letter of the second word of the button label, or the first letter of the stressed syllable of the most important word of the label.
The return value is the index among the buttons of the button that the user selects to dismiss the dialog. The function doesn't return until the user selects one of the buttons.
'prompt' is the message string to display in the dialog to let the user know what type of file is being requested. 'dialogType' is one of the InFileXxx constants specifying whether the request is to select an existing file or to specify the name for a new file. 'fileType' is a FileTypeXxx constant giving the format of the file being requested; this is used on some systems to filter the displayed list of existing files so that only files of the same format are included, to reduce clutter. 'flags' is reserved for future use and should simply be set to zero.
The return value is a list. The first element is an integer giving the status: InFileSuccess indicates that the user successfully selected a file, whose name is given as a string in the second element of the result list; InFileFailure indicates a system error of some kind showing the dialog; and InFileCancel indicates that the user explicitly canceled the dialog.
On success (return list == InFileSuccess), the list contains the following additional elements:
 = the selected filename
 = nil (reserved for future use)
 = script warning message, or nil if no warning
The warning message is a string to be displayed to the user to warn about a possible error condition in the script input. The script reader checks the file specified in the script to see if it's valid; if the dialog type is Open, the script reader verifies that the file exists, and for a Save dialog the reader warns if the file *does* already exist or is not writable. In the conventional UI, the script reader displays these warnings directly to the user through the console UI, but this isn't possible in the Web UI since the user might be running on a remote browser. Instead, the script reader still checks for the possible errors, but rather than displaying any warnings, it returns them here. The caller is responsible for displaying the warning and asking the user for confirmation.
For localization purposes, the warning message starts with a two-letter code indicating the specific error, followed by a space, followed by the English text of the warning. The codes are:
OV - the script might overwrite an existing file (Save dialog)
WR - the file can't be created/written (Save dialog)
RD - the file doesn't exist/can't be read (Open dialog)
Note that the warning message will always be nil if the script reader displayed the warning message itself. This means that your program can unconditionally display this message if it's non-nil - there's no danger that the script reader will have redundantly displayed the message.
This function updates the UI to reflect that command line editing is no longer in progress. If 'reset' is true, it also resets the internal memory of the command editing session, so that a subsequent call to inputLineTimeout() will start from scratch with an empty command line. If 'reset' is nil, this function merely adjusts the UI, but does not clear the internal memory; the next call to inputLineTimeout() will automatically restore the editing status, re-displaying what the user had typed so far on the interrupted command line and restoring the cursor position to its position when the timeout occurred.
Note that it's not necessary (or desirable) to call this function after a timed-out input line if the next input/output function that affects the main window is simply another call to inputLineTimeout(). In this case, inputLineTimeout() simply picks up where it left off, without any indication to the user that the input editing was ever interrupted.
The return value is a list. The first element is an InEvtXxx code giving the status. If the status is InEvtLine, the second element is a string giving the command line the user entered. If the status is InEvtTimeout, the second element is a string giving the text of the command line so far - that is, the text that the user had typed up to the point when the timeout expired. Other status codes have no additional list elements.
When an InEvtTimeout status is returned, the caller must either cancel the interrupted input line with inputLineCancel(), or must make another call to inputLineTimeout() without any intervening call to any output function that displays anything in the main window, or any input function other than inputLineTimeout().
'evt' is a list describing the event, using the same format that inputEvent() returns. Note one special extension: if the first element of the list is a string, the string is used as the tag name if we're writing an event script. This can be used to write custom events or events with no InEvtXxx type code, such as <dialog> input events.
Note that the ScriptFileEvent flag is ignored if included in the 'flags' parameter. The script reader automatically determines the script type by examining the file's contents, so you can't set the type using flags. This flag is used only in "get status" requests (ScriptReqGetStatus) - it's included in the returned flags if applicable. The purpose of this flag is to let you determine what the script reader decided about the script, rather than telling the script reader how to interpret the script.
If 'filename' is nil, this cancels the current script. If the script was invoked from an enclosing script, this resumes the enclosing script, otherwise it resumes reading input from the keyboard. The 'flags' argument is ignored in this case.
New in 3.0.17: if 'filename' is one of the ScriptReqXxx constants, this performs a special script request. See the ScriptReqXxx constants for details. Note that calling this function with a ScriptReqXxx constant on an VM prior to 3.0.17 will result in a run-time error, so you can use try-catch to detect whether the request is supported.
2 /* size is in natural units of window type */
1 /* size is a percentage of available space */
0x0010 /* automatic horizontal scrolling */
0x0008 /* automatic vertical scrolling */
0x0001 /* banner has a visible border */
0x0004 /* horizontal scrollbar */
0x0080 /* include in parent's auto width */
0x0040 /* use MORE mode */
alignment support */
0x0002 /* vertical scrollbar */
0x0100 /* include in parent's auto height */
1 /* ordinary text stream window */
2 /* text grid window */
1 /* the display/keyboard character set */
3 /* default file contents character set */
2 /* the file system character set */
0x0005 /* close the game window */
ColorRGB(0x00, 0xFF, 0xFF)
ColorRGB(0x00, 0x00, 0x00)
ColorRGB(0x00, 0x00, 0xFF)
ColorRGB(0x00, 0xFF, 0xFF)
ColorRGB(0xFF, 0x00, 0xFF)
ColorRGB(0x80, 0x80, 0x80)
ColorRGB(0x00, 0x80, 0x00)
ColorRGB(0x00, 0xFF, 0x00)
ColorRGB(0xFF, 0x00, 0xFF)
ColorRGB(0x80, 0x00, 0x00)
ColorRGB(0x00, 0x00, 0x80)
ColorRGB(0x80, 0x80, 0x00)
ColorRGB(0x80, 0x00, 0x80)
ColorRGB(0xff, 0x00, 0x00)
((((r) & 0xff) << 16) + (((g) & 0xff) << 8) + ((b) & 0xff))
RGB colors are specified with each component given in the range 0 to 255; the color (0,0,0) is pure black, and (255,255,255) is pure white.
The special value "transparent" is not a color at all, but rather specifies that the current screen color should be used.
The "Text" and "TextBg" colors are the current default text and text background colors. The actual colors displayed for these values depend on the system, and on some systems these colors might be configurable by the user through a preferences selection. These are the same colors selected by the HTML parameterized color names 'text' and 'bgcolor'.
The "StatusText" and "StatusBg" colors are the current default statusline text and background colors, which depend on the system and may be user-configurable on some systems. These are the same colors selected by the HTML parameterized color names 'statustext' and 'statusbg'.
The "input" color is the current default input text color.
ColorRGB(0xC0, 0xC0, 0xC0)
ColorRGB(0x00, 0x80, 0x80)
ColorRGB(0xff, 0xff, 0xff)
ColorRGB(0xFF, 0xFF, 0x00)
8 /* binary data file */
5 /* command input file */
4 /* arbitrary data file */
2 /* a transcript (log) file */
12 /* T3 executable image (game) file */
15 /* T3 saved state file */
7 /* text file */
11 /* unknown file type */
0x0006 /* show game HELP */
4 /* (note minor capitalization variation) */
2 /* player canceled the file selector */
1 /* an error occurred asking for a file */
1 /* open an existing file for reading */
2 /* save to the file */
0 /* success - 2nd list element is filename */
2 /* log only command-line input */
3 /* log all input events */
1 /* log all input and output to a transcript */
0x0004 /* QUIT the game */
0x0002 /* RESTORE a saved position */
0x0001 /* SAVE the current position */
4 /* this is an event script (query only) */
2 /* turn off MORE prompt while reading script */
1 /* do not display output while reading script */
0 /* displaying normal text */
1 /* display status line text */
0x0003 /* UNDO one turn */