Edit

This page has been automatically translated using the Google Translate API services. We are working on improving texts. Thank you for your understanding and patience.

Functions

EditBox are small text boxes with editing capabilities. Like the Label they are of uniform format: The typeface and colors will affect the entire text (Figure 1). They are usually used to edit fields in forms, normally restricted to a single line, although they can also be extended to several of them. To edit texts with multiple attributes use TextView. In Hello Edit and UpDown! you have an example of use.

• Use edit_createto create an edit box.
• Use edit_multiline to create a multi-line editing box.
• Use edit_passmode to hide the text of the control.
• Use edit_phtext to set a placeholder.
• Use edit_autoselect to automatically select all text.

1. Filter texts

• Use edit_OnChange to validate the final text.
• Use edit_OnFilter to detect and correct each user keystroke.

Depending on the value we are editing, it may be necessary to validate the entered text. We can do this when finishing editing or while we are writing. For the first case we will use the edit_OnChange (Listing 1) event that will call the handler just before the control loses keyboard focus (Figure 2). If the text is invalid, the handler must return FALSE, thus preventing the focus from changing to the next control, remaining in the editbox and forcing the user to correct it.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

static void i_OnChange(UserData *data, Event *e)
{
    const EvText *p = event_params(e, EvText);
    if (is_valid_text(data, p->text) == FALSE)
    {
        // Force the focus remain in editbox
        bool_t *r = event_result(e, bool_t);
        *r = FALSE;
    }
}
...
edit_OnChange(edit, listener(NULL, i_OnChange, void));

It will not be possible to move keyboard focus to another control while the text is invalid.

In case we want to implement more elaborate filters that correct the text while it is being written, we will use the edit_OnFilter event. We will receive, through the EvText structure, a copy of the current text, the position of the cursor (caret) and the number of characters added or deleted. From here, the filter will be able to validate the text, setting the apply field of EvTextFilter to FALSE. If the new characters are not appropriate, we will return the new text and cursor position in the text and cpos fields of EvTextFilter, putting apply to TRUE. For example, in (Listing 2) we have a simple filter that only allows numeric characters (Figure 3).

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

static void OnFilter(void *noused, Event *e)
{
    const EvText *params = event_params(e, EvText);
    EvTextFilter *result = event_result(e, EvTextFilter);
    uint32_t i = 0, j = 0;
    while (params->text[i] != '\0')
    {
        if (params->text[i] >= '0' && params->text[i] <= '9')
        {
            result->text[j] = params->text[i];
            j += 1;
        }

        i += 1;
    }

    result->text[j] = '\0';
    result->apply = TRUE;
}
...
edit_OnFilter(edit, listener(NULL, i_OnFilter, void));

2. Clipboard operations

Being native components, the Edit controls support typical clipboard operations: Copy, Paste, Cut, etc, as well as their keyboard shortcuts. However, it can be useful to access these operations from the program code, allowing, for example, the text selected in the control to be copied to the clipboard.

• Use edit_copy to copy the selected text to the clipboard.
• Use edit_cut to cut the selected text, copying it to the clipboard.
• Use edit_paste to paste the clipboard text at the caret position.

edit_create ()

Create a text edit control.

Edit*
edit_create(void);

Return

The edit.

edit_multiline ()

Create a text editing control that allows multiple lines.

Edit*
edit_multiline(void);

Return

The edit.

edit_OnFilter ()

Set a function to filter the text while editing.

void
edit_OnFilter(Edit *edit,
              Listener *listener);

Remarks

See Filter texts and GUI Events.

edit_OnChange ()

Set a function to detect when the text has changed.

void
edit_OnChange(Edit *edit,
              Listener *listener);

Remarks

See Filter texts and GUI Events.

edit_OnFocus ()

Sets a handler for keyboard focus.

void
edit_OnFocus(Edit *edit,
             Listener *listener);

Remarks

See GUI Events.

edit_text ()

Set the edit control text.

void
edit_text(Edit *edit,
          const char_t *text);

edit_font ()

Set the font of the edit control.

void
edit_font(Edit *edit,
          const Font *font);

edit_align ()

Set text alignment.

void
edit_align(Edit *edit,
           const align_t align);

edit_passmode ()

Activate the password mode, which will hide the typed characters.

void
edit_passmode(Edit *edit,
              const bool_t passmode);

edit_editable ()

Enable or disable editing in the control.

void
edit_editable(Edit *edit,
              const bool_t is_editable);

edit_autoselect ()

Activate or deactivate auto-selection of text.

void
edit_autoselect(Edit *edit,
                const bool_t autoselect);

Remarks

Default FALSE.

edit_select ()

Select text.

void
edit_select(Edit *edit,
            const int32_t start,
            const int32_t end);

edit_tooltip ()

Assigns a tooltip to the edit control.

void
edit_tooltip(Edit *edit,
             const char_t *text);

edit_color ()

Set the text color.

void
edit_color(Edit *edit,
           const color_t color);

Remarks

RGB values may not be fully portable. See Colors.

edit_color_focus ()

Sets the color of the text, when the control has the keyboard focus.

void
edit_color_focus(Edit *edit,
                 const color_t color);

Remarks

RGB values may not be fully portable. See Colors.

edit_bgcolor ()

Set the background color.

void
edit_bgcolor(Edit *edit,
             const color_t color);

Remarks

RGB values may not be fully portable. See Colors.

edit_bgcolor_focus ()

Sets the background color, when the control has keyboard focus.

void
edit_bgcolor_focus(Edit *edit,
                   const color_t color);

Remarks

RGB values may not be fully portable. See Colors.

edit_phtext ()

Set an explanatory text for when the control is blank (placeholder).

void
edit_phtext(Edit *edit,
            const char_t *text);

edit_phcolor ()

Set the color of the placeholder text.

void
edit_phcolor(Edit *edit,
             const color_t color);

Remarks

RGB values may not be fully portable. See Colors.

edit_phstyle ()

Set the font style for the placeholder.

void
edit_phstyle(Edit *edit,
             const uint32_t fstyle);

edit_vpadding ()

Sets the inner vertical margin.

void
edit_vpadding(Edit *edit,
              const real32_t padding);

edit_get_text ()

Get control text.

const char_t*
edit_get_text(const Edit *edit);

Return

UTF8 C-string terminated in null character '\0'.

edit_get_height ()

Gets the current height of the control.

real32_t
edit_get_height(const Edit *edit);

Return

The height of the control, which will change depending on the font size and vpadding.

edit_copy ()

Copies the selected text to the clipboard.

void
edit_copy(const Edit *edit);

Remarks

See Clipboard operations.

edit_cut ()

Cuts the selected text, copying it to the clipboard.

void
edit_cut(Edit *edit);

Remarks

See Clipboard operations.

edit_paste ()

Pastes the text from the clipboard into the caret position.

void
edit_paste(Edit *edit);

Remarks

See Clipboard operations.