muiref

MUI Naming Convention
MUIF, MUIF Callback and FDS Macro Reference
MUI API
MUIF Helper Functions

MUI Naming Convention

Definitions

Form
- A form describes the content of one full display screen.
- The user interface must include at least one form.
- Each form includes one or more fields (see below).
- MUI supports up to 255 forms.
- Each form in MUI has a unique number (1..255).
- All forms are defined in FDS (Form Definition String)
- Each form starts with the FDS Macro MUI_FORM(x) with x = 1..255.
Field
- A field is an element of a form.
- A field can be an interactive element, like a button or a selection box.
- A field can be a static element, like a text label or an icon.
- A field can modify a value (field value), like a field input for a numerical value.
- A field often supports two different edit modes: MSE and MUD
- A field is placed at a specific XY position.
- Each field has a two char identifier, which connects the field to a field processing function (MUIF).
- A field might have an extra argument, which could be used by the field processing function (MUIF).
- A Field is defined with a FDS Macro as part of a Form within the FDS.
- Example: MUI_LABEL(5, 15, "Hello U8g2") is a FDS Macro which defines a read only text field. The FDS Macro MUI_XYT("BN",64, 30, " Exit ") places a button with the text " Exit " on a form.
FDS (Form Definition String)
- A normal C-String, which is usually composed with special macros (FDS Macro).
- Defines all the forms along with all the fields.
- The FDS is passed to the menu system during initalization (mui.begin(u8g2, fds_data, muif_list, sizeof(muif_list)/sizeof(muif_t)); )
- Example:
```
fds_t fds_data[] = 
MUI_FORM(1)                     // no comma allowed, because fds_data is a string
MUI_STYLE(0)
MUI_XYT("BN",64, 30, " Select Me ")
;
```
FDS Macro
- A C macro which is part of the FDS (Form Definition String).
- All FDS Macros start with MUI_.
- A FDS Macro may define a field at a specific position on the form (for example MUI_XYT("BN",64, 30, " Exit ")).
- There are some other FDS Macros, for example to start a new form (MUI_FORM()) or to change the current style (MUI_STYLE()).
MUIF (MUI Field Processing Function)
- Each MUIF has a unique two char identifier (Exceptions: MUIF_STYLE will use a number, MUIF_U8G2_LABEL() does not require a number or identifier)
- A MUIF is often connected to a MUIF callback function.
- A MUIF can be connected to an outside variable (data pointer). Data input from the user can be stored in those variables.
- A MUIF can be referenced by one or more fields via the field's definition in the FDS Macro
- A MUIF can be a simple text output function such as MUIF_U8G2_LABEL(), which is placed with the FDS Macro MUI_LABEL() .
- A MUIF can be a complex interactive numeric value input, which is rendered as a number field and writes the number to a corresponding data variable.
- An array with all MUIFs (MUIF List) for the current menu is passed to the menu system during initalization.
- MUIF always starts with MUIF_.
- A MUIF is a C Macro (MUIF macro) which may have several arguments (like identifier, MUIF callback or the address of a variable).
- Example: MUIF_BUTTON("BN", mui_u8g2_btn_exit_wm_fi) is a MUIF macro with MUIF callback mui_u8g2_btn_exit_wm_fi. MUIF_U8G2_LABEL() is a MUIF macro without MUIF callback.
MUIF Callback
- A MUIF (MUI Field Processing Function) might refer to a callback function (MUIF Callback).
- The MUIF Callback defines additional characteristics and behaviour of the field.
- Custom MUIF Callbacks can be created: Existing MUIF Callbacks can be extended or modified, but also complete new MUIF Callbacks can be implemented.
- Example: In the MUIF MUIF_BUTTON("BN", mui_u8g2_btn_exit_wm_fi), the identifier mui_u8g2_btn_exit_wm_fi is called the MUIF Callback.

MUIF List

A C array with all MUIFs, which are required for the menu system.
The MUIF List is passed to the menu system during initalization (mui.begin(u8g2, fds, muif_list, sizeof(muif_list)/sizeof(muif_t));).

Example:

muif_t muif_list[] = {  
  MUIF_U8G2_FONT_STYLE(0, u8g2_font_helvR08_tr),  /* define style 0 */
  MUIF_U8G2_LABEL(),                              /* allow MUI_LABEL FDS Macro */
  MUIF_BUTTON("BN", mui_u8g2_btn_exit_wm_fi)      /* define exit button MUIF */
};

MUD
- Modify Up Down
- Field data entry mode, where the user has to (a) select the field, (b) use prev/next button to change the value and (c) press select again to confirm the value and leave the value chang mode
- See MUI Callback Edit Mode
MSE
- Modify with SElect
- Field data entry mode, where the user just moves the focus cursor into the field. Pressing "select" will increment the value
- See MUI Callback Edit Mode

FDS macros

This section describes all available FDS Macros. The FDS Macros are used to describe the visual layout of the menu including the position of each text and button on a form.

