sdk_lib_nbgl: pure commit from SDK master

sdk_lib_nbgl/README.md

@@ -0,0 +1,2 @@
+# NBGL library
+Graphic library for Stax

sdk_lib_nbgl/doc/mainpage.dox

@@ -0,0 +1,61 @@
+#ifdef HAVE_SE_TOUCH
+/** @page nbgl_mainpage New BOLOS Graphic API for Stax
+
+@section mainpage_intro Introduction
+
+This documentation describes the different interfaces of <b>NBGL</b>, the library that
+is targeted to be integrated in Stax product.
+
+<b>NBGL Engine</b> is responsible for constructing screens and handling Touchscreen input.
+
+@section mainpage_overall_archi Overall architecture
+
+<b>NBGL Engine</b> is a library to be integrated in SDK.
+It is intended to replace existing BAGL/FLOW Graphical Engine (used on Nanos/Blue products)
+
+\image{inline} html NBGLArchi.png "caption" height=600
+
+@section nbgl_drawing_api Screen drawing APIs
+
+@subsection nbgl_app_use_case_api_1 Application Use-cases API
+This is the most preferred API level to write an embedded Application.
+
+The @subpage nbgl_app_use_case page contains all information necessary to understand
+and use \b NBGL Application Use cases API
+
+@subsection nbgl_high_level_api_1 High-Level API
+The @subpage nbgl_page page contains all information necessary to understand
+and use \b NBGL High-Level API, using predefined pages
+
+@subsection nbgl_mid_level_api_1 Mid-Level API
+The @subpage nbgl_layout page contains all information necessary to understand
+and use \b NBGL Mid-Level API, using complex objects
+
+@subsection nbgl_low_level_api_1 Low-Level API
+The @subpage nbgl_obj page contains all information necessary to understand
+and use \b NBGL Low-Level API
+
+@section nbgl_screen_objs Screen and objects management
+The @subpage nbgl_screens_and_objs page contains all information necessary to understand
+how \b NBGL manages the screens stack and the dynamically allocated objects
+
+@section nbgl_touch_api Touchscreen events management
+The @subpage nbgl_touchscreen page contains all information necessary to understand
+how \b NBGL manages the touchscreen events and how to receive and process these events.
+
+@section nbgl_building Compilation options
+In order to reduce the footprint (RAM+Flash), some features are only activated if some building options are defined.
+
+Define        | Meaning       | Default state
+------------- | ------------- | -------------
+\b NBGL_PAGE     | Activate High-Level API  | Active in SDK, not in OS
+\b NBGL_USE_CASE | Activate Use Case API    | Active in SDK, not in OS
+\b NBGL_KEYBOARD | Activate Keyboard object | Active in OS, not in SDK
+\b NBGL_KEYPAD   | Activate Keypad object   | Active in OS, not in SDK
+\b NBGL_QRCODE   | Activate QRCode object   | Active in OS, not in SDK
+
+Applications are free to define \b NBGL_KEYBOARD, \b NBGL_KEYPAD or \b NBGL_QRCODE in their own Makefile if they need to use these
+"rare" objects.
+
+*/
+#endif // HAVE_SE_TOUCH

sdk_lib_nbgl/doc/mainpage_nanos.dox

