Laine at 22:10, 11 June 2007

Laine — Mon, 11 Jun 2007 22:10:57 GMT

New page

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

==See Also==

[[man input|input(mechanisms)]], [[man dialog|dialog(descriptors)]], [[man input to|input_to(efun)]]

Man input core - Revision history

Laine at 22:10, 11 June 2007