MUI_FORM(form_id): Start a new form with given form_id (0..255). A form ends with the next MUI_FORM or at the end of the FDS.
- form_id: A value between 0..255. Value 0 is possible for form_id but should be avoided. The form_id is a plain number like MUI_FORM(123).
MUI_STYLE(style_id): Assign a style (0..9) to the following fields.
- style_id: The style_id is a plain number from 0 to 9. Example: MUI_STYLE(0).
MUI_DATA(muif_id, string): Places a data object into the form. Data objects are required for special MUIF.
- muif_id: A string with exactly two chars (like "G0"), which referes to the corresping field function in MUIF array.
- string: Additional data for some graphical user elements (see description for the MUIF below).
MUI_XY(muif_id, x, y): Places field muif_id at the specified x,y position.
- muif_id: A string with exactly two chars (like "G0"), which referes to the corresping field function in MUIF array.
- x, y: Position for the field. Values are between 0 and 255. For bigger displays, the value is automatically multiplied with 2 (which means, that a field can be placed only at every second pixel on a 320x200 screen).
MUI_XYT(muif_id, x, y, text): Places field muif_id with text argument at the specified x,y position.
- muif_id: A string with exactly two chars (like "G0"), which referes to the corresping field function in MUIF array.
- x, y: Position for the field. Values are between 0 and 255. For bigger displays, the value is automatically multiplied with 2 (which means, that a field can be placed only at every second pixel on a 320x200 screen).
- text: Contains additional data for the field. See the description for the MUIF below for details.
MUI_XYA(muif_id, x, y, arg): Places field muif_id with additional arginformation at the specified x,y position.
- muif_id: A string with exactly two chars (like "G0"), which referes to the corresping field function in MUIF array.
- x, y: Position for the field. Values are between 0 and 255. For bigger displays, the value is automatically multiplied with 2 (which means, that a field can be placed only at every second pixel on a 320x200 screen).
- arg: Additional value used by the field function. This might be the field width in pixel or the form id for a jump button, depending on the MUIF (see below).
MUI_XYAT(muif_id, x, y, arg, text): Places field muif_id at the specified x,y position with additional arg and text information.
- muif_id: A string with exactly two chars (like "G0"), which referes to the corresping field function in MUIF array.
- x, y: Position for the field. Values are between 0 and 255. For bigger displays, the value is automatically multiplied with 2 (which means, that a field can be placed only at every second pixel on a 320x200 screen).
- arg: Additional value used by the field function. This might be the field width in pixel or the form id for a jump button, depending on the MUIF (see below).
- text: Contains additional data for the field. See the description for the MUIF below for details.
MUI_AUX(muif_id): Adds a (invisible) field to the form without providing a x,y position. See the stopwatch example.
- muif_id: A string with exactly two chars (like "G0"), which referes to the corresping field function in MUIF array.

All FDS Macros are written in a sequence in the form definition string (FDS).

Example:

fds_t fds_data[] = 
MUI_FORM(1)                     // no comma allowed, because fds_data is a string
MUI_STYLE(0)
MUI_XYT("BN",64, 30, " Select Me ")
;

Note: FDS is a C string, this means that there must be no comma to separate above macros.

MUIF and MUIF Callbacks

MUIF (MUI Field Processing Function) define properties (display style, behavior, etc) for a field on the form (FDS Macro, see above): Mosst FDS macros require a corresponding MUIF (with same muif_id or same number) .

FDS macro MUI_XYT("BN",64, 30, " Button ") will use MUIF MUIF_BUTTON("BN", mui_u8g2_btn_exit_wm_fi) because they share the same muif_id "BN"
FDS macro MUI_STYLE(0) will use MUIF_U8G2_FONT_STYLE(0, u8g2_font_helvR08_tr) because they share the same number 0.
FDS macro MUI_LABEL(5, 15, "Hello U8g2") will always use MUIF MUIF_U8G2_LABEL().

Some MUIF require an additional MUIF callback function. For example MUIF MUIF_BUTTON("BN", mui_u8g2_btn_exit_wm_fi) requires the MUIF callback mui_u8g2_btn_exit_wm_fi which defines additional properties for the field.

The following sections will explain the naming convention for the MUIF callbacks.

The last section will provide an overview on the available MUIF (MUIF_).

MUIF Callback Field Width Property

hint	field width	example MUIF callback
`wm`	minimum width (often defined by a text string)	`mui_u8g2_btn_goto_wm_fi`
`wa`	width can be provided via FDS Macro argument	`mui_u8g2_u8_opt_line_wa_mse_pi`
`w1`	full display width	`mui_u8g2_btn_goto_w1_pi`
`w2`	half display size (minus some pixel)	`mui_u8g2_btn_goto_w2_fi`
`w3`	one/third of the dispay width (minus some pixel)	(not yet implemented)

The field width hint is always part of the MUIF callback name (Only exceptions are MUIF callbacks for invisible fields, like mui_u8g2_goto_data).

MUI Callback Edit Mode

Some MUIF callbacks include a hint for the data change method for the field value:

hint	description
`mse`	edit Mode SElect: The select event will increment the value.
`mud`	edit Mode Up/Down: The select event will enter the edit mode for the field. Next/prev event will increment/decrement the value.

If the mse or mud hint is missing in the MUI function name, then this function either doesn't change a value (buttons) or the value change is trivial (checkbox). Examples:

mui_u8g2_u8_min_max_wm_mse_pi: The input function for a uint8_t value with mse input method .
mui_u8g2_u8_chkbox_wm_pi: There is no mse or mud mode for the checkbox, instead the select event will toggle the value directly.

MUI Callback Display Style

Each MUIF Callback has a postfix, which describes the display style of the field in different modes (focus, no focus, mud edit mode). Note: "mud" doesn't exist for buttons, so the styles "fi" and "if" don't have a separate "mud" edit mode style.

postfix	field selection style	usually used for...	unselected style	selected style	edit mode (mud)
pi	inverted field	input elements	plain	inverted	inverted + gap + frame
fi	inverted field	button elements	frame	frame+inverted	(frame)
pf	frame around field	input elements	plain	frame	inverted+frame
if	frame around field	button elements	inverted	frame	(inverted + frame)

MUIF Overview

A field can be used in a form only, if a MUIF exists for that field. All MUIF are collected in a list (MUIF list). Most MUIF require a MUIF callback (cb in the below table) as part of the MUIF arguments. MUIF macros are:

MUIF Macro	FDS Macros	Identifier	Description
`MUIF_U8G2_FONT_STYLE(n,font)`	MUI_STYLE	Single number, no double quotes	Define a new font style
`MUIF_VARIABLE(id,var,cb)`	MUI_XY, MUI_XYT, MUI_XYA, MUI_XYAT	Two chars in double quotes	Input field for the user: Exit Button, Checkbox and Radiobutton, Character Input, One of Many Selection, List Selection
`MUIF_BUTTON(id,cb)`	MUI_XYAT	Two chars in double quotes	User selectable field: Jump Button, Exit Button, Scrollable Jump Table
`MUIF_EXECUTE_ON_SELECT_BUTTON(id,cb)`	MUI_XYAT	Two chars in double quotes	User selectable field, same as `MUIF_BUTTON(id,cb)`, see here
`MUIF_U8G2_LABEL()`	MUI_LABEL	No identifier and no callback required	Place a text on the form
`MUIF_RO(id,cb)`	MUI_DATA, MUI_AUX, MUI_XY	Two chars in double quotes	Inactive or hidden field, also used to define extra data for Scrollable Jump Table, see also stopwatch example
`MUIF_U8G2_U8_MIN_MAX(id, var, min, max, cb)`	MUI_XY	Two chars in double quotes	Numeric input field: Number Entry
`MUIF_U8G2_U8_MIN_MAX_STEP(id, var, min, max, step, flags, cb)`	MUI_XY	Two chars in double quotes	Numeric input field: Bar Graph
`MUIF_U8G2_U8_MIN_MAX_STEP_WIDTH(id, var, min, max, step, width, flags, cb)`	MUI_XY	Two chars in double quotes	Numeric input field: Fixed Width Bar Graph
`MUIF_U8G2_U16_LIST(id, valptr, dataptr, getcb, cntcb, muif)`	MUI_XYA	Two chars in double quotes	List selection input field: One of Many Selection, List Selection, Scrollable Jump Table

