Man input core
From LSWiki
Contents |
Files
/daemon/input.c /lib/input.h /std/def/input.c /def/input
Description
This document describes the internal workings of the input system for core systems developers who need to maintain or create input types. You will want to be familiar with the user-level perspective on the input system as described in 'man input' and 'man dialog'.
As typical of definition-based mechanisms, the input system has a broker daemon, /daemon/input.c, a header file, /lib/input.h, a definition base, /std/def/input.c, and a definition directory, /def/input. The input type definitions are heavily relied upon to determine the behavior of the input types. An excellent way to learn about the system is to study the existing input type definitions in /def/input.
Adding an Input Type
Input types each have a macro in input.h, so adding one requires creating the appropriate macro. Add the new macro to the list at the top of input.h according to alphabetical order and either make its value equal to Inputs_Count plus one (easy way) or renumber all the input types (hard way). Then increment Inputs_Count and Inputs_Array_Size by one. Since input type codes are not saved, you can renumber the input types if you wish, but the MUD does need to be immediately shut down if you do this, or potentially very troublesome errors will arise from older code with the previous values compiled in.
Once your macro exists, create your input type definition in /def/input and configure it appropriately.
Input Type Configuration
Input types define the following configuration functions:
void set_input(int code)
Sets the input type's macro code.
void set_input_name(string name)
Sets the input type's name. The name should match the filename of the input definition; if it doesn't, a warning will be issued.
void set_input_inherent_flags(int flags)
Specifies one or more dialog flags which are automatically applied to dialogs of this input type.
void set_input_unsupported_fields(int array fields)
Sets an array of dialog fields which are not supported by dialogs of this input type.
void set_input_handler(closure proc)
Sets, as a closure, the procedure the input type uses to process raw input received from the user. When input is received, this closure is called with arguments of 1) the string input received 2) the dialog descriptor. This procedure is completely responsible for everything to be done with the input, with the help of the support functions described below. At the beginning of the function, the input should be processed with check_newline() and strip_newlines() if appropriate. Any handling of defaults should be performed using input_empty(), check_flag(), and input_default(). The function may reprompt the user if appropriate for the input by giving feedback with input_feedback() and then calling Dialog_Process(dialog, True). Otherwise, the function should set the dialog's Dialog_Input field as appropriate and then process the dialog's action using perform_input_action(). The function's return value is ignored.
void set_input_prompt_add(closure proc)
Sets a closure that provides additions to the prompts of dialogs using the input type. The closure receives the dialog descriptor as argument and is expected to return zero, a string, or a dialog message array as described in the Dialog Colorization section of 'man dialog'; dialog colorization will, of course, be applied to the result.
void set_input_desc_add(closure proc)
Sets a closure that provides additions to the descriptive content of dialogs using the input type. The closure receives the dialog descriptor as argument; its return value is handled in the same way as for prompt adds.
void set_input_dialog_initialize(closure proc)
Sets a closure that will be called when dialogs of this input type are being set up. The closure will be called with the dialog descriptor as argument; its return value is ignored.
Support Functions
void check_newline(string line, descriptor dialog)
Attempts to determine whether a newline should be displayed to the user, and displays it if so. The logic currently implemented for determining that a newline should be displayed are: if the dialog is in single character mode and the input line is less than 2 characters long, display newline; otherwise, if the dialog is in hidden mode, display a newline. The idea behind this is to supply newlines when the user's local terminal is likely not to have, to prevent subsequent output from appearing on the same line as a prompt and/or response.
string strip_newlines(string line, descriptor dialog)
Strips any ++n and ++r characters off the end of the line and returns the result.
status input_empty(string line)
Returns true if the input line passed as argument should be considered an empty response, e.g. for purposes of invoking a default.
status check_flag(descriptor dialog, int flag)
Return true if the specified flag is set in the dialog passed.
void input_feedback(mixed feedback, descriptor dialog)
Displays the specified feedback, which can be any of the output forms described in the Dialog Colorization section of 'man dialog', by setting the dialog's Dialog_Feedback field to the value specified and immediately displaying the feedback to the user. If you are going to be calling perform_input_action(), give feedback simply by setting the Dialog_Feedback field; this function is intended for use when you will not be calling perform_input_action().
mixed input_default(descriptor dialog)
Retrieves the default value from the specified dialog, evaluating closures as necessary.
varargs void perform_input_action(descriptor dialog, mixed action)
Retrieves the specified dialog's input action, evaluates and performs it as appropriate. The descriptor's Dialog_Input field should be set as appropriate before calling this function. The second argument is optional and, if specified, overrides the normal action setting for the dialog.
int input_output_length(mixed output, descriptor dialog)
Retrieves the effective display width, in characters, of the output specified, which can be a string or a dialog message array.
string input_colorize_output(mixed output, descriptor dialog)
Takes any of the output forms described in the Dialog Colorization section of 'man dialog' and returns the final output string, with the specified dialog's color settings applied.
