From 9af341502c1cdf1d40a41e8fe6c3922f1e409f33 Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Thu, 1 Jun 2023 10:22:47 -0600 Subject: expo: Allow setting the start of the dynamic-ID range Provide a way to set this value so that it is easy to separate the statically allocated IDs (generated by the caller) from those generated dynamically by expo itself. Signed-off-by: Simon Glass --- doc/develop/expo.rst | 3 +++ 1 file changed, 3 insertions(+) (limited to 'doc/develop') diff --git a/doc/develop/expo.rst b/doc/develop/expo.rst index 32dd7f09030..9565974a28e 100644 --- a/doc/develop/expo.rst +++ b/doc/develop/expo.rst @@ -85,6 +85,9 @@ or even the IDs of objects. Programmatic creation of many items in a loop can be handled by allocating space in the enum for a maximum number of items, then adding the loop count to the enum values to obtain unique IDs. +Where dynamic IDs are need, use expo_set_dynamic_start() to set the start value, +so that they are allocated above the starting (enum) IDs. + All text strings are stored in a structure attached to the expo, referenced by a text ID. This makes it easier at some point to implement multiple languages or to support Unicode strings. -- cgit v1.2.3 From 699b0acb522fd808b67b745b541bacf18c275d15 Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Thu, 1 Jun 2023 10:22:52 -0600 Subject: expo: Set up the width and height of objects Provide a way to set the full dimensions of objects, i.e. including the width and height. For menus, calculate the bounding box of all objects in the menu. Set all labels to be the same size, so that highlighting works correct, once implemented. Signed-off-by: Simon Glass --- doc/develop/expo.rst | 2 -- 1 file changed, 2 deletions(-) (limited to 'doc/develop') diff --git a/doc/develop/expo.rst b/doc/develop/expo.rst index 9565974a28e..54861b93acf 100644 --- a/doc/develop/expo.rst +++ b/doc/develop/expo.rst @@ -182,8 +182,6 @@ Some ideas for future work: - Add a Kconfig option to drop the names to save code / data space - Add a Kconfig option to disable vidconsole support to save code / data space - Support both graphical and text menus at the same time on different devices -- Implement proper measurement of object bounding boxes, to permit more exact - layout. This would tidy up the layout when Truetype is not used - Support unicode - Support curses for proper serial-terminal menus -- cgit v1.2.3 From 2e59389704cd1e46101f7ffda2dac3f44f2fa332 Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Thu, 1 Jun 2023 10:22:53 -0600 Subject: expo: Support simple themes It is a pain to manually set the fonts of all objects to be consistent. Some spacing settings are also better set globally than by manually positioning each object. Add a 'theme' to the expo, to hold this information. For now it includes only the font size. Signed-off-by: Simon Glass --- doc/develop/expo.rst | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) (limited to 'doc/develop') diff --git a/doc/develop/expo.rst b/doc/develop/expo.rst index 54861b93acf..2f4882899b6 100644 --- a/doc/develop/expo.rst +++ b/doc/develop/expo.rst @@ -155,8 +155,13 @@ such as scanning devices for more bootflows. Themes ------ -Expo does not itself support themes. The bootflow_menu implement supposed a -basic theme, applying font sizes to the various text objects in the expo. +Expo supports simple themes, for setting the font size, for example. Use the +expo_apply_theme() function to load a theme, passing a node with the required +properties: + +font-size + Font size to use for all text (type: u32) + API documentation ----------------- -- cgit v1.2.3 From 4e64beeba7de7720b42714cbc542c9f7dfbba841 Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Thu, 1 Jun 2023 10:22:59 -0600 Subject: expo: Implement the keypress logic for popup menus In 'popup' mode, the expo allows moving around the objects in a scene. When 'enter' is pressed on a menu, it opens and the user can move around the items in the menu. Implement this using keypress handles and actions. Signed-off-by: Simon Glass --- doc/develop/expo.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) (limited to 'doc/develop') diff --git a/doc/develop/expo.rst b/doc/develop/expo.rst index 2f4882899b6..80e435c5e65 100644 --- a/doc/develop/expo.rst +++ b/doc/develop/expo.rst @@ -178,8 +178,7 @@ Some ideas for future work: - Image formats other than BMP - Use of ANSI sequences to control a serial terminal - Colour selection -- Better support for handling lots of settings, e.g. with multiple menus and - radio/option widgets +- Better support for handling lots of settings, e.g. with radio/option widgets - Mouse support - Integrate Nuklear, NxWidgets or some other library for a richer UI - Optimise rendering by only updating the display with changes since last render -- cgit v1.2.3 From 7230fdb3837ad745adff4cf129dd04e893fe0a36 Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Thu, 1 Jun 2023 10:23:00 -0600 Subject: expo: Add spacing around menus and items It looks better if menus have a bit of an inset, rather than be drawn hard up against the background. Also, menu items look better if they have a bit of spacing between them. Add theme options for these and implement the required changes. Signed-off-by: Simon Glass --- doc/develop/expo.rst | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'doc/develop') diff --git a/doc/develop/expo.rst b/doc/develop/expo.rst index 80e435c5e65..bd593dc2b3f 100644 --- a/doc/develop/expo.rst +++ b/doc/develop/expo.rst @@ -162,6 +162,12 @@ properties: font-size Font size to use for all text (type: u32) +menu-inset + Number of pixels to inset the menu on the sides and top (type: u32) + +menuitem-gap-y + Number of pixels between menu items + API documentation ----------------- -- cgit v1.2.3 From 82cafee133ee5c087449761988c096fc26a17cf6 Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Thu, 1 Jun 2023 10:23:01 -0600 Subject: expo: Support building an expo from a description file The only way to create an expo at present is by calling the functions to create each object. It is useful to have more data-driven approach, where the objects can be specified in a suitable file format and created from that. This makes testing easier as well. Add support for describing an expo in a devicetree node. This allows more complex tests to be set up, as well as providing an easier format for users. It also provides a better basis for the upcoming configuration editor. Signed-off-by: Simon Glass --- doc/develop/expo.rst | 282 +++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 276 insertions(+), 6 deletions(-) (limited to 'doc/develop') diff --git a/doc/develop/expo.rst b/doc/develop/expo.rst index bd593dc2b3f..f5caadbfd98 100644 --- a/doc/develop/expo.rst +++ b/doc/develop/expo.rst @@ -100,10 +100,13 @@ objects first, then create the menu item, passing in the relevant IDs. Creating an expo ---------------- -To create an expo, use `expo_new()` followed by `scene_new()` to create a scene. -Then add objects to the scene, using functions like `scene_txt_str()` and -`scene_menu()`. For every menu item, add text and image objects, then create -the menu item with `scene_menuitem()`, referring to those objects. +To create an expo programmatically, use `expo_new()` followed by `scene_new()` +to create a scene. Then add objects to the scene, using functions like +`scene_txt_str()` and `scene_menu()`. For every menu item, add text and image +objects, then create the menu item with `scene_menuitem()`, referring to those +objects. + +To create an expo using a description file, see :ref:`expo_format` below. Layout ------ @@ -168,6 +171,273 @@ menu-inset menuitem-gap-y Number of pixels between menu items +.. _expo_format: + +Pop-up mode +----------- + +Expos support two modes. The simple mode is used for selecting from a single +menu, e.g. when choosing with OS to boot. In this mode the menu items are shown +in a list (label, > pointer, key and description) and can be chosen using arrow +keys and enter:: + + U-Boot Boot Menu + + UP and DOWN to choose, ENTER to select + + mmc1 > 0 Fedora-Workstation-armhfp-31-1.9 + mmc3 1 Armbian + +The popup mode allows multiple menus to be present in a scene. Each is shown +just as its title and label, as with the `CPU Speed` and `AC Power` menus here:: + + Test Configuration + + + CPU Speed <2 GHz> (highlighted) + + AC Power Always Off + + + UP and DOWN to choose, ENTER to select + + +Expo Format +----------- + +It can be tedious to create a complex expo using code. Expo supports a +data-driven approach, where the expo description is in a devicetree file. This +makes it easier and faster to create and edit the description. An expo builder +is provided to convert this format into an expo structure. + +Layout of the expo scenes is handled automatically, based on a set of simple +rules. + +Top-level node +~~~~~~~~~~~~~~ + +The top-level node has the following properties: + +dynamic-start + type: u32, optional + + Specifies the start of the dynamically allocated objects. This results in + a call to expo_set_dynamic_start(). + +The top-level node has the following subnodes: + +scenes + Specifies the scenes in the expo, each one being a subnode + +strings + Specifies the strings in the expo, each one being a subnode + +`scenes` node +~~~~~~~~~~~~~ + +Contains a list of scene subnodes. The name of each subnode is passed as the +name to `scene_new()`. + +`strings` node +~~~~~~~~~~~~~~ + +Contains a list of string subnodes. The name of each subnode is ignored. + +`strings` subnodes +~~~~~~~~~~~~~~~~~~ + +Each subnode defines a string which can be used by scenes and objects. Each +string has an ID number which is used to refer to it. + +The `strings` subnodes have the following properties: + +id + type: u32, required + + Specifies the ID number for the string. + +value: + type: string, required + + Specifies the string text. For now only a single value is supported. Future + work may add support for multiple languages by using a value for each + language. + +Scene nodes (`scenes` subnodes) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Each subnode of the `scenes` node contains a scene description. + +Most properties can use either a string or a string ID. For example, a `title` +property can be used to provide the title for a menu; alternatively a `title-id` +property can provide the string ID of the title. If both are present, the +ID takes preference, except that if a string with that ID does not exist, it +falls back to using the string from the property (`title` in this example). The +description below shows these are alternative properties with the same +description. + +The scene nodes have the following properties: + +id + type: u32, required + + Specifies the ID number for the string. + +title / title-id + type: string / u32, required + + Specifies the title of the scene. This is shown at the top of the scene. + +prompt / prompt-id + type: string / u32, required + + Specifies a prompt for the scene. This is shown at the bottom of the scene. + +The scene nodes have a subnode for each object in the scene. + +Object nodes +~~~~~~~~~~~~ + +The object-node name is used as the name of the object, e.g. when calling +`scene_menu()` to create a menu. + +Object nodes have the following common properties: + +type + type: string, required + + Specifies the type of the object. Valid types are: + + "menu" + Menu containing items which can be selected by the user + +id + type: u32, required + + Specifies the ID of the object. This is used when referring to the object. + + +Menu nodes have the following additional properties: + +title / title-id + type: string / u32, required + + Specifies the title of the menu. This is shown to the left of the area for + this menu. + +item-id + type: u32 list, required + + Specifies the ID for each menu item. These are used for checking which item + has been selected. + +item-label / item-label-id + type: string list / u32 list, required + + Specifies the label for each item in the menu. These are shown to the user. + In 'popup' mode these form the items in the menu. + +key-label / key-label-id + type: string list / u32 list, optional + + Specifies the key for each item in the menu. These are currently only + intended for use in simple mode. + +desc-label / desc-label-id + type: string list / u32 list, optional + + Specifies the description for each item in the menu. These are currently + only intended for use in simple mode. + + +Expo layout +~~~~~~~~~~~ + +The `expo_arrange()` function can be called to arrange the expo objects in a +suitable manner. For each scene it puts the title at the top, the prompt at the +bottom and the objects in order from top to bottom. + +Expo format example +~~~~~~~~~~~~~~~~~~~ + +This example shows an expo with a single scene consisting of two menus. The +scene title is specified using a string from the strings table, but all other +strings are provided inline in the nodes where they are used. + +:: + + #define ID_PROMPT 1 + #define ID_SCENE1 2 + #define ID_SCENE1_TITLE 3 + + #define ID_CPU_SPEED 4 + #define ID_CPU_SPEED_TITLE 5 + #define ID_CPU_SPEED_1 6 + #define ID_CPU_SPEED_2 7 + #define ID_CPU_SPEED_3 8 + + #define ID_POWER_LOSS 9 + #define ID_AC_OFF 10 + #define ID_AC_ON 11 + #define ID_AC_MEMORY 12 + + #define ID_DYNAMIC_START 13 + + &cedit { + dynamic-start = ; + + scenes { + main { + id = ; + + /* value refers to the matching id in /strings */ + title-id = ; + + /* simple string is used as it is */ + prompt = "UP and DOWN to choose, ENTER to select"; + + /* defines a menu within the scene */ + cpu-speed { + type = "menu"; + id = ; + + /* + * has both string and ID. The string is ignored + * if the ID is present and points to a string + */ + title = "CPU speed"; + title-id = ; + + /* menu items as simple strings */ + item-label = "2 GHz", "2.5 GHz", "3 GHz"; + + /* IDs for the menu items */ + item-id = ; + }; + + power-loss { + type = "menu"; + id = ; + + title = "AC Power"; + item-label = "Always Off", "Always On", + "Memory"; + + item-id = ; + }; + }; + }; + + strings { + title { + id = ; + value = "Test Configuration"; + value-es = "configuración de prueba"; + }; + }; + }; + API documentation ----------------- @@ -180,11 +450,10 @@ Future ideas Some ideas for future work: - Default menu item and a timeout -- Higher-level / automatic / more flexible layout of objects - Image formats other than BMP - Use of ANSI sequences to control a serial terminal - Colour selection -- Better support for handling lots of settings, e.g. with radio/option widgets +- Support for more widgets, e.g. text, numeric, radio/option - Mouse support - Integrate Nuklear, NxWidgets or some other library for a richer UI - Optimise rendering by only updating the display with changes since last render @@ -194,6 +463,7 @@ Some ideas for future work: - Support both graphical and text menus at the same time on different devices - Support unicode - Support curses for proper serial-terminal menus +- Add support for large menus which need to scroll .. Simon Glass .. 7-Oct-22 -- cgit v1.2.3 From a0874dc4ac7153f49f72c3fb818422d940ecbfea Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Thu, 1 Jun 2023 10:23:02 -0600 Subject: expo: Add a configuration editor Add a new 'cedit' command which allows editing configuration using an expo. The configuration items appear as menus on the display. This is extremely basic, only supporting menus and not providing any way to load or save the configuration. Signed-off-by: Simon Glass --- doc/develop/expo.rst | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) (limited to 'doc/develop') diff --git a/doc/develop/expo.rst b/doc/develop/expo.rst index f5caadbfd98..2ac4af232da 100644 --- a/doc/develop/expo.rst +++ b/doc/develop/expo.rst @@ -171,8 +171,6 @@ menu-inset menuitem-gap-y Number of pixels between menu items -.. _expo_format: - Pop-up mode ----------- @@ -202,6 +200,8 @@ just as its title and label, as with the `CPU Speed` and `AC Power` menus here:: UP and DOWN to choose, ENTER to select +.. _expo_format: + Expo Format ----------- @@ -211,7 +211,8 @@ makes it easier and faster to create and edit the description. An expo builder is provided to convert this format into an expo structure. Layout of the expo scenes is handled automatically, based on a set of simple -rules. +rules. The :doc:`../usage/cmd/cedit` can be used to load a configuration +and create an expo from it. Top-level node ~~~~~~~~~~~~~~ @@ -464,6 +465,7 @@ Some ideas for future work: - Support unicode - Support curses for proper serial-terminal menus - Add support for large menus which need to scroll +- Add support for reading and writing configuration settings with cedit .. Simon Glass .. 7-Oct-22 -- cgit v1.2.3