There are some advanced MUIF macros, which are usually not required (because a simplified / predefined MUIF exists).

MUIF Macro	FDS Macros	Identifier	Description	Simplified MUIF Macro
`MUIF_STYLE(n,cb)`	MUI_STYLE	Single number, no double quotes	Define a new generic style	`MUIF_U8G2_FONT_STYLE(n,font)`
`MUIF_LABEL(cb)`	MUI_LABEL	No identifier required	Place a text on the form	`MUIF_U8G2_LABEL()`

Each FDS Macro for a field requires a corresponding and fitting MUIF Macro. The reference part below describes which MUIF Macro (and MUIF callback) must be used for a FDS Macro (field). For example the MUIF Callback mui_u8g2_btn_exit_wm_fi (exit button callback) should be used with the MUIF MUIF_VARIABLE so that the FDS Macro* MUI_XYAT field can be used within FDS.

MUIF, MUIF Callback and FDS Macro Reference

Generic Style

Description:

Change the current drawing style. This will change the style for all MUI macros after this macro.
MUIF Macro:

MUIF_STYLE(style_id, style_callback)
FDS Macro:

MUI_STYLE(style_id): Change the current drawing style (usually the text font).
Note:

A more simpler version is MUIF_U8G2_FONT_STYLE (see below) if only the U8g2 font needs to be changed.

Example:

uint8_t mui_style_helv_r_08(mui_t *ui, uint8_t msg) {  
  u8g2_t *u8g2 = mui_get_U8g2(ui);
  switch(msg) {
    case MUIF_MSG_DRAW:
      u8g2_SetFont(u8g2, u8g2_font_helvR08_tr);
      break;
  }
  return 0;
}
...
muif_t muif_list[] = {
  /* normal text style */
  MUIF_STYLE(0, mui_style_helv_r_08),
  ...
}

...
MUI_FORM(123)
MUI_STYLE(0)
...

Font Style

Description:

The style FDS macro will change the style for all other FDS macros listed after the style FDS macro. The font style FDS macro will change the current U8g2 font. This is a more simpler version of MUIF_STYLE in cases where only the font needs to be changed. The U8g2 font can be used as argument of the corresponding (same style id) MUIF style entry. No additional callback function is required for the MUIF macro.
MUIF Macro:

MUIF_U8G2_FONT_STYLE(style_id, u8g2_font))
FDS Macro:

MUI_STYLE(style_id): Change the current text font to the font which was assigned in the MUIF macro.

Example:

muif_t muif_list[] = {
  /* normal text style */
  MUIF_U8G2_FONT_STYLE(0, u8g2_font_helvR08_tr),
  ...
}

...
MUI_FORM(1)                            /* This will start the definition of form 1 */
MUI_STYLE(0)                           /* select the font defined with style 0: u8g2_font_helvR08_tr */
MUI_LABEL(5, 15, "Hello U8g2")         /* place text at postion x=5, y=15, use style 0 */
...

Label

Description:

Write a text string on any position of the form.
MUIF Macro:
- MUIF_U8G2_LABEL(): The standard label draw MUIF
- MUIF_LABEL(mui_u8g2_draw_text): Same as MUIF_U8G2_LABEL() but you could exchange the standard label draw MUIF Callback mui_u8g2_draw_text with your own custom MUIF Callback.
FDS Macro:

MUI_LABEL(x, y, "Text"): The specified "Text" is placed at position x,y on the form.

Example:

muif_t muif_list[] = {  
  MUIF_U8G2_FONT_STYLE(0, u8g2_font_helvR08_tr),   /* define style 0 */
  MUIF_U8G2_LABEL(),                               /* allow MUI_LABEL macro */
  MUIF_BUTTON("BN", mui_u8g2_btn_exit_wm_fi)       /* define exit button */
};

fds_t fds_data[] =                     /* Don't use comma between the commands! */
MUI_FORM(1)                            /* This will start the definition of form 1 */
MUI_STYLE(0)                           /* select the font defined with style 0 */
MUI_LABEL(5, 15, "Hello U8g2")         /* place text at postion x=5, y=15 */
MUI_XYT("BN",64, 30, " Exit ")         /* place the exit button at pos x=64, y=30 */
;

mui.begin(u8g2, fds_data, muif_list, sizeof(muif_list)/sizeof(muif_t));
mui.gotoForm(/* form_id= */ 1, /* initial_cursor_position= */ 0);

Jump Button

Description:

When selected, jump to the specified form. The form number is provided as argument to the FDS Macro.
MUIF Macro: (pi/fi)
- MUIF_BUTTON("G0", mui_u8g2_btn_goto_wm_fi)
- MUIF_BUTTON("G1", mui_u8g2_btn_goto_w1_fi)
- MUIF_BUTTON("G2", mui_u8g2_btn_goto_w1_pi)
- MUIF_BUTTON("G3", mui_u8g2_btn_goto_w2_fi)
- MUIF_BUTTON("G4", mui_u8g2_btn_goto_w2_if)
- MUIF_BUTTON("G5", mui_u8g2_btn_goto_wm_if)
FDS Macro:

MUI_XYAT("ID", x, y, destination_form, "Text"): Draw the bottom at position x,y on the form. If the button receives the select event, then the new form specified by destination_form will be activated.

Example:

