Laine at 20:11, 11 June 2007

2007-06-11T20:11:54Z

New page

==Files==

/daemon/input.c
/def/descriptor/dialog.c
/lib/descriptors/dialog.h

==Description==

Dialog descriptors are used by the input system to manage the data
associated with input dialogs. See 'man input' for documentation on the
input system itself; see 'man descriptors' for a general overview of the
descriptor system. One type of dialog, menu dialogs, also use menu item
descriptors, documented in 'man menu_item'.

The header file for dialog descriptors is /lib/descriptors/dialog.h;
however, for working with them, it is generally preferable to #include
<input.h>, since that file automatically includes dialog.h and contains
the input type macros you will also need.

===Dialog Colorization===

Dialog descriptors support a specialization of the color system based on
a generic color and a highlight color. Practically anything that winds up
being displayed via a dialog descriptor can be defined as any of the below:

A string: Will be colorized with the generic color.

An array: String elements at the first level of the array will be
colorized with the generic color, those at the second level of the
array will be colored with the highlight color, and the entirety will
be joined together. A simple example will illustrate the principle:
the array ({ "A ", ({ "highlighted" }), " message" }) will be resolved
to "A highlighted message", with the word "highlighted" in the
highlight color and the rest in the generic color.

A closure: Will be called with the dialog descriptor as argument, and
is expected to return 0 (resulting in no display) or one of the above
options.

The purpose of all this is to provide a simple, easy-to-use format that
makes quick work of tweaking the color "style" of a set of input dialogs.
Ordinary color codes may still be used when neither the generic nor the
highlight color is what you want.

===Dialog Actions===

Dialogs define actions which are to take place upon receiving a response
from the user. Most typically, this is done by supplying a closure that
receives the dialog descriptor as argument, analyzes the response, and
provides a return value that indicates what action should be taken.
However, any of those return values could also simply be given as the
action itself, without involving the closure. (This makes more sense
when dealing with menu dialogs, where each menu item can define its own
action.) The list below defines the valid actions which can be specified
as the return value of a closure action or as the action itself.

Dialog_Action_None: Take no further action; effectively terminates the
dialog.

Dialog_Action_Redisplay: Re-request input, redisplaying the entire
descriptive content for the dialog.

Dialog_Action_Reprompt: Re-request input, displaying only the prompt.

Dialog_Action_Attach: Send the user to a sub-dialog. The dialog to attach
is specified by setting the Dialog_Next field in the current dialog. The
attached dialog will automatically have its Dialog_Attached field set to
the current dialog, its Dialog_User set the same as in the current dialog,
and its Dialog_Extra field set the same as in the current dialog if it
does not already have a setting for that field. The Dialog_Next field in
the current dialog will be cleared when this action is carried out.

Dialog_Action_Return: Return to a previous dialog, found in the
Dialog_Attached field, displaying the entire descriptive content for that
dialog. The Dialog_User field in the dialog being returned to will be set
the same as in the current dialog.

Dialog_Action_Return_Prompt: The same as Dialog_Action_Return, except only
the prompt for the dialog being returned to is displayed.

Dialog_Action_Transfer: Transfer to the dialog in the Dialog_Next field.
This differs from Dialog_Action_Attach in that the new dialog is not
considered a sub-dialog of this one; it is a "lateral" transfer. The
dialog being transferred to will have its Dialog_Attached and Dialog_User
fields set the same as in the current dialog, as well as its Dialog_Extra
unless it already has a value for that field. The Dialog_Next field in
the current dialog will be cleared when this action is carried out.

A dialog descriptor: As an action specification, places the dialog
specified in the current dialog's Dialog_Next field and acts as if
Dialog_Action_Attach had been returned.

===Fields===

Dialog descriptors essentially have three kinds of fields: public fields,
internal fields which are intended for your use in some fashion, and
internal fields that should be left alone.

====Public Fields====

Dialog_Type: Sets the type of input dialog, generally using one of the type
macros from input.h, such as Input_Text, Input_Yes_No, or Input_Menu.
The characteristic behavior of each of the input types is described in
'man input'.

Dialog_Action: Specifies the action to be taken on receiving input, as
described under Dialog Actions. For menu dialogs, this is the default
action to be taken if the menu item selected does not define one.

Dialog_Flags: Sets the flags for the dialog. Dialog flags are bitmasks,
added using bitwise or. The flag values are:

