1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
|
Coding style
============
File template
-------------
Use `misc/lv_templ.c <https://github.com/lvgl/lvgl/blob/master/src/misc/lv_templ.c>`__
and `misc/lv_templ.h <https://github.com/lvgl/lvgl/blob/master/src/misc/lv_templ.h>`__
Naming conventions
------------------
- Words are separated by '\_'
- In variable and function names use only lower case letters
(e.g. *height_tmp*)
- In enums and defines use only upper case letters
(e.g. *e.g. MAX_LINE_NUM*)
- Global names (API):
- start with *lv*
- followed by module name: *button*, *label*, *style* etc.
- followed by the action (for functions): *set*, *get*, etc.
- closed with the subject: *name*, *size*, *state* etc.
- Typedefs
- prefer ``typedef struct`` and ``typedef enum`` instead of
``struct name`` and ``enum name``
- always end ``typedef struct`` and ``typedef enum`` type names with
``_t``
- Abbreviations:
- The following abbreviations are used and allowed:
- ``dsc`` descriptor
- ``param`` parameter
- ``indev`` input device
- ``anim`` animation
- ``buf`` buffer
- ``str`` string
- ``min/max`` minimum/maximum
- ``alloc`` allocate
- ``ctrl`` control
- ``pos`` position
- Avoid adding new abbreviations
Coding guide
------------
- Functions:
- Write function with single responsibility
- Make the functions ``static`` where possible
- Variables:
- One line, one declaration (BAD: char x, y;)
- Use ``<stdint.h>`` (*uint8_t*, *int32_t* etc)
- Declare variables where needed (not all at function start)
- Use the smallest required scope
- Variables in a file (outside functions) are always *static*
- Do not use global variables (use functions to set/get static
variables)
Comments
--------
Before every function have in ``.h`` files a comment like this:
.. code:: c
/**
* Return with the screen of an object
* @param obj pointer to an object
* @return pointer to a screen
*/
lv_obj_t * lv_obj_get_screen(lv_obj_t * obj);
Always use ``/*Something*/`` format and NOT ``//Something``
Write readable code to avoid descriptive comments like:
``x++; /*Add 1 to x*/``. The code should show clearly what you are
doing.
You should write **why** have you done this:
``x++; /*Because of closing '\0' of the string*/``
Short "code summaries" of a few lines are accepted. E.g.
``/*Calculate the new coordinates*/``
In comments use \` \` when referring to a variable. E.g.
:literal:`/\*Update the value of \`x_act`*/`
API Conventions
----------------------
To support the auto-generation of bindings, the LVGL C API must
follow some coding conventions:
- Use ``enum``\ s instead of macros. If inevitable to use ``define``\ s
export them with :cpp:expr:`LV_EXPORT_CONST_INT(defined_value)` right after the ``define``.
- In function arguments use ``type name[]`` declaration for array parameters instead of :cpp:expr:`type * name`
- Use typed pointers instead of :cpp:expr:`void *` pointers
- Widget constructor must follow the ``lv_<widget_name>_create(lv_obj_t * parent)`` pattern.
- Widget members function must start with ``lv_<widget_name>`` and should receive :cpp:expr:`lv_obj_t *` as first
argument which is a pointer to widget object itself.
- ``struct`` APIs should follow the widgets' conventions. That is to receive a pointer to the ``struct`` as the
first argument, and the prefix of the ``struct`` name should be used as the prefix of the
function name too (e.g. :cpp:expr:`lv_display_set_default(lv_display_t * disp)`)
- Functions and ``struct``\ s which are not part of the public API must begin with underscore in order to mark them as "private".
- Argument must be named in H files too.
- Do not ``malloc`` into a static or global variables. Instead declare the variable in ``lv_global_t``
structure in ``lv_global.h`` and mark the variable with :cpp:expr:`(LV_GLOBAL_DEFAULT()->variable)` when it's used.
- To register and use callbacks one of the following needs to be followed.
- Pass a pointer to a ``struct`` as the first argument of both the registration function and the callback. That
``struct`` must contain ``void * user_data`` field.
- The last argument of the registration function must be ``void * user_data`` and the same ``user_data``
needs to be passed as the last argument of the callback.
To learn more refer to the documentation of `MicroPython <integration/bindings/micropython>`__.
Formatting
----------
Here is example to show bracket placing and using of white spaces:
.. code:: c
/**
* Set a new text for a label. Memory will be allocated to store the text by the label.
* @param label pointer to a label object
* @param text '\0' terminated character string. NULL to refresh with the current text.
*/
void lv_label_set_text(lv_obj_t * label, const char * text)
{ /*Main brackets of functions in new line*/
if(label == NULL) return; /*No bracket only if the command is inline with the if statement*/
lv_obj_inv(label);
lv_label_ext_t * ext = lv_obj_get_ext(label);
/*Comment before a section*/
if(text == ext->txt || text == NULL) { /*Bracket of statements start inline*/
lv_label_refr_text(label);
return;
}
...
}
Use 4 spaces indentation instead of tab.
You can use **astyle** to format the code. Run ``code-format.py`` from
the ``scripts`` folder.
pre-commit
----------
`pre-commit <https://pre-commit.com/>`__ is a multi-language package
manager for pre-commit hooks. See the `installation
guide <https://pre-commit.com/#installation>`__ to get pre-commit python
package installed into your development machine.
Once you have ``pre-commit`` installed you will need to `set up the git
hook scripts <https://pre-commit.com/#3-install-the-git-hook-scripts>`__
with:
.. code:: console
pre-commit install
now ``pre-commit`` will run automatically on ``git commit``!
Hooks
-----
The ``format-source`` local hook (see ``.pre-commit-config.yaml``) runs
**astyle** on all the staged source and header files (that are not
excluded, see ``exclude`` key of the hook configuration) before entering
the commit message, if any file gets formatted by **astyle** you will
need to add the change to the staging area and run ``git commit`` again.
The ``trailing-whitespace`` hook fixes trailing whitespaces on all of
the files.
Skipping hooks
--------------
If you want to skip any particular hook you can do so with:
.. code:: console
SKIP=name-of-the-hook git commit
Testing hooks
-------------
It's no necessary to do a commit to test the hooks, you can test hooks
by adding the files into the staging area and run:
.. code:: console
pre-commit run name-of-the-hook
|