MUI_XYAT("G0", 1, 42, 10, "Press here")

Exit Button

Description:

When selected, stop the menu system. The current form and cursor position is stored and MUI can be reactivated with restoreForm.
MUIF Macro: (fi)
- MUIF_VARIABLE("XX",&exit_code,mui_u8g2_btn_exit_wm_fi): Close the menu system, when selected. An exit code is stored in variable exit_code (unit8_t).
- MUIF_BUTTON("XX", mui_u8g2_btn_exit_wm_fi): Can be used if the exit code is not required.
FDS Macro:
- MUI_XYAT("XX", x, y, exit_code, "Text"): Draw the bottom at position x,y on the form. If the button receives the select event, then the menu system will be closed. The exit code will be stored in the connected variable.
- MUI_XYT("XX", x, y, "Text"): Draw the bottom at position x,y on the form. If the button receives the select event, then the menu system will be closed. The exit code will be 0.

Example:

muif_t muif_list[] = {  
  MUIF_U8G2_FONT_STYLE(0, u8g2_font_helvR08_tr),  /* define style 0 */
  MUIF_U8G2_LABEL(),                                                    /* allow MUI_LABEL command */
  MUIF_BUTTON("BN", mui_u8g2_btn_exit_wm_fi)        /* define exit button */
};

fds_t fds_data[] =                              /* Don't use comma between the commands! */
MUI_FORM(1)                                     /* This will start the definition of form 1 */
MUI_STYLE(0)                                    /* select the font defined with style 0 */
MUI_LABEL(5, 15, "Hello U8g2")          /* place text at postion x=5, y=15 */
MUI_XYT("BN",64, 30, " Exit ")     /* place the exit button at pos x=64, y=30 */
;

mui.begin(u8g2, fds_data, muif_list, sizeof(muif_list)/sizeof(muif_t));
mui.gotoForm(/* form_id= */ 1, /* initial_cursor_position= */ 0);

Checkbox and Radiobutton

Animation:
Description:
- Checkbox: A field which assignes 0 or 1 to variable. If the field receives the select event, then the field value changes from 0 to 1 or from 1 to 0.
- Radiobutton: A field which assigns the FDS Macro argument value (MUI_XYA or MUI_XYAT) to variable. If the field receives the select event, then this field is checked and all other radiobuttons on the same form with the same ID are unchecked.
MUIF Macro:
- MUIF_VARIABLE("CB",&variable,mui_u8g2_u8_chkbox_wm_pi)
- MUIF_VARIABLE("RB",&variable,mui_u8g2_u8_radio_wm_pi)
FDS Macro:
- MUI_XY("CB", x, y): The check box field is placed at the specified x,y position.
- MUI_XYAT("RB", x, y, value, "Radio Label"): The radiobutton is placed at x,y position. value is assigned to variable if this field receives the select event. The "Radio Label" text is placed after the radio checkbox but is optional (Use MUI_XYA if "Radio Label" is not required).

Example:

MUI_FORM(31)
MUI_STYLE(0)
MUI_LABEL(1,40, "Checkbox 1: ")
MUI_XY("CB",66, 40)
MUI_GOTO(110, 54, 30, "OK")

MUI_FORM(32)
MUI_STYLE(0)
MUI_XYAT("RB", 1, 40, 1, "Radio 1")
MUI_XYAT("RB", 1, 55, 2, "Radio 2")
MUI_GOTO(110, 54, 30, "OK")

Numbers (uint8)

Animation:
Description:

Input of a number between a lower and an upper limit. The input will be
stored in a uint8_t variable.
- mse mode: Select event selects the next number (2-button input).
- mud mode: Select enters "mud" update mode. Within "mud" update mode use prev and next event to decrease/increase the number (3-button and rotary encoder input).
MUIF Macro:

MUIF_U8G2_U8_MIN_MAX(id, valptr, min, max, cb)
- id: Unique id for this field
- valptr: The address of the uint8_t variable
- min: Minimum value of the number (lower limit)
- max: Maximum value of the number (upper limit)
- cb: One of the following MUIF Callbacks (mse/mud, pi/pf):
  - mui_u8g2_u8_min_max_wm_mse_pi
  - mui_u8g2_u8_min_max_wm_mud_pi
  - mui_u8g2_u8_min_max_wm_mse_pf
  - mui_u8g2_u8_min_max_wm_mud_pf
FDS Macro:

MUI_XY("ID", x, y): Position of the number input field on the target form.

Example:

uint8_t number = 0;
...
MUIF_U8G2_U8_MIN_MAX("NR", &number, 0, 9, mui_u8g2_u8_min_max_wm_mse_pi),

MUI_FORM(21)
MUI_STYLE(0)
MUI_LABEL(1,40, "Number: ")
MUI_XY("NR",70, 40)
MUI_GOTO(64, 59, 20, " Ok ")

Bar Graph (uint8)

Animation:
Description:

Input of a number between a lower and an upper limit. The input will be
stored in a uint8_t variable. The value is displayed as a horizontal bar graph.

Incrementing the max value will wrap over to the min value and decrementing the min value will wrap over to the max value. This can be avoided with the MUI_MMS_NO_WRAP option (Note: Using the MUI_MMS_NO_WRAP in two button "mse" mode does NOT make sense).

The width of the bar graph is equal to the max argument of the MUIF Macro (see below).

The height of the bar graph is defined by the ascent (height) of the current font.
- mse mode: Select event selects the next number (2-button input).
- mud mode: Select enters update mode. Within update mode use prev and next event to decrease/increase the number (3-button and rotary encoder input).
MUIF Macro:

MUIF entry: MUIF_U8G2_U8_MIN_MAX_STEP(id, valptr, min, max, step, flags, cb)
- id: Unique id for this field
- valptr: The address of the uint8_t variable
- min: Minimum value of the number (lower limit, uint8_t)
- max: Maximum value of the number (upper limit, uint8_t)
- step: Increment/decrement value (uint8_t)
- flags: One or more of the following flags (multiple flags can be used with the "or" operator |):
  - MUI_MMS_2X_BAR: Horizontal scale by 2
  - MUI_MMS_4X_BAR: Horizontal scale by 4
  - MUI_MMS_SHOW_VALUE: Additionally show the current value
  - MUI_MMS_NO_WRAP: Increment (decrement) the max value (min value) will force the bar graph to stay at the max (min) value. Available with v2.34.
