mirror of
https://github.com/lvgl/lvgl.git
synced 2024-11-27 11:43:43 +08:00
212 lines
6.7 KiB
ReStructuredText
212 lines
6.7 KiB
ReStructuredText
.. _coding-style:
|
|
|
|
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
|