TextView

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.

Header

#include <gui/textview.h>

Functions

TextView are views designed to work with rich text blocks (Figure 1), where fonts, sizes and colors can be combined. The text can be edited directly or by code using the functions provided by the SDK. In Hello TextView! you have an example of use.

• Use textview_create to create a text view.
• Use textview_printf to add text in the format of printf.
• Use textview_cpos_printf to insert text into the cursor position.
• Use textview_clear to erase all text.
• Use textview_editable to allow editing the text.

1. Character format

One of the advantages of rich text over plain text is the ability to combine different character formats within the same paragraph (Figure 2). Changes will be applied to new text added to the control.

Use textview_family to set the font.

Use textview_fsize to set the character size.

Use textview_fstyle to set the style.

Use textview_color to set the text color.

Use textview_bgcolor to set the background color of the text.

2. Paragraph format

You can also set attributes per paragraph (Figure 3). The new line character '\n' is considered the closing or end of the paragraph.

Use textview_halign to set to paragraph alignment.

Use textview_lspacing to set line spacing (line spacing).

Use textview_bfspace to indicate the vertical space before the paragraph.

Use textview_afspace to indicate the vertical space after the paragraph.

3. Document format

Finally we have several attributes that affect the entire document or control.

Use textview_units to set the text units.

Use textview_pgcolor to set the background color of the control (page).

4. Apply format

The format functions that we have just presented do not modify, by themselves, the appearance of the existing text in the control. They establish the default properties that will be applied below, according to the following criteria. In Hello TextEditor! you have an example of use (Figure 4).

• Use textview_apply_all to apply attributes to the entire text.
• Use textview_apply_select to apply the attributes to the selected text. If there is no selected text, they will be established for the new text inserted in the position of the cursor.
• When we use textview_printf or textview_writef, the text will be added at the end of the control, using the established default attributes. In this way we can compose texts sequentially, altering the attributes to apply to each new string.
• When we use textview_cpos_printf or textview_cpos_writef, the format will be that of the character prior to the current position of the cursor (not the default format).
• In the same way, when the user edits the text directly, the format will be that of the character prior to the current position of the cursor. Except when writing the first character, which will take the format of the following (if any) or the default format.

5. Filter inserted text

• Use textview_OnFilter to filter texts.

Every time the user inserts new text in the control, through pulsations or clipboard operations, an event will be sent that we can capture if necessary. In Hello TextSel and Clipboard! you have an example. We will receive, through the EvText, a copy of the inserted text (EvText::text), the position of the cursor (EvText::cpos) and the number of inserted characters (EvText::len). From here, if the text must be modified, we must obtain the result structure EvTextFilter, setting TRUE its apply field. In EvTextFilter::text we must copy the new text and, in EvTextFilter::cpos, the new position of the cursor.

6. Select text

• Use textview_select to select text.
• Use textview_del_select to delete the selected text.

It is possible through code to change the text selection and the position of the cursor (caret), using this logic.

• If start == -1 and end == 0, all text is deselected, leaving the caret in its current position.
• If start == -1 and end == -1, all text is deselected, moving the caret to the end of the text.
• If start == 0 and end == -1 all the text is selected, moving the caret to the end of the text.
• If start > 0 and end == -1 is selected until the end, moving the caret to the end of the text.
• If start == end the caret is moved to the position, deselecting all text.

7. Clipboard

• Use textview_copy to copy the selected text to the clipboard.
• Use textview_cut to cut the selected text, copying it to the clipboard.
• Use textview_paste to paste the clipboard text at the caret position.

8. Text wrapping

• Use textview_wrap to turn text wrapping on/off.

By default, the control automatically adjusts the width of the text, cutting lines when necessary. This can be avoided by passing wrap=FALSE, where each line will occupy its natural width and a horizontal scroll bar will appear to scroll the text (Figure 5).

textview_create ()

Create a text view.

TextView*
textview_create(void);

Return

The text view.

textview_OnFilter ()

Set a handler to filter text while editing.

void
textview_OnFilter(TextView *view,
                  Listener *listener);

Remarks

It works the same way as in Edit controls. See Filter inserted text and GUI Events.

textview_OnFocus ()

Sets a handler for keyboard focus.

void
textview_OnFocus(TextView *view,
                 Listener *listener);

Remarks

See GUI Events.

textview_size ()

Sets the default size of the view.

void
textview_size(TextView *view,
              const S2Df size);

Remarks

It corresponds to the Natural sizing of the control. Default 245x144.

textview_clear ()

Clears all content from view.

void
textview_clear(TextView *view);

textview_printf ()

Add text to the end using the format of the printf.

uint32_t
textview_printf(TextView *view,
                const char_t *format,
                ...);

1