- cb: One of the following MUIF Callbacks (mse/mud, pi/pf):
  - mui_u8g2_u8_bar_wm_mse_pi
  - mui_u8g2_u8_bar_wm_mud_pi
  - mui_u8g2_u8_bar_wm_mse_pf
  - mui_u8g2_u8_bar_wm_mud_pf
FDS Macro:

MUI_XY("ID", x, y): Position of the bar graph input field on the target form.

Example:

uint8_t number = 0;
...
MUIF_U8G2_U8_MIN_MAX_STEP("B0", &number, 0, 20, 2, MUI_MMS_2X_BAR|MUI_MMS_SHOW_VALUE, mui_u8g2_u8_bar_wm_mse_pi),

MUI_FORM(91)
MUI_STYLE(0)
MUI_LABEL(1,40, "Bar: ")
MUI_XY("B0",40, 40)
MUI_GOTO(64, 59, 90, " Ok ")

Fixed Width Bar Graph (uint8)

Description:

Input of a number between a lower and an upper limit. The input will be
stored in a uint8_t variable. The value is displayed as a horizontal bar graph.

Incrementing the max value will wrap over to the min value and decrementing the min value will wrap over to the max value. This can be avoided with the MUI_MMS_NO_WRAP option (Note: Using the MUI_MMS_NO_WRAP in two button "mse" mode does NOT make sense).

The width of the bar graph is defined by the width argument of the MUIF Macro (see below).

The height of the bar graph is defined by the ascent (height) of the current font.
- mse mode: Select event selects the next number (2-button input).
- mud mode: Select enters update mode. Within update mode use prev and next event to decrease/increase the number (3-button and rotary encoder input).
MUIF Macro:

MUIF entry: MUIF_U8G2_U8_MIN_MAX_STEP_WIDTH(id, valptr, min, max, step, width, flags, cb)
- id: Unique id for this field
- valptr: The address of the uint8_t variable
- min: Minimum value of the number (lower limit, uint8_t)
- max: Maximum value of the number (upper limit, uint8_t)
- step: Increment/decrement value
- width: Pixel size of the bar without any decoration (uint8_t)
- flags: One or more of the following flags (multiple flags can be used with the "or" operator |):
  - MUI_MMS_2X_BAR: Multiply width with factor 2
  - MUI_MMS_4X_BAR: Multiply width with factor 4
  - MUI_MMS_SHOW_VALUE: Additionally show the current value
  - MUI_MMS_NO_WRAP: Increment (decrement) the max value (min value) will force the bar graph to stay at the max (min) value.
- cb: One of the following MUIF Callbacks (mse/mud, pi/pf):
  - mui_u8g2_u8_fixed_width_bar_wm_mse_pi
  - mui_u8g2_u8_fixed_width_bar_wm_mud_pi
  - mui_u8g2_u8_fixed_width_bar_wm_mse_pf
  - mui_u8g2_u8_fixed_width_bar_wm_mud_pf
FDS Macro:

MUI_XY("ID", x, y): Position of the bar graph input field on the target form.

Example:

uint8_t number = 0;
...
MUIF_U8G2_U8_MIN_MAX_STEP_WIDTH("B0", &number, 0, 20, 2, 50, MUI_MMS_2X_BAR|MUI_MMS_SHOW_VALUE, mui_u8g2_u8_fixed_width_bar_wm_mse_pi),

MUI_FORM(91)
MUI_STYLE(0)
MUI_LABEL(1,40, "Bar: ")
MUI_XY("B0",40, 40)
MUI_GOTO(64, 59, 90, " Ok ")

Note: Available with v2.34

Character Input

Animation:
Description:

Input field for a single character. Characters are limited to ' ', 'A'-'Z', 'a'-'z' and '0'-'9'. The character will be stored in the specified variable. Multiple MUIF Macros with different IDs can be used to input more than one character on the same form.
MUIF Macro: (mud, pi)

MUIF_VARIABLE("ID",&variable,mui_u8g2_u8_char_wm_mud_pi)
FDS Macro:

MUI_XY("ID", x, y): Place the field a the specified x,y position. Use a monospaced font for this field (for example u8g2_font_profont12_tr).

Example:

char s[5] = "aaaa";
...
MUIF_VARIABLE("T0",s+0,mui_u8g2_u8_char_wm_mud_pi),
MUIF_VARIABLE("T1",s+1,mui_u8g2_u8_char_wm_mud_pi),
MUIF_VARIABLE("T2",s+2,mui_u8g2_u8_char_wm_mud_pi),
MUIF_VARIABLE("T3",s+3,mui_u8g2_u8_char_wm_mud_pi),
...
MUI_FORM(61)
MUI_STYLE(0)
MUI_LABEL(5,40, "Text:")
MUI_STYLE(5)                        /* use a monospaced font */
MUI_XY("T0",40, 40)
MUI_XY("T1",48, 40)
MUI_XY("T2",56, 40)
MUI_XY("T3",64, 40)
MUI_STYLE(0)
MUI_GOTO(64, 59, 60, " Ok ")

One of Many Selection (Cycle, uint8, static list)

Animation:
Description: Select one option out of a list of options. The number of the selected option will be stored in variable (uint8_t, first option in the list has the number 0).
- mse mode: Select event selects the next option (2-button input).
- mud mode: Select enters update mode. Within update mode use prev and next event to cycle between options (3-button and rotary encoder input).
MUIF Macro: (mse/mud, pi/pf)
- MUIF_VARIABLE("ID",&variable,mui_u8g2_u8_opt_line_wa_mse_pi)
- MUIF_VARIABLE("ID",&variable,mui_u8g2_u8_opt_line_wa_mse_pf)
- MUIF_VARIABLE("ID",&variable,mui_u8g2_u8_opt_line_wa_mud_pi)
- MUIF_VARIABLE("ID",&variable,mui_u8g2_u8_opt_line_wa_mud_pf)
FDS Macro:

MUI_XYAT("ID", x, y, arg, "Banana|Apple|Melon|Cranberry"): Defines a list of options, separated with |. The user can select one option. The first option has the number 0. arg defines the pixel width of the field.

