t03 - olikraus/m2tklib GitHub Wiki

Tutorial 3: User Interface Design

This tutorial will show how to design a dialog box which allows the user to enter a number from 0 to 9999.

The layout should be similar to this:

Information text "Num:"	Four digit input field	Ok button

Theory

Steps for creating a menu are:

Identify input fields and read only text.
Map these fields to m2tklib elements (see the Element Reference).
Combine and position elements on the screen with a suitable container element (see also the Element Reference).
Container and field elements can be nested. However, there is an upper bound (somewhere around 5 levels).

Example

Reference: U32 example.

Field Elements

Information text "Num:"

A constant string is displayed by the M2_LABEL Element.

M2_LABEL(el_label, NULL, "Num: ")

Four digit input field

To enter a number, use one of the number entry elements. With four digits, use the M2_U32NUM Element.

M2_U32NUM(el_num, "a1c4", &number)

The "c4" option restricts the number of digits to 4.
The "a1" modifies the behavior how the cursor moves through the field.

Ok button

The "ok" button can be implemented with the M2_BUTTON Element.

M2_BUTTON(el_ok, "", " ok ", fn_ok);

Container Elements

Container elements can group one or more elements together. m2tklib requires two steps:

Group elements together into one list (M2_LIST).
Assign the list to a container element (e.g. M2_VLIST).

The first step combines the address of each element into an array:

M2_LIST(list) = { &el_label, &el_num, &el_ok };

Use the "&" operator to obtain the address of the elements.

The second step creates the container element.

M2_HLIST(list_element, NULL, list);

The M2_HLIST element arranges the elements of list next to each other, side by side.

Result

Altogether the code will look like this:

void fn_ok(m2_el_fnarg_p fnarg) {
  /* do something with the number */
}
M2_LABEL(el_label, NULL, "Num: ");
M2_U32NUM(el_num, "a1c4", &number);
M2_BUTTON(el_ok, "", " ok ", fn_ok);
M2_LIST(list) = { &el_label, &el_num, &el_ok };
M2_HLIST(top_el_hlist, NULL, list);

M2tk m2(&top_el_hlist, m2_es_arduino, m2_eh_2bs, m2_gh_dogm_fbs);

The following picture shows the menu on a EA DOGS102 graphics display:

Conclusion

Use field elements to interact with the user.
Use container elements to combine and arrange field elements.
Finally apply the one "top-level" element to the library.