github-code/lvgl
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(bindings): proofread batch 20 (#7764)

Browse Source
This commit is contained in:
Victor Wheeler
2025-02-24 15:24:51 -07:00
committed by GitHub
parent d4b5bf8af0
commit fb3903c55e
6 changed files with 396 additions and 350 deletions
Download Patch File Download Diff File Expand all files Collapse all files

133
docs/CONTRIBUTING.rst
View File

@@ -1,10 +1,11 @@
.. _contributing:
============
Contributing
============
Introduction
------------
************
Join LVGL's community and leave your footprint in the library!
@@ -15,39 +16,38 @@ It might be scary to make the first step but you have nothing to be
afraid of. A friendly and helpful community is waiting for you. Get to
know like-minded people and make something great together.
So let's find which contribution option fits you the best and help you
So let's find which contribution option fits you the best and helps you
join the development of LVGL!
Ways to contribute
-------------------
Ways to Contribute
******************
- **Spread the Word**: Share your LVGL experience with friends or on social media to boost its visibility.
- **Star LVGL** Give us a star on `GitHub <https://github.com/lvgl/lvgl>`__ ! It helps a lot to LVGL more appealing for newcomers.
- **Report a bug**: Open a `GitHub Issue <https://github.com/lvgl/lvgl/issues>`__ if something is not working.
- **Join our** `Forum <https://forum.lvgl.io/>`__ : Meet fellow developers and discuss questions
- **Tell your ideas**: If you miss something from LVGL we would love to hear about it in a `GitHub Issue <https://github.com/lvgl/lvgl/issues>`__
- **Develop features**: Help to design or develop a feature. See below.
- **Star LVGL** Give us a star on `GitHub <https://github.com/lvgl/lvgl>`__! It helps a lot to make LVGL more appealing for newcomers.
- **Report a Bug**: Open a `GitHub Issue <https://github.com/lvgl/lvgl/issues>`__ if something is not working.
- **Join Our** `Forum <https://forum.lvgl.io/>`__ : Meet fellow developers and discuss questions.
- **Tell Us Your Ideas**: If you feel something is missing from LVGL, we would love to hear about it in a `GitHub Issue <https://github.com/lvgl/lvgl/issues>`__
- **Develop Features**: Help to design or develop a feature. See below.
Mid- and large-scale issues are discussed in `Feature Planning <https://github.com/lvgl/lvgl/issues/new?assignees=&labels=&projects=&template=feat-planning.yml>`__ issues.
Mid and large scale issues are discussed in `Feature planning <https://github.com/lvgl/lvgl/issues/new?assignees=&labels=&projects=&template=feat-planning.yml>`__ issues.
An issue can be developed when all the questions in the issue template are answered and there is no objection from any core member.
An issue can be developed when all the questions in the issue template are answered and there are no objection from any core member.
We are using GitHub labels to show the state and attributes of the issues and Pull requests.
If you are looking for contribution opportunities you can `Filter for these labels <https://github.com/lvgl/lvgl/labels>`__ :
- ``Simple``: Good choice to get started with LVGL contribution
- ``Simple``: Good choice to get started with an LVGL contribution
- ``PR needed``: We investigated the issue but it still needs to be implemented
- ``Review needed``: A Pull request is opened and it needs review/testing
.. _contributing_pull_request:
.. _contributing_pull_requests:
Pull request
------------
Pull Requests
*************
Merging new code into the lvgl, documentation, blog, examples, and other
repositories happen via *Pull requests* (PR for short). A PR is a
Merging new code into LVGL, documentation, blog, examples, and other
repositories happens via *Pull requests* (PR for short). A PR is a
notification like "Hey, I made some updates to your project. Here are
the changes, you can add them if you want." To do this you need a copy
(called fork) of the original project under your account, make some
@@ -57,20 +57,20 @@ https://github.com/lvgl/lvgl/pulls.
To add your changes you can edit files online on GitHub and send a new
Pull request from there (recommended for small changes) or add the
updates in your favorite editor/IDE and use git to publish the changes
updates in your favorite editor/IDE and use ``git`` to publish the changes
(recommended for more complex updates).
From GitHub
~~~~~~~~~~~
-----------
1. Navigate to the file you want to edit.
2. Click the Edit button in the top right-hand corner.
3. Add your changes to the file.
4. Add a commit message on the bottom of the page.
4. Add a commit message at the bottom of the page.
5. Click the *Propose changes* button.
From command line
~~~~~~~~~~~~~~~~~
From Command Line
-----------------
The instructions describe the main ``lvgl`` repository but it works the
same way for the other repositories.
@@ -79,23 +79,23 @@ same way for the other repositories.
"Fork" button in the top right corner. It will "copy" the ``lvgl``
repository to your GitHub account (``https://github.com/<YOUR_NAME>?tab=repositories``)
2. Clone your forked repository.
3. Add your changes. You can create a *feature branch* from *master* for the updates: ``git checkout -b <the-new-feature-branch-name>``
3. Add your changes. You can create a *feature branch* from THE ``master`` branch for the updates: ``git checkout -b <new-feature-branch-name>``
4. Commit and push your changes to the forked ``lvgl`` repository.
5. Create a PR on GitHub from the page of your ``lvgl`` repository (``https://github.com/<YOUR_NAME>/lvgl``) by
clicking the *"New pull request"* button. Don't forget to select the branch where you added your changes.
6. Set the base branch. It means where you want to merge your update. In the ``lvgl`` repo both the fixes
and new features go to ``master`` branch.
7. Describe what is in the update. An example code is welcome if applicable.
6. Set the base branch where you want to merge your update. In the ``lvgl`` repo both fixes
and new features are directed to the ``master`` branch.
7. Describe what is in the update. Example code is welcome if applicable.
8. If you need to make more changes, just update your forked ``lvgl`` repo with new commits.
They will automatically appear in the PR.
.. _contributing_commit_message_format:
Commit message format
~~~~~~~~~~~~~~~~~~~~~
Commit Message Format
---------------------
The commit messages format is inspired by `Angular Commit
Format <https://gist.github.com/brianclements/841ea7bffdb01346392c>`__.
Format <https://github.com/angular/angular/blob/main/CONTRIBUTING.md#commit>`__.
The following structure should be used:
@@ -109,54 +109,70 @@ The following structure should be used:
Possible ``<type>``\ s:
- ``fix`` bugfix in the source code.
- ``fix`` bugfix in LVGL source code
- ``feat`` new feature
- ``arch`` architectural changes
- ``perf`` changes that affect the performance
- ``example`` anything related to examples (even fixes and new examples)
- ``docs`` anything related to the documentation (even fixes, formatting, and new pages)
- ``perf`` changes that affect performance
- ``example`` anything related to examples (including fixes and new examples)
- ``docs`` anything related to documentation (including fixes, formatting, and new pages)
- ``test`` anything related to tests (new and updated tests or CI actions)
- ``chore`` any minor formatting or style changes that would make the changelog noisy
``<scope>`` is the module, file, or sub-system that is affected by the
``<scope>`` is the name of the module, file, or subsystem affected by the
commit. It's usually one word and can be chosen freely. For example
``img``, ``layout``, ``txt``, ``anim``. The scope can be omitted.
``<subject>`` contains a short description of the change:
- use the imperative, present tense: "change" not "changed" nor "changes"
- don't capitalize the first letter
- no dot (``.``) at the end
- max 90 characters
- use the imperative, present tense: "change" not "changed" nor "changes",
- don't capitalize the first letter,
- no period (``.``) at the end,
- max 90 characters.
``<body>`` optional and can be used to describe the details of this
``<body>`` optional and can be used to describe details of the
change.
``<footer>`` shall contain
- the words "BREAKING CHANGE" if the changes break the API
- reference to the GitHub issue or Pull Request if applicable.
(See `Linking a pull rquest to an issue <https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/using-keywords-in-issues-and-pull-requests#linking-a-pull-request-to-an-issue>`__
for details.)
Some examples:
- fix(img): update size if a new source is set
- fix(bar): fix memory leak
The animations weren't deleted in the destructor.
.. code-block:: text
fix(image): update size when a new source is set
.. code-block:: text
fix(bar): fix memory leak
The animations weren't deleted in the destructor.
Fixes: #1234
.. code-block:: text
feat: add span widget
The span widget allows mixing different font sizes, colors and styles.
It's similar to HTML <span>
.. code-block:: text
docs(porting): fix typo
Fixes: #1234
- feat: add span widget
The span widget allows mixing different font sizes, colors and styles.
It's similar to HTML <span>
- docs(porting): fix typo
.. _contributing_dco:
Developer Certification of Origin (DCO)
---------------------------------------
***************************************
Overview
~~~~~~~~
--------
To ensure all licensing criteria are met for every repository of the
LVGL project, we apply a process called DCO (Developer's Certificate of
@@ -167,30 +183,31 @@ The text of DCO can be read here: https://developercertificate.org/.
By contributing to any repositories of the LVGL project you agree that
your contribution complies with the DCO.
If your contribution fulfills the requirements of the DCO no further
action is needed. If you are unsure feel free to ask us in a comment.
If your contribution fulfills the requirements of the DCO, no further
action is needed. If you are unsure feel free to ask us in a comment,
e.g. in your submitted :ref:`Pull Request <contributing_pull_requests>`.
Accepted licenses and copyright notices
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
---------------------------------------
To make the DCO easier to digest, here are some practical guides about
specific cases:
Your own work
^^^^^^^^^^^^^
~~~~~~~~~~~~~
The simplest case is when the contribution is solely your own work. In
this case you can just send a Pull Request without worrying about any
licensing issues.
Use code from online source
^^^^^^^^^^^^^^^^^^^^^^^^^^^
~~~~~~~~~~~~~~~~~~~~~~~~~~~
If the code you would like to add is based on an article, post or
comment on a website (e.g. StackOverflow) the license and/or rules of
that site should be followed.
For example in case of StackOverflow a notice like this can be used:
For example in case of StackOverflow, a notice like this can be used:
.. code-block::
@@ -204,7 +221,7 @@ For example in case of StackOverflow a notice like this can be used:
... code snippet here ...
Use MIT licensed code
^^^^^^^^^^^^^^^^^^^^^
~~~~~~~~~~~~~~~~~~~~~
As LVGL is MIT licensed, other MIT licensed code can be integrated
without issues. The MIT license requires a copyright notice be added to
@@ -212,7 +229,7 @@ the derived work. Any derivative work based on MIT licensed code must
copy the original work's license file or text.
Use GPL licensed code
^^^^^^^^^^^^^^^^^^^^^
~~~~~~~~~~~~~~~~~~~~~
The GPL license is not compatible with the MIT license. Therefore, LVGL
cannot accept GPL licensed code.

24
docs/_static/css/custom.css vendored
View File

@@ -152,7 +152,23 @@ div.body {
font-size: 75%;
}
/* This replaces a color present in `pygments.css` which is used to highlight
* function names. It is too dark for DARK mode, and nearly black in LIGHT mode so it is
* difficult to tell that it is even highlighted. This color override remedies both. */
.highlight .nf { color: #2648ee } /* Name.Function */
/* These replace colors present in `pygments.css` which is used in code highlighting.
* These are too dark to be readlable in DARK mode. They include:
* .highlight .nf -- function names
* .highlight .nl -- code labels
* .descname .n -- API documentation function names
* The first 2 were created by lightening the `pygments.css` colors without changing their
* angle on the color wheel. The added "conditional" also limits this change to
* DARK MODE only instead of both light and dark modes.
*/
html[data-theme="dark"] .highlight .nf {
color: #3569f5;
}
html[data-theme="dark"] .highlight .nl {
color: #0043e2;
}
html[data-theme="dark"] .descname .n {
color: #0a44de;
}

335
docs/details/integration/bindings/api_json.rst
View File

@@ -1,258 +1,273 @@
Output API as JSON data
.. _output_api_as_json_data:
=======================
Output API as JSON Data
=======================
We have written a script that will read the header files in LVGL and outputs a more friendly JSON format for the API.
This is done so that bindings that generate code automatically will have an easy way to collect the needed information
without having to reinvent the wheel. The JSON data format has already made libraries for reading the format for just
about every programming language out there.
As of 20-Jun-2024, LVGL comes packaged with a Python script
(``./scripts/gen_json/gen_json.py``) that reads the header files in LVGL and outputs
a more friendly JSON format for the API. This is done so that bindings that generate
code automatically will have an easy way to collect the needed information without
having to reinvent the wheel. JSON format was chosen because there are libraries for
reading JSON data in almost every programming language.
The script in order to run does have some requirements.
Requirements
************
- Python >= 3.10
- Pycparser >= 2.21: Python Library for reading the preprocessor ouotput from the C compiler
- PyMSVC >= 0.4.0: Python library is using MSVC Compiler
- C compiler, gcc for Linux, clang for OSX and MSVC for Windows
- Doxygen: used to read the docstrings from the header files.
- Pycparser >= 2.22: Python Library for reading C preprocessor output
- PyMSVC >= 0.4.0: Python library for using the MSVC Compiler
- A C compiler: gcc for Linux, clang for OSX and MSVC for Windows
- Doxygen: used to read Doxygen comments (the API documentation) from the header files.
There are several options when running the script. They are as follows
- `--output-path`: output directory for JSON file. If one is not supplied then it will be output stdout
- `--lvgl-config`: path to lv_conf.h (including file name), if this is not set then a config file will be
generated that has most common things turned on
- `--develop`: leaves the temporary folder in place.
Usage
*****
Command-Line Options
--------------------
to use the script
- ``--output-path``: output directory for JSON file. If one is not supplied then it
will be output to stdout.
- ``--lvgl-config``: path to lv_conf.h (including file name). If this is not set then
a config file will be generated that has the most common LVGL options turned on.
- ``--develop``: leaves the files generated in the temporary folder in place.
Examples
--------
Normal usage:
.. code-block:: shell
python /scripts/gen_json/gen_json.py --output-path=json/output/directory --lvgl-config=path/to/lv_conf.h
python ./scripts/gen_json/gen_json.py --output-path=json/output/directory --lvgl-config=path/to/lv_conf.h
or if you want to run a subprocess from inside of a generation script and read the output from stdout
If you want to run a subprocess from inside of a generation script and read the output from stdout:
.. code-block:: shell
python /scripts/gen_json/gen_json.py --lvgl-config=path/to/lv_conf.h
python ./scripts/gen_json/gen_json.py --lvgl-config=path/to/lv_conf.h
Output Data
-----------
The JSON data is broken apart into a couple of main categories.
The contents of the output file is a large JSON object (``{...}``) with the following
key/value pairs (these are the keys):
- enums
- functions
- function_pointers
- structures
- unions
- variables
- typedefs
- forward_decls
- macros
.. parsed-literal::
Those categories are the element names undert the root of the JSON data.
The value for each categry is an array of JSON elements. There is a bit of
nesting with the elements in the arrays and I have created "json_types" that
will allow you to identify exactly what you are dealing with.
{
"enums" : [...],
"functions" : [...],
"function_pointers": [...],
"structures" : [...],
"unions" : [...],
"variables" : [...],
"typedefs" : [...],
"forward_decls" : [...],
"macros" : [...]
}
The different "json_types" are as follows:
As you can see, the value of each of these elements is an array. The elements in
each array are JSON objects, each with a structure unique to the type indicated by
the parent element name (e.g. "enums", "functions", etc.).
A key/value pair has been added to each object (key = "json_type") to make it possible
to pass an object to a generic function and have each object know its own type through
this field. The possible "json_type" values are:
- ``"array"``: The array type is used to identify arrays.
Available JSON fields:
- ``"dim"``: number of items in the array
Fields:
- ``"dim"``: number of items in array
- ``"quals"``: array of qualifiers, IE "const"
- ``"type"``: This may or may not be available.
- ``"name"``: the name of the data type
- ``"name"``: name of data type
- ``"field"``: This type is used to describe fields in structures and unions.
It is used in the ``"fields"`` array of the ``"struct"`` and ``"union"`` JSON types.
It is used in the ``"fields"`` array of the ``"struct"`` and ``"union"`` types
covered below.
Available JSON fields:
- ``"name"``: The name of the field.
- ``"type"``: This contains the type information for the field. Check the
``"json_type"`` to know what type you are dealing with.
- ``"bitsize"``: The number of bits the field has or ``null``
if there is no bit size defined
- ``"docstring"``: you should know what this is.
Fields:
- ``"name"``: field name
- ``"type"``: data type
``"json_type"`` carries object type (e.g. "enum", "function", etc.) identifying the top-level group it comes from
- ``"bitsize"``: The number of bits for bit-fields, or ``null`` for normal field types.
- ``"docstring"``: string containing Doxygen-extracted documentation
- ``"arg"``: Used to describe an argument/parameter in a function or a function pointer.
- ``"arg"``: Describes a function argument
Available JSON fields:
- ``"name"``: The name of the argument/parameter.
- ``"type"``: This contains the type information for the field. Check the
``"json_type"`` to know what type you are dealing with.
- ``"docstring"``: you should know what this is.
- ``"quals"``: array of qualifiers, IE "const"
Fields:
- ``"name"``: argument name
- ``"type"``: data type
``"json_type"`` carries object type (e.g. "enum", "function", etc.) identifying the top-level group it comes from.
- ``"docstring"``: string containing Doxygen-extracted documentation
- ``"quals"``: array of any qualifiers present, e.g. "const"
- ``"forward_decl"``: Describes a forward declaration.There are structures in
- ``"forward_decl"``: Describes a forward declaration. There are structures in
LVGL that are considered to be private and that is what these desccribe.
Available JSON fields:
- ``"name"``: The name of the formard declaration.
- ``"type"``: This contains the type information for the field. Check the
``"json_type"`` to know what type you are dealing with.
- ``"docstring"``: you should know what this is.
- ``"quals"``: array of qualifiers, IE "const"
Fields:
- ``"name"``: name of forward declaration
- ``"type"``: data type
``"json_type"`` carries object type (e.g. "enum", "function", etc.) identifying the top-level group it comes from.
- ``"docstring"``: string containing Doxygen-extracted documentation
- ``"quals"``: array of any qualifiers present, e.g. "const"
- ``"function_pointer"``: Describes a function pointer. These are used when
- ``"function_pointer"``: Describes a function pointer. These are used when
registering callback functions in LVGL.
Available JSON fields:
- ``"name"``: The name of the function pointer.
- ``"type"``: This contains the return type information for the function pointer.
- ``"docstring"``: you should know what this is.
- ``"args"``: array of ``"arg"`` Widgets. This describes the function arguments/parameters.
- ``"quals"``: array of qualifiers, IE "const"
Fields:
- ``"name"``: name of function pointer
- ``"type"``: function return type
- ``"docstring"``: string containing Doxygen-extracted documentation
- ``"args"``: array of ``"arg"`` objects described above
- ``"quals"``: array of any qualifiers present, e.g. "const"
- ``"variable"``: Describes a global variable.
Available JSON fields:
- ``"name"``: The name of the variable.
- ``"type"``: This contains the type information for the field. Check the
``"json_type"`` to know what type you are dealing with.
- ``"docstring"``: you should know what this is.
- ``"quals"``: array of qualifiers, IE "const"
- ``"storage"``: array of storage classifiers, IE "extern"
Fields:
- ``"name"``: variable name
- ``"type"``: data type
``"json_type"`` carries object type (e.g. "enum", "function", etc.) identifying the top-level group it comes from.
- ``"docstring"``: string containing Doxygen-extracted documentation
- ``"quals"``: array of any qualifiers present, e.g. "const"
- ``"storage"``: array of any storage-class specifiers present (e.g. "auto", "static", "extern", etc.)
- ``"special_type"``: Currently only used to describe an ellipsis argument
for a function.
- ``"special_type"``: Currently only used to describe an ellipsis argument of a function.
Available JSON fields:
- ``"name"``: will always be "ellipsis".
Fields:
- ``"name"``: always "ellipsis"
- ``"primitive_type"``: This is a base type. There or no other types beneith this.
This tells you that the type is a basic or primitive C type.
IE: struct, union, int, unsigned int, etc...
- ``"primitive_type"``: Data type that does not begin with ``"lv_"`` and end with
``"_t"``. Compare to ``"lvgl_type"`` This includes struct, union, integral types
(e.g. int, unsigned int), etc..
Available JSON fields:
- ``"name"``: The name of the primitive type.
Fields:
- ``"name"``: name of primitive type
- ``"enum"``: Describes a grouping of enumeration items/members.
- ``"enum"``: C enumerations
Available JSON fields:
- ``"name"``: The name of the enumeration group/type.
- ``"type"``: This contains the type information for the enumeration group.
This is always going to be an "int" type. Make sure you do not use this
type as the type for the members of this enumeration group. Check the
enumeration members type to get the correct type.
- ``"docstring"``: you should know what this is.
- ``"members"``: array of ``"enum_member"`` Widgets
Fields:
- ``"name"``: If enumeration is the result of a ``typedef``, this field carries
the type name defined. Example: ``lv_align_t``. (Not always available.)
- ``"type"``: type of enumerators (always "int")
- ``"docstring"``: string containing Doxygen-extracted documentation
- ``"members"``: array of ``"enum_member"`` objects
- ``"enum_member"``: Describes an enumeration item/member. Only found under
the ``"members"`` field of an ``"enum"`` JSON type
- ``"enum_member"``: enumerator (enumeration value). This "json_type" is only found
in the ``"members"`` array of an ``"enum"`` object
Available JSON fields:
- ``"name"``: The name of the enumeration.
- ``"type"``: This contains the type information for the enum member.
This gets a bit tricky because the type specified in here is not always
going to be an "int". It will usually point to an lvgl type and the type
of the lvgl type can be found in the ``"typedefs"`` section.
- ``"docstring"``: you should know what this is.
- ``"value"``: the enumeration member/item's value
Fields:
- ``"name"``: enumerator name
- ``"type"``: If enumeration is the result of a ``typedef``, this field carries
the type name defined. Example: ``lv_align_t``.
- ``"docstring"``: string containing Doxygen-extracted documentation
- ``"value"``: enumerator value
- ``"lvgl_type"``: This is a base type. There or no other types beneith this.
This tells you that the type is an LVGL data type.
- ``"lvgl_type"``: Data type defined in LVGL (begins with ``"lv_"`` and ends with ``"_t"``.
Available JSON fields:
- ``"name"``: The name of the type.
- ``"quals"``: array of qualifiers, IE "const
Fields:
- ``"name"``: type name
- ``"quals"``: array of any qualifiers present, e.g. "const"
- ``"struct"``: Describes a structure
- ``"struct"``: C struct
Available JSON fields:
- ``"name"``: The name of the structure.
- ``"type"``: This contains the primitive type information for the structure.
- ``"docstring"``: you should know what this is.
Fields:
- ``"name"``: struct name (data type if defined by ``typedef``)
- ``"type"``: a "primitive_type" object {"name": "struct", "json_type": "primitive_type"}. (See definition above.)
- ``"docstring"``: string containing Doxygen-extracted documentation
- ``"fields"``: array of ``"field"`` objects (See definition above.)
- ``"quals"``: array of any qualifiers present, e.g. "const"
- ``"union"``: C union
Fields:
- ``"name"``: union name (data type if defined by ``typedef``)
- ``"type"``: a "primitive_type" object {"name": "union", "json_type": "primitive_type"}. (See definition above.)
- ``"docstring"``: string containing Doxygen-extracted documentation
- ``"fields"``: array of ``"field"`` elements.
- ``"quals"``: array of qualifiers, IE "const"
- ``"quals"``: array of any qualifiers present, e.g. "const"
- ``"union"``: Describes a union
Available JSON fields:
- ``"name"``: The name of the union.
- ``"type"``: This contains the primitive type information for the union.
- ``"docstring"``: you should know what this is.
- ``"fields"``: array of ``"field"`` elements.
- ``"quals"``: array of qualifiers, IE "const"
- ``"macro"``: describes a macro. There is limited information that can be
- ``"macro"``: C macro. There is limited information that can be
collected about macros and in most cases a binding will need to have these
statically added to a binding. It is more for collecting the docstrings than
statically added to a binding. It is more for collecting the docstrings than
anything else.
Available JSON fields:
- ``"name"``: The name of the macro.
- ``"docstring"``: you should know what this is.
Fields:
- ``"name"``: macro name
- ``"docstring"``: string containing Doxygen-extracted documentation
- ``"ret_type"``: return type from a function. This is only going to be seen in the ``"type"``
element of a ``"function"`` type.
Available JSON fields:
- ``"type"``: This contains the type information for the field. Check the
``"json_type"`` to know what type you are dealing with.
- ``"docstring"``: you should know what this is.
Fields:
- ``"type"``: data type
``"json_type"`` carries object type (e.g. "enum", "function", etc.) identifying the top-level group it comes from.
- ``"docstring"``: string containing Doxygen-extracted documentation
- ``"function"``: Describes a function.
- ``"function"``: C function
Available JSON fields:
- ``"name"``: The name of the function.
- ``"type"``: This contains the type information for the return value.
- ``"docstring"``: you should know what this is.
- ``"args"``: array of ``"arg"`` json types. This describes the function arguments/parameters.
Fields:
- ``"name"``: function name
- ``"type"``: A "ret_type" object. (See definition above.)
- ``"docstring"``: string containing Doxygen-extracted documentation
- ``"args"``: array of ``"arg"`` json types. (See definition above.)
- ``"stdlib_type"``: This is a base type, meaning that there are no more
type levels beneith this. This tells us that the type is from the C stdlib.
- ``"stdlib_type"``: C integral type (int, unsigned int, float, etc.)
Available JSON fields:
- ``"name"``: The name of the type.
- ``"quals"``: array of qualifiers, IE "const
Fields:
- ``"name"``: type name
- ``"quals"``: array of any qualifiers present, e.g. "const"
- ``"unknown_type"``: This should not be seen. If it is then there needs to be
an adjustment made to the script. Please open an issue and let us know if you see this type.
Available JSON fields:
- ``"name"``: The name of the type.
- ``"quals"``: array of qualifiers, IE "const
Fields:
- ``"name"``: type name
- ``"quals"``: array of any qualifiers present, e.g. "const"
- ``"pointer"``: This is a wrapper object to let you know that the type you
are dealing with is a pointer
- ``"pointer"``: C pointer
Available JSON fields:
- ``"type"``: This contains the type information for the pointer. Check the
``"json_type"`` to know what type you are dealing with.
- ``"quals"``: array of qualifiers, IE "const", may or may not be available.
Fields:
- ``"type"``: pointer type
``"json_type"`` carries object type (e.g. "enum", "function", etc.) identifying the top-level group it comes from.
- ``"quals"``: array of any qualifiers present, e.g. "const"
- ``"typedef"``: type definitions. I will explain more on this below.
- ``"typedef"``: C type definition
Available JSON fields:
- ``"name"``: The name of the typedef.
- ``"type"``: This contains the type information for the field. Check the
``"json_type"`` to know what type you are dealing with.
- ``"docstring"``: you should know what this is.
- ``"quals"``: array of qualifiers, IE "const"
Fields:
- ``"name"``: type name (e.g. ``lv_part_t``)
- ``"type"``: a "primitive_type" object {"name": "uint32_t", "json_type": "stdlib_type"}. (See definition above.)
``"json_type"`` carries object type (e.g. "enum", "function", etc.) identifying the top-level group it comes from.
- ``"docstring"``: string containing Doxygen-extracted documentation
- ``"quals"``: array of any qualifiers present, e.g. "const"
Here is an example of what the output will look like.
Here is a shortened example of what the output looks like.
.. code-block:: json

46
docs/details/integration/bindings/javascript.rst
View File

@@ -2,31 +2,18 @@
JavaScript
==========
With `lv_binding_js <https://github.com/lvgl/lv_binding_js>`__ you can write lvgl with JavaScript.
With `lv_binding_js <https://github.com/lvgl/lv_binding_js>`__ you can use LVGL from within JavaScript.
It uses React's virtual DOM concept to manipulate lvgl UI components, providing a familiar React-like
It uses React's virtual DOM concept to manipulate LVGL UI components, providing a familiar React-like
experience to users.
**Code**
**Code Running on Real Device**
Table of Contents
-----------------
- `Features <#features>`__
- `Demo <#demo>`__
- `Building <#building>`__
- `Components <#components>`__
- `Font <#font>`__
- `Animation <#animation>`__
- `Style <#style>`__
- `JSAPI <#jsapi>`__
- `Thanks <#thanks>`__
Features
--------
********
- Support all lvgl built-in components
- Fully support lvgl flex and grid style
@@ -36,34 +23,33 @@ Features
Demo
----
****
See the `demo <https://github.com/lvgl/lv_binding_js/tree/master/demo>`__ folder
Building
--------
********
The following are developer notes on how to build lvgljs on your native platform. They are not complete guides,
but include notes on the necessary libraries, compile flags, etc.
lvgljs
~~~~~~
------
- `ubuntu build Notes for sdl simulator <https://github.com/lvgl/lv_binding_js/blob/master/doc/build/build-ubuntu-arm.md>`__
- `macos x86 build Notes for sdl simulator <https://github.com/lvgl/lv_binding_js/blob/master/doc/build/build-macos-x86-simulator.md>`__
- `ubuntu build Notes for platform arm <https://github.com/lvgl/lv_binding_js/blob/master/doc/build/build-ubuntu-x86-simulator.md>`__
- `Build Notes for embedded Linux device <https://github.com/lvgl/lv_binding_js/blob/master/doc/build/build-device.md>`__
- `Build Notes for SDL Simulator (Linux and macOS) <https://github.com/lvgl/lv_binding_js/blob/master/doc/build/build-simulator.md>`__
JS Bundle
~~~~~~~~~
---------
- `JS Bundle build Notes <https://github.com/lvgl/lv_binding_js/blob/master/doc/build/js-bundle.md>`__
Components
----------
**********
- `View <https://github.com/lvgl/lv_binding_js/blob/master/doc/component/View.md>`__
- `Image <https://github.com/lvgl/lv_binding_js/blob/master/doc/component/Image.md>`__
@@ -83,19 +69,19 @@ Components
Font
----
****
- `Builtin-Symbol <https://github.com/lvgl/lv_binding_js/blob/master/doc/Symbol/symbol.md>`__
Animation
---------
*********
- `Animation <https://github.com/lvgl/lv_binding_js/blob/master/doc/animate/animate.md>`__
Style
-----
*****
.. include::https://github.com/lvgl/lv_binding_js/blob/master/doc/style/position-size-layout.md
@@ -117,7 +103,7 @@ Style
JSAPI
-----
*****
- `network <https://github.com/lvgl/lv_binding_js/blob/master/doc/jsapi/network.md>`__
- `filesystem <https://github.com/lvgl/lv_binding_js/blob/master/doc/jsapi/fs.md>`__
@@ -125,9 +111,9 @@ JSAPI
Thanks
------
******
lvgljs depends on following excellent work
**lvgljs** depends on following excellent work:
- `lvgl <https://github.com/lvgl/lvgl>`__: Create beautiful UIs for any MCU, MPU and display type
- `QuickJS <https://bellard.org/quickjs/>`__: JavaScript engine

151
docs/details/integration/bindings/micropython.rst
View File

@@ -6,46 +6,49 @@ MicroPython
What is MicroPython?
--------------------
********************
`MicroPython <http://micropython.org/>`__ is Python for microcontrollers. Using MicroPython, you can write Python3
code and run it even on a bare metal architecture with limited resources.
`MicroPython <http://micropython.org/>`__ is Python for microcontrollers. Using
MicroPython, you can write Python3 code and run it even on a bare metal architecture
with limited resources. One of its powerful features is the ability to change the
behavior of a device by changing the Python code on removable (or internal) storage,
without having to change the device's firmware.
Highlights of MicroPython
~~~~~~~~~~~~~~~~~~~~~~~~~
-------------------------
- **Compact**: Fits and runs within just 256k of code space and 16k of RAM. No OS is needed, although you
can also run it with an OS, if you want.
- **Compatible**: Strives to be as compatible as possible with normal Python (known as CPython).
- **Versatile**: Supports many architectures (x86, x86-64, ARM, ARM Thumb, Xtensa).
- **Interactive**: No need for the compile-flash-boot cycle. With the REPL (interactive prompt) you can type
commands and execute them immediately, run scripts, etc.
- **Popular**: Many platforms are supported. The user base is growing bigger. Notable forks:
:Compact: Fits and runs within just 256k of code space and 16k of RAM. No OS is
needed, although you can also run it with an OS, if you want.
:Compatible: Strives to be as compatible as possible with normal Python (known as CPython).
:Versatile: Supports many architectures (x86, x86-64, ARM, ARM Thumb, Xtensa).
:Interactive: No need for the compile-flash-boot cycle. With the REPL (interactive
prompt) you can type commands and execute them immediately, run scripts, etc.
:Popular: Many platforms are supported. The user base is growing larger. Notable forks:
- `MicroPython <https://github.com/micropython/micropython>`__
- `CircuitPython <https://github.com/adafruit/circuitpython>`__
- `MicroPython_ESP32_psRAM_LoBo <https://github.com/loboris/MicroPython_ESP32_psRAM_LoBo>`__
- `MicroPython <https://github.com/micropython/micropython>`__
- `CircuitPython <https://github.com/adafruit/circuitpython>`__
- `MicroPython_ESP32_psRAM_LoBo <https://github.com/loboris/MicroPython_ESP32_psRAM_LoBo>`__
- **Embedded Oriented**: Comes with modules specifically for embedded systems, such as the
`machine module <https://docs.micropython.org/en/latest/library/machine.html#classes>`__
for accessing low-level hardware (I/O pins, ADC, UART, SPI, I2C, RTC, Timers etc.)
:Embedded Oriented: Comes with modules specifically for embedded systems, such as the
`machine module <https://docs.micropython.org/en/latest/library/machine.html#classes>`__
for accessing low-level hardware (I/O pins, ADC, UART, SPI, I2C, RTC, Timers etc.)
--------------
Why MicroPython + LVGL?
-----------------------
***********************
MicroPython `does not have a good native high-level GUI library <https://forum.micropython.org/viewtopic.php?f=18&t=5543>`__.
LVGL is an `Object-Oriented Component Based <https://blog.lvgl.io/2018-12-13/extend-lvgl-objects>`__
high-level GUI library, which seems to be a natural candidate to map into a higher level language, such as Python.
high-level GUI library, which is a natural candidate to map into a higher level language, such as Python.
LVGL is implemented in C and its APIs are in C.
Here are some advantages of using LVGL in MicroPython:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
------------------------------------------------------
- Develop GUI in Python, a very popular high level language. Use paradigms such as Object-Oriented Programming.
- Usually, GUI development requires multiple iterations to get things right. With C, each iteration consists of
@@ -55,24 +58,26 @@ Here are some advantages of using LVGL in MicroPython:
MicroPython + LVGL could be used for:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-------------------------------------
- Fast prototyping GUI.
- Shortening the cycle of changing and fine-tuning the GUI.
- Modelling the GUI in a more abstract way by defining reusable composite Widgets, taking advantage of Python's language features
such as Inheritance, Closures, List Comprehension, Generators, Exception Handling, Arbitrary Precision Integers and others.
- Make LVGL accessible to a larger audience. No need to know C to create a nice GUI on an embedded system. This goes well with
- Fast GUI prototyping
- Shortening the cycle of changing and fine-tuning a GUI
- Modelling a GUI in a more abstract way by defining reusable composite Widgets,
taking advantage of Python's language features such as Inheritance, Closures, List
Comprehension, Generators, Exception Handling, Arbitrary Precision Integers and others.
- Make LVGL accessible to a larger audience. No need to know C to create a nice GUI
on an embedded system. This goes well with
`CircuitPython vision <https://learn.adafruit.com/welcome-to-circuitpython/what-is-circuitpython>`__.
CircuitPython was designed with education in mind, to make it easier for new or inexperienced users to get started with
embedded development.
CircuitPython was designed with education in mind, to make it easier for new or
inexperienced programmers to get started with embedded development.
- Creating tools to work with LVGL at a higher level (e.g. drag-and-drop designer).
--------------
So what does it look like?
--------------------------
What does it look like?
***********************
It's very much like the C API, but Object-Oriented for LVGL components.
@@ -80,7 +85,7 @@ Let's dive right into an example!
A simple example
~~~~~~~~~~~~~~~~
----------------
.. code-block:: python
@@ -97,12 +102,12 @@ A simple example
lv.screen_load(scr)
How can I use it?
-----------------
How Can I Use It?
*****************
Online Simulator
~~~~~~~~~~~~~~~~
----------------
If you want to experiment with LVGL + MicroPython without downloading anything, you can use our online
simulator! It's a fully functional LVGL + MicroPython that runs entirely in the browser and allows you to
@@ -114,27 +119,30 @@ Many :ref:`LVGL examples <examples>` are available also for MicroPython. Just cl
PC Simulator
~~~~~~~~~~~~
------------
MicroPython is ported to many platforms. One notable port is "unix", which allows you to build and run MicroPython
(+LVGL) on a Linux machine. (On a Windows machine you might need Virtual Box or WSL or MinGW or Cygwin etc.)
MicroPython is ported to many platforms. One notable port is to "Unix", which allows
you to build and run MicroPython (+LVGL) on a Linux machine. (On a Windows machine
you might need Virtual Box or WSL or MinGW or Cygwin etc.)
`Click here to know more information about building and running the unix port <https://github.com/lvgl/lv_micropython>`__
`Click here to learn more about building and running the Unix port. <https://github.com/lvgl/lv_micropython>`__
Embedded Platforms
~~~~~~~~~~~~~~~~~~
------------------
In the end, the goal is to run it all on an embedded platform. Both MicroPython and LVGL can be used on many embedded
architectures. `lv_micropython <https://github.com/lvgl/lv_micropython>`__ is a fork of MicroPython+LVGL and currently
supports Linux, ESP32, STM32 and RP2. It can be ported to any other platform supported by MicroPython.
In the end, the goal is to run it all on an embedded platform. Both MicroPython and LVGL can
be used on many embedded architectures. `lv_micropython <https://github.com/lvgl/lv_micropython>`__
is a fork of MicroPython+LVGL and currently supports Linux, ESP32, STM32 and RP2.
It can be ported to any other platform supported by MicroPython.
- You would also need display and input drivers. You can either use one of the existing drivers provided with lv_micropython,
or you can create your own input/display drivers for your specific hardware.
- Drivers can be implemented either in C as a MicroPython module, or in pure Python!
- You would also need display and input drivers. You can either use one of the
existing drivers provided with lv_micropython, or you can create your own
input/display drivers for your specific hardware.
- Drivers can be implemented either in C as a MicroPython module, or in pure Python.
lv_micropython already contains these drivers:
**lv_micropython** already contains these drivers:
- Display drivers:
@@ -164,7 +172,7 @@ lv_micropython already contains these drivers:
Where can I find more information?
----------------------------------
**********************************
- ``lv_micropython`` `README <https://github.com/lvgl/lv_micropython>`__
- ``lv_binding_micropython`` `README <https://github.com/lvgl/lv_binding_micropython>`__
@@ -174,7 +182,7 @@ Where can I find more information?
The MicroPython Binding is auto generated!
------------------------------------------
******************************************
- LVGL is a git submodule inside `lv_micropython <https://github.com/lvgl/lv_micropython>`__
(LVGL is a git submodule of `lv_binding_micropython <https://github.com/lvgl/lv_binding_micropython>`__
@@ -184,7 +192,7 @@ The MicroPython Binding is auto generated!
LVGL C API Coding Conventions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-----------------------------
For a summary of coding conventions to follow see the :ref:`coding-style`.
@@ -192,30 +200,31 @@ For a summary of coding conventions to follow see the :ref:`coding-style`.
.. _memory_management:
Memory Management
~~~~~~~~~~~~~~~~~
-----------------
- When LVGL runs in MicroPython, all dynamic memory allocations (:cpp:func:`lv_malloc`) are handled by MicroPython's memory
manager which is `garbage-collected <https://en.wikipedia.org/wiki/Garbage_collection_(computer_science)>`__ (GC).
- To prevent GC from collecting memory prematurely, all dynamic allocated RAM must be reachable by GC.
- GC is aware of most allocations, except from pointers on the `Data Segment <https://en.wikipedia.org/wiki/Data_segment>`__:
- To prevent GC from collecting memory prematurely, all dynamic allocated RAM must be reachable by the GC.
- GC is aware of most allocations, except from pointers to the `Data Segment <https://en.wikipedia.org/wiki/Data_segment>`__:
- Pointers which are global variables
- Pointers which are static global variables
- Pointers which are static local variables
Such pointers need to be defined in a special way to make them reachable by GC
Such pointers need to be defined in a special way to make them reachable by the GC.
Identify The Problem
^^^^^^^^^^^^^^^^^^^^
~~~~~~~~~~~~~~~~~~~~
Problem happens when an allocated memory's pointer (return value of :cpp:func:`lv_malloc`) is stored only in either **global**,
**static global** or **static local** pointer variable and not as part of a previously allocated ``struct`` or other variable.
A problem occurs when an allocated memory's pointer (return value of :cpp:func:`lv_malloc`)
is stored only in either **global**, **static global** or **static local** pointer
variable and not as part of a previously allocated ``struct`` or other variable.
Solve The Problem
^^^^^^^^^^^^^^^^^
Solving the Problem
~~~~~~~~~~~~~~~~~~~
- Replace the global/static local var with :cpp:expr:`(LV_GLOBAL_DEFAULT()->_var)`
- Include ``lv_global.h`` on files that use ``LV_GLOBAL_DEFAULT``
@@ -223,11 +232,11 @@ Solve The Problem
Example
^^^^^^^
~~~~~~~
More Information
^^^^^^^^^^^^^^^^
Further Reading on Memory Management
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- `In the README <https://github.com/lvgl/lv_binding_micropython#memory-management>`__
- `In the Blog <https://blog.lvgl.io/2019-02-20/micropython-bindings#i-need-to-allocate-a-littlevgl-struct-such-as-style-color-etc-how-can-i-do-that-how-do-i-allocatedeallocate-memory-for-it>`__
@@ -236,13 +245,13 @@ More Information
.. _callbacks:
Callbacks
~~~~~~~~~
---------
In C a callback is just a function pointer. But in MicroPython we need to register a *MicroPython callable object* for each
callback. Therefore in the MicroPython binding we need to register both a function pointer and a MicroPython object for every callback.
Therefore we defined a **callback convention** for the LVGL C API that expects lvgl headers to be defined in a certain
way. Callbacks that are declared according to the convention would allow the binding to register a MicroPython object
Therefore we defined a **callback convention** for the LVGL C API that expects LVGL headers to be defined in a certain
way. Callbacks that are declared according to this convention allow the binding to register a MicroPython object
next to the function pointer when registering a callback, and access that object when the callback is called.
- The basic idea is that we have ``void * user_data`` field that is used automatically by the MicroPython Binding
@@ -259,8 +268,8 @@ There are a few options for defining a callback in LVGL C API:
- There's a struct that contains a field called ``void * user_data``
- A pointer to that struct is provided as the **first** argument of a callback registration function
- A pointer to that struct is provided as the **first** argument of the callback itself
- A pointer to that struct is provided as the **first** argument of a callback registration function.
- A pointer to that struct is provided as the **first** argument of the callback itself.
- Option 2: ``user_data`` as a function argument
@@ -277,11 +286,11 @@ There are a few options for defining a callback in LVGL C API:
In practice it's also possible to mix these options, for example provide a struct pointer when registering a callback
(option 1) and provide ``user_data`` argument when calling the callback (options 2),
**as long as the same ``user_data`` that was registered is passed to the callback when it's called**.
**as long as the same** ``user_data`` **that was registered is passed to the callback when it's called**.
Examples
^^^^^^^^
~~~~~~~~
- :cpp:type:`lv_anim_t` contains ``user_data`` field. :cpp:func:`lv_anim_set_path_cb` registers `path_cb` callback.
Both ``lv_anim_set_path_cb`` and :cpp:type:`lv_anim_path_cb_t` receive :cpp:type:`lv_anim_t` as their first argument
@@ -293,12 +302,12 @@ Examples
.. _more-information-1:
More Information
^^^^^^^^^^^^^^^^
Further Reading on Callbacks
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- In the `Blog <https://blog.lvgl.io/2019-08-05/micropython-pure-display-driver#using-callbacks>`__
and in the `README <https://github.com/lvgl/lv_binding_micropython#callbacks>`__
- `[v6.0] Callback conventions #1036 <https://github.com/lvgl/lvgl/issues/1036>`__
- Various discussions: `here <https://github.com/lvgl/lvgl/pull/3294#issuecomment-1184895335>`__
and `here <https://github.com/lvgl/lvgl/issues/1763#issuecomment-762247629>`__
and`here <https://github.com/lvgl/lvgl/issues/316#issuecomment-467221587>`__
and `here <https://github.com/lvgl/lvgl/issues/316#issuecomment-467221587>`__

57
docs/details/integration/bindings/pikascript.rst
View File

@@ -1,19 +1,21 @@
==========
PikaScript
==========
What is PikaScript ?
--------------------
What is PikaScript?
*******************
`PikaScript <https://github.com/pikasTech/pikascript>`__ is a Python interpreter designed specifically for
microcontrollers, and it supports a subset of the common Python3 syntax.
It's lighter, requiring only 32k of code space and 4k of RAM, which means it can run on stm32f103c8 (blue-pill)
or even stm32g030c8, on the other hand, you can leave valuable space for more material or larger buffer areas.
It's lighter than MicroPython, requiring only 32k of code space and 4k of RAM, which
means it can run on stm32f103c8 (blue-pill) or even stm32g030c8. On the other hand,
you can leave valuable space for more material or larger buffer areas.
It is simpler, out of the box, runs with no porting and configuration at all, does not depend on OS or file
system, has good support for popular IDEs for Windows platforms like Keil, IAR, RT-Thread-Studio, and of course,
supports linux-gcc development platforms.
supports Linux gcc development platforms.
It's smarter, with a unique C module mechanism that allows you to generate bindings automatically by simply
writing the API for the C module in Python, and you don't need to deal with the headache of writing any macros
@@ -24,23 +26,24 @@ of your arguments .
--------------
Why PikaScript + LVGL ?
-----------------------
Why PikaScript + LVGL?
**********************
- PikaScript now supports the main features of LVGL8, and these APIs are fully compatible with MicroPython!
This means that you can continue to use already written code from MicroPython, and then use less code space and RAM.
- Enjoy detailed code hints down to the parameter type for a better programming experience
- Use a more convenient IDE, such as vs-based simulation projects
- PikaScript now supports the main features of LVGL8, and these APIs are fully compatible with MicroPython.
This means that you can continue to use already written code from MicroPython, but use less code space and RAM.
- Enjoy detailed code hints down to the parameter type for a better programming experience.
- Use a more convenient IDE, such as Visual-Studio-based simulation projects.
So how does it look like?
-------------------------
What Does It Look Like?
***********************
Here are some examples of lvgl that PikaScript can already run, they are mainly from the lvgl documentation examples
Here are some examples of using LVGL that PikaScript can already run. They are mainly
from the LVGL documentation examples.
LV_ARC
~~~~~~
------
.. code-block:: python
@@ -57,7 +60,7 @@ LV_ARC
LV_BAR
~~~~~~
------
.. code-block:: python
@@ -73,7 +76,7 @@ LV_BAR
LV_BTN
~~~~~~
------
.. code-block:: python
@@ -103,7 +106,7 @@ LV_BTN
LV_CHECKBOX
~~~~~~~~~~~
-----------
.. code-block:: python
@@ -132,12 +135,12 @@ LV_CHECKBOX
--------------
How does it work?
-----------------
How Does It Work?
*****************
PikaScript has a unique C module smart binding tool
PikaScript has a unique C module smart binding tool.
Just write the Python interface in pika_lvgl.pyi (.pyi is the python interface file)
Just write the Python interface in pika_lvgl.pyi (.pyi is a Python interface file)
.. code-block:: python
@@ -169,7 +172,7 @@ in the module_class_method format, without any additional work, and all binding
To use the module, just ``import pika_lvgl`` and the precompiler will automatically scan main.py and bind the
``pika_lvgl`` module
``pika_lvgl`` module.
.. code-block:: shell
@@ -183,7 +186,7 @@ To use the module, just ``import pika_lvgl`` and the precompiler will automatica
binding pika_lvgl.pyi...
The precompiler is written in Rust, runs on windows and linux, and is completely open source.
The precompiler is written in Rust, runs on Windows and Linux, and is completely open source.
In addition to binding C modules, the precompiler compiles Python scripts to bytecode in the PC, reducing the
size of the script and increasing its speed.
@@ -192,7 +195,7 @@ size of the script and increasing its speed.
--------------
How can I use it?
-----------------
How Can I Use It?
*****************
The simulation repo on vs is available on https://github.com/pikasTech/lv_pikascript
The simulation repository for Visual Studio is available at https://github.com/pikasTech/lv_pikascript .