Example:

MUI_FORM(41)
MUI_STYLE(0)
MUI_LABEL(5,40, "Fruit:")
MUI_XYAT("ID",60, 40, 60, "Banana|Apple|Melon|Cranberry")
MUI_STYLE(0)
MUI_GOTO(64, 59, 40, " Ok ")

One of Many Selection (Cycle, uint16, dynamic list)

Animation:
Description: Select one option out of a list of options. The number of the selected option will be stored in variable (uint16_t, first option in the list has the number 0). The options are provided by callback functions.
- mse mode: Select event selects the next option (2-button input).
- mud mode: Select enters update mode. Within update mode use prev and next event to cycle between options (3-button and rotary encoder input).
MUIF Macro:

MUIF entry: MUIF_U8G2_U16_LIST(id, valptr, dataptr, getcb, cntcb, cb)
- id: Unique id for this field
- valptr: The address of the uint16_t variable
- dataptr: Optional data pointer which will be passed to the callback functions (use NULL if not used)
- getcb: A callback function, which should return a \0 terminated string with the option name at the provided index. Prototype: const char *get_str(void *data, uint16_t index)
- cntcb: A callback function, which should retun the total number of elements in the list. Prototype: uint16_t get_cnt(void *data)
- cb: One of the following MUIF Callbacks (mse/mud, pi):
  - mui_u8g2_u16_list_line_wa_mse_pi
  - mui_u8g2_u16_list_line_wa_mud_pi
FDS Macro:

MUI_XYA("ID", x, y, arg): The user can select one option (string returned by getcb function). The first option has the number 0. arg defines the pixel width of the field.

Example:

static const char *animals[] = { 
  "Bird", "Bison", "Cat", "Crow", "Dog", "Elephant", "Fish", "Gnu", "Horse", 
  "Koala", "Lion", "Mouse", "Owl", "Rabbit", "Spider", "Turtle", "Zebra" };
  
uint16_t animals_get_cnt(void *data) {
  return sizeof(animals)/sizeof(*animals);    /* number of animals */
}
const char *animals_get_str(void *data, uint16_t index) {
  return animals[index];
}
...
uint16_t selection = 0;
...
MUIF_U8G2_U16_LIST("A1", &selection, NULL, animals_get_str, animals_get_cnt, mui_u8g2_u16_list_line_wa_mse_pi),

MUI_FORM(71)
MUI_STYLE(0)
MUI_LABEL(5,40, "Animal:")
MUI_XYA("A1",45, 40, 50)
MUI_GOTO(64, 59, 70, " Ok ")

List Selection (Child form, uint8, static list)

Animation:
Description: Select one option out of a list of options.

mui_u8g2_u8_opt_parent_wm_pi will show the selected option in the parent form. The option number is stored in variable (uint8_t). The select event for mui_u8g2_u8_opt_parent_wm_pi will open a child form. A different option can be selected in the child form.

The child form must include on or more child fields (MUI_XYA()). Only one type of child field is allowed (all active child fields must have the same ID). Other active elements than the child field should not be used in the child form.
MUIF Macro: (pi)
- MUIF_VARIABLE("PP",&variable,mui_u8g2_u8_opt_parent_wm_pi): The parent field which should appear on the parent form.
- MUIF_VARIABLE("CC",&variable,mui_u8g2_u8_opt_radio_child_w1_pi): The field for the child form. The current selected option is prefixed with a solid box.
- MUIF_VARIABLE("CC",&variable,mui_u8g2_u8_opt_child_wm_pi): The field for the child form. Options are just displayed.
FDS Macro:
- MUI_XYAT("PP", x, y, arg, "red|orange|yellow|green|cyan|azure|blue|violet|magenta|rose"): Defines a list of options, separated with |. The user can select one option. The first option has the number 0. arg defines the form number of the child form.
- MUI_XYA("CC", x, y, n): Defines one or more fields on the child form. Each field must have the same id (here: "CC"), but must have a unique number n starting with 0. These fields define the scroll area for the list of options.

Example:

MUI_FORM(51)        /* Parent Form */
MUI_STYLE(0)
MUI_LABEL(5,40, "Color:")
MUI_XYAT("PP",60, 40, 52, "red|orange|yellow|green|cyan|azure|blue|violet|magenta|rose")
MUI_STYLE(0)
MUI_GOTO(64, 59, 50, " Ok ")

MUI_FORM(52) /* Child Form, called by "PP" element */
MUI_STYLE(0)
MUI_XYA("CC", 5, 38, 0) /* Three child elements of the same type "CC" */
MUI_XYA("CC", 5, 49, 1) 
MUI_XYA("CC", 5, 60, 2)

List Selection (Child form, uint16, dynamic list)

Animation:
Description:

Select one option out of a list of options. The number of the selected option will be stored via valptr (uint16_t *, first option in the list has the number 0).

The selection will happen in a child form. The child form must include on or more child fields (MUI_XYA()). Only one type of child field is allowed (all active child fields must have the same ID). Other active elements than the child field should not be used in the child form.
MUIF Macro:

MUIF entry: MUIF_U8G2_U16_LIST(id, valptr, dataptr, getcb, cntcb, cb)
- id: Unique id for this field
- valptr: The address of the uint16_t variable
- dataptr: Optional data pointer which will be passed to the callback functions (use NULL if not used)
- getcb: A callback function, which should return a \0 terminated string with the option name at the provided index. Prototype: const char *get_str(void *data, uint16_t index)
- cntcb: A callback function, which should retun the total number of elements in the list. Prototype: uint16_t get_cnt(void *data)
- cb: One of the following MUIF Callbacks (pi):
  - mui_u8g2_u16_list_parent_wm_pi: Use this field on the parent form
  - mui_u8g2_u16_list_child_w1_pi: Use this field on the child form
FDS Macro:
- MUI_XYA("PP", x, y, arg): Defines a list of options, separated with |. The user can select one option. The first option has the number 0. arg defines the form number of the child form. Use this for mui_u8g2_u16_list_parent_wm_pi.
- MUI_XYA("CC", x, y, n): Defines one or more fields on the child form. Each field must have the same id (here: "CC"), but must have a unique number n starting with 0. These fields define the scroll area for the list of options. Use this for mui_u8g2_u16_list_child_w1_pi.

