@node Part III Input Objects
@chapter Input Objects

It is often required to obtain textual input from the user, e.g., a
file name, some fields in a database, etc. To this end input fields
exist in the Forms Library. An input field is a field that can be
edited by the user using the keyboard.

@ifnottex

@menu
* Adding Input Objects:   Adding Input Objects
* Input Types:            Input Types
* Input Interaction:      Input Interaction
* Other Input Routines:   Other Input Routines
* Input Attributes:       Input Attributes
* Remarks:                Input Remarks
@end menu

@end ifnottex


@node Adding Input Objects
@section Adding Input Objects

Adding an object To add an input field to a form you use the routine
@findex fl_add_input()
@anchor{fl_add_input()}
@example
FL_OBJECT *fl_add_input(int type, FL_Coord x, FL_Coord y,
                        FL_Coord w, FL_Coord h, const char *label)
@end example
@noindent
The meaning of the parameters is as usual. The label is by default
placed in front of the input field.


@node Input Types
@section Input Types

The following types of input fields exist:
@table @code
@tindex FL_NORMAL_INPUT
@anchor{FL_NORMAL_INPUT}
@item FL_NORMAL_INPUT
Any type of text can be typed into this field.

@tindex FL_FLOAT_INPUT
@anchor{FL_FLOAT_INPUT}
@item FL_FLOAT_INPUT
Only a floating point numbers can be typed in (e.g., -23.2e12). The
resulting string will be accepted by @code{strtod()} in its entirety
(but may be too big to be represented by an @code{int} or
@code{long}).

@tindex FL_INT_INPUT
@anchor{FL_INT_INPUT}
@item FL_INT_INPUT
Only an integers can be typed in (e.g., -86). The resulting string will
be accepted by @code{strtol()} in its entirety (but may be too big to
be represented by an @code{float} or @code{double}).


@tindex FL_DATE_INPUT
@anchor{FL_DATE_INPUT}
@item FL_DATE_INPUT
Only a date (MM/DD/YY or DD/MM/YY) can be typed in (and limited per
default to 10 characters).

@tindex FL_MULTILINE_INPUT
@anchor{FL_MULTILINE_INPUT}
@item FL_MULTILINE_INPUT
An input field allowing for multiple lines.

@tindex FL_SECRET_INPUT
@anchor{FL_SECRET_INPUT}
@item FL_SECRET_INPUT
A normal input field that does not show the text (and limited per
default to a maximum length of 16 characters).

@tindex FL_HIDDEN_INPUT
@anchor{FL_HIDDEN_INPUT}
@item FL_HIDDEN_INPUT
A normal input field but invisible.
@end table

A normal input field can contain one line of text, to be typed in by
the user. A float input field can only contain a float number. If the
user tries to type in something else than a float, it is not shown and
the bell is sounded. Similarly, an int input field can only contain an
integer number and a date input field can only contain a valid date
(see below). A multi-line input field can contain multiple lines of
text. A secret input field works like a normal input field but the
text is not shown (or scrambled). Only the cursor is shown which does
move while text is being entered. This can for example be used for
getting passwords. Finally, a hidden input field is not shown at all
but does collect text for the application program to use.


@node Input Interaction
@section Input Interaction

Whenever the user presses the mouse inside an input field a cursor
will appear in it (and the field will change color to indicate that it
received the input focus). Further input will be directed into this
field. The user can use the following keys (as in @code{emacs(1)}) to
edit or move around inside the input field:
@table @asis
@item delete previous char
@code{<Backspace>}, @code{<Ctrl>h}
@item delete next char
@code{<Delete>}
@item delete previous word
@code{<Ctrl><Backspace>}
@item delete next word
@code{<Ctrl><Delete>}
@item delete from cursor position to end of line
@code{<Ctrl>k}
@item delete from cursor position to begin of line
@code{<Meta>h}
@item jump to begin of line
@code{<Ctrl>a}
@item jump to end of line
@code{<Ctrl>e}
@item move char backward
@code{<Ctrl>b}
@item move char forward
@code{<Ctrl>f}
@item move to next line
@code{<Ctrl>n}, @code{<Down>}
@item move to previous line
@code{<Ctrl>p}, @code{<Up>}
@item move word backward
@code{<Meta>b}
@item move word forward
@code{<Meta>f}
@item move to begin of field
@code{<Home>}
@item move to end of field
@code{<End>}
@item clear input field
@code{<Ctrl>u}
@item paste
@code{<Ctrl>y}
@end table