Dialog_Flag_No_Override: Do not allow the user to override the input
dialog with ! commands. This will be ignored if not permitted for a
given user.

Dialog_Flag_No_Player_Override: As Dialog_Flag_No_Override, but does
not apply to developers.

Dialog_Flag_Hidden: Attempt to signal the user's terminal to hide his
or her input, as with passwords.

Dialog_Flag_Single_Character: Attempt to signal the user's terminal to
enter single-character mode. If any prompt is set for the dialog,
causes a * to be added to the prompt.

Dialog_Flag_Default: Allow the input to default or return an empty
result. Normally, a lack of input results in the user being given
a message regarding valid responses and being re-prompted. You do not
need to specify this flag if you set the Dialog_Default field; setting
that field also sets this flag automatically.

Dialog_Flag_Unknown_Defaults: For input types which restrict the valid
responses to a specific set, this flag causes responses which do not
match any element of the set to act as if the default were selected.
Normally, an unknown response causes the user to be given a message
regarding valid responses and then re-prompted.

Dialog_Flag_Match_Case: For input types which restrict the valid
responses to a specific set, causes matching to be case-sensitive,
where normally it is not.

Dialog_Flag_Center_Desc: Center the content from the Dialog_Desc field
on the user's screen. (Only applies to the Dialog_Desc, not to any
additions to it.)

Dialog_Flag_Suppress_Prompt_Add: Suppress additions to the prompt.
There are two kinds of prompt adds: those defined by the input type,
and the * added by Dialog_Flag_Single_Character, as described above.
This flag suppresses both of these additions.

Dialog_Flag_Suppress_Desc_Add: Suppress additions to the dialog
descriptive content. For menu dialogs, this suppresses the menu
generation, including the blank line normally generated between the
dialog descriptive content and the prompt. For block and edit
dialogs, this suppresses the interface description.

Dialog_Flag_Full_Word: For yes/no dialogs, requires the entire word
"yes" or "no" to be input; similarly for yes/no/other dialogs. Not
used by any other input types.

Dialog_Flag_Suppress_Extra_Line: In menu dialogs, prevents a blank line
from being inserted between the dialog descriptive content and the
prompt.

Dialog_Prompt: The basic prompt for the dialog, which may be modified
in various ways. Dialog colorization applies.

Dialog_Default: Specifies the default value to be substituted for input
if the user provides none. If this field is specified, Dialog_Flag_Default
is automatically set.

Dialog_User: Sets the user to interact with the dialog. Expected to be
an interactive object; if not, the input system will attempt to handle it
by processing dialogs as if defaults had been selected, erroring if no
default is available. Though you can set this field in the specification,
it is more usual to provide it as argument to the Dialog_Enter() function
(see below) when activating the dialog.

Dialog_Extra: A space in the descriptor for arbitrary user-defined data to
be stored. Put whatever you like in here and use it however you like.

Dialog_Color: Sets the generic color for the dialog, as described in Dialog
Colorization. Specified as a bare color code, e.g. "blue".

Dialog_Highlight: Sets the highlight color for the dialog, as described in
Dialog Colorization. Specified as a bare color code, e.g. "white".

Dialog_Desc: A description or message regarding what the dialog is asking.
Dialog colorization applies.

Dialog_Content: For option dialogs, this is a string array list of the
valid input responses. For edit dialogs, this is a string defining
starting content to be edited. For menu dialogs, this is an array of the
menu item descriptors for the menu. For yes/no/other dialogs, this is the
string text of the third choice, which defaults to "Quit"; a custom option
should use the same capitalization pattern, and should not begin with Y or
N.

Dialog_Init: A closure that will be called when the dialog is first
entered via Dialog_Enter(). The dialog descriptor will be passed as
argument. Return values are ignored.

Dialog_Run: A closure that will be called every time the dialog is
processed -- that is, any time input is requested from the user, whether
with a full display of descriptive content or not. The closure will
receive the dialog descriptor as argument. Return values are ignored.

Dialog_Exit: A closure that will be called whenever the dialog is exited,
including Dialog_Action_None, Dialog_Action_Attach, Dialog_Action_Return,
Dialog_Action_Return_Prompt, and Dialog_Action_Transfer actions. The
closure receives the dialog descriptor as argument; its return value is
ignored.