Example:

static const char *animals[] = { 
  "Bird", "Bison", "Cat", "Crow", "Dog", "Elephant", "Fish", "Gnu", "Horse", 
  "Koala", "Lion", "Mouse", "Owl", "Rabbit", "Spider", "Turtle", "Zebra" };
  
uint16_t animals_get_cnt(void *data) {
  return sizeof(animals)/sizeof(*animals);    /* number of animals */
}
const char *animals_get_str(void *data, uint16_t index) {
  return animals[index];
}
...
uint16_t selection = 0;

MUIF_U8G2_U16_LIST("PP", &selection, NULL, animals_get_str, animals_get_cnt, mui_u8g2_u16_list_parent_wm_pi)
MUIF_U8G2_U16_LIST("CC", &selection, NULL, animals_get_str, animals_get_cnt, mui_u8g2_u16_list_child_w1_pi)

MUI_FORM(81)
MUI_STYLE(0)
MUI_LABEL(5,40, "Animal:")
MUI_XYA("PP",50, 40, 82)     /* jump to sub form 82 */
MUI_GOTO(64, 59, 80, " Ok ")

MUI_FORM(82)
MUI_STYLE(0)
MUI_XYA("CC", 5, 38, 0) 
MUI_XYA("CC", 5, 49, 1) 
MUI_XYA("CC", 5, 60, 2)

Scrollable Jump Table (static)

Description:

