Other Input Routines (XForms (Forms Library) - Version 1.2 (Rev. 4) A Graphical User Interface Toolkit for X)

Next: Input Attributes, Previous: Input Interaction, Up: Part III Input Objects [Contents][Index]

### 18.4 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:

    void fl_set_input(FL_OBJECT *obj, const char *str);
    void fl_set_input_f(FL_OBJECT *obj, const char *fmt, ...);

The first one takes a simple string while the second expects a format string with format specifiers just like `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 `isprint()` function) and, in the case of `FL_MULTILINE_INPUT` objects, new-lines (`'\n'`) are accepted (i.e., all that don’t fit are skipped). Use an empty string (or a `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 `fl_call_object_callback()`.

To obtain the string in the field (when the user has changed it) use:

    const char *fl_get_input(FL_OBJECT *obj);

This function returns a char pointer for all input types. Thus for numerical input types e.g., `strtol(3)`, `atoi(3)`, `strtod(3)`, `atof(3)` or `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

    void fl_set_input_selected(FL_OBJECT *obj, int flag);
    void fl_set_input_selected_range(FL_OBJECT *obj, int start, int end);

where `start` and `end` are measured in characters. When `start` is 0 and `end` equals the number of characters in the string, `fl_set_input_selected()` makes the entire input field selected. However, there is a subtle difference between this routine and `fl_set_input_selected()` when called with `flag` set to 1: `fl_set_input_selected()` always places the cursor at the end of the string while `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

    const char *fl_get_input_selected_range(FL_OBJECT *obj,
                                            int *start, int *end);

where `start` and `end`, if not `NULL`, are set to the begining and end position of the selected range, measured in characters. For example, if `start` is 5 after the function returned and `end` is 7, it means the selection starts at character 6 (`str[5]`) and ends before character 8 (`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 `NULL` and both `start` and `end` are set to -1. Note that the `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

    int fl_get_input_cursorpos(FL_OBJECT *obj, int *xpos, int *ypos);

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, `ypos` is set to the number of the line (starting from 1) the cursor is on, and `xpos` set to the number of characters in front of the cursor measured from the beginning of the current line as indicated by `ypos`. If the input field does not have input focus the `xpos` is set to -1.

It is possible to move the cursor within the input field programmatically using the following routine

    void fl_set_input_cursorpos(FL_OBJECT *obj, int xpos, int ypos);

where `xpos` and `ypos` are measured in characters (lines). E.g., given the input field `"an arbitrary string"` the call

    fl_set_input_cursorpos(ob, 4, 1);

places the the cursor after the first character of the word `"arbitrary"`, i.e., directly after the first `a`.

By default, if an input field of type `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

    void fl_set_input_hscrollbar(FL_OBJECT *obj, int how);
    void fl_set_input_vscrollbar(FL_OBJECT *obj, int how);

where `how` can be one of the following values

`FL_AUTO`

  The default. Shows the scrollbar only if needed.

`FL_ON`

  Always shows the scrollbar.

`FL_OFF`

  Never show scrollbar.

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 `yes_no`

    void fl_set_input_scroll(FL_OBJECT *obj, int yes_no);

There are also routines that can scroll the input field programmatically. To scroll vertically (for input fields of type `FL_MULTILINE_INPUT` only), use

    void fl_set_input_topline(FL_OBJECT *obj, int line);

where `line` is the new top line (starting from 1) in the input field. To programmatically scroll horizontally, use the following routine

    void fl_set_input_xoffset(FL_OBJECT *obj, int pixels);

where `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

    int fl_get_input_xoffset(FL_OBJECT *obj);

It is possible to turn off the cursor of the input field using the following routine with a false value for `yes_no`:

    void fl_set_input_cursor_visible(FL_OBJECT *obj, int yes_no);

To obtain the number of lines in the input field, call

    int fl_get_input_numberoflines(FL_OBJECT *obj);

To obtain the current topline in the input field, use

    int fl_get_input_topline(FL_OBJECT *obj);

To obtain the number of lines that fit inside the input box, use

    int fl_get_input_screenlines(FL_OBJECT *obj);

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

    int fl_set_input_fieldchar(FL_OBJECT *obj, int field_char);

The function returns the old field char.

Next: Input Attributes, Previous: Input Interaction, Up: Part III Input Objects [Contents][Index]