Man dialog
From LSWiki
Contents |
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
input(mechanisms), menu_item(descriptors), descriptors(mechanisms)
