init Files
This commit is contained in:
195
libraries/lvgl/docs/widgets/textarea.rst
Normal file
195
libraries/lvgl/docs/widgets/textarea.rst
Normal file
@@ -0,0 +1,195 @@
|
||||
.. _lv_textarea:
|
||||
|
||||
=======================
|
||||
Text area (lv_textarea)
|
||||
=======================
|
||||
|
||||
Overview
|
||||
********
|
||||
|
||||
The Text Area is a `Base object </widgets/obj.html>`__ with a
|
||||
`Label </widgets/label.html>`__ and a cursor on it. Texts or characters
|
||||
can be added to it. Long lines are wrapped and when the text becomes
|
||||
long enough the Text area can be scrolled.
|
||||
|
||||
One line mode and password modes are supported.
|
||||
|
||||
.. _lv_textarea_parts_and_styles:
|
||||
|
||||
Parts and Styles
|
||||
****************
|
||||
|
||||
- :cpp:enumerator:`LV_PART_MAIN` The background of the text area. Uses all the
|
||||
typical background style properties and the text related style
|
||||
properties including ``text_align`` to align the text to the left,
|
||||
right or center.
|
||||
- :cpp:enumerator:`LV_PART_SCROLLBAR` The scrollbar that is shown when the text is
|
||||
too long.
|
||||
- :cpp:enumerator:`LV_PART_SELECTED` Determines the style of the :ref:`selected
|
||||
text <lv_label_text_selection>`. Only ``text_color`` and
|
||||
``bg_color`` style properties can be used. ``bg_color`` should be set
|
||||
directly on the label of the text area.
|
||||
- :cpp:enumerator:`LV_PART_CURSOR` Marks the position where the characters are
|
||||
inserted. The cursor's area is always the bounding box of the current
|
||||
character. A block cursor can be created by adding a background color
|
||||
and background opacity to :cpp:enumerator:`LV_PART_CURSOR`\ 's style. The create
|
||||
line cursor leave the cursor transparent and set a left border. The
|
||||
``anim_time`` style property sets the cursor's blink time.
|
||||
- :cpp:enumerator:`LV_PART_TEXTAREA_PLACEHOLDER` Unique to Text Area, allows styling
|
||||
the placeholder text.
|
||||
|
||||
.. _lv_textarea_usage:
|
||||
|
||||
Usage
|
||||
*****
|
||||
|
||||
Add text
|
||||
--------
|
||||
|
||||
You can insert text or characters to the current cursor's position with:
|
||||
|
||||
- :cpp:expr:`lv_textarea_add_char(textarea, 'c')`
|
||||
- :cpp:expr:`lv_textarea_add_text(textarea, "insert this text")`
|
||||
|
||||
To add wide characters like ``'á'``, ``'ß'`` or CJK characters use
|
||||
:cpp:expr:`lv_textarea_add_text(ta, "á")`.
|
||||
|
||||
:cpp:expr:`lv_textarea_set_text(ta, "New text")` changes the whole text.
|
||||
|
||||
Placeholder
|
||||
-----------
|
||||
|
||||
A placeholder text can be specified
|
||||
|
||||
- which is displayed when the Text area is empty
|
||||
- with :cpp:expr:`lv_textarea_set_placeholder_text(ta, "Placeholder text")`
|
||||
|
||||
Delete character
|
||||
----------------
|
||||
|
||||
To delete a character from the left of the current cursor position use
|
||||
:cpp:expr:`lv_textarea_delete_char(textarea)`.
|
||||
|
||||
To delete from the right use :cpp:expr:`lv_textarea_delete_char_forward(textarea)`
|
||||
|
||||
Move the cursor
|
||||
---------------
|
||||
|
||||
The cursor position can be modified directly like
|
||||
:cpp:expr:`lv_textarea_set_cursor_pos(textarea, 10)`. The ``0`` position means
|
||||
"before the first characters", :cpp:enumerator:`LV_TA_CURSOR_LAST` means "after the
|
||||
last character"
|
||||
|
||||
You can step the cursor with
|
||||
|
||||
- :cpp:expr:`lv_textarea_cursor_right(textarea)`
|
||||
- :cpp:expr:`lv_textarea_cursor_left(textarea)`
|
||||
- :cpp:expr:`lv_textarea_cursor_up(textarea)`
|
||||
- :cpp:expr:`lv_textarea_cursor_down(textarea)`
|
||||
|
||||
If :cpp:expr:`lv_textarea_set_cursor_click_pos(textarea, true)` is applied the
|
||||
cursor will jump to the position where the Text area was clicked.
|
||||
|
||||
Hide the cursor
|
||||
---------------
|
||||
|
||||
The cursor is always visible, however it can be a good idea to style it
|
||||
to be visible only in :cpp:enumerator:`LV_STATE_FOCUSED` state.
|
||||
|
||||
One line mode
|
||||
-------------
|
||||
|
||||
The Text area can be configured to be on a single line with
|
||||
:cpp:expr:`lv_textarea_set_one_line(textarea, true)`. In this mode the height is
|
||||
set automatically to show only one line, line break characters are
|
||||
ignored, and word wrap is disabled.
|
||||
|
||||
Password mode
|
||||
-------------
|
||||
|
||||
The text area supports password mode which can be enabled with
|
||||
:cpp:expr:`lv_textarea_set_password_mode(textarea, true)`.
|
||||
|
||||
By default, if the ``•`` (`Bullet,
|
||||
U+2022 <http://www.fileformat.info/info/unicode/char/2022/index.htm>`__)
|
||||
character exists in the font, the entered characters are converted to it
|
||||
after some time or when a new character is entered. If ``•`` does not
|
||||
exist in the font, ``*`` will be used. You can override the default
|
||||
character with :cpp:expr:`lv_textarea_set_password_bullet(textarea, "x")`.
|
||||
|
||||
In password mode :cpp:expr:`lv_textarea_get_text(textarea)` returns the actual
|
||||
text entered, not the bullet characters.
|
||||
|
||||
The visibility time can be adjusted with :c:macro:`LV_TEXTAREA_DEF_PWD_SHOW_TIME` in ``lv_conf.h``.
|
||||
|
||||
Accepted characters
|
||||
-------------------
|
||||
|
||||
You can set a list of accepted characters with
|
||||
:cpp:expr:`lv_textarea_set_accepted_chars(textarea, "0123456789.+-")`. Other
|
||||
characters will be ignored.
|
||||
|
||||
Max text length
|
||||
---------------
|
||||
|
||||
The maximum number of characters can be limited with
|
||||
:cpp:expr:`lv_textarea_set_max_length(textarea, max_char_num)`
|
||||
|
||||
Very long texts
|
||||
---------------
|
||||
|
||||
If there is a very long text in the Text area (e.g. > 20k characters),
|
||||
scrolling and drawing might be slow. However, by enabling
|
||||
:c:macro:`LV_LABEL_LONG_TXT_HINT` in ``lv_conf.h`` the performance can be
|
||||
hugely improved. This will save some additional information about the
|
||||
label to speed up its drawing. Using :c:macro:`LV_LABEL_LONG_TXT_HINT` the
|
||||
scrolling and drawing will as fast as with "normal" short texts.
|
||||
|
||||
Select text
|
||||
-----------
|
||||
|
||||
Any part of the text can be selected if enabled with
|
||||
:cpp:expr:`lv_textarea_set_text_selection(textarea, true)`. This works much like
|
||||
when you select text on your PC with your mouse.
|
||||
|
||||
.. _lv_textarea_events:
|
||||
|
||||
Events
|
||||
******
|
||||
|
||||
- :cpp:enumerator:`LV_EVENT_INSERT` Sent right before a character or text is
|
||||
inserted. The event parameter is the text about to be inserted.
|
||||
:cpp:expr:`lv_textarea_set_insert_replace(textarea, "New text")` replaces the
|
||||
text to insert. The new text cannot be in a local variable which is
|
||||
destroyed when the event callback exists. ``""`` means do not insert
|
||||
anything.
|
||||
- :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` Sent when the content of the text area has
|
||||
been changed.
|
||||
- :cpp:enumerator:`LV_EVENT_READY` Sent when :cpp:enumerator:`LV_KEY_ENTER` is pressed (or sent) to
|
||||
a one line text area.
|
||||
|
||||
See the events of the :ref:`Base object <lv_obj>` too.
|
||||
|
||||
Learn more about :ref:`events`.
|
||||
|
||||
.. _lv_textarea_keys:
|
||||
|
||||
Keys
|
||||
****
|
||||
|
||||
- ``LV_KEY_UP/DOWN/LEFT/RIGHT`` Move the cursor
|
||||
- ``Any character`` Add the character to the current cursor position
|
||||
|
||||
Learn more about :ref:`indev_keys`.
|
||||
|
||||
.. _lv_textarea_example:
|
||||
|
||||
Example
|
||||
*******
|
||||
|
||||
.. include:: ../examples/widgets/textarea/index.rst
|
||||
|
||||
.. _lv_textarea_api:
|
||||
|
||||
API
|
||||
***
|
||||
Reference in New Issue
Block a user