Implements a scrollable list of buttons. Each button can be used to jump to a different form (Limitation: The forms 0, 124 and 255 can't be used as jump target, because these number have special meanings in the text argument).

If this function receives the "select" event then it will jump to the target form and additionally store the current menu cursor position. A jump back to this form (for example with the mui_u8g2_btn_goto_xxx MUIF Callback) will restore the menu cursor position.
MUIF Macro: (pi)
- MUIF_RO("GP",mui_u8g2_goto_data): Create field for the definition of jump targets
- MUIF_BUTTON("GC", mui_u8g2_goto_form_w1_pi): Buttons for "inverted text cursor"
- MUIF_BUTTON("GC", mui_u8g2_goto_form_w1_pf): Buttons for "frame around text cursor"
FDS Macro:
- MUI_DATA("GP", ...): Defines a list of jump targets (form number and form name). Entries in this list are separated with the | symbol. Each entry starts with the form number prefixed with MUI_(see example below).
- MUI_XYA("GC", x, y, n): Defines one or more fields on the form. Each field must have the same id (here: "GC"), but must have a unique number n starting with 0. These fields define the scroll area for the jump targets.
Note: Do not use any other fields on the same form than the above mention MUIF fields.

Example:

MUI_FORM(1)
MUI_STYLE(0)
MUI_DATA("GP", 
    MUI_10 "Goto Buttons|"
    MUI_20 "uint8 Number|"
    MUI_30 "uint8 Checkbox|"
    MUI_40 "uint8 Cycle Options|"
    MUI_50 "uint8 ParentChild Select|"
    MUI_60 "uint8 Char/Text Input|"
    MUI_70 "uint16 Cycle Options|"
    MUI_80 "uint16 ParentChild Select")
MUI_XYA("GC", 5, 25, 0) 
MUI_XYA("GC", 5, 37, 1) 
MUI_XYA("GC", 5, 49, 2) 
MUI_XYA("GC", 5, 61, 3)

Scrollable Jump Table (dynamic)

Description:

Implements a scrollable list of buttons. Each button can be used to jump to a different form (Limitation: The form 0 can't be used as jump target, because this number has a special meanings in strings).

If this function receives the "select" event then it will jump to the target form and additionally store the current menu cursor position. A jump back to this form (for example with the mui_u8g2_btn_goto_xxx MUIF) will restore the menu cursor position.
MUIF Macro:

MUIF entry: MUIF_U8G2_U16_LIST(id, valptr, dataptr, getcb, cntcb, muifcb)
- id: Unique id for this field
- valptr: The address of a uint16_t variable (optional, use NULL if not used)
- dataptr: Optional data pointer which will be passed to the callback functions (use NULL if not used)
- getcb: A callback function, which should return a \0 terminated string with the form name at the provided index. The first char of this name must be the form number. Prototype: const char *get_str(void *data, uint16_t index)
- cntcb: A callback function, which should retun the total number of elements in the list. Prototype: uint16_t get_cnt(void *data)
- muifcb: mui_u8g2_u16_list_goto_w1_pi (pi)
FDS Macro:

MUI_XYA("ID", x, y, n): Defines one or more fields on the form. Each field must have the same id, but must have a unique number n starting with 0. These fields define the scroll area for the jump targets.
Note: Do not use any other fields on the same form than the above mention MUIF fields.

Example:

uint16_t menu_get_cnt(void *data) {
  return 10;    /* number of menu entries */
}

const char *menu_get_str(void *data, uint16_t index) {
  static const char *menu[] = { 
    MUI_1 "Goto Main Menu",
    MUI_10 "Enter a number",
    MUI_11 "Parent/Child Selection",
    MUI_13 "Checkbox",
    MUI_14 "Radio Selection",
    MUI_15 "Text Input",
    MUI_16 "Single Line Selection",
    MUI_17 "List Line Selection",
    MUI_18 "Parent/Child List",
    MUI_20 "Array Edit",
  };
  return menu[index];
}
...
uint16_t selection = 0;
...
MUIF_U8G2_U16_LIST("ID", &selection, NULL, menu_get_str, menu_get_cnt, mui_u8g2_u16_list_goto_w1_pi),

MUI_FORM(3)
MUI_STYLE(0)
MUI_XYA("ID", 5, 25, 0) 
MUI_XYA("ID", 5, 37, 1) 
MUI_XYA("ID", 5, 49, 2) 
MUI_XYA("ID", 5, 61, 3)

MUI API

begin

C++/Arduino Prototype:

void MUI::begin(U8G2 &u8g2, fds_t *fds, muif_t *muif_list, size_t muif_cnt)
void mui_Init(mui_t *ui, void *graphics_data, fds_t *fds, muif_t *muif_list, size_t muif_cnt)

Description: Setup MUI and connect MUI to u8g2. After the setup of MUI, the menu system is inactive and has no current form assigned. A call to gotoForm is required to activate MUI.
Arguments: -
- u8g2 : Pointer to the u8g2 structure (C interface only).
- fds: Address of the field definition string
- muif_list: Address of the MUIF list
- muif_list: Number of entries in the MUIF list
- ui: Address of an empty and unused mui_t object.
- graphics_data: Address of the u8g2 C structure (C++/Arduino: (void *)u8g2.getU8g2()).
Returns: -
See also: Minimal Example
Example:

U8G2_UC1701_EA_DOGS102_1_4W_HW_SPI u8g2(U8G2_R0, /* cs=*/ 10, /* dc=*/ 9, /* reset=*/ 8);
MUIU8G2 mui;

muif_t muif_list[] = {  
  MUIF_VARIABLE("BN", NULL, mui_u8g2_btn_exit_wm_fi)
};

fds_t fds_data[] = 
MUI_FORM(1)
MUI_XYT("BN", 64, 30, " Select Me ")
;

void setup(void) {
  u8g2.begin(/* menu_select_pin= */ 5, /* menu_next_pin= */ 4, /* menu_prev_pin= */ 2, /* menu_up_pin= */ U8X8_PIN_NONE, /* menu_down_pin= */ U8X8_PIN_NONE, /* menu_home_pin= */ 3);  
  mui.begin(u8g2, fds_data, muif_list, sizeof(muif_list)/sizeof(muif_t));
  mui.gotoForm(/* form_id= */ 1, /* initial_cursor_position= */ 0);
}

getCurrentFormId

C++/Arduino Prototype:

int MUI::getCurrentFormId(void)
int mui_GetCurrentFormId(mui_t *ui)

Description: Return the current form id (argument for MUI_FORM()). This function will return -1 if MUI is not active.
Arguments: -
- ui : Pointer to the mui structure (C interface only).
Returns: The current dorm id or -1

gotoForm

C++/Arduino Prototype:

uint8_t MUI::gotoForm(uint8_t form_id, uint8_t initial_cursor_position)
uint8_t mui_GotoForm(mui_t *ui, uint8_t form_id, uint8_t initial_cursor_position)

Description: Change the current form and cursor position. The cursor focus will be assigned to the initial_cursor_position-th location which can receive cursor focus. Field locations are enumerated in the sequence as they are defined in the FDS string. The value 0 will place the cursor forcus on the first selectable element of the given form with form number id.

Additionally: If MUI is inactive, then this call will activate MUI. gotoForm is usually called after MUI begin.
Arguments: -
- ui : Pointer to the mui structure (C interface only).
- form_id : The form number (defined by FDS macro MUI_FORM
- initial_cursor_position : The selectable field which should receive the cursor focus.
Returns: 0, if the form with id doesn't exist.
See also: Minimal Example

nextField

C++/Arduino Prototype:

void MUI::nextField(void)
void mui_NextField(mui_t *ui)

Description: Send a "next field" event to the current form of the menu system. Usually this should be done, if the user hits the "next" button. The menu system will usually move the cursor to the next field on the form or increment a field value.
Arguments: -
- ui : Pointer to the mui structure (C interface only).
Returns: -
See also: Event Mapping

prevField

C++/Arduino Prototype:

void MUI::prevField(void)
void mui_PrevField(mui_t *ui)

Description: Send a "prev field" event to the current form of the menu system. Usually this should be done, if the user hits the "previous" button. The menu system will usually move the cursor to the previous field on the form or decrement a field value.
Arguments: -
- ui : Pointer to the mui structure (C interface only).
Returns: -
See also: Event Mapping

restoreForm

C++/Arduino Prototype:

void MUI::restoreForm(void)
void mui_RestoreForm(mui_t *ui)

Description: Jump to a previously saved form and cursor position. This is identical to gotoForm except that a previously saved location is used.

The current form and cursor position is saved by the "exit" buttons.
Arguments: -
- ui : Pointer to the mui structure (C interface only).
Returns: -
See also: gotoForm Exit Button MUICountDown.ino

sendSelect

C++/Arduino Prototype:

void MUI::sendSelect(void)
void mui_SendSelect(mui_t *ui)

Description: Send a "select" event to field which has the current cursor focus in the menu system. Usually this should be done, if the user hits the select button.
Arguments: -
- ui : Pointer to the mui structure (C interface only).
Returns: -
See also: Minimal Example, Event Mapping

sendSelectWithExecuteOnSelectFieldSearch

C++/Arduino Prototype:

void MUI::sendSelectWithExecuteOnSelectFieldSearch(void)
void mui_SendSelectWithExecuteOnSelectFieldSearch(mui_t *ui)

Description: This call will search for a EXECUTE_ON_SELECT button (a button which has been defined with MUIF_EXECUTE_ON_SELECT_BUTTON). Then the "select" event is sent to this button. If a EXECUTE_ON_SELECT button is not available on the form, then this function behaves like sendSelect.
Arguments: -
- ui : Pointer to the mui structure (C interface only).
Returns: -
See also: sendSelect, Event Mapping , MUIInputVersatileRotaryEncoder.ino

MUIF Helper Functions

The functions below should be used only within a field function (MUIF):

  typedef uint8_t (*muif_cb)(mui_t *ui, uint8_t msg);

mui_get_U8g2

Prototype:

u8g2_t *mui_get_U8g2(mui_t *ui)

Description: Return a pointer to the u8g2_t structure.
Arguments: -
- ui : Pointer to the mui structure..
Returns: Pointer to the u8g2_t structure
See also: Stopwatch Example

mui_get_x

Prototype:

u8g2_uint_t mui_get_x(mui_t *ui)

Description: Return the x position of a field (usually provided by MUI_XY())
Arguments: -
- ui : Pointer to the mui structure..
Returns: x position
See also: Stopwatch Example

mui_get_y

Prototype:

u8g2_uint_t mui_get_y(mui_t *ui)

Description: Return the y position of a field (usually provided by MUI_XY())
Arguments: -
- ui : Pointer to the mui structure..
Returns: y position
See also: Stopwatch Example