It is possible to remap the the bindings, see below for details.

A single click into the input field positions the cursor at the
position of the mouse click.

There are three ways to select part of the input field. Dragging,
double-click and triple-click. A double-click selects the word the
mouse is on and a triple-click selects the entire line the mouse is
on. The selected part of the input field is removed when the user
types the @code{<Backspace>} or @code{<Delete>} key or replaced by
what the user types in. 

One additional property of selecting part of the text field is that if
the selection is done with the left mouse button the selected part
becomes the primary (@code{XA PRIMARY}) selection of the X Selection
mechanism, thus other applications, e.g., @code{xterm}, can request
this selection. Conversely, the cut-buffers from other applications
can be pasted into the input field. Use the middle mouse button for
pasting. Note that @code{<Ctrl>y} only pastes the cut-buffer generated
by @code{<Ctrl>k} and is not related to the X Selection mechanism,
thus it only works within the same application. When the user presses
the @code{<Tab>} key the input field is returned to the application
program and the input focus is directed to the next input field. This
also happens when the user presses the @code{<Return>} key but only if
the form does not contain a return button. The order which input
fields get the focus when the @code{<Tab>} is pressed is the same as
the order the input fields were added to the form. From within Form
Designer, using the raising function you can arrange (re-arrange) the
focus order, see @ref{Raising and Lowering}, in Part II for details. If
the @code{<Shift>} key is pressed down when the @code{<Tab>} is
pressed, the focus is directed to the previous input field.

Leaving an input field using the @code{<Return>}) key does not work for
multi-line input fields since the @code{<Return>} key is used to start
a new line.

Per default the input object gets returned to the application (or the
callback set for the input object is invoked) when the input field is
left and has been changed. Depending on the application, other options
might be useful. To change the precise condition for the object to be
returned (or its callback to become invoked), the
@code{@ref{fl_set_object_return()}} function can be used with one of
the following values:
@table @code
@item @ref{FL_RETURN_NONE}
Never return or invoke callback

@item @ref{FL_RETURN_END_CHANGED}
Default, object is returned or callback is called at the end if the
field had been modified.

@item @ref{FL_RETURN_CHANGED}
Return or invoke the callback function whenever the field had
been changed.

@item @ref{FL_RETURN_END}
Return or invoke the callback function at the end regardless if the
field was modified or not.

@item @ref{FL_RETURN_ALWAYS}
Return or invoke the callback function upon each keystroke and at
the end (regardless if the field was changed or not)
@end table

See demo @file{objreturn.c} for an example use of this.

