diff options
Diffstat (limited to 'doc/develop/expo.rst')
| -rw-r--r-- | doc/develop/expo.rst | 96 |
1 files changed, 77 insertions, 19 deletions
diff --git a/doc/develop/expo.rst b/doc/develop/expo.rst index 2ac4af232d..c87b6ec812 100644 --- a/doc/develop/expo.rst +++ b/doc/develop/expo.rst @@ -63,9 +63,12 @@ select the item), label and description. All three are shown in a single line within the menu. Items can also have a preview image, which is shown when the item is highlighted. -All components have a name. This is purely for debugging, so it is easy to see -what object is referred to. Of course the ID numbers can help as well, but they -are less easy to distinguish. +A `textline object` contains a label and an editable string. + +All components have a name. This is mostly for debugging, so it is easy to see +what object is referred to, although the name is also used for saving values. +Of course the ID numbers can help as well, but they are less easy to +distinguish. While the expo implementation provides support for handling keypresses and rendering on the display or serial port, it does not actually deal with reading @@ -136,7 +139,9 @@ this is to use `cli_ch_process()`, since it handles conversion of escape sequences into keys. However, expo has some special menu-key codes for navigating the interface. These are defined in `enum bootmenu_key` and include `BKEY_UP` for moving up and `BKEY_SELECT` for selecting an item. You can use -`bootmenu_conv_key()` to convert an ASCII key into one of these. +`bootmenu_conv_key()` to convert an ASCII key into one of these, but if it +returns a value >= `BKEY_FIRST_EXTRA` then you should pass the unmodified ASCII +key to the expo, since it may be used by textline objects. Once a keypress is decoded, call `expo_send_key()` to send it to the expo. This may cause an update to the expo state and may produce an action. @@ -312,11 +317,26 @@ type "menu" Menu containing items which can be selected by the user + "textline" + A line of text which can be edited + id type: u32, required Specifies the ID of the object. This is used when referring to the object. +Where CMOS RAM is used for reading and writing settings, the following +additional properties are required: + +start-bit + Specifies the first bit in the CMOS RAM to use for this setting. For a RAM + with 0x100 bytes, there are 0x800 bit locations. For example, register 0x80 + holds bits 0x400 to 0x407. + +bit-length + Specifies the number of CMOS RAM bits to use for this setting. The bits + extend from `start-bit` to `start-bit + bit-length - 1`. Note that the bits + must be contiguous. Menu nodes have the following additional properties: @@ -350,6 +370,26 @@ desc-label / desc-label-id Specifies the description for each item in the menu. These are currently only intended for use in simple mode. +Textline nodes have the following additional properties: + +label / label-id + type: string / u32, required + + Specifies the label of the textline. This is shown to the left of the area + for this textline. + +edit-id + type: u32, required + + Specifies the ID of the of the editable text object. This can be used to + obtain the text from the textline + +max-chars: + type: u32, required + + Specifies the maximum number of characters permitted to be in the textline. + The user will be prevented from adding more. + Expo layout ~~~~~~~~~~~ @@ -358,6 +398,9 @@ 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_example: + Expo format example ~~~~~~~~~~~~~~~~~~~ @@ -367,22 +410,30 @@ strings are provided inline in the nodes where they are used. :: - #define ID_PROMPT 1 - #define ID_SCENE1 2 - #define ID_SCENE1_TITLE 3 + /* this comment is parsed by the expo.py tool to insert the values below + + enum { + ZERO, + ID_PROMPT, + ID_SCENE1, + ID_SCENE1_TITLE, - #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 + ID_CPU_SPEED, + ID_CPU_SPEED_TITLE, + ID_CPU_SPEED_1, + ID_CPU_SPEED_2, + ID_CPU_SPEED_3, - #define ID_POWER_LOSS 9 - #define ID_AC_OFF 10 - #define ID_AC_ON 11 - #define ID_AC_MEMORY 12 + ID_POWER_LOSS, + ID_AC_OFF, + ID_AC_ON, + ID_AC_MEMORY, - #define ID_DYNAMIC_START 13 + ID_MACHINE_NAME, + ID_MACHINE_NAME_EDIT, + + ID_DYNAMIC_START, + */ &cedit { dynamic-start = <ID_DYNAMIC_START>; @@ -427,6 +478,13 @@ strings are provided inline in the nodes where they are used. item-id = <ID_AC_OFF ID_AC_ON ID_AC_MEMORY>; }; + + machine-name { + id = <ID_MACHINE_NAME>; + type = "textline"; + max-chars = <20>; + title = "Machine name"; + edit-id = <ID_MACHINE_NAME_EDIT>; }; }; @@ -454,7 +512,7 @@ Some ideas for future work: - Image formats other than BMP - Use of ANSI sequences to control a serial terminal - Colour selection -- Support for more widgets, e.g. text, numeric, radio/option +- Support for more widgets, e.g. 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 @@ -465,7 +523,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 +- Update expo.py tool to check for overlapping names and CMOS locations .. Simon Glass <sjg@chromium.org> .. 7-Oct-22 |