Dialog_Done: A closure that will be called when the dialog is exited
without an expectation that it is likely to be returned to; that is, the
same as Dialog_Exit, except it is not called for Dialog_Attach actions.
The closure receives the dialog descriptor as argument; its return value
is ignored.

Dialog_Max_Length: Used by block and edit dialogs. If specified, this is
the maximum number of lines the user is allowed to have in the final
result.

====User-Serviceable Internal Fields====

Dialog_Input: This is the field where the input received from the user
will be placed in the dialog descriptor for you to examine. It should
be accessed using Dialog_Query(dialog, Dialog_Input). You should not
set this field. The input result will be processed in different ways by
different input types; see 'man input' for details.

Dialog_Argument: Menu dialogs can be set to allow an "argument" to a menu
choice; that is, additional information provided after the menu item key.
If this has been enabled for a menu item and the user provided an argument,
the argument will appear in this field. It should be accessed using
Dialog_Query(dialog, Dialog_Argument). You should not set this field.

Dialog_Source: The string object name of the object which requested the
creation of the dialog. It should be accessed using Dialog_Query(dialog,
Dialog_Source). You should not set this field.

Dialog_Next: Used to specify the next dialog to send the user to, for
Dialog_Action_Attach and Dialog_Action_Transfer actions. It should be set
using Dialog_Set(dialog, Dialog_Next, other_dialog). You should not need
to query this field, but if you do, use Dialog_Query(dialog, Dialog_Next).
This field is automatically cleared when actions using it are carried out.

Dialog_Feedback: Used to specify feedback to be displayed to the user
before carrying out its next action. Dialog colorization applies. It
should be set using Dialog_Set(dialog, Dialog_Feedback, feedback). You
should not need to query this field, but if you do, do so using
Dialog_Query(dialog, Dialog_Feedback).

====Non-User-Serviceable Fields====

Dialog_Attached: Used for storing a dialog that the current dialog is
"attached" to. The dialog stored here comes into play when
Dialog_Action_Return and Dialog_Action_Return_Prompt actions are taken.

Dialog_Info: A space for individual input types to store information for
their own use. The meaning of anything here is defined by the individual
input type.

Dialog_Tag: The tag value for the descriptor system.

===Support Functions===

Dialog descriptors also define several support functions for working with
them. As usual with descriptor support functions, these are handled via
macros. The definitions below are given using the macro names, but with
function-style type information to make the arguments and return values
clear.

'''void Dialog_Enter(descriptor dialog, object user)'''

Sets the dialog's user to the object given as the second argument and
processes the dialog, calling Dialog_Init if present.

'''varargs void Dialog_Process(descriptor dialog, status suppress_desc)'''

Processes the specified dialog. If the optional second argument is true,
the full descriptive content for the dialog will be suppressed, so that
only the prompt is shown. This is mostly intended for internal system
use, but is available in case you need it; you should generally use
Dialog_Enter() to start your dialogs.

'''void Dialog_Display(descriptor dialog, mixed message)'''

Displays a message to the dialog's user, with dialog colorization applying
to the message. This is useful when setting dialog feedback or a dialog
description doesn't do exactly what you want.

'''descriptor Dialog_Active(object|mixed array what)'''

Requests information on a user's current active dialog. If an object is
given, this is the user you are requesting information on. If a dialog
descriptor is given, information is requested on that dialog's user.
The return value is the current input dialog the user is engaged in,
if any (only applying to dialogs managed via the input system, not other
uses of input_to()).

'''void Dialog_Show_Prompt(object|mixed array what)'''

Displays a dialog's prompt to its user without actually processing the
dialog. If an object is given, the prompt for that user's active dialog,
if any, is shown, and as a special case, if the user has no active dialog,
their normal prompt is shown. If a dialog is given, the prompt for that
dialog is shown.

'''status Dialog_Abort(object|mixed array what)'''

Attempts to abort a user's input dialog. If an object is given, the
user's current dialog, if any, is considered the dialog to be aborted.
If a dialog descriptor is given, that dialog will be aborted if and only
if it is the current dialog for its user. Returns True if successful,
False otherwise. This function should not be used without a good deal
of caution.

==See Also==

[[man input|input(mechanisms)]], [[man menu item|menu_item(descriptors)]], [[man descriptors|descriptors(mechanisms)]]

Man dialog - Revision history

Laine at 20:11, 11 June 2007