A few additional notes: when you read "the fields has been changed"
this includes the case that the user e.g., deleted a character and
then added it back again. Also this case is reported as a "change" (a
delete alone isn't) so the term "changed" does not necessarily mean
that the content of the field has changed but that the user made
changes (but which still might result in the exact same content as
before).

Another term that may be understood differently is "end". In the
versions since 1.0.91 it means that the users either hits the
@code{<Tab>} or the @code{<Return>} key (except for multi-line
inputs) or that she clicks onto some other object that in principle
allows user interaction. These events are interpreted as an
indication the user is done editing the input field and thus are
reported back to the program, either by returning the input object
or invoking its callback. But unless the user goes to a different
input object the input field edited retains the focus.

Up to version 1.0.90 this was handled a bit differently: an "end
of edit" event was not reported back to the program when the user
clicked on a non-input object, i.e., changed to a different input
object. This let to some problems when the interaction with the
clicked-on non-input object dependet on the new content of the
input object, just having been edited, but which hadn't been
been reported back to the caller. On the other hand, some programs
rely on the "old" behaviour. These programs can switch back to the
traditional behaviour by calling the new function (available since
1.0.93)
@findex fl_input_end_return_handling()
@anchor{fl_input_end_return_handling()}
@example
fl_input_end_return_handling(int type);
@end example
@noindent
where @code{type} can be either
@tindex FL_INPUT_END_EVENT_ALWAYS
@anchor{FL_INPUT_END_EVENT_ALWAYS}
@code{FL_INPUT_END_EVENT_ALWAYS}, which is now the default, or
@tindex FL_INPUT_END_EVENT_CLASSIC
@anchor{FL_INPUT_END_EVENT_CLASSIC}
@code{FL_INPUT_END_EVENT_CLASSIC}, which switches back to the type
of handing used in versions up and including to 1.0.90. The function
can be used at any time to change between the two possible types of
behaviour. The function returns the previous setting.

There is a routine that can be used to limit the number of characters
per line for input fields of type @code{@ref{FL_NORMAL_INPUT}}
@findex fl_set_input_maxchars()
@anchor{fl_set_input_maxchars()}
@example
void fl_set_input_maxchars(FL_OBJECT *obj, int maxchars);
@end example
@noindent
To reset the limit to unlimited, set @code{maxchars} to 0. Note that
input objects of type @code{@ref{FL_DATE_INPUT}} are limited to 10
characters per default and those of type @code{@ref{FL_SECRET_INPUT}}
to 16.

Although an input of type @code{@ref{FL_RETURN_ALWAYS}} can be used in
combination with the callback function to check the validity of
characters that are entered into the input field, use of the following
method may simplify this task considerably:
@tindex FL_INPUT_VALIDATOR
@anchor{FL_INPUT_VALIDATOR}
@findex fl_set_input_filter()
@anchor{fl_set_input_filter()}
@example
typedef int (*FL_INPUT_VALIDATOR)(FL_OBJECT *obj, const char *old,
                                 const char *cur, int c);
FL_INPUT_VALIDATOR fl_set_input_filter(FL_OBJECT *obj,
                                       FL_INPUT_VALIDATOR filter);
@end example
@noindent
@anchor{FL_VALID}
@anchor{FL_INVALID}
@anchor{FL_RINGBELL}
The function @code{filter()} is called whenever a new (regular)
character is entered. @code{old} is the string in the input field
before the newly typed character @code{c} was added to form the new
string @code{cur}. If the new character is not an acceptable character
for the input field, the filter function should return
@tindex FL_INVALID
@code{FL_INVALID}
otherwise
@tindex FL_VALID
@code{FL_VALID}. If @code{FL_INVALID} is returned, the new character
is discarded and the input field remains unmodified. The function
returns the old filter. While the built-in filters also sound the
keyboard bell, this doesn't happpen if a custom filter only returns
@code{FL_INVALID}. To also sound the keyboard bell logically or it
with
@tindex FL_RINGBELL
@code{FL_INVALID | FL_RINGBELL}.

This still leaves the possibility that the input is valid for every
character entered, but the string is invalid for the field because it
is incomplete. For example, 12.0e is valid for a float input field for
every character typed, but the final string is not a valid floating
point number. To guard against such cases the filter function is also
called just prior to returning the object with the argument @code{c}
(for the newly entered character) set to zero. If the validator
returns @code{FL_INVALID} the object is not returned to the
application program, but input focus can change to the next input
field. If the return value is @code{FL_INVALID | FL_RINGBELL} the
keyboard bell is sound, the object is also not returned to the
application program and the input focus remains in the object.


To facilitate specialized input fields using validators, the following
validator dependent routines are available
@findex fl_set_input_format()
@anchor{fl_set_input_format()}
@findex fl_get_input_format()
@anchor{fl_get_input_format()}
@example
void fl_set_input_format(FL_OBJECT *obj, int attrib1, int attrib2);
void fl_get_input_format(FL_OBJECT *obj, int *attrib1, int *attrib2);
@end example
@noindent
These two routines more or less provide a means for the validator to
store and retrieve some information about user preference or other
state dependent information. @code{attrib1} and @code{attrib2} can be
any validator defined variables. For the built-in class, only the one
of type @code{@ref{FL_DATE_INPUT}} utilizes these to store the date format:
for @code{attrib1}, it can take
@tindex FL_INPUT_MMDD
@code{FL_INPUT_MMDD} or
@tindex FL_INPUT_DDMM
@code{FL_INPUT_DDMM} and @code{attrib2} is the separator between month
and day. For example, to set the date format to @code{dd/mm}, use
@example
fl_set_input_format(obj, FL_INPUT_DDMM, '/');
@end example
For the built-in type @code{@ref{FL_DATE_INPUT}} the default is
@code{FL_INPUT_MMDD} and the separator is @code{'/'}. There is no
limit on the year other than it must be an integer and appear after
month and day.

The function
@findex fl_validate_input()
@anchor{fl_validate_input()}
@example
int fl_validate_input(FL_OBJECT *obj);
@end example
can be used to test if the value in an input field is valid. It
returns @code{@ref{FL_VALID}} if the value is valid or if there is no
validator function set for the input, otherwise
@code{@ref{FL_INVALID}}.


There are two slightly different input modes for input objects. In the
"normal" mode, when the input field is entered not using the mouse
(e.g., by using of the <Tab> key) the cursor is placed again at the
position it was when the field was left (or at the end of a possibly
existing string when it's entered for the first time). When an input
object has a maximum number of allowed characters set (via the
@code{@ref{fl_set_input_maxchars()}} function) and there's no room
left no new input is accepted until at least one character has been
deleted.

As an alternative there's an input mode that is similar to the way
things were handle in DOS forms etc. Here, when the field is entered
by any means but clicking into it with the mouse, the cursor is placed
at the start of the text. And for fields with a maximum capacity, that
contain already as many characters as possible, the character at the
end of the field are removed when a new one is entered.

To switch between the two modes use the function
@findex fl_set_input_mode()
@anchor{fl_set_input_mode()}
@example int fl_set_input_mode( int mode );
@end example
@noindent
where @code{mode} is one of
@table @code
@tindex FL_NORMAL_INPUT_MODE
@anchor{FL_NORMAL_INPUT_MODE}
@item FL_NORMAL_INPUT_MODE
The default. Use it to switch to the "normal" input mode
@tindex FL_DOS_INPUT_MODE
@anchor{FL_DOS_INPUT_MODE}
@item FL_DOS_INPUT_MODE
For selecting the DOS-like input mode (in this mode, when a maximum
number of characters has been set, as many characters already have
been entered, and a new character is inserted somewhere in the middle
the character at the very end gets deleted to make room for the new
character)
@end table
@noindent
The function returns the previous setting. Note that the function
changes the input mode for all input fields in your application.


@node Other Input Routines
@section Other Input Routines


Note that the label is not the default text in the input field. To set
the contents of the input field use one of these routines:
@findex fl_set_input()
@anchor{fl_set_input()}
@findex fl_set_input_f()
@anchor{fl_set_input_f()}
@example
void fl_set_input(FL_OBJECT *obj, const char *str);
void fl_set_input_f(FL_OBJECT *obj, const char *fmt, ...);
@end example
@noindent
The first one takes a simple string while the second expects a format
string with format specifiers just like @code{printf()} etc. and as
many (appropriate) arguments as there are format specifiers.

Only a limited check on the string passed to the function is done in
that only printable characters (according to the @code{isprint()}
function) and, in the case of @code{@ref{FL_MULTILINE_INPUT}} objects,
new-lines (@code{'\n'}) are accepted (i.e., all that don't fit are
skipped). Use an empty string (or a @code{NULL} pointer as the second
argument) to clear an input field.

Setting the content of an input field does not trigger an object
event, i.e., the object callback is not called. In some situations
you might want to have the callback invoked. For this, you may use
the function @code{@ref{fl_call_object_callback()}}.

To obtain the string in the field (when the user has changed it) use:
@findex fl_get_input()
@anchor{fl_get_input()}
@example
const char *fl_get_input(FL_OBJECT *obj);
@end example
@noindent
This function returns a char pointer for all input types. Thus for
numerical input types e.g., @code{strtol(3)}, @code{atoi(3)},
@code{strtod(3)}, @code{atof(3)} or @code{sscanf(3)} should be used to
convert the string to the proper data type you need. For multiline
input, the returned pointer points to the entire content with possibly
embedded newlines. The application may not modify the content pointed
to by the returned pointer, it points to the internal buffer.


To select or deselect the current input or part of it, the following
two routines can be used
@findex fl_set_input_selected()
@anchor{fl_set_input_selected()}
@findex fl_set_input_selected_range()
@anchor{fl_set_input_selected_range()}
@example
void fl_set_input_selected(FL_OBJECT *obj, int flag);
void fl_set_input_selected_range(FL_OBJECT *obj, int start, int end);
@end example
where @code{start} and @code{end} are measured in characters. When
@code{start} is 0 and @code{end} equals the number of characters in
the string, @code{@ref{fl_set_input_selected()}} makes the entire
input field selected. However, there is a subtle difference between
this routine and @code{@ref{fl_set_input_selected()}} when called with
@code{flag} set to 1: @code{@ref{fl_set_input_selected()}} always
places the cursor at the end of the string while
@code{@ref{fl_set_input_selected_range()}q} places the cursor at the
beginning of the selection.

To obtain the currently selected range, either selected by the
application or by the user, use the following routine
@findex fl_get_input_selected_range()
@anchor{fl_get_input_selected_range()}
@example
const char *fl_get_input_selected_range(FL_OBJECT *obj,
                                        int *start, int *end);
@end example
@noindent
where @code{start} and @code{end}, if not @code{NULL}, are set to the
begining and end position of the selected range, measured in
characters. For example, if @code{start} is 5 after the function
returned and @code{end} is 7, it means the selection starts at
character 6 (@code{str[5]}) and ends before character 8
(@code{str[7]}), so a total of two characters are selected (i.e.,
character 6 and 7). The function returns the selected string (which
may not be modified). If there is currently no selection, the function
returns @code{NULL} and both @code{start} and @code{end} are set to
-1. Note that the @code{char} pointer returned by the function points
to (kind of) a static buffer, and will be overwritten by the next
call.

It is possible to obtain the cursor position using the following
routine
@findex fl_get_input_cursorpos()
@anchor{fl_get_input_cursorpos()}
@example
int fl_get_input_cursorpos(FL_OBJECT *obj, int *xpos, int *ypos);
@end example
@noindent
The function returns the cursor position measured in number of
characters (including newline characters) in front of the cursor. If
the input field does not have input focus (thus does not have a
cursor), the function returns -1. Upon function return, @code{ypos} is
set to the number of the line (starting from 1) the cursor is on, and
@code{xpos} set to the number of characters in front of the cursor
measured from the beginning of the current line as indicated by
@code{ypos}. If the input field does not have input focus the
@code{xpos} is set to -1.

It is possible to move the cursor within the input field
programmatically using the following routine
@findex fl_set_input_cursorpos()
@anchor{fl_set_input_cursorpos()}
@example
void fl_set_input_cursorpos(FL_OBJECT *obj, int xpos, int ypos);
@end example
@noindent
where @code{xpos} and @code{ypos} are measured in characters (lines).
E.g., given the input field @code{"an arbitrary string"} the call
@example
fl_set_input_cursorpos(ob, 4, 1);
@end example
@noindent
places the the cursor after the first character of the word
@code{"arbitrary"}, i.e., directly after the first @code{a}.

By default, if an input field of type @code{@ref{FL_MULTILINE_INPUT}}
contains more text than can be shown, scrollbars will appear with
which the user can scroll the text around horizontally or vertically.
To change this default, use the following routines
@findex fl_set_input_hscrollbar()
@anchor{fl_set_input_hscrollbar()}
@findex fl_set_input_vscrollbar()
@anchor{fl_set_input_vscrollbar()}
@example
void fl_set_input_hscrollbar(FL_OBJECT *obj, int how);
void fl_set_input_vscrollbar(FL_OBJECT *obj, int how);
@end example
@noindent
where @code{how} can be one of the following values
@table @code
@tindex FL_AUTO
@item FL_AUTO
The default. Shows the scrollbar only if needed.
@tindex FL_ON
@item FL_ON
Always shows the scrollbar.
@tindex FL_OFF
@item FL_OFF
Never show scrollbar.
@end table
@noindent
Note however that turning off scrollbars for an input field does not
turn off scrolling, the user can still scroll the field using cursor
and other keys.

To completely turn off scrolling for an input field (for both
multiline and single line input field), use the following routine with
a false value for @code{yes_no}
@findex fl_set_input_scroll()
@anchor{fl_set_input_scroll()}
@example
void fl_set_input_scroll(FL_OBJECT *obj, int yes_no);
@end example

There are also routines that can scroll the input field
programmatically. To scroll vertically (for input fields of type
@code{@ref{FL_MULTILINE_INPUT}} only), use
@findex fl_set_input_topline()
@anchor{fl_set_input_topline()}
@example
void fl_set_input_topline(FL_OBJECT *obj, int line);
@end example
@noindent
where @code{line} is the new top line (starting from 1) in the input
field. To programmatically scroll horizontally, use the following routine
@findex fl_set_input_xoffset()
@anchor{fl_set_input_xoffset()}
@example
void fl_set_input_xoffset(FL_OBJECT *obj, int pixels);
@end example
@noindent
where @code{pixels}, which must be a positive number, indicates how
many pixels to scroll to the left relative to the nominal position of
the text lines.

To obtain the current xoffset, use
@findex fl_get_input_xoffset()
@anchor{fl_get_input_xoffset()}
@example
int fl_get_input_xoffset(FL_OBJECT *obj);
@end example

It is possible to turn off the cursor of the input field using the
following routine with a false value for @code{yes_no}:
@findex fl_set_input_cursor_visible()
@anchor{fl_set_input_cursor_visible()}
@example
void fl_set_input_cursor_visible(FL_OBJECT *obj, int yes_no);
@end example

To obtain the number of lines in the input field, call
@findex fl_get_input_numberoflines()
@anchor{fl_get_input_numberoflines()}
@example
int fl_get_input_numberoflines(FL_OBJECT *obj);
@end example

To obtain the current topline in the input field, use
@findex fl_get_input_topline()
@anchor{fl_get_input_topline()}
@example
int fl_get_input_topline(FL_OBJECT *obj);
@end example

To obtain the number of lines that fit inside the input box, use
@findex fl_get_input_screenlines()
@anchor{fl_get_input_screenlines()}
@example
int fl_get_input_screenlines(FL_OBJECT *obj);
@end example

For secret input field, the default is to draw the text using spaces.
To change the character used to draw the text, the following function
can be used
@findex fl_set_input_fieldchar()
@anchor{fl_set_input_fieldchar()}
@example
int fl_set_input_fieldchar(FL_OBJECT *obj, int field_char);
@end example
@noindent
The function returns the old field char.


@node Input Attributes
@section Input Attributes

Never use @code{@ref{FL_NO_BOX}} as the boxtype.

The first color argument (@code{col1}) to
@code{@ref{fl_set_object_color()}} controls the color of the input
field when it is not selected and the second (@code{col2}) is the
color when selected.

To change the color of the input text or the cursor use
@findex fl_set_input_color()
@anchor{fl_set_input_color()}
@example
void fl_set_input_color(FL_OBJECT *obj, FL_COLOR tcol, FL_COLOR ccol);
@end example
@noindent
Here @code{tcol} indicates the color of the text and @code{ccol} is
the color of the cursor.

If you want to know the colors of the text and cursor use
@findex fl_get_input_color()
@anchor{fl_get_input_color()}
@example
void fl_get_input_color(FL_OBJECT *obj, FL_COLOR *tcol, FL_COLOR *ccol);
@end example

By default, the scrollbar size is dependent on the initial size of the
input box. To change the size of the scrollbars, use the following
routine
@findex fl_set_input_scrollbarsize()
@anchor{fl_set_input_scrollbarsize()}
@example
void fl_set_input_scrollbarsize(FL_OBJECT *obj, int hh, int vw);
@end example
@noindent
where @code{hh} is the horizontal scrollbar height and @code{vw} is
the vertical scrollbar width in pixels.

To determine the current settings for the horizontal scrollbar height
and the vertical scrollbar width use
@findex fl_get_input_scrollbarsize()
@anchor{fl_get_input_scrollbarsize()}
@example
void fl_get_input_scrollbarsize(FL_OBJECT *obj, int *hh, int *vw);
@end example

The default scrollbar types are @code{@ref{FL_HOR_THIN_SCROLLBAR}} and
@code{@ref{FL_VERT_THIN_SCROLLBAR}}. There are two ways you can change
the default. One way is to use @code{@ref{fl_set_defaults()}} or
@code{@ref{fl_set_scrollbar_type()}} to set the application wide
default (preferred); another way is to use
@code{@ref{fl_get_object_component()}} to get the object handle to the
scrollbars and change the the object type forcibly. Although the
second method of changing the scrollbar type is not recommended, the
object handle obtained can be useful in changing the scrollbar colors
etc.

As mentioned earlier, it is possible for the application program to
change the default edit keymaps. The editing key assignment is held in
a structure of type
@tindex FL_EditKeymap
@anchor{FL_EditKeymap}
@code{FL_EditKeymap} defined as follows:
@example
typedef struct @{
    long del_prev_char;     /* delete previous char */
    long del_next_char;     /* delete next char */
    long del_prev_word;     /* delete previous word */
    long del_next_word;     /* delete next word */
    long del_to_eol;        /* delete from cursor to end of line */
    long del_to_bol;        /* delete from cursor to begin of line */
    long clear_field;       /* delete all */
    long del_to_eos;        /* not implemented */
    long backspace;         /* alternative for del_prev_char */

    long moveto_prev_line;  /* one line up */
    long moveto_next_line;  /* one line down */
    long moveto_prev_char;  /* one char left */
    long moveto_next_char;  /* one char right */
    long moveto_prev_word;  /* one word left */
    long moveto_next_word;  /* one word right */
    long moveto_prev_page;  /* one page up */
    long moveto_next_page;  /* one page down */
    long moveto_bol;        /* move to begining of line */
    long moveto_eol;        /* move to end of line */
    long moveto_bof;        /* move to begin of file */
    long moveto_eof;        /* move to end of file */

    long transpose;         /* switch two char positions*/
    long paste;             /* paste the edit buffer */
@} FL_EditKeymap;
@end example

To change the default edit keymaps, the following routine is available:
@findex fl_set_input_editkeymap()
@anchor{fl_set_input_editkeymap()}
@example
void fl_set_input_editkeymap(const FL_EditKeymap *km);
@end example
@noindent
with a filled or partially filled @code{@ref{FL_EditKeymap}}
structure. The unfilled members must be set to 0 so the default
mapping is retained. Change of edit keymap is global and affects all
input field within the application.

Calling @code{@ref{fl_set_input_editkeymap()}} with @code{km} set to
@code{NULL} restores the default. All cursor keys (@code{<Left>},
@code{<Home>} etc.) are reserved and their meanings hard-coded, thus
can't be used in the mapping. For example, if you try to set
@code{del_prev_char} to @code{<Home>}, pressing the @code{<Home>} key
will not delete the previous character.

To obtain the current map of the edit keys use the function
@findex fl_get_input_editkeymap()
@anchor{fl_get_input_editkeymap()}
@example
void fl_get_input_editkeymap(FL_EditKeymap *km);
@end example
@noindent
with the @code{km} argument pointing of a user supplied structure
which after the call will be set up with the current settings for
the edit keys.

In filling the keymap structure, ASCII characters (i.e., characters
with values below 128, including the control characters with values
below 32) should be specified by their ASCII codes (@code{<Ctrl> C}
is 3 etc.), while all others by their @code{Keysym}s (@code{XK_F1}
etc.). Control and special character combinations can be obtained by adding
@tindex FL_CONTROL_MASK
@anchor{FL_CONTROL_MASK}
@code{FL_CONTROL_MASK} to the @code{Keysym}. To specify @code{Meta} add
@tindex FL_ALT_MASK
@anchor{FL_ALT_MASK}
@code{FL_ALT_MASK} to the key value.

@example
FL_EditKeymap ekm;
memset(&ekm, 0, sizeof ekm);                  /* zero struct */

ekm.del_prev_char = 8;                        /* <Backspace> */
ekm.del_prev_word = 8 | FL_CONTROL_MASK;      /* <Ctrl><Backspace> */
ekm.del_next_char = 127;                      /* <Delete> */
ekm.del_prev_word = 'h' | FL_ALT_MASK;        /* <Meta>h */
ekm.del_next_word = 127 | FL_ALT_MASK;        /* <Meta><Delete> */
ekm.moveto_bof    = XK_F1;                    /* <F1> */
ekm.moveto_eof    = XK_F1 | FL_CONTROL_MASK;  /* <Ctrl><F1> */

fl_set_input_editkeymap(&ekm);
@end example

Note: In earlier versions of XForms (all version before 1.2) the
default behaviour of the edit keys was slightly different which
doesn't fit modern user expectations, as was the way the way the
edit keymap was to be set up. If you use XForms for some older
application that makes massive use of the "classical" behaviour
you can compile XForms to use the old behaviour by using the
@code{--enable-classic-editkeys} option when configuring the
library for compilation.

@node Input Remarks
@section Remarks

Always make sure that the input field is high enough to contain a
single line of text. If the field is not high enough, the text may get
clipped, i.e., become unreadable.

See the program @file{demo06.c} for an example of the use of input
fields. See @file{minput.c} for multi-line input fields. See
@file{secretinput.c} for secret input fields and @file{inputall.c} for
all input fields.