@@ -0,0 +1,60 @@
+#ifndef HAVE_SE_TOUCH
+/** @page nbgl_mainpage New BOLOS Graphic API for Nanos
+
+@section mainpage_intro Introduction
+
+This documentation describes the different interfaces of <b>NBGL</b>, the library that
+is targeted to be integrated in Nano products (Nano X and Nano S+).
+
+<b>NBGL Engine</b> is responsible for constructing screens and handling Buttons input.
+
+@section mainpage_overall_archi Overall architecture
+
+<b>NBGL Engine</b> is a library to be integrated in SDK.
+It is intended to replace existing BAGL/FLOW Graphical Engine (used on Nano S product)
+
+\image{inline} html NBGLArchi.png "caption" height=600
+
+@section nbgl_drawing_api Screen drawing APIs
+
+@subsection nbgl_app_use_case_api_1 Application Use-cases API
+This is the most preferred API level to write an embedded Application.
+
+The @subpage nbgl_app_use_case_nanos page contains all information necessary to understand
+and use \b NBGL Application Use cases API
+
+@subsection nbgl_flow_level_api_1 Flow API
+The @subpage nbgl_flow page contains all information necessary to understand
+and use \b NBGL Flow API, managing a scenario flow, made of one or several steps
+
+@subsection nbgl_step_level_api_1 Step API
+The @subpage nbgl_step page contains all information necessary to understand
+and use \b NBGL Step API, managing the page(s) of a scenario step
+
+@subsection nbgl_mid_level_api_1 Complex objects (layout) API
+The @subpage nbgl_layout page contains all information necessary to understand
+and use \b NBGL Mid-Level API, using complex objects
+
+@subsection nbgl_low_level_api_1 Low-Level API
+The @subpage nbgl_obj page contains all information necessary to understand
+and use \b NBGL Low-Level API
+
+@section nbgl_screen_objs Screen and objects management
+The @subpage nbgl_screens_and_objs page contains all information necessary to understand
+how \b NBGL manages the screens stack and the dynamically allocated objects
+
+@section nbgl_building Compilation options
+In order to reduce the footprint (RAM+Flash), some features are only activated if some building options are defined.
+
+Define        | Meaning       | Default state
+------------- | ------------- | -------------
+\b NBGL_USE_CASE | Activate Use Case API    | Active in SDK, not in OS
+\b NBGL_KEYBOARD | Activate Keyboard object | Active in OS, not in SDK
+\b NBGL_KEYPAD   | Activate Keypad object   | Active in OS, not in SDK
+\b NBGL_QRCODE   | Activate QRCode object   | Active in OS, not in SDK
+
+Applications are free to define \b NBGL_KEYBOARD, \b NBGL_KEYPAD or \b NBGL_QRCODE in their own Makefile if they need to use these
+"rare" objects.
+
+*/
+#endif // HAVE_SE_TOUCH

sdk_lib_nbgl/doc/nbgl_api.dox