textview_printf(view, Code: %-10s Price %5.2f\n", code, price);

Return

The number of bytes written.

Remarks

The new text will be added at the end of the control. If there is a selected text, it will be deselected, but it will not be deleted. The cursor will be at the end of the text.

textview_writef ()

Add text to the end.

void
textview_writef(TextView *view,
                const char_t *str);

Remarks

The new text will be added at the end of the control. If there is a selected text, it will be deselected, but it will not be deleted. The cursor will be at the end of the text.

textview_cpos_printf ()

Insert text into the cursor position using the printf format.

uint32_t
textview_cpos_printf(TextView *view,
                     const char_t *format,
                     ...);

1

textview_cpos_printf(view, Code: %-10s Price %5.2f\n", code, price);

Return

The number of bytes written.

Remarks

The new text will be inserted into the current cursor position. If there is a selected text, it will be deleted (replaced) by the new one. The cursor will be located just after the inserted text.

textview_cpos_writef ()

Insert text into the cursor position.

void
textview_cpos_writef(TextView *view,
                     const char_t *str);

Remarks

The new text will be inserted into the current cursor position. If there is a selected text, it will be deleted (replaced) by the new one. The cursor will be located just after the inserted text.

textview_rtf ()

Insert text in Microsoft RTF format.

void
textview_rtf(TextView *view,
             Stream *rtf_in);

textview_units ()

Sets the text units.

void
textview_units(TextView *view,
               const uint32_t units);

Remarks

ekFPOINTS is the default value and the one normally used by word processors. See Size in points and Document format.

textview_family ()

Sets the font family of the text ("Arial", "Times New Roman", "Helvetica", etc).

void
textview_family(TextView *view,
                const char_t *family);

Remarks

Not all families will be present on all platforms. Use font_exists_family or font_installed_families to check. See Character format.

textview_fsize ()

Set the text size.

void
textview_fsize(TextView *view,
               const real32_t size);

Remarks

The value is conditional on the units established in textview_units. See Character format.

textview_fstyle ()

Sets the text style.

void
textview_fstyle(TextView *view,
                const uint32_t fstyle);

Remarks

See Character format.

textview_color ()

Sets the text color.

void
textview_color(TextView *view,
               const color_t color);

Remarks

See Character format.

textview_bgcolor ()

Sets the background color of the text.

void
textview_bgcolor(TextView *view,
                 const color_t color);

Remarks

See Character format.

textview_pgcolor ()

Sets the background color of the control.

void
textview_pgcolor(TextView *view,
                 const color_t color);

Remarks

See Document format.

textview_halign ()

Sets the alignment of text in a paragraph.

void
textview_halign(TextView *view,
                const align_t align);

Remarks

See Paragraph format.

textview_lspacing ()

Sets the line spacing of the paragraph.

void
textview_lspacing(TextView *view,
                  const real32_t scale);

Remarks

See Paragraph format.

textview_bfspace ()

Sets a vertical space before the paragraph.

void
textview_bfspace(TextView *view,
                 const real32_t space);

Remarks

See Paragraph format.

textview_afspace ()

Sets a vertical space after the paragraph.

void
textview_afspace(TextView *view,
                 const real32_t space);

Remarks

See Paragraph format.

textview_apply_all ()

Applies the character and paragraph attributes to all text in the control. If there is no text, they will be taken as the default attributes of the text added using the keyboard.

void
textview_apply_all(TextView *view);

1
2
3
4
5

textview_family(view, "Arial");
textview_fsize(view, 16);
textview_color(view, kCOLOR_RED);
// Arial:16:Red to all text or default
textview_apply_all(view);

Remarks

See Apply format.

textview_apply_select ()

Applies character and paragraph attributes to selected text.

void
textview_apply_select(TextView *view);

Remarks

See Apply format.

textview_scroll_visible ()

Show or hide scroll bars.

void
textview_scroll_visible(TextView *view,
                        const bool_t horizontal,
                        const bool_t vertical);

textview_editable ()

Sets whether or not the control text is editable.

void
textview_editable(TextView *view,
                  const bool_t is_editable);

textview_select ()

Select text.

void
textview_select(TextView *view,
                const int32_t start,
                const int32_t end);

Remarks

See Select text.

textview_show_select ()

Sets whether to show or hide the text selection when keyboard focus is lost.

void
textview_show_select(TextView *view,
                     const bool_t show);

Remarks

When lose keyboard focus, the control will retain the text selection. This feature only affects the visibility of the selection.

textview_del_select ()

Delete the selected text.

void
textview_del_select(TextView *view);

Remarks

It has an effect similar to textview_cut, but without copying the eliminated text on the clipboard. See Select text.

textview_scroll_caret ()

In texts that exceed the visible part, it scrolls to the position of the caret.

void
textview_scroll_caret(TextView *view);

textview_get_text ()

Gets the text of the control.

const char_t*
textview_get_text(const TextView *view);

Return

Null-terminated UTF8 C string '\0'.

textview_copy ()

Copies the selected text to the clipboard.

void
textview_copy(const TextView *view);

Remarks

It works the same way as in Edit controls. See Clipboard.

textview_cut ()

Cuts the selected text, copying it to the clipboard.

void
textview_cut(TextView *view);

Remarks

It works the same way as in Edit controls. See Clipboard.

textview_paste ()

Pastes the text from the clipboard into the caret position.

void
textview_paste(TextView *view);

Remarks

It works the same way as in Edit controls. See Clipboard.

textview_wrap ()

Turn automatic text wrapping on or off.

void
textview_wrap(TextView *view,
              const bool_t wrap);

Remarks

See Text wrapping.