Laine at 22:08, 11 June 2007

2007-06-11T22:08:01Z

New page

==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==

[[man dialog|dialog(descriptors)]], [[man menu item|menu_item(descriptors)]], [[man descriptors|descriptors(mechanisms)]], [[man input core|input_core(mechanisms)]], [[man input to|input_to(efun)]]

Man input - Revision history

Laine at 22:08, 11 June 2007