@@ -0,0 +1,170 @@
+/** @page nbgl_obj Advanced BOLOS GL API
+
+@section nbgl_api_intro Introduction
+This chapter describes briefly the main interface functions of NBGL Graphical Engine. A
+full description of each function can be found in this document
+
+@section concepts Concepts
+In this section, we provide information on how to use NBGL API
+
+@subsection obj_hierarchy Graphic objects hierarchy
+
+@startuml
+
+title Graphic objects types hierarchy
+
+abstract nbgl_obj_t
+nbgl_obj_t <|-- nbgl_container_t
+nbgl_obj_t <|-- nbgl_text_area_t
+nbgl_obj_t <|-- nbgl_button_t
+nbgl_obj_t <|-- nbgl_switch_t
+nbgl_obj_t <|-- nbgl_progress_bar_t
+nbgl_obj_t <|-- nbgl_page_indicator_t
+nbgl_obj_t <|-- nbgl_image_t
+
+@enduml
+
+@startuml
+
+title Graphic objects composition
+
+SCREEN o-- OBJECTS
+SCREEN o-- CONTAINER
+CONTAINER o-- OBJECTS
+
+@enduml
+
+@subsection create_objects Creating graphic objects
+
+Graphic objects cannot be created dynamically so they must be statically declared.
+
+There must be at least as many declared objects as objects presented on a given screen. But objects can be reused in another
+screen, as long as they are properly set.
+
+For example, if a "Back" button is present in many different screens of the application, it can be reused, the only change being
+the touch callback.
+
+For all objects, its **type** field must be explicitly specified, even if it seems redundant with the nbgl_<type>_t.
+
+For example:
+
+@code
+    nbgl_button_t backButton = {
+        .type = BUTTON,                           // Type of object, MANDATORY
+        .innerColor = WHITE,                      // Color used inside of the button, MANDATORY
+        .borderColor = LIGHT_GRAY,                // Color used for border, MANDATORY
+        .foregroundColor = BLACK,                 // Color used for text and/or icon, MANDATORY
+        .width = 128,                             // Width in pixels, MANDATORY
+        .height = 64,                             // Height in pixels, MANDATORY
+        .radius = 32,                             // Radius of corners in pixels, can be null
+        .text = "Back",                           // Text of the button, if NULL, only an icon
+        .fontId = BAGL_FONT_INTER_REGULAR_24,     // Font used for text, if text is not null
+        .icon = &C_leftArrow32px,                 // Icon of the button, if NULL, only text
+        .alignmentMarginX = 20,                   // Horizontal margin (see layout & alignment)
+        .alignmentMarginY = 20,                   // Vertical margin (see layout & alignment)
+        .alignment = TOP_LEFT,                    // Type of alignment (see layout & alignment)
+        .alignTo = NULL,                          // Alignment reference, if NULL, use parent (see layout & alignment)
+        .touchMask = (1<<VALUE_CHANGED)           // Types of touchscreen events that we want to receive
+        };
+@endcode
+
+For some types of objects (@ref CONTAINER), the **children** field must be set with an
+array of pointers on @ref nbgl_obj_t, which are all the objects contained in these containers.
+
+Once all your objects are defined, they shall be added as children of the main (and unique) @ref SCREEN object, which is
+a special container, thanks to @ref nbgl_screenSet() or @ref nbgl_screenPush().
+
+For example, with a static allocation of objects (not recommended, see @ref nbgl_objs_mngt):
+
+@code
+    nbgl_button_t backButton = {
+        .type = BUTTON
+        /*....*/
+    };
+    nbgl_text_area_t text1 = {
+        .type = TEXT_AREA
+        /*....*/
+    };
+    nbgl_text_area_t text2 = {
+        .type = TEXT_AREA
+        /*....*/
+    };
+    nbgl_obj_t* containerChildren[] = {
+        (nbgl_obj_t*)&text1,
+        (nbgl_obj_t*)&text2
+    };
+    // container containing 2 text areas
+    nbgl_container_t container = {
+        .type = CONTAINER,
+        .children = containerChildren,
+        .nbChildren = 2
+        /*....*/
+    };
+    // allocate screen 0 for 2 children
+    nbgl_screenSet(&screenChildren, 2, NULL, &touchCallback);
+    // set children of screen
+    screenChildren[0] = (nbgl_obj_t*)&backButton;
+    screenChildren[1] = (nbgl_obj_t*)&container;
+
+@endcode
+
+The same example with dynamic  allocation of objects:
+
+@code
+    /* layer 0 is used (background)
+    uint8_t layer = 0;
+
+    /* allocate layer 0 for 2 children (it also releases any objects/containers allocated previously in layer 0) */
+    nbgl_screenSet(&screenChildren, 2, NULL, &touchCallback);
+
+    /* allocate backButton dynamically */
+    nbgl_button_t *backButton = nbgl_objPoolGet(BUTTON, layer);
+    /* configure backButton properties here */
+
+    /* allocate text1 dynamically */
+    nbgl_text_area_t *text1 = (nbgl_text_area_t*)nbgl_objPoolGet(TEXT_AREA, layer);
+    /* configure text1 properties here */
+
+    /* allocate text2 dynamically */
+    nbgl_text_area_t *text2 = (nbgl_text_area_t*)nbgl_objPoolGet(TEXT_AREA, layer);
+    /* configure text2 properties here */
+
+    /* allocate container object dynamically */
+    nbgl_container_t *container = (nbgl_container_t*)nbgl_objPoolGet(CONTAINER, layer);
+    /* configure container properties here */
+    container->nbChildren = 2;
+    container->children = (nbgl_obj_t**)nbgl_containerPoolGet(container->nbChildren, layer);
+
+    /* set text areas as children of container */
+    container->children[0] = (nbgl_obj_t*)&text1;
+    container->children[1] = (nbgl_obj_t*)&text2;
+
+    /* set backButton and container as children of screen */
+    screenChildren[0] = (nbgl_obj_t*)backButton;
+    screenChildren[1] = (nbgl_obj_t*)container;
+
+@endcode
+
+@subsection draw_objects Drawing graphic objects
+
+Once defined and set as children (or sub-children) of the main @ref SCREEN, all objects can be drawn in **framebuffer**
+with a simple call to @ref nbgl_screenRedraw().
+
+But if only a given object has been modified since the last redraw, for example by changing its text or its color, it can be redrawn
+(with all of its children and sub-children, if any) with a call to @ref nbgl_redrawObject().
+
+The only properties that should not have changed for this object are its dimensions and position.
+
+Except in some specific cases, the previousObj parameter of @ref nbgl_redrawObject() can be set to NULL and computeDimensions set to false.
+
+@subsection refresh Refreshing screen
+
+After having drawn graphic objects in **framebuffer**, it is necessary to transfer the content of the **framebuffer** on display.
+This operation is called a refresh.
+
+The API to do that is @ref nbgl_refresh().
+
+It will only refresh the rectangle part of the screen having changed (with any object redrawn) since the last refresh.
+
+
+*/