diff --git a/docs/README.md b/docs/README.md index eae2a9adef..8254e14c57 100644 --- a/docs/README.md +++ b/docs/README.md @@ -5,58 +5,38 @@ Building the documentation is easy. Here are the requirements: -* Doxygen -* Python >= 3.10 -* C compiler (gcc, msvc, clang, etc...) +- Doxygen +- Python >= 3.10 +- C compiler (gcc, msvc, clang, etc...) Once Python is installed pip install -r requirements.txt -will install all the prerequisite packages: +will install all the prerequisite packages. -* Sphinx -* breathe -* imagesize -* importlib-metadata -* sphinx-rtd-theme -* sphinx-sitemap -* sphinxcontrib-applehelp -* sphinxcontrib-devhelp -* sphinxcontrib-htmlhelp -* sphinxcontrib-jsmath -* sphinxcontrib-qthelp -* sphinxcontrib-serializinghtml -* sphinxcontrib-mermaid==0.9.2 -* sphinx-copybutton -* sphinx-design -* typing-extensions -* sphinx-reredirects -* dirsync -* furo -* accessible-pygments - -Now you are ready to build the documentation: +To build the documentation on Windows: python build.py html -or if you are on a Unix like OS: +On Linux: python3 build.py html -Intermediate files are normally prepared in `./docs/intermediate/` and the final documentation will normally appear in `./docs/build/html/`. (Both of these directories can be overridden using environment variables. See documentation in `build.py` header comment for details.) +Intermediate files are normally prepared in `./docs/intermediate/` and the final documentation will normally appear in `./docs/build/html/`. Both of these directories can be overridden using environment variables. See documentation in `build.py` header comment for details. -If the list of document source files has changed (names or paths): +If the list of document source files (including the `.h` files in the `./src/` directory) has changed (names or paths): - python build.py clean html + python build.py clean -Will remove the old intermediate and build files and regenerate new ones matching the new structure, eliminating the orphan files that would otherwise result. +Will remove the old intermediate and build files, eliminating the orphan files that would otherwise result. To see a list of options available: python build.py -Read the header comment in `build.py` for detailed documentation of each option. +Read the header comment in `build.py` for detailed documentation on each option. + ## For Developers @@ -66,43 +46,35 @@ One of our firm policies is ***EVERYTHING MUST BE DOCUMENTED***. The below are some rules to follow when updating any of the `.rst` files located in the `./docs/src/` directory tree. -### What to Name Your `.rst` File -The directory structure under the `./docs/src/` directory, and the filenames of the `.rst` files govern the eventual URLs that are generated in the HTML output. These directories are organized so as to reflect the nature of the content. Example: the `.rst` files under `./docs/src/intro` contain introductory material—detailed reference material would not go there, but instead in an appropriate subdirectory of `./docs/src/details/`. It is expected that the content and location of any new documents added would be in alignment with this directory structure, and placed and named according to their content. Additionally, to be linked into the eventual generated documentation, the stem of the new filename needs to appear in at least one (normally *only one*) `.. toctree::` directive, normally in an `index.rst` file in the directory where it will appear in that page's table of contents (TOC). +## reStructuredText Content -Other than that, there are no restrictions on filenames. Previous linking of filenames to generated API links has been removed and replaced by a better scheme. For sake of illustration, let's say you are creating (or enhancing) documentation related to the `lv_scale_t` data type (one of the LVGL Widgets): if you want the doc-build logic to generate appropriate links to LVGL API pages, place an API section at the end of your document (it must be at the end) like this: +LVGL documentation uses **reStructuredText** (reST), rendered into HTML by Sphinx. You will find the following is a fairly-complete list of references about how to do things using reStructuredText: -```rst -API -*** -``` +| Docutils References (Fundamentals) | Sphinx References (What Sphinx Adds to Docutils) | +| --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | +| [Introduction](https://docutils.sourceforge.io/docs/ref/rst/introduction.html) | [Configuration](https://www.sphinx-doc.org/en/master/usage/configuration.html) | +| [Markup Specification](https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html) | [Directives](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html) | +| [Markup Specification ∙ Tables](https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#tables) | [Directives ∙ Admonitions](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#admonitions-messages-and-warnings) | +| [Markup Specification ∙ Substitution References](https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#substitution-references) | [Referencing](https://www.sphinx-doc.org/en/master/usage/referencing.html) | +| [Directives](https://docutils.sourceforge.io/docs/ref/rst/directives.html) | [Interpreted Text Roles](https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html) | +| [Interpreted Text Roles](https://docutils.sourceforge.io/docs/ref/rst/roles.html) | [Glossary](https://www.sphinx-doc.org/en/master/glossary.html) | +| [Quickstart](https://docutils.sourceforge.io/docs/user/rst/quickstart.html) | [Furo-theme Examples](https://sphinx-themes.org/sample-sites/furo/) | +| [Examples](https://docutils.sourceforge.io/docs/user/rst/demo.html) | [Kitchen Sink Page](https://sphinx-themes.org/sample-sites/furo/kitchen-sink/) | +| [Quick Reference](https://docutils.sourceforge.io/docs/user/rst/quickref.html) | [Sphinx Themes Gallery](https://sphinx-themes.org/) | -and then, if you want the API-link-generation logic to generate hyperlinks to API pages based on an ***exact, case-sensitive string match*** with specific C symbols, follow it with a reStructuredText comment using this syntax: +If you prefer to learn by examples, the [Furo-theme Examples](https://sphinx-themes.org/sample-sites/furo/) and especially the [Kitchen Sink Page](https://sphinx-themes.org/sample-sites/furo/kitchen-sink/) are excellent resources. View the `.rst` source file that generated that page by clicking the "eye" icon at the top of the page. -```rst -.. API equals: lv_scale_t, lv_scale_create -``` +Note: the section headings in these pages use a different convention than the one presented below. For LVGL documentation, use the [section-heading convention presented below](https://github.com/lvgl/lvgl/tree/master/docs#section-headings). -What follows the colon is a comma- or space-separated list of exact C symbols documented somewhere in the `lvgl/src/` directory. If the list is long, it can be wrapped to subsequent lines, though continuation lines must be all indented at the same level. The list ends with the first blank line after this pseudo-directive. - -If you instead want the API-link-generation logic to simply include links to code that ***starts with a specific string*** use this syntax instead. The format of the list is the same as for `.. API equals:`: - -```rst -.. API startswith: lv_scale, lv_obj_set_style -``` - -You can also manually link to API pages, in which case the API-link-generation logic will see that you have already added links and will not repeat them. - -```rst -:ref:`lv_scale_h` -``` - -Note that the period before the `h` is replaced with an underscore (`_`). The naming of this reference (`lv_scale_h`) will generate a hyperlink to the documentation extracted by Doxygen from the `lvgl/src/widgets/scale/lv_scale.h` file. ### Text Format -With `.md` files, it is important to allow paragraphs to flow off to the right with one long line so that when they are formatted as `.html` files, the paragraphs will word-wrap with the width of the browser. Thankfully, this liability is not present with reStructuredText (`.rst` files). [Sphinx](https://www.sphinx-doc.org/en/master/) and its underlying [docutils parsing engine](https://docutils.sourceforge.io/docs/) conveniently combine grouped text into a proper paragraph with that word-wrapping behavior. This allows the source text documents to be nicely word-wrapped so that they are more readable in text- and code-editors that do not have wide editing windows. So please wrap the text around column 86 or narrower. Wrapping at *exactly* column 86 is not important, but readability and ease of editing is. +Please wrap the text around column 86 or narrower. Wrapping at *exactly* column 86 is not important, but readability and ease of editing is. + +Indent using 4 spaces (not tab characters). This applies to code blocks as well. + ### index.rst Files @@ -111,7 +83,7 @@ If you create a new directory you will need an `index.rst` file in that director Let's take a look at the `index.rst` file that is located in the `docs/src/details/common-widget-features/layouts` directory. -``` +```rst .. _layouts: ======= @@ -122,14 +94,15 @@ Layouts .. toctree:: :maxdepth: 2 + overview flex grid ``` -The below explains the parts of this file. +Explanation: -``` +```rst .. _layouts: <=== Creates an explicit link target <=== Empty line -- important! ======= @@ -141,100 +114,67 @@ Layouts <=== Document title, seen in documentation .. toctree:: <=== Table of contents directive :maxdepth: 2 <=== Internal use and needs to always be set this way - flex <=== relative path to .rst files located in the same directory + overview <=== relative path to .rst files located in the same directory + flex grid ``` -The first line is for the purposes of providing a uniquely-named **link target** that can be referenced elsewhere in the documentation. - - .. _{LINK NAME}: - -Note that `{LINK NAME}`: - -- **must** be preceded by a single underscore, -- **must** be followed by a single colon, and -- **must** be followed by at least one blank line for the doc-generation logic to process it correctly. - -Replace `{LINK NAME}` with a link name that is unique among all documents under the `./docs/src/` directory. It can have multiple words if needed to make it unique or when otherwise appropriate for clarity. If multiple words are used, they can be separated with single spaces, hyphens or underscores. Whatever you use, the `{LINK NAME}` string used to reference it must be identical. `{LINK NAME}` strings are not case sensitive. - -That unique name is then used to provide a link reference elsewhere in the documentation using one of two formats. - - - -##### When the "link text" should be a title or section heading from the target document: - -```reStructuredText -:ref:`{LINK NAME}` -``` - -This in-line markup (interpreted text using the Sphinx-defined custom `:ref:` role) is then replaced with a hyperlink whose "link text" is the name of the section heading or document title just below the **link target**. For this reason, when using this syntax, `{LINK NAME}` must reference **link target**s that are just above a title or section heading. - - - -##### When "link text" should be something else: - -```reStructuredText -:ref:`other link text <{LINK NAME}>` -``` - -This latter syntax enables you to put a **link target** anywhere in an .RST file (not just above a heading) and link to it using this syntax. - -Note: This latter syntax was either added or fixed in Sphinx recently. It did not work in Sphinx 7.3.7. - - ### Section Headings -[Section headings](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#sections) are created by underlining the section title with a punctuation character, at least as long as the text. Example: +Section headings are created by underlining the section title with a punctuation character, at least as long as the text. Example: ``` This Is a Heading ***************** ``` -reStructuredText does not impose any particular heading levels assigned to certain characters since the structure is determined from the succession of headings. However, the LVGL docs policy is to use the below heading convention: +Use these conventions for section headings in LVGL documentation: ``` -===== -Title -===== - -Chapter -******* +============== +Document Title +============== Section -------- +******* Sub Section -~~~~~~~~~~~ +----------- Sub Sub Section -^^^^^^^^^^^^^^^ - -Sub Sub Sub Section -''''''''''''''''''' +~~~~~~~~~~~~~~~ ``` -Being consistent about this helps the Sphinx/docutils parser to format the tables of contents correctly. +1. ``====``, ``****``, ``----`` are encouraged. +2. ``~~~~`` only if really needed. -Note that the "underlining" can be longer than the heading title, but if it is shorter, the documentation-generation logic will fail with an error. +Being consistent about this helps the reST parser to format the tables of contents correctly. -For improved readability in the .RST file: +For improved readability in text editors: + +- place 3 blank lines above the 2nd and subsequent "Section" titles (see above), +- 2 blank lines above "Sub Section" headings, and +- 1 at least blank line above all lower-level section headings. + + + +### Italics, Boldface and Underlining + +Emphasis using `*italics*`. Emphasis using `**boldface**`. + +Normally underlining and combining these text styles is not possible in reStructuredText. However, LVGL documentation provides a work-around for this using reST Interpreted Text Roles. Just remember that the Interpreted Text Role names combine the letters `i`, `b` and `u` to provide the desired combination. All possible permutations of these letters are supported so you do not have to remember what sequence works. Examples: ``:u:`underline` ``, ``:ub:`underline and bold` ``, `` `:bi:bold italic` ``. -- place 3 blank lines above the 2nd and subsequent chapter titles (see above), and -- place 2 blank lines above section headings below chapters. ### Code Blocks -* Do not use tab characters in code blocks. -* Each indentation level use 4 spaces. +* Indent using 4 spaces (not tab characters). * Include at least 1 empty line after a code block. * There must be one empty line between the code block directive and the code. -* `.. code-block::` is the only directive that should be used. Note carefully that unlike the **link target** directive above, this directive has 2 colons. (The only reST and Sphinx directives that are valid with one colon are **link target**s as shown above.) Lone `::`, `:code:` or `.. code:` should not be used. -* If you want to separate code into easier-to-understand sections you can do so with a single empty line. -* For syntax highlighting appropriate to the language in the code block, specify the language after the directive. Some examples are: +* `.. code-block::` is the only directive that should be used. Do not use lone `::`, `:code:` or `.. code::`. +* Specify the language after the directive for appropriate syntax highlighting. Examples: - `.. code-block:: c`, - `.. code-block:: cpp`, @@ -244,48 +184,167 @@ For improved readability in the .RST file: - `.. code-block:: kconfig`, - `.. code-block:: json`, - `.. code-block:: yaml`, - - `.. code-block:: csharp` (or "cs"), - - `.. code-block:: vb.net`, - `.. code-block:: dot` (graphviz), - `.. code-block:: html`, - `.. code-block:: css`, - `.. code-block:: xml`, - `.. code-block:: make`. -The full set of supported lexers are listed in the [Pygments Library documentation](https://pygments.org/docs/lexers/). +See [the full set of supported code lexers](https://pygments.org/docs/lexers/) for more details. + ### Bulleted Lists -To create a bulleted list, do the following: +```rst +- First item description +- If you want to span multiple lines, indent subsequent + lines to align with item text like this. +- If you want to include multiple paragraphs and/or code blocks under a + list item, it must be intended to align with the list item like this: - - First item description - - If you want to span multiple lines, indent subsequent - lines to align with item text like this. - - If you want to include a code block under a list item, - it must be intended to align with the list item like this: - - .. code-block: python - <=== blank line here is important - # this is some code - <=== blank line here is important - - If you want to have nested bulleted lists, indent each - new level to align with its parent list item like this: - <=== blank line here is important - - level 2 item 1: text - - level 2 item 2: text - <=== blank line here is important - - Last list item. Note that the nested list above is preceded - and followed by 1 blank line. + Second paragraph. + + .. code-block: python + <=== blank line here is important + # Python code here + <=== blank line here is important +- If you want to have nested bulleted lists, indent each + new level to align with its parent list item like this: + <=== blank line here is important + - level 2 item 1: text + - level 2 item 2: text + <=== blank line here is important +- Last list item. Note that the nested list above is preceded + and followed by 1 blank line. +``` + +All lists (including nested lists) **must** be preceded and followed with at least 1 blank line for the reST parser to process it correctly. + + + +### External Links + +URLs are converted to links automatically. E.g. `Visit https://lvgl.io`. + +To add links with custom link text use + +```rst +Visit `My Website `__. +``` + +If an external link will be used on many pages: + +- Add it to `./docs/src/include/external_links.txt` if not already there. Example: + + ```rst + .. _LVGL Pro: https://pro.lvgl.io + ``` + +- `.. include: /include/external_links.txt` once at the top of each `.rst` file that uses it. + +- Use it by name in text: + + ```rst + For further details see `LVGL Pro`_. + ``` + + Note: back-quotes are not needed if there are no spaces in the name. + + + +### Internal Links + +Add a link target (anchor) before heading or paragraph that will be linked to: + +```rst +.. _unique_anchor_name: + +My Heading +********** +``` + +`unique_anchor_name` must be unique throughout all `.rst` files under `./docs/src/`. + +Reference the link (anchor) by: + +```rst +Click :ref:`here ` for more details. +``` + +Result: "Click **_here_** for more details." + +Or use the heading's text as the link's text: + +```rst +Click :ref:`unique_anchor_name` for more details. +``` + +Result: "Click **_My Heading_** for more details." + +`unique_anchor_name` may appear in places other than before a heading, but if so, custom link text (like "here" the first example above) must be provided. + + + +### Tightening Tables + +reStructuredText syntax for creating tables can be found in the [reST examples](https://sphinx-themes.org/sample-sites/furo/kitchen-sink/tables/) referred to above. (Click on the "eye" icon to see the source file.) + +Very long or very wide tables can be difficult to read and use. To squeeze them down to make them more readable and usable, move your existing table under a `.. container:: tighter-table-N` directive (`N` = digit 1-7 with 7 being the tightest), and indent your table to make it the "content" of the directive. Example: + +```rst +.. container:: tighter-table-3 + + +-----------+--------------+--------------+--------+ + | Heading 1 | Heading 2 | Heading 3 | Hdg 4 | + +===========+==============+==============+========+ + | row 1 c 1 | row 1 col 3 | row 1 col 3 | r1 c4 | + +-----------+--------------+--------------+--------+ + | row 2 c 1 | row 2 col 3 | row 2 col 3 | r2 c4 | + +-----------+--------------+--------------+--------+ + | row 3 c 1 | row 3 col 3 | row 3 col 3 | r3 c4 | + +-----------+--------------+--------------+--------+ +``` + +This works for all types of tables. + + + +### Special Symbols + +Because not everyone has editors that deal with Unicode characters well, please reST substitutions to insert special characters into documentation. A list of the most commonly-used special symbols can be found in `./docs/src/include/substitutions.txt`. To use one of these, add this line at the top of the `.rst` file if it is not already there: + +```rst +.. include:: /include/substitutions.txt +``` + +Then, any of those substitutions can be used in that `.rst` file. Example: + +```rst +The temperature outside is 20\ |deg|\ C. +``` + +Result: "The temperature outside is 20°C." + +The spaces surrounding substitutions *are required for parsing*, but when you need to remove them in the output (as in the example above), do so by escaping them with the `\` character. Exception: the `substitutions.txt` file contains 3 substitution definitions which are marked with the `:trim:` option since their use *always* removes these spaces in the output. These do not need this escaping: + +- `|nbsp|` (non-breaking space), +- `|shy|` (soft hyphen), and +- `|nbhyph|` (non-breaking hyphen used in titles and official names) + +If you need a substitution that is not already in `substitutions.txt`, please add it. -All lists (including nested lists) **must** be preceded and followed with at least 1 blank line. This is mandatory for the documentation-generation logic to process it correctly. ### Referencing API Documentation -If you want to reference portions of the LVGL code from the documentation (in .RST files) there are special directives to do this: +Using the following generates links to API documentation that the reader can click directly in the text. - :cpp:func:`lv_init` +#### In-Line Code Expressions + +Use the following Interpreted Text Roles in text to include in-line C code that links to documentation on that symbol when available: + + :cpp:func:`lv_init` (note there are no parentheses after the function name) :c:macro:`LV_USE_FLEX` :cpp:type:`lv_event_t` :cpp:enum:`lv_state_t` @@ -293,26 +352,49 @@ If you want to reference portions of the LVGL code from the documentation (in .R :cpp:struct:`lv_image_dsc_t` :cpp:union:`lv_style_value_t` -There is a special directive when wanting to use a more complex expression. For example when showing the arguments passed to a function. +#### More Complex Expressions + +Use the `:cpp:expr:` Interpreted Text Role for more complex expressions, for example when showing the arguments passed to a function. :cpp:expr:`lv_obj_set_layout(widget, LV_LAYOUT_FLEX)` :cpp:expr:`lv_slider_set_mode(slider, LV_SLIDER_MODE_...)` -Arguments that are expressions (more than one word), or contain non-alphanumeric characters will cause the `:cpp:expr:` interpreted-text to fail. Examples: +Arguments that contain more than one word or non-alphanumeric characters will cause the `:cpp:expr:` interpreted-text to fail. Examples: - :cpp:expr:`lv_obj_set_layout(widget, LV_LAYOUT_FLEX/GRID)` <== arg with > 1 word - :cpp:expr:`lv_obj_set_layout(widget, LV_LAYOUT_*)` <== asterisk - :cpp:expr:`lv_obj_set_layout(*widget, LV_LAYOUT_FLEX)` <== asterisk - :cpp:expr:`lv_obj_set_layout((lv_obj_t *)widget, LV_LAYOUT_FLEX)` <== cast - :cpp:expr:`lv_obj_set_layout(&widget, LV_LAYOUT_FLEX);` <== ampersand & semicolon - :cpp:expr:`lv_obj_set_layout(widget, ...)` <== lone ellipsis +| Expression | Cause of Failure | +| ------------------------------------------------------------ | ---------------------- | +| :cpp:expr:\`lv_obj_set_layout(widget, LV_LAYOUT_FLEX/GRID)\` | argument with > 1 word | +| :cpp:expr:\`lv_obj_set_layout(widget, LV_LAYOUT_*)\` | asterisk | +| :cpp:expr:\`lv_obj_set_layout(*widget, LV_LAYOUT_FLEX)\` | asterisk | +| :cpp:expr:\`lv_obj_set_layout((lv_obj_t *)widget, LV_LAYOUT_FLEX)\` | cast | +| :cpp:expr:\`lv_obj_set_layout(&widget, LV_LAYOUT_FLEX);\` | semicolon | +| :cpp:expr:\`lv_obj_set_layout(widget, ...)\` | lone ellipsis | For such examples, simply use reStructuredText literal markup like this: - ``lv_obj_set_layout(widget, LV_LAYOUT_FLEX/GRID)`` - ``lv_obj_set_layout(widget, LV_LAYOUT_*)`` - ``lv_obj_set_layout(*widget, LV_LAYOUT_FLEX)`` - ``lv_obj_set_layout((lv_obj_t *)widget, LV_LAYOUT_FLEX)`` - ``lv_obj_set_layout(&widget, LV_LAYOUT_FLEX);`` - ``lv_obj_set_layout(widget, ...)`` +```rst +``lv_obj_set_layout(widget, LV_LAYOUT_FLEX/GRID)`` +``lv_obj_set_layout(widget, LV_LAYOUT_*)`` +``lv_obj_set_layout(*widget, LV_LAYOUT_FLEX)`` +``lv_obj_set_layout((lv_obj_t *)widget, LV_LAYOUT_FLEX)`` +``lv_obj_set_layout(&widget, LV_LAYOUT_FLEX);`` +``lv_obj_set_layout(widget, ...)`` +``` +#### Providing Links to API Pages + +To create a link to 1 or more API pages, set up a section at the end of your `.rst` file that looks like this, and use one or both types of the ``.. API `` pseudo-directives below: + +```rst +API +*** + +.. API equals: lv_scale_t, lv_scale_create + +.. API startswith: lv_scale, lv_obj_set_style + +``` + +The list of symbols (or prefixes) can be separated by commas or spaces, and they can wrap onto subsequent lines of text so long as they are indented. A blank line after each list ends that list. + +The API-page generation logic will add at most 1 link to each API documentation page containing matched symbols. The links are to the whole API page, not to the symbols. The purpose is to provide the reader with links to applicable API pages. Links directly to code (e.g. function documentation) are accomplished by using the In-Line Code Expressions documented above. diff --git a/docs/src/details/common-widget-features/coordinates.rst b/docs/src/details/common-widget-features/coordinates.rst index cbb396ee5f..b41fddffba 100644 --- a/docs/src/details/common-widget-features/coordinates.rst +++ b/docs/src/details/common-widget-features/coordinates.rst @@ -79,10 +79,10 @@ widgets are marked as "dirty." LVGL recalculates dirty widgets’ positions, siz and layouts just before redrawing the screen. So, if you change a widget’s position or size and then immediately read it, call -:cpp:func:`lv_obj_update_layout()` first to ensure the values are up to date. +:cpp:func:`lv_obj_update_layout` first to ensure the values are up to date. Note: Since layout and size may depend on the parent, -:cpp:func:`lv_obj_update_layout()` recalculates coordinates for **all** widgets on +:cpp:func:`lv_obj_update_layout` recalculates coordinates for **all** widgets on the screen of the given object. diff --git a/docs/src/details/common-widget-features/screens.rst b/docs/src/details/common-widget-features/screens.rst index 0e3e4b55c5..d26f40490f 100644 --- a/docs/src/details/common-widget-features/screens.rst +++ b/docs/src/details/common-widget-features/screens.rst @@ -26,7 +26,7 @@ Screens are created on the :ref:`Default display `. As typicall there is only one displays the screen are created on them automatically. The resolution of the screen always matches the resolution of the display. Functions -such as :cpp:func:`lv_obj_set_pos()` and :cpp:func:`lv_obj_set_size()` cannot be used +such as :cpp:func:`lv_obj_set_pos` and :cpp:func:`lv_obj_set_size` cannot be used on screens. The created Screens can be deleted with :cpp:expr:`lv_obj_delete(scr)`, but be sure diff --git a/docs/src/details/debugging/monkey.rst b/docs/src/details/debugging/monkey.rst index 1b86993eb0..49a9a2dbd9 100644 --- a/docs/src/details/debugging/monkey.rst +++ b/docs/src/details/debugging/monkey.rst @@ -19,7 +19,7 @@ Usage First, enable :c:macro:`LV_USE_MONKEY` in ``lv_conf.h``. -Next, declare a variable (it can be local) of type :c:type:`lv_monkey_config_t` to +Next, declare a variable (it can be local) of type :cpp:type:`lv_monkey_config_t` to define the configuration structure, initialize it using :cpp:expr:`lv_monkey_config_init(cfg)` then set its ``type`` member to the desired type of :ref:`input device `, and set the ``min`` and ``max`` values for its @@ -60,3 +60,4 @@ Example API *** +.. API equals: lv_monkey_create diff --git a/docs/src/details/debugging/obj_id.rst b/docs/src/details/debugging/obj_id.rst index 00d19fc85a..c043fc6397 100644 --- a/docs/src/details/debugging/obj_id.rst +++ b/docs/src/details/debugging/obj_id.rst @@ -60,7 +60,7 @@ other things, depending on the implementation. This function (whether provided by LVGL or by you --- more on this below) is responsible for doing the clean-up of any resources allocated by -:cpp:func:`lv_obj_assign_id()` +:cpp:func:`lv_obj_assign_id` :c:macro:`LV_USE_OBJ_ID_BUILTIN` diff --git a/docs/src/details/integration/chip_vendors/nxp/overview.rst b/docs/src/details/integration/chip_vendors/nxp/overview.rst index 92b6ea9d47..48606bfd34 100644 --- a/docs/src/details/integration/chip_vendors/nxp/overview.rst +++ b/docs/src/details/integration/chip_vendors/nxp/overview.rst @@ -58,7 +58,7 @@ Basic configuration: Basic initialization: ^^^^^^^^^^^^^^^^^^^^^ -PXP draw initialization is done automatically in :cpp:func:`lv_init()` once the +PXP draw initialization is done automatically in :cpp:func:`lv_init` once the PXP is enabled as a draw unit or to rotate the screen, no user code is required: .. code-block:: c @@ -192,16 +192,16 @@ PXP default configuration: - Implementation depends on multiple OS-specific functions. The struct :cpp:struct:`pxp_cfg_t` with callback pointers is used as a parameter for the - :cpp:func:`lv_pxp_init()` function. Default implementation for + :cpp:func:`lv_pxp_init` function. Default implementation for FreeRTOS in lv_pxp_osa.c. - - :cpp:func:`pxp_interrupt_init()`: Initialize PXP interrupt (HW setup, + - :cpp:func:`pxp_interrupt_init`: Initialize PXP interrupt (HW setup, OS setup) - - :cpp:func:`pxp_interrupt_deinit()`: Deinitialize PXP interrupt (HW setup, + - :cpp:func:`pxp_interrupt_deinit`: Deinitialize PXP interrupt (HW setup, OS setup) - - :cpp:func:`pxp_run()`: Start PXP job. Use OS-specific mechanism to block + - :cpp:func:`pxp_run`: Start PXP job. Use OS-specific mechanism to block drawing thread. - - :cpp:func:`pxp_wait()`: Wait for PXP completion. + - :cpp:func:`pxp_wait`: Wait for PXP completion. VGLite accelerator @@ -229,7 +229,7 @@ Basic configuration: Basic initialization: ^^^^^^^^^^^^^^^^^^^^^ -Initialize VGLite GPU before calling :cpp:func:`lv_init()` by specifying the +Initialize VGLite GPU before calling :cpp:func:`lv_init` by specifying the width/height of tessellation window. The default values for tessellation width and height, and command buffer size are in the SDK file "vglite_support.h". @@ -258,7 +258,7 @@ and height, and command buffer size are in the SDK file "vglite_support.h". } #endif -VGLite draw initialization is done automatically in :cpp:func:`lv_init()` once +VGLite draw initialization is done automatically in :cpp:func:`lv_init` once the VGLite is enabled, no user code is required: .. code-block:: c @@ -433,7 +433,7 @@ Basic configuration: Basic initialization: ^^^^^^^^^^^^^^^^^^^^^ -G2D draw initialization is done automatically in :cpp:func:`lv_init()` once the +G2D draw initialization is done automatically in :cpp:func:`lv_init` once the G2D is enabled as a draw unit , no user code is required: .. code:: c diff --git a/docs/src/details/integration/overview/connecting_lvgl.rst b/docs/src/details/integration/overview/connecting_lvgl.rst index fedb4c20d6..48ff9bbb9f 100644 --- a/docs/src/details/integration/overview/connecting_lvgl.rst +++ b/docs/src/details/integration/overview/connecting_lvgl.rst @@ -110,7 +110,7 @@ Reliability Advancing the tick value should be done in such a way that its timing is reliable and not dependent on anything that consumes an unknown amount of time. For an example of what *not* to do: this can "seem" to work, but LVGL's timing will be incorrect -because the execution time of :c:func:`lv_timer_handler` varies from call to call and +because the execution time of :cpp:func:`lv_timer_handler` varies from call to call and thus the delay it introduces cannot be known. .. code-block:: c diff --git a/docs/src/details/integration/overview/timer_handler.rst b/docs/src/details/integration/overview/timer_handler.rst index b053bb35ee..cf3795e5a9 100644 --- a/docs/src/details/integration/overview/timer_handler.rst +++ b/docs/src/details/integration/overview/timer_handler.rst @@ -66,7 +66,7 @@ See :ref:`timer` section to learn more about timers. When No Timers Are Ready ************************ -:c:func:`lv_timer_handler` will return :c:macro:`LV_NO_TIMER_READY` (``UINT32_MAX``) +:cpp:func:`lv_timer_handler` will return :c:macro:`LV_NO_TIMER_READY` (``UINT32_MAX``) if there are no running timers. This can happen if there are no indevs or they are disabled with `lv_indev_enable()`, running animations, or running user-created timers. :cpp:func:`lv_timer_handler` will continue to return :c:macro:`LV_NO_TIMER_READY` until there is a running timer. Display @@ -99,7 +99,7 @@ If there is no external event source, you may choose to exit the loop or simply delay for a long time. If another :ref:`thread ` is -calling LVGL functions, you may want to call :c:func:`lv_timer_handler` again +calling LVGL functions, you may want to call :cpp:func:`lv_timer_handler` again very soon to handle the effects of those other threads. diff --git a/docs/src/details/libs/font_support/tiny_ttf.rst b/docs/src/details/libs/font_support/tiny_ttf.rst index a967f4ebe5..12c910d0c4 100644 --- a/docs/src/details/libs/font_support/tiny_ttf.rst +++ b/docs/src/details/libs/font_support/tiny_ttf.rst @@ -19,7 +19,7 @@ Usage When enabled in ``lv_conf.h`` by setting :c:macro:`LV_USE_TINY_TTF` to ``1``, :cpp:expr:`lv_tiny_ttf_create_data(data, data_size, font_size)` can be used to create a TTF font instance with the specified line height. You can then -use that font anywhere :c:struct:`lv_font_t` is accepted. +use that font anywhere :cpp:struct:`lv_font_t` is accepted. By default, the TTF or OTF file must be embedded as an array, either in a header, or loaded into RAM in order to function. diff --git a/docs/src/details/libs/image_support/bmp.rst b/docs/src/details/libs/image_support/bmp.rst index 6396ef1c87..35982000fc 100644 --- a/docs/src/details/libs/image_support/bmp.rst +++ b/docs/src/details/libs/image_support/bmp.rst @@ -30,7 +30,7 @@ Limitations *********** - Only BMP files are supported. BMP images as C arrays - (:c:struct:`lv_image_dsc_t`) are not. This is because there is no practical + (:cpp:struct:`lv_image_dsc_t`) are not. This is because there is no practical differences between how the BMP files and LVGL's image format stores the image data. - BMP files can be loaded only from .BMP files. If you want to store them in diff --git a/docs/src/details/libs/image_support/gif.rst b/docs/src/details/libs/image_support/gif.rst index 4e9a79a7b9..494adc5112 100644 --- a/docs/src/details/libs/image_support/gif.rst +++ b/docs/src/details/libs/image_support/gif.rst @@ -35,7 +35,7 @@ The supported color formats are: - :cpp:enumerator:`LV_COLOR_FORMAT_ARGB8888` :cpp:expr:`lv_gif_set_src(widget, src)` works very similarly to :cpp:func:`lv_image_set_src`. -As source, it also accepts images as variables (:c:struct:`lv_image_dsc_t`) or files. +As source, it also accepts images as variables (:cpp:struct:`lv_image_dsc_t`) or files. Converting GIF Files to C Arrays diff --git a/docs/src/details/libs/image_support/rlottie.rst b/docs/src/details/libs/image_support/rlottie.rst index feab6b86b7..5331293ca9 100644 --- a/docs/src/details/libs/image_support/rlottie.rst +++ b/docs/src/details/libs/image_support/rlottie.rst @@ -138,7 +138,7 @@ If you don't enable looping, a :cpp:enumerator:`LV_EVENT_READY` is sent when the animation cannot make more progress without looping. To get the number of frames in an animation or the current frame index, -you can cast the :c:struct:`lv_obj_t` instance to a :c:struct:`lv_rlottie_t` instance +you can cast the :cpp:struct:`lv_obj_t` instance to a :cpp:struct:`lv_rlottie_t` instance and inspect the ``current_frame`` and ``total_frames`` members. diff --git a/docs/src/details/main-modules/indev/overview.rst b/docs/src/details/main-modules/indev/overview.rst index 45b8dc9475..3285684a70 100644 --- a/docs/src/details/main-modules/indev/overview.rst +++ b/docs/src/details/main-modules/indev/overview.rst @@ -75,7 +75,7 @@ read and it should call ``read_cb`` again. If the driver can provide precise timestamps for buffered events, it can overwrite ``data->timestamp``. By default, this is initialized to -:cpp:func:`lv_tick_get()` just before invoking ``read_cb``. +:cpp:func:`lv_tick_get` just before invoking ``read_cb``. .. _indev event mode: diff --git a/docs/src/details/widgets/label.rst b/docs/src/details/widgets/label.rst index 04ee16dd2b..57650dacc5 100644 --- a/docs/src/details/widgets/label.rst +++ b/docs/src/details/widgets/label.rst @@ -56,7 +56,7 @@ they are stored in ROM memory, which is always accessible. .. warning:: Do not use ``const`` strings with :cpp:func:`lv_label_set_text_static` when the - Label is being used in :cpp:enumerator:`LV_LABEL_LONG_DOT` mode since the Label + Label is being used in :cpp:enumerator:`LV_LABEL_LONG_MODE_DOTS` mode since the Label will attempt to do an in-place edit of the string. This will cause an MCU exception by attempting to modify program memory (ROM). @@ -117,13 +117,13 @@ of the text is greater than the height of the Label. You can specify the long mode with :cpp:expr:`lv_label_set_long_mode(label, LV_LABEL_LONG_...)` -Note that :cpp:enumerator:`LV_LABEL_LONG_DOT` manipulates the text buffer in-place in +Note that :cpp:enumerator:`LV_LABEL_LONG_MODE_DOTS` manipulates the text buffer in-place in order to add/remove the dots. When :cpp:func:`lv_label_set_text` or :cpp:func:`lv_label_set_array_text` are used, a separate buffer is allocated and this implementation detail is unnoticed. This is not the case with :cpp:func:`lv_label_set_text_static`. The buffer you pass to :cpp:func:`lv_label_set_text_static` must be writable if you plan to use -:cpp:enumerator:`LV_LABEL_LONG_DOT`. +:cpp:enumerator:`LV_LABEL_LONG_MODE_DOTS`. .. _lv_label_text_recolor: diff --git a/docs/src/details/widgets/win.rst b/docs/src/details/widgets/win.rst index 67db7735c0..3d1708762d 100644 --- a/docs/src/details/widgets/win.rst +++ b/docs/src/details/widgets/win.rst @@ -64,7 +64,7 @@ will be placed in the Header in left-to-right order as they are added. These functions can be called in any order, any number of times. - :cpp:expr:`lv_win_add_title(win, "The title")` adds a Label to the header, with - long mode :c:enumerator:`LV_LABEL_LONG_DOT` so that if its text contents are wider + long mode :cpp:enumerator:`LV_LABEL_LONG_MODE_DOTS` so that if its text contents are wider than the area it has, the text will be truncated with an ellipsis ("...") placed at the end of the text. It is set to be FLEX GROW 1, so if it is the only Label in the header, it will occupy all available space after any Buttons are added.