typedef void (*ControlFunc) (Control *c);
Control *new_text_box(Window *w, Rect r, char *text); Control *add_text_box(Control *c, Rect r, char *text); void set_control_text(Control *c, char *newtext); char * get_control_text(Control *c); void set_focus(Control *c); void set_field_allowed_width(Control *c, int width); void set_field_allowed_chars(Control *c, char *allowed); void set_field_disallowed_chars(Control *c, char *disallowed);
To create a text field which can contain multiple lines of text use the new_text_box function. A text box has a vertical scrollbar which allows the user to move the text up and down. If a word will not fit on one line of text, that word will 'wrap' onto the next line of text.
The text inside a text box can be changed using the set_control_text function. This function makes a copy of the string and stores it into the text box.
The add_text_box function works in the same way as new_text_box, except that it attaches the text box to a control rather than directly to a window.
Use get_control_text to find the current text inside a text box. The string returned is a read-only string, so care must be taken not to free or modify the string.
Text can be cut to the clipboard using Ctrl-X, copied using Ctrl-C, and pasted using Ctrl-V. Arrow keys, mouse and shift-arrow selection, and the delete, home, end, page up and page down keys will all work as expected.
Note that keyboard events will not be sent to a text box unless it currently has keyboard focus. The set_focus function can be used to set a window's key focus to a given control. Setting focus will remove the focus from whichever control previously had it, if any.
The maximum number of characters which can be typed into a text box can be controlled with the set_field_allowed_width function. The width parameter controls the number of Unicode characters which can be typed. If the value is zero, the text box is unrestricted in width, which is the default.
A text box can be restricted with set_field_allowed_chars, so that only a set of allowed characters can be typed into it by the user. All other characters will be passed to the parent control or window. Setting the allowed characters to the UTF-8 encoded string "0123456789", for example, restricts a field so it only accepts digits, while setting the allowed string to "0123456789.$" additionally allows the decimal point and dollar sign. Setting the allowed string to NULL removes all restrictions, which is the default situation.
A text box can also be instructed to ignore certain characters, and instead pass them up to its parent control or window, using the set_field_disallowed_chars function. For example, if the disallowed string was set to "\n\t", the enter and tab keys could not be typed into a text box, and could thus propagate to the window, where a key handler function could decide to shift focus, or perform some other action as a result. By default, the escape key is disallowed for text boxes, but the tab and newline keys are allowed, so this function is particularly useful for controlling multi-line text boxes.