## Text Boxes

### OBJECTS

      typedef void (*ControlFunc)  (Control *c);

### FUNCTIONS

      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);

### NOTES

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.