Man input
From LSWiki
Contents |
Files
/lib/input.h /daemon/input.c /std/def/input.c /def/input /def/descriptor/dialog.c /lib/descriptors/dialog.h /def/descriptor/menu_item.c /lib/descriptors/menu_item.h
Description
The input system is a set of mechanics for handling input dialogs with users. It uses the input_to() function at its core, but greatly extends and refines the capabilities of that routine.
Input dialogs are defined using dialog descriptors, documented in 'man dialog'. Much of what you need to know to use the input system is in that file; this document concentrates on describing the various input types from a user perspective. If you are a core systems developer who needs to maintain the input system, you will want to be familiar with this document and then proceed to 'man input_core'.
A reasonably good starting example of the input system in action can be found in /daemon/mudlib_change.c, which uses a series of text dialogs followed by a single-character-input menu. The example is simple enough not to be too overwhelming but exercises the system's features well. Other prominent examples of input system usage include /obj/interfaces/login.c, /std/atman.c, and /daemon/more.c.
Input Types
The input types are listed in /lib/input.h, and are as follows. Comments relevant to particular dialog fields and flags are noted below the type.
Input_Text: A simple line-of-text input.
Dialog_Input: Will be set to the text line received (without newline), or the default value if appropriate.
Input_Password: Similar to Input_Text, but specialized for passwords.
Dialog_Input: Will be set to the text line received (without newline), or the default value if appropriate.
Dialog_Flags:
Dialog_Flag_Hidden: Automatically turned on.
Dialog_Flag_No_Override: Automatically turned on.
Input_Character: A special mode for single-character input, intended for situations where a complex interface is being controlled by character-mode input. Usually, when you want single-character input, all you really need is to turn on Dialog_Flag_Single_Character in a yes-or-no or menu dialog, rather than using this input type. This type the special behavior that, if multiple characters are received (as will occur if character mode cannot be engaged), the system will attempt to process the characters as individual responses. It will only be able to do so as long as the action triggered by each character continues to keep the current dialog engaged, however.
Dialog_Input: Will be set to the *integer* character value received.
Dialog_Flags:
Dialog_Flag_Single_Character: Automatically turned on.
Dialog_Flag_No_Override: Automatically turned on.
Dialog_Flag_Default: Automatically turned on.
Input_Yes_No: A dialog requiring a yes/no response. The Dialog_Input
Dialog_Input: Will be set to True for a "yes" response and False for a "no" response.
Dialog_Default: Should be set to True for a "yes" default and False for a "no" default.
Dialog_Flags:
Dialog_Flag_Full_Word: Causes a requirement that the entire word
"yes" or "no" to be input rather than simply "y" or "n".
Dialog_Flag_Match_Case: Causes a requirement that the response be
"Y" or "N", without Dialog_Flag_Full_Word, or "Yes" or "No" with
Dialog_Flag_Full_Word.
Dialog_Flag_Suppress_Prompt_Add: The input type normally appends
a "response guide" to the prompt, which will look like "[y/n]",
varying depending on the dialog settings; for example, if there
is a default, it will be capitalized. This flag prevents this
from occurring.
Input_Yes_No_Other: A dialog requiring a response of yes, no, or a third option.
Dialog_Input: Will be set to True for a "yes" response, False for a "no" response, and Null for an "other" response.
Dialog_Default: Should be set to True for a "yes" default, False for a "no" default, and Null for an "other" default.
Dialog_Content: Defines the word for the "other" response; defaults to "Quit". Your setting should use the same capitalization pattern and not begin with "Y" or "N".
Dialog_Flags:
Dialog_Flag_Full_Word: Causes a requirement that the entire
word of the response be typed in rather than merely the first
character of it.
Dialog_Flag_Match_Case: Requires case matching; the case patterns
for the yes and no choices are "Yes" and "No".
Dialog_Flag_Suppress_Prompt_Add: The input type normally appends a
"response guide" to the prompt, which will look like "[y/n/q]",
varying depending on the dialog settings; for example, if there is
a default, it will be capitalized. This flag prevents this from
occurring.
Input_Option: A dialog with valid responses limited to a specific list. Though this input type is available, be aware that often an Input_Menu is a better way to handle situations it is applicable to.
Dialog_Input: Will be set to the string selected from the option list.
Dialog_Content: A string array of the valid options.
Dialog_Flags:
Dialog_Flag_Match_Case: Specifies case-sensitive matching; normally
matching is case insensitive.
Dialog_Flag_Suppress_Prompt_Add: Normally, if a default is present,
the input type will append to the prompt an indication of the
default; for example, if the default is "N", the prompt add will
look like "[N]". This flag prevents this from occurring.
Input_Menu: A dialog where valid options are defined by a set of menu item descriptors. See 'man menu_item' for specifics on this type of descriptor.
Dialog_Input: Will be set to the menu item descriptor which was selected.
Dialog_Content: Is an array of the menu item descriptors for the menu.
Dialog_Action: Is used only if the selected menu item descriptor defines no action.
Dialog_Flags:
Dialog_Flag_Match_Case: Matching of input to menu item keys is case
insensitive unless this flag is turned on.
Dialog_Flag_Suppress_Desc_Add: Normally, a menu dialog will
generate additional content to be added to the Dialog_Desc based
on the menu items; this flag prevents this.
Dialog_Flag_Suppress_Prompt_Add: Normally, if a default is present,
the input type will append to the prompt an indication of the
default; for example, if the default is "N", the prompt add will
look like "[N]". This flag prevents this from occurring.
Dialog_Flag_Suppress_Extra_Line: The input type normally adds a
blank line between the dialog descriptive content and the prompt,
unless this flag is present. (Dialog_Flag_Suppress_Desc_Add makes
this flag superfluous.)
Input_Block: A dialog for input of multiple lines of text. The user is provided with a simple interface that allows arbitrary lines of text to be entered, but has no editing capability.
Dialog_Input: Will be set to the final text block.
Dialog_Action: Is only carried out once the user is finished.
Dialog_Max_Length: If specified, this is the maximum number of lines that may be entered.
Dialog_Flags:
Dialog_Flag_Suppress_Desc_Add: Normally, a block dialog will
generate an introductory message requesting input and giving the
basic options for the dialog. This flag prevents this.
Dialog_Flag_No_Abort: Disallows the user from aborting the dialog.
Input_Simple_Edit: A dialog form that encapsulates editing a text document with a simple non-modal editor reasonably suitable for players.
Dialog_Input: Will be set to the final document.
Dialog_Action: Is only carried out once the user is finished.
Dialog_Content: If set, specifies the initial content of the document.
Dialog_Max_Length: If specified, this is the maximum number of lines that may be entered.
Dialog_Flags:
Dialog_Flag_Suppress_Desc_Add: Normally, the input type will
generate an introductory message requesting input and giving an
overview of a few editor commands. This flag prevents this.
Dialog_Flag_No_Abort: Disallows the user from aborting the dialog.
Input_Line_Edit: A dialog form that encapsulates editing a text document with a modal line editor, designed to resemble Unix's ed and ex, generally only suitable for developer use.
Dialog_Input: Will be set to the final document.
Dialog_Action: Is only carried out once the user is finished.
Dialog_Content: If set, specifies the initial content of the document.
Dialog_Max_Length: If specified, this is the maximum number of lines that may be entered.
Dialog_Flags:
Dialog_Flag_Suppress_Desc_Add: Normally, the input type will
generate an introductory message requesting input and giving an
overview of a few editor commands. This flag prevents this.
Dialog_Flag_No_Abort: Disallows the user from aborting the dialog.
Input_Screen_Edit: Unimplemented. Intended to be used for a screen-based non-modal editor suitable for player use.
Input_Visual_Edit: Unimplemented. Intended to be used for a screen-based modal editor resembling Unix's vi, suitable for developer use.
See Also
dialog(descriptors), menu_item(descriptors), descriptors(mechanisms), input_core(mechanisms), input_to(efun)
