1.. _lv_table:
2
3================
4Table (lv_table)
5================
6
7
8Overview
9********
10
11Tables are built from rows, columns, and cells containing text.
12
13The Table Widget is very lightweight because only the text strings are stored.
14No real Widgets are created for cells --- they are just drawn on the fly.
15
16The Table is added to the default group (if one is set).
17Table is an editable Widget, allow selecting a cell with encoder and keyboard
18navigation as well.
19
20
21
22.. _lv_table_parts_and_styles:
23
24Parts and Styles
25****************
26
27-  :cpp:enumerator:`LV_PART_MAIN` The background of the Table; uses the :ref:`typical
28   background style properties <typical bg props>`.
29-  :cpp:enumerator:`LV_PART_ITEMS` The cells of the Table also use the
30   :ref:`typical background style properties <typical bg props>` as well as text
31   style properties.
32
33
34
35.. _lv_table_usage:
36
37Usage
38*****
39
40Set cell value
41--------------
42
43Cells can store only text so numbers need to be converted to text
44before displaying them in a Table.
45
46:cpp:expr:`lv_table_set_cell_value(table, row, col, "Content")`. The text is
47saved by the Table so the buffer containing the string can be a local variable.
48
49Line breaks can be used in the text like ``"Value\n60.3"``.
50
51New rows and columns are automatically added as required.
52
53Rows and Columns
54----------------
55
56To explicitly set number of rows and columns use
57:cpp:expr:`lv_table_set_row_count(table, row_cnt)` and
58:cpp:expr:`lv_table_set_column_count(table, col_cnt)`.
59
60Width and Height
61----------------
62
63Column width can be set with
64:cpp:expr:`lv_table_set_column_width(table, col_id, width)`. The overall width of
65the Table Widget will be set to the sum of all column widths.
66
67Height is calculated automatically from the cell styles (font,
68padding etc) and the number of rows.
69
70Merge cells
71-----------
72
73Cells can be merged horizontally with
74:cpp:expr:`lv_table_add_cell_ctrl(table, row, col, LV_TABLE_CELL_CTRL_MERGE_RIGHT)`.
75To merge more adjacent cells, call this function for each cell.
76
77Scrolling
78---------
79
80If a Table's width or height is set to :c:macro:`LV_SIZE_CONTENT` that size
81will be used to show the whole Table in the respective direction. E.g.
82:cpp:expr:`lv_obj_set_size(table, LV_SIZE_CONTENT, LV_SIZE_CONTENT)`
83automatically sets the Table size to show all columns and rows.
84
85If the width or height is set to a smaller number than its "intrinsic"
86size then the Table becomes scrollable.
87
88
89
90.. _lv_table_events:
91
92Events
93******
94
95-  :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` Sent when a new cell is selected with
96   keys.
97
98.. admonition::  Further Reading
99
100    Learn more about :ref:`lv_obj_events` emitted by all Widgets.
101
102    Learn more about :ref:`events`.
103
104
105
106.. _lv_table_keys:
107
108Keys
109****
110
111The following *Keys* are processed by Table Widgets:
112
113- ``LV_KEY_RIGHT/LEFT/UP/DOWN/`` Select a cell.
114
115Note that, as usual, the state of :cpp:enumerator:`LV_KEY_ENTER` is translated to
116``LV_EVENT_PRESSED/PRESSING/RELEASED`` etc.
117
118:cpp:expr:`lv_table_get_selected_cell(table, &row, &col)` can be used to get the
119currently selected cell. Row and column will be set to
120:c:macro:`LV_TABLE_CELL_NONE` if no cell is selected.
121
122.. admonition::  Further Reading
123
124    Learn more about :ref:`indev_keys`.
125
126
127
128.. _lv_table_example:
129
130Example
131*******
132
133.. include:: ../../examples/widgets/table/index.rst
134
135MicroPython
136-----------
137
138No examples yet.
139
140
141
142.. _lv_table_api:
143
144API
145***
146