elref - olikraus/m2tklib GitHub Wiki

General Notes on Elements

Use of Elements

  • Elements are implemented as C-macros.
  • Elements do not return any values: Do not assign the Element to something.
  • Elements should have global scope. Avoid using them inside C-functions.
  • The first argument of an element is always its name. Elements are referred by this name.
  • To refer an element, use the address operator '&' together with the name (M2_LIST is an exception, but M2_LIST is also not a real element)
  • The second argument of an element is always a format string which provides additional information about style, format and behavior of the element. The format string can be NULL.

Naming Convention

This is a suggestion for a useful naming strategy of your elements. Usually there will be more than one menu (element hierarchy) in a program: The second part in the element name is a unique name of the menu.

The element name has three parts:

  1. Elements start with el_, top elements of the element hierarchy start with top_el_.
  2. Second part is the name of the element hierarchy.
  3. Final part is either a user invented name for the field or the field type (u8, label, ...).

The list name (M2_LIST argument) has three parts:

  1. Lists start with list_.
  2. Second part is the name of the element hierarchy.
  3. Final part is either a user invented name or empty if this is the only list in the element hierarchy.

See Tutorial 4 for an application of the naming convention.

Element Format String

Syntax

  • A format string is a sequence of format options.
  • A format option is a single character followed by a number.
  • Example: "f2w40". Depending on the element, this format string will select font 2 and render the element at a width of 40 pixel.
  • Valid format options are described along with the elements (see below).

Width and Height

Lowercase letters "w" and "h" set the pixel size of the element without the border. This means, that the resulting size of the element is the value provided by "w" or "h" together with the current border. Uppercase letters calculate the pixel size from the display height or width. The pixel size for the value v as an argument to "W" is v*display_width/64.

Quick Key

Version v1.11 introduces "quick keys". An element can have the format option "q1" to "q4". If the corresponding quick key is pressed (M2_KEY_Q1 ... M2_KEY_Q4), then this element will automatically receive a select message.

Note: Quick keys are not supported by all event handlers!

Fonts

The value for the font option f depends on the graphics handler. However most handler will implement the following behavior:

Font Option Value Description
0-3 normal fonts
4-7 highlight text
8-11 centered normal font
12-15 centered highlight text

Example:

int a0Pin = 9;
Dogm dogm(a0Pin);

M2_LABEL(label0, "f0", "5x7 abcdefg");
M2_LABEL(label1, "f1", "6x12 abcdefg");
M2_LABEL(label2, "f2", "7x13 abcdefg");
M2_BUTTON(button, "f0", "ok", (m2_button_fnptr)NULL);
M2_LIST(label_list) = { &label0, &label1, &label2, &button };
M2_VLIST(list_element, NULL,label_list);
M2tk m2(&list_element, NULL, NULL, m2_gh_dogm_fbs);

void setup() {
  m2.setFont(0, font_5x7);
  m2.setFont(1, font_6x12);
  m2.setFont(2, font_7x13);
}

void loop() {
  dogm.start();
  do{
    m2.draw();
  } while( dogm.next() );
}

Overview

Options are documented and valid only for a specific element. However the same option (character) is usually used only for one functionality across all elements:

Option Description Version
+ Control visibility of the '+' sign
a Automatic down/selection option (M2_TEXT, M2_U32NUM, M2_U8NUM)
b Border modifification (M2_LABEL and variants)
c columns (M2_TEXT, M2_GRIDLIST, M2_U32NUM, M2_U8NUM)
d Internal Option, do not use! (deep draw)
e, E Extra column size (M2_STRLIST, M2_2LMENU) v1.08
F Extra column font (M2_STRLIST, M2_2LMENU) v1.08
f Font selection (all elements)
h, H Element height (all elements)
l Visible line count (M2_VSB, M2_STRLIST, M2_INFO)
n Change initial focus to field n (M2_ROOT) v1.09
q Quick key v1.11
r Read only flag (all elements)
t Enable element for touch screen mode (all elements, except TSK) v1.10
v M2_RADIO: Individual button value, M2_ROOT: Root change value M2_ROOT: v1.09
w, W Element width (all elements)
x X-position within M2_XYLIST
y Y-position within M2_XYLIST
- M2_ALIGN
M2_ALIGN
. Dot position (M2_U32NUM)

Note: 't' defaults to 1 for M2_BUTTON, M2_BUTTONPTR, M2_ROOT, M2_XBMBUTTON and M2_XBMROOT.

Forward Declaration

In many cases it is sufficient that subsequent elements refer to previous elements. However sometimes it is required to refer to an element which is defined later. Typical examples include independent menus which refer to each other. Such an example is provided together with the change ROOT button. The syntax for this forward declaration is described below with every element.

Null Element

The Null element is a predefined element, which does nothing. Its name is

m2_null_element

Use

&m2_null_element

as a reference to the null element.

Examples

The reference part of this document usually does not provide complete examples. Instead, complete examples are discussed now.

Differences between the graphics devices

Include

  • Dogm128 Library: Dogm.h and m2ghdogm.h
  • Liquid Crystal: m2ghlc.h

Setup

  • Graphics Library: Usually the user must provide at least one font.
  • Liquid Crystal: Fonts are build in. setFont is not required.

Loop

  • Dogm128 Library: Requires "picture loop"
  • All others: Just call draw

Dogm128 Library

This is the complete U32NUM example for the Dogm128 library:

#include "Dogm.h"
#include "M2tk.h"
#include "m2ghdogm.h"

#ifdef DOGS102_HW
// DOGS102 shield 
uint8_t uiKeyUpPin = 5;
uint8_t uiKeyDownPin = 3;
uint8_t uiKeySelectPin = 4;
#else
// DOGM132, DOGM128 and DOGXL160 shield
uint8_t uiKeyUpPin = 7;
uint8_t uiKeyDownPin = 3;
uint8_t uiKeySelectPin = 2;
#endif

int a0Pin = 9;
Dogm dogm(a0Pin);

uint32_t number = 1234;

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(list_element, NULL, list);
M2tk m2(&list_element, m2_es_arduino, m2_eh_2bs, m2_gh_dogm_fbs);

void setup() {
  m2.setFont(0, font_6x12);
  m2.setPin(M2_KEY_SELECT, uiKeySelectPin);
  m2.setPin(M2_KEY_NEXT, uiKeyDownPin);
}

void loop() {
  m2.checkKey();
  if ( m2.handleKey() ) {
    dogm.start();
    do{
      m2.checkKey();
      m2.draw();
    } while( dogm.next() );
  }
}

Result:

http://wiki.m2tklib.googlecode.com/hg/pic/dogm128/dogm_u32.jpg

Liquid Crystal

This is the complete U32NUM example for the Liquid Crystal library. Note, that there is an additional call to the graphic handler specific procedure m2_SetLiquidCrystal().

#include "M2tk.h"
#include "m2ghlc.h"

LiquidCrystal lcd(12, 11, 5, 4, 3, 2);

uint8_t uiKeySelectPin = 10;
uint8_t uiKeyNextPin = 9;

uint32_t number = 1234;

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(list_element, NULL, list);
M2tk m2(&list_element, m2_es_arduino, m2_eh_2bs, m2_gh_lc);

void setup() {
  m2_SetLiquidCrystal(&lcd, 16, 2);
  m2.setPin(M2_KEY_SELECT, uiKeySelectPin);
  m2.setPin(M2_KEY_NEXT, uiKeyNextPin);
}

void loop() {
  m2.checkKey();
  m2.checkKey();
  if ( m2.handleKey() )
    m2.draw();
  m2.checkKey();
}

Result:

http://wiki.m2tklib.googlecode.com/hg/pic/lcd/lc_u32.jpg

Element Overview

Container Elements

Elements, which include other elements.

M2_ALIGN Align (e.g. center) sub-element
M2_HLIST Horizontal list of elements
M2_GRIDLIST Sub-elements are placed on a virtual grid
M2_VLIST Vertical list of elements
M2_XYLIST Sub-elements are placed at the specified x/y position

Read-Only Elements

M2_BOX Draw box, horizontal or vertical line
M2_INFO Display long text string
M2_LABEL Display text string
M2_LABELPTR Display text string
M2_LABELFN Display text string
M2_LABELP Display text string
M2_XBMLABELP Display XBM bitmap
M2_SPACE Add extra space on the dialog box
M2_SPACECB Add extra space on the dialog box

Numeric Input

M2_S8NUM signed 8 bit value
M2_S8NUMFN signed 8 bit value
M2_U8NUM unsigned 8 bit value
M2_U8NUMFN unsigned 8 bit value
M2_U32NUM unsigned 32 bit value
M2_U32NUMFN unsigned 32 bit value

Other Input

M2_RADIO "radio" buttons
M2_COMBO one of many selection
M2_COMBOPTR one of many selection
M2_COMBOFN one of many selection
M2_TOGGLE on/off switch, toggle button

Text Input

M2_TEXT Text input

Menu Navigation

M2_ROOT Jump to other menus
M2_XBMROOTP Jump to other menus, XBM bitmap
2LMENU Menu table with expandable sub elements
X2LMENU Extended menu table with expandable sub elements

User Function Call

M2_BUTTON Selectable text, which calls a user defined procedure
M2_XBMBUTTONP Selectable XBM bitmap, which calls a user defined procedure
M2_STRLIST Selectable list of strings, which calls a user defined procedure

TSK Elements

Elements for touch screen support.

M2_TSK Selectable string, generate key event
M2_TSKP Selectable string, generate key event
M2_XBMTSKP Selectable XBM picture, generate key event

Additional Elements

M2_VSB Vertical scroll bar

Element Reference

2LMENU

  • Protoype

    M2_2LMENU(el,fmt,first,cnt,menu_data,menu_char,expanded_char,submenu_char)

  • Forward Declaration

    M2_EXTERN_2LMENU(el)

  • Description

    This element defines a scrollable menu with expandable submenus. The state of the menu entry is shown in the first column (e or E option). The vertical scroll bar can be connected to this element.

    The menu is defined by a list of menu entries:

      struct _m2_menu_entry
  {
    const char *label;
    m2_rom_void_p element;
  };
  typedef struct _m2_menu_entry m2_menu_entry;

  • Available: v1.08

  • Arguments

    • el: Name of the element.
    • fmt: Pointer (const char *) to the format string.
    • first: Pointer to uint8_t, which contains the index number of the first string which is visible (range is from 0 to cnt - l).
    • cnt: Pointer to the total number of strings (Pointer to uint8_t).
    • menu_data: List of menu entries (pointer to m2_menu_entry).
    • menu_char: Character (icon) for the non-expanded menu entry. Visible only with e or E option.
    • expanded_char: Character (icon) for the expanded menu entry. Visible only with e or E option.
    • submenu_char: Character (icon) for the sub-menu entry. Visible only with e or E option.

  • Format Options

    • e / E: Pixel/char space of the first colunn / relative space of the first column.
    • f: Font
    • F: Font of the first (extra) column (Default: Same value as f).
    • w: Width, value is interpreted as number of pixels.
    • W: Value is relative width according to the total width of the display (W64 = total display width, W32 = half display width, ...)
    • h: Height
    • l: Number of visible lines (required).
    • x, y: Position of the element, if the parent element is a XYLIST.

  • See also: X2LMENU

  • Example:

    http://wiki.m2tklib.googlecode.com/hg/pic/u8g/u8g_2lmenu.png

    One menu entry has a label and a reference to a target element. The target element should be the root element of an element tree. This tree becomes visible as soon as the entry is selected. The special character "." marks a sub-menu.

    m2_menu_entry menu_data[] =
{
  { "Menu 1", NULL },
  { ". Sub 1-1", &dialog11 },
  { ". Sub 1-2", &dialog12 },
  { "Menu 2", &dialog2 },
  { "Menu 3", NULL },
  { ". Sub 3-1", &dialog31 },
  { ". Sub 3-2", &dialog32 },
  { "Menu 4", &dialog4 },
  { "Menu 5", NULL },
  { ". Sub 5-1", &dialog51 },
  { ". Sub 5-2", &dialog52 },
  { ". Sub 5-3", &dialog53 },
  { NULL, NULL },
};

    Notes to the 2LMENU from the following code:

    • f option is not used, so the font 0 will be used.
    • W defines the relative width of the 2LMENU (47/64 of the total display width)
    • F defines the icon font. The icons for the first column are taken from this font.
    • l defines 4 visible lines
    • el_2lme_cnt will contain the number of menu entries. This value is automatically calculated. Any assignments to this value will be overwritten.
    • el_2lme_first contains the first visible menu entry.
    uint8_t el_2lme_first = 0;
uint8_t el_2lme_cnt = 3;

M2_2LMENU(el_2lme_strlist, "l4e15F3W47", &el_2lme_first, &el_2lme_cnt, menu_data, 65, 102, '\0');
M2_SPACE(el_2lme_space, "W1h1");
M2_VSB(el_2lme_vsb, "l4W4r1", &el_2lme_first, &el_2lme_cnt);
M2_LIST(list_2lme_strlist) = { &el_2lme_strlist, &el_2lme_space, &el_2lme_vsb };
M2_HLIST(el_2lme_hlist, NULL, list_2lme_strlist);
M2_ALIGN(top_el_2l_menu, "-1|1W64H64", &el_2lme_hlist);

ALIGN

  • Protoype

    M2_ALIGN(el,fmt,ref)

  • Forward Declaration

    M2_EXTERN_ALIGN(el)

  • Description

    This element aligns its child (given by ref) within a provided area ('w' and 'h' options of the format string).

  • Arguments

    • el: Name of the element.
    • fmt: Pointer (const char *) to the format string.
    • ref: The address of an element

  • Format Options

    • |: 0 bottom, 1 center (default), 2 up.
    • -: 0 left, 1 center (default), 2 right.
    • w: Width.
    • h: Height.
    • 'W': Relative width (W64 = display width)
    • 'H': Relative height (H64 = display height)
    • x, y: Position of the element, if the parent element is a XYLIST.

  • Note 1: It is required to apply the width and height for this element.

  • Note 2: To center a toplevel element, put it into M2_ALIGN:

    M2_ALIGN(el_centered_toplevel, "W64H64", &el_toplevel);

  • Note 3: With v1.11 there is a further simplification: To center the child element you can use:

    M2_ALIGN(el_centered_toplevel, NULL, &el_toplevel);

BOX

  • Protoype

    M2_BOX(el,fmt)

  • Forward Declaration

    M2_EXTERN_BOX(el)

  • Available: v1.11, U8glib

  • Description

    Read only element: Draw box, horizontal or vertical line. The size of the box is defined by w/h or W/H format options.

  • Arguments

    • el: Name of the element.
    • fmt: Pointer (const char *) to the format string.

  • Format Options

    • h: Absolute pixel height (defaults to 0).
    • H: Relative height according to the total height of the display (H64 = total display height, H32 = half display height, ...)
    • w: Absolute pixel width (defaults to 0).
    • W: Relative width according to the total width of the display (W64 = total display width, W32 = half display width, ...)

BUTTON

BUTTONPTR

  • Protoype

    M2_BUTTON(el,fmt,str,cb_fn)
M2_BUTTONPTR(el,fmt,strptr,cb_fn)

  • Forward Declaration

    M2_EXTERN_BUTTON(el)
M2_EXTERN_BUTTONPTR(el)

  • Description

    This element puts str on the screen. This element can be activated. Procedure cb_fn is called if the element receives the M2_KEY_SELECT message.

    Important: If this button is intended to finish the user input, then the code should do one of the following:

    • Assign a new menu (element hierarchy) or
    • Clear the existing menu

    If this is not done, the old menu might receive (key-) events which might be intended for the new menu. Clearing the menu will stop event queue processing until a new menu is set with setRoot.

  • Arguments

    • el: Name of the element.
    • fmt: Pointer (const char *) to the format string.
    • str: This string will be displayed on the screen.
    • strptr: A pointer which contains the address of a string.
    • cb_fn: Callback procedure

    void my_cb_fn(m2_el_fnarg_p fnarg)

  • Format Options

    • f: Select a font, default is f0
    • r: r1 read-only field, default is r0 (v1.01 and above)
    • x, y: Position of the element, if the parent element is a XYLIST.
    • w: Width. Default: Width of the string.
    • h: Height. Default: Height of the selected font.

  • Example: The unsigned 8 bit value can be modified by the two button elements.

    void fn_plus10(m2_el_fnarg_p fnarg) {
  value += 10;
}
void fn_minus10(m2_el_fnarg_p fnarg) {
  value -= 10;
}
M2_U8NUM(el_u8num, "x15y20", 0, 255, &value);
M2_BUTTON(el_plus10, "x0y1", "-10", fn_minus10);
M2_BUTTON(el_minus10, "x30y1", "+10", fn_plus10);
M2_LIST(list) = { &el_u8num, &el_plus10, &el_minus10 };
M2_XYLIST(list_element, NULL,list);
M2tk m2(&list_element, m2_es_arduino, m2_eh_2bs, m2_gh_dogm_fbs);

    The M2_BUTTONPTR element is used in the Bookmarks example.

    const char *bm_last_name = "";
/* ... */
M2_BUTTONPTR(el_bm_home_last, "f4", &bm_last_name, bm_return_to_last_menu_cb);

    The name of the last menu is stored in the pointer variable bm_last_name. M2_BUTTONPTR will display the sting pointed to by the pointer variable.

COMBO

COMBOPTR

COMBOFN

  • Protoype

    M2_COMBO(el,fmt,var,len,cb_fn)
M2_COMBOPTR(el,fmt,var,lenptr,cb_fn)
M2_COMBOFN(el,fmt,len,combofn_fn)

  • Forward Declaration

    M2_EXTERN_COMBO(el)
M2_EXTERN_COMBOPTR(el)

  • Description

    Selects one string of a predefined list of strings. The selected string is displayed and its corresponding value is stored in a variable. This is a data entry field and processes M2_KEY_DATA_UP and M2_KEY_DATA_DOWN messages. Some event handler also translate the M2_KEY_SELECT into M2_KEY_DATA_UP.

    The first string of the list has the corresponding value 0 and the last string has the value len-1, were len is the total number of strings in the list.

  • Arguments

    • el: Name of the element.
    • fmt: Pointer (const char *) to the format string.
    • var: Pointer to an unsigned 8bit variable (uint8_t *).
    • len: The number of strings in the list.
    • lenptr: Pointer to an unsigned 8bit int which contains the number of strings in the list.
    • cb_fn: Callback procedure const char *fn_idx_to_string(uint8_t idx)
    • combofn_fn: Callback procedure const char *m2_combofn_fnptr(m2_rom_void_p element, uint8_t msg, uint8_t *valptr)
      • msg==M2_COMBOFN_MSG_GET_VALUE: Get current value, write to*valptr.
      • msg==M2_COMBOFN_MSG_SET_VALUE: Set current value, read from *valptr.
      • msg==M2_COMBOFN_MSG_GET_STRING: Return string for current value in *valptr.

  • Format Options

    • f: Select a font, default is f0
    • r: r1 read-only field, default is r0 (v1.01 and above)
    • w: Width. Default: Width of the largest string.
    • h: Height. Default: Height of the selected font.
    • x, y: Position of the element, if the parent element is a XYLIST.

  • Note: COMBOPTR is available with v1.10

  • Note: COMBOFN is available with v1.11

  • Pictures: Combo-Field rendered on a KS0108 display:

    http://wiki.m2tklib.googlecode.com/hg/pic/glcd/glcd_combo.jpg

  • Example: The unsigned 8 bit value will have the value 0, 1, or 2 depending on the selected string 'red', 'green' or 'blue'.

    uint8_t select_color = 0;
const char *fn_idx_to_color(uint8_t idx)
{
  if ( idx == 0 )
    return "red";
  else if (idx == 1 )
    return "green";
  return "blue";
}
M2_COMBO(el_combo1, NULL, &select_color, 3, fn_idx_to_color);

  • Example 2: Use of COMBOPTR

    uint8_t comboptr_val = 0;
uint8_t comboptr_cnt = 3;

/* use same procedure as above */

M2_COMBOPTR(el_comboptr, NULL, &comboptr_val, &comboptr_cnt, fn_idx_to_color);
M2_ALIGN(top_el_comboptr_menu, "W64H64", &el_comboptr);

  • Example 3: Use of COMBOFN

    uint8_t combofn_color = 0;

const char *combofn_color_cb(m2_rom_void_p element, uint8_t msg, uint8_t *valptr)
{
        switch(msg)
        {
                case M2_COMBOFN_MSG_GET_VALUE:
                        *valptr = combofn_color;
                        break;
                case M2_COMBOFN_MSG_SET_VALUE:
                        combofn_color = *valptr;
                        break;
                case M2_COMBOFN_MSG_GET_STRING:
                        if ( *valptr == 0 )
                                return "orange";
                        else if (*valptr == 1 )
                                return "yellow";
                        return "cyan";
        }
        return NULL;
}

M2_COMBOFN(el_combofn1, NULL, 3, combofn_color_cb);

GRIDLIST

  • Protoype

    M2_GRIDLIST(el,fmt,list)

  • Forward Declaration

    M2_EXTERN_GRIDLIST(el)

  • Description

    GRIDLIST is a container element. All sub-elements are displayed as cells of a table. The table has a fixed number of columns (provided with option c). With 5 elements in the list and 2 columns, the layout will be:

    1 2
    3 4
    5

The null element m2_null_element can be used to display nothing at a certain position. The elements have center left alignment.

  • Arguments
    • el: Name of the element.
    • fmt: Pointer (const char *) to the format string.
    • list: A list, defined with M2_LIST. Do NOT use '&' on the list argument.
  • Format Options
    • x, y: Position of the element, if the parent element is a XYLIST.
    • c: Number of columns of the table
  • Example: See RADIO

HLIST

  • Protoype

    M2_HLIST(el,fmt,list)

  • Forward Declaration

    M2_EXTERN_HLIST(el)

  • Description

    HLIST is a container element. All sub-elements are put in one row from left to right.

  • Arguments

    • el: Name of the element.
    • fmt: Pointer (const char *) to the format string.
    • list: A list, defined with M2_LIST. Do NOT use '&' on the list argument.

  • Format Options

    • r: r1 read-only field, default is r0 (v1.01 and above)
    • x, y: Position of the element, if the parent element is a XYLIST.

  • Example: See also U32NUM

    M2_LABEL(el_label, NULL, "Num: ");
M2_U32NUM(el_text, "a1c4", &number);
M2_BUTTON(el_ok, "", " ok ", fn_ok);
M2_LIST(list) = { &el_label, &el_text, &el_ok };
M2_HLIST(list_element, NULL, list);

INFO

  • Protoype

    M2_INFO(el,fmt,first,cnt,str,fn)
M2_INFOP(el,fmt,first,cnt,strp,fn)

  • Forward Declaration

    M2_EXTERN_INFO(el)
M2_EXTERN_INFOP(el)

  • Available: v1.03

  • Description

    INFO displays a string with up to 254 lines, each line with up to 40 characters. INFO works similar to STRLIST, however INFO assigns the calculated number of lines to cnt.

  • Arguments

    • el: Name of the element.
    • fmt: Pointer (const char *) to the format string.
    • first: Pointer to uint8_t, which contains the index number of the first line which is visible (range is from 0 to cnt - l).
    • cnt: Pointer to the calculated number of lines (Pointer to uint8_t).
    • str: Address of a string inside RAM.
    • strp: Address of a string in the PROGMEM area.
    • fn: Callback procedure (will be called if the user selects a line).
    void fn(m2_el_fnarg_p fnarg)

  • Format Options

    • w: Width, value is interpreted as number of pixels.
    • W: Value is relative width according to the total width of the display (W64 = total display width, W32 = half display width, ...)
    • f: Font
    • l: Number of visible lines (required).
    • x, y: Position of the element, if the parent element is a XYLIST.

  • Note: One of w or W is required.

  • Example

    uint8_t total_lines1 = 0;
uint8_t first_visible_line1 = 0;

void goto_top_fn(m2_el_fnarg_p fnarg) {
  m2.setRoot(&el_top);
}

M2_INFOP(el_info1, "W60l" LINES, &first_visible_line1, &total_lines1, part1, goto_top_fn);
M2_VSB(el_vsb1, "W2r1l" LINES, &first_visible_line1, &total_lines1);
M2_LIST(el_list1) = { &el_info1, &el_vsb1};
M2_HLIST(el_part1, NULL, el_list1);

  • Picture: INFO element on a DOGS102 Display (see also the VSB Element)

    http://wiki.m2tklib.googlecode.com/hg/pic/dogm128/dogs102_rapunzel.jpg

LABEL

LABELFN

LABELP

LABELPTR

  • Protoype

    M2_LABEL(el,fmt,str)
M2_LABELFN(el,fmt,labelcb)
M2_LABELP(el,fmt,strp)
M2_LABELPTR(el,fmt,strptr)

  • Forward Declaration

    M2_EXTERN_LABEL(el)
M2_EXTERN_LABELFN(el)
M2_EXTERN_LABELP(el)
M2_EXTERN_LABELPTR(el)

  • Available: LABELPTR v1.03, LABELFN v1.05, Option 'b' v1.08

  • Description

    This element puts a read only text on the screen.

  • Arguments

    • el: Name of the element.
    • fmt: Pointer (const char *) to the format string.
    • str: This string will be displayed on the screen.
    • strp: This string (PROGMEM) will be displayed on the screen.
    • strptr: A Pointer to a string. The string will be displayed on the screen.
    • labelcb: Callback procedure: The returned string will be displayed.
    const char *labelcb(m2_rom_void_p element)

  • Format Options

    • b: no border ("b0") or additional space at top and bottom ("b1")
    • f: Select a font, default is f0
    • x, y: Position of the element, if the parent element is a XYLIST.
    • w: Width. Default: Width of the string.
    • h: Height. Default: Height of the selected font.

  • Example 1:

    #include "Dogm.h"
#include "M2tk.h"
#include "m2ghdogm.h"

int a0Pin = 9;
Dogm dogm(a0Pin);

M2_LABEL(hello_world_label, NULL, "Hello World");
M2tk m2(&hello_world_label, NULL, NULL, m2_gh_dogm_fbs);

void setup() {
  m2.setFont(0, font_7x13);
}

void loop() {
  dogm.start();
  do{
    m2.draw();
  } while( dogm.next() );
}

    LABELPTR requires a pointer variable. The address of this pointer variable is passed to LABELPTR:

    char *str = "text";
M2_LABELPTR(el_labelptr, NULL, &str);

    LABELFN requires a callback procedre. The returned value of this procedure must be a pointer to a string. This string is used as a label text.

    const char *label_cb(m2_rom_void_p element)
{  
  static const char s[] = "label";
  return s;
}

M2_LABELFN(el_labefn, NULL, label_cb);

  • Example 2:

    This example demonstrates the effect of the "b1" option (m2tklib v1.08). The first dot of the following "date entry" dialog is correct ("b1"). The second dot has the default "b0" option and is drawn below the baseline.

    http://wiki.m2tklib.googlecode.com/hg/pic/u8g/u8g_date_b1_b0.png

    uint8_t dt_day = 1;
uint8_t dt_month = 1;
uint8_t dt_year = 12;

void dt_ok_fn(m2_el_fnarg_p fnarg)  {
  m2_SetRoot(&top_el_tlsm);
}

M2_U8NUM(el_dt_day, "c2", 1,31,&dt_day);
M2_LABEL(el_dt_sep1, "b1", ".");		// dot is drawn on the baseline
M2_U8NUM(el_dt_month, "c2", 1,12,&dt_month);
M2_LABEL(el_dt_sep2, "b0", ".");		// dot will be too low 
M2_U8NUM(el_dt_year, "c2", 0,99,&dt_year);

M2_LIST(list_date) = { &el_dt_day, &el_dt_sep1, &el_dt_month, &el_dt_sep2, &el_dt_year };
M2_HLIST(el_date, NULL, list_date);

M2_ROOT(el_dt_cancel, NULL, "cancel", &top_el_tlsm);
M2_BUTTON(el_dt_ok, NULL, "ok", dt_ok_fn);
M2_LIST(list_dt_buttons) = {&el_dt_cancel, &el_dt_ok };
M2_HLIST(el_dt_buttons, NULL, list_dt_buttons);

M2_LIST(list_dt) = {&el_date, &el_dt_buttons };
M2_VLIST(el_top_dt, NULL, list_dt);

RADIO

  • Protoype

    M2_RADIO(el,fmt,variable)

  • Forward Declaration

    M2_EXTERN_RADIO(el)

  • Description

    This element allows to select an element. All element refer to the same variable. If the RADIO element receives a M2_KEY_SELECT message, the value from the format option v is assigned to the variable. This element does not output any text. Instead an icon will be displayed.

  • Arguments

    • el: Name of the element.
    • fmt: Pointer (const char *) to the format string.
    • variable: Address of a variable.

  • Format Options

    • f: Select a font. This might have an effect on the icon size.
    • r: r1 read-only field, default is r0 (v1.01 and above)
    • v: Value
    • x, y: Position of the element, if the parent element is a XYLIST.

  • Picture

    Arduino Hardware with KS0066 16x4 LCD

    http://wiki.m2tklib.googlecode.com/hg/pic/lcd/Radio.jpg

  • Example: The value of variable select_color is changed by the Menu. The default value of the variable should match one of the possible selections.

    uint8_t select_color = 0;

void fn_ok(m2_el_fnarg_p fnarg) {
  /* accept selection */
}

void fn_cancel(m2_el_fnarg_p fnarg) {
  /* discard selection */
}

M2_LABEL(el_label1, NULL, "red");
M2_RADIO(el_radio1, "v0", &select_color);

M2_LABEL(el_label2, NULL, "green");
M2_RADIO(el_radio2, "v1", &select_color);

M2_LABEL(el_label3, NULL, "blue");
M2_RADIO(el_radio3, "v2", &select_color);

M2_BUTTON(el_cancel, NULL, "cancel", fn_cancel);
M2_BUTTON(el_ok, NULL, " ok ", fn_ok);

M2_LIST(list) = { 
    &el_label1, &el_radio1, 
    &el_label2, &el_radio2,  
    &el_label3, &el_radio3, 
    &el_cancel, &el_ok 
};
M2_GRIDLIST(list_element, "c2",list);
M2tk m2(&list_element, m2_es_arduino, m2_eh_2bs, m2_gh_dogm_fbs);

ROOT

  • Protoype

    M2_ROOT(el,fmt,str,new_root_el)

  • Forward Declaration

    M2_EXTERN_ROOT(el)

  • Description

    This element puts str on the screen. This element can be activated. The new root element is assigned to m2tk, if this element receives the M2_KEY_SELECT message.

  • Arguments

    • el: Name of the element.
    • fmt: Pointer (const char *) to the format string.
    • str: This string will be displayed on the screen.
    • new_root_el: Element, which will be assigned as a new root.

  • Format Options

    • f: Select a font, default is f0
    • n: Change inital focus. Simulate n NEXT events. Default is 0 (first writable element) (Available with v1.09).
    • v: "Change root" value, will be the third argument to the "change root" callback procedure (change value, v1.09 and above).
    • r: r1 read-only field, default is r0 (v1.01 and above)
    • x, y: Position of the element, if the parent element is a XYLIST.
    • w: Width. Default: Width of the string.
    • h: Height. Default: Height of the selected font.

  • Example

    • setup() and loop() procedures are removed for this example. These procedures are identical the BUTTON example.
    • Two different methods are used to switch between menues:
      1. A BUTTON element with the setRoot function.
      2. The ROOT element.
    • This example also requires the forward declaration of the top-level elements el_list1 and el_list2.
    M2_EXTERN_VLIST(el_list1);
M2_EXTERN_VLIST(el_list2);

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

void fn_ok1(m2_el_fnarg_p fnarg) {
  m2.setRoot(&el_list2);
}

M2_LABEL(el_label1, NULL, "First Menu");
M2_BUTTON(el_ok1, NULL, " Goto 2 ", fn_ok1);
M2_LIST(list1) = { &el_label1, &el_ok1 };
M2_VLIST(el_list1, NULL, list1);

M2_LABEL(el_label2, NULL, "Second Menu");
M2_ROOT(el_ok2, NULL, " Goto 1 ", &el_list1);
M2_LIST(list2) = { &el_label2, &el_ok2 };
M2_VLIST(el_list2, NULL, list2);

S8NUM

S8NUMFN

  • Protoype

    M2_S8NUM(el,fmt,min,max,number)
M2_S8NUMFN(el,fmt,min,max,s8numcb)

  • Forward Declaration

    M2_EXTERN_S8NUM(el)
M2_EXTERN_S8NUMFN(el)

  • Available: v1.10

  • Description

    This element allows to enter a 8bit signed integer value.

  • Arguments

    • el: Name of the element.
    • fmt: Pointer (const char *) to the format string.
    • min: Lowest possible value.
    • max: Highest possible value.
    • number: Pointer to a 8bit variable.
    • s8numcb: Pointer to a callback procedure.
    int8_t s8numcb(m2_rom_void_p element, uint8_t msg, uint8_t val);

  • Format Options

    • +: Visibility of the '+' sign (+0: prefix positive number with blank, +1: prefix positive numbers with '+', default is +0)
    • c: Number of digits, e.g. "c2" allows numbers between "-99" and "+99". Note, that this setting must fit to the min and max value.
    • f: Select a font, default is f0
    • r: r1 read-only field, default is r0 (v1.01 and above).
    • x, y: Position of the element, if the parent element is a XYLIST.

  • Callback Procedure

    S8NUMFN requires a callback procedre.

    • msg == M2_U8_MSG_SET_VALUE: The new value (val) for the variable must be set. This message also indicates a change of the value. The return value is ignored.
    • msg == M2_U8_MSG_GET_VALUE: The current value must be returned by the callback procedure. Example code:
    int8_t global_value = 0;

int8_t s8_cb(m2_rom_void_p element, uint8_t msg, uint8_t val)
{
  if ( msg == M2_U8_MSG_SET_VALUE )
    global_value = val;
  return global_value;
}

M2_S8NUMFN(el_u8_cb, "+1", -10, 20, s8_cb);

SPACE

SPACECB

  • Protoype

    M2_SPACE(el,fmt)
M2_SPACECB(el,fmt,cb)

  • Forward Declaration

    M2_EXTERN_SPACE(el)
M2_EXTERN_SPACECB(el)

  • Available: v1.03, SPACECB: v1.10

  • Description

    This element occupies some space on the display. The size of the element is defined by the 'w' and 'h' format option. The format option "w1h1" will define a box of 1 pixel (one character for character LCDs) width and height. This element can be used inside VLIST, HLIST or GRIDLIST to add an extra column or row with fixed size.

    The callback procedure "cb" is called, when the dialog is drawn for the first time on the screen.

  • Arguments

    • el: Name of the element.
    • fmt: Pointer (const char *) to the format string.
    • cb: Callback procedure, called once, if this dialog appears on the display. Prototype:
        void fn_space_cb(m2_el_fnarg_p fnarg) {
    }

  • Format Options

    • w: Width.
    • h: Height

  • Example: In the following example, the SPACE element is placed between the STRLIST element and the vertical scroll bar.

    M2_STRLIST(el_strlist, "l2w90", &el_strlist_first, &el_strlist_cnt, el_strlist_getstr);
M2_SPACE(el_space, "w1h1");
M2_VSB(el_strlist_vsb, "l2w5r1", &el_strlist_first, &el_strlist_cnt);
M2_LIST(list_strlist) = { &el_strlist, &el_space, &el_strlist_vsb };
M2_HLIST(el_strlist_hlist, NULL, list_strlist);

  • Example 2: M2_SPACECB can be used as callback procedure for a 2LMENU.

    M2_EXTERN_ALIGN(top_el_spacecb_menu);

uint8_t el_space_u8 = 0;

void fn_space_cb_zero(m2_el_fnarg_p fnarg) {
  el_space_u8 = 0;
  m2_SetRootExtended(&top_el_spacecb_menu, 0, 0);
}

void fn_space_cb_inc(m2_el_fnarg_p fnarg) {
  puts("inc");
  el_space_u8++;
  m2_SetRootExtended(&top_el_spacecb_menu, 1, 0);
}

void fn_space_cb_dec(m2_el_fnarg_p fnarg) {
  el_space_u8--;
  m2_SetRootExtended(&top_el_spacecb_menu, 2, 0);
}

M2_SPACECB(el_space_cb_zero, NULL, fn_space_cb_zero);
M2_SPACECB(el_space_cb_inc, NULL, fn_space_cb_inc);
M2_SPACECB(el_space_cb_dec, NULL, fn_space_cb_dec);
m2_menu_entry space_cb_menu_data[] =  {
  { "Zero", &el_space_cb_zero },
  { "Inc", &el_space_cb_inc },
  { "Dec", &el_space_cb_dec },
  { NULL, NULL },
};
uint8_t el_2lspace_first = 0;
uint8_t el_2lspace_cnt = 3;
M2_U8NUM(el_2lspace_u8, "r1c3", 0, 255, &el_space_u8);
M2_2LMENU(el_2lspace_strlist, "l3e15F3W47", &el_2lspace_first, &el_2lspace_cnt, space_cb_menu_data, 65, 102, '\0');
M2_LIST(list_2lspace_strlist) = { &el_2lspace_u8, &el_2lspace_strlist };
M2_VLIST(el_2lspace_hlist, NULL, list_2lspace_strlist);
M2_ALIGN(top_el_spacecb_menu, "-1|1W64H64", &el_2lspace_hlist);

STRLIST

  • Protoype

    M2_STRLIST(el,fmt, first, cnt, fn)

  • Forward Declaration

    M2_EXTERN_STRLIST(el)

  • Available: v1.03

  • Description

    Displays up to 254 strings in a smaller box with one or more lines.

    This element expects a callback procedure (function pointer fn) which must return the string for given line number and will be informed if a line is selected:

    const char *el_strlist_getstr(uint8_t idx, uint8_t msg)

    The message argument are:

    • M2_STRLIST_MSG_GET_STR: Return string for the provided idx.
    • M2_STRLIST_MSG_SELECT: The user has selected the line with idx.
    • M2_STRLIST_MSG_GET_EXTENDED_STR (v1.08): String for the extra (prefix) column in line idx (Format option e or E).
    • M2_STRLIST_MSG_NEW_DIALOG (v1.08): First message to the callback procedure. The STRLIST element will be visible soon. This message can be used to setup the code for the callback procedure.

    The number of strings (cnt, up to 254) may change and is provided in a variable. The address of cnt must be passed to the element. STRLIST only reads the number of strings from cnt. cnt is not modified by the STRLIST element, but may be changed by other parts of the program at any time.

    Additionally STRLIST requires a variable to store the position of the first visible element (first). cnt and first can be shared with the scroll bar element.

  • Arguments

    • el: Name of the element.
    • fmt: Pointer (const char *) to the format string.
    • first: Pointer to uint8_t, which contains the index number of the first string which is visible (range is from 0 to cnt - l).
    • cnt: Pointer to the total number of strings (Pointer to uint8_t).
    • fn: Callback procedure.
    const char *el_strlist_getstr(uint8_t idx, uint8_t msg)

  • Format Options

    • e / E: Pixel/char space of the first colunn / relative space of the first column.
    • f: Font
    • F: Font of the first (extra) column (Default: Same value as f).
    • w: Width, value is interpreted as number of pixels.
    • W: Value is relative width according to the total width of the display (W64 = total display width, W32 = half display width, ...)
    • h: Height
    • l: Number of visible lines (required).
    • x, y: Position of the element, if the parent element is a XYLIST.
    • t: Enable touch screen support (available with v1.11)

  • Note:

    • One of w or W is required. e or E will activate the additional first column.
    • The message M2_STRLIST_MSG_NEW_DIALOG is generated if this element or a parent of this element is assined to fnref#setRoot, the constructor or the init procedure. If the constructor sends M2_STRLIST_MSG_NEW_DIALOG, then the callback procedure can receive this message before the Arduino setup() is executed.

  • Example

    const char *selected = "Nothing";
const char *el_strlist_getstr(uint8_t idx, uint8_t msg) {
  const char *s = "";
  if  ( idx == 0 )
    s = "Apple";
  else if ( idx == 1 )
    s = "Banana";
  else if ( idx == 2 )
    s = "Peach";
  else if ( idx == 3 )
    s = "Pumpkin";
  else if ( idx == 4 )
    s = "Corn";
  if (msg == M2_STRLIST_MSG_GET_STR) {
    /* nothing else todo, return the correct string */
  } else if ( msg == M2_STRLIST_MSG_SELECT ) {
    selected = s;
  }
  return s;
}

uint8_t el_strlist_first = 0;
uint8_t el_strlist_cnt = 5;

M2_STRLIST(el_strlist, "l2w90", &el_strlist_first, &el_strlist_cnt, el_strlist_getstr);
M2_SPACE(el_space, "w1h1");
M2_VSB(el_strlist_vsb, "l2w5r1", &el_strlist_first, &el_strlist_cnt);
M2_LIST(list_strlist) = { &el_strlist, &el_space, &el_strlist_vsb };
M2_HLIST(el_strlist_hlist, NULL, list_strlist);

M2_LABEL(el_label,NULL, "Selected:");
M2_LABELPTR(el_labelptr,NULL, &selected);
M2_LIST(list_label) = { &el_label, &el_labelptr };
M2_HLIST(el_label_hlist, NULL, list_label);

M2_LIST(list) = { &el_strlist_hlist, &el_label_hlist };
M2_VLIST(el_vlist, NULL, list);
M2_ALIGN(top_el, "-1|1W64H64", &el_vlist);

M2tk m2(&top_el, m2_es_arduino, m2_eh_4bs, m2_gh_glcd_ffs);

    See also the file selection box for another example. The file selection box code pattern also uses the extra column (e / E);

  • Picture: STRLIST element on a DOGS102 Display

    http://wiki.m2tklib.googlecode.com/hg/pic/dogm128/dogs102_strlist.jpg

TEXT

  • Protoype

    M2_TEXT(el,fmt,text,len)

  • Forward Declaration

    M2_EXTERN_TEXT(el)

  • Description

    This element is a text input element.

  • Arguments

    • el: Name of the element.
    • fmt: Pointer (const char *) to the format string.
    • text: Pointer to an array of len characters. The user can modify characters of this text array.
    • len: The length of the text array without the terminating '\0' character.

  • Format Options

    • a: auto-down option
      • "a0": The user has to select the number and can cycle within the characters of the text field (default behavior).
      • "a1": The user does not need to select the text field. The focus cycles between the character of the text field and all other elements of the parent.
    • f: Select a font, default is f0
    • r: r1 read-only field, default is r0 (v1.01 and above). Note: Option a1 has precedence over r1.
    • x, y: Position of the element, if the parent element is a XYLIST.

  • Picture: Text input field on the DOGS102 Display

    http://wiki.m2tklib.googlecode.com/hg/pic/dogm128/dogm_text.jpg

  • Example: The user can put some text into the variable text. Note, that text is an array with 12+1 elements. The string assignment also adds a terminating '\0' character.

    #define TEXT_LEN 12
char text[] = "abcdefghijkl";

void fn_text_ok(m2_el_fnarg_p fnarg) {
  /* do something with the text */
}

M2_LABEL(el_label, NULL, "Enter Text:");
M2_TEXT(el_text, NULL, text, TEXT_LEN);
M2_BUTTON(el_ok, "", " ok ", fn_text_ok);
M2_LIST(list) = { &el_label, &el_text, &el_ok };
M2_VLIST(list_element, NULL, list);
M2tk m2(&list_element, m2_es_arduino, m2_eh_2bs, m2_gh_dogm_fbs);

TOGGLE

  • Protoype

    M2_TOGGLE(el,fmt,variable)

  • Forward Declaration

    M2_EXTERN_TOGGLE(el)

  • Description

    This element allows to select values 0 and 1 for a variable. If the TOGGLE element receives a M2_KEY_SELECT message, the value of the variable will change from zero to 1 or from any other value to zero. This element does not output any text. Instead an icon will be displayed.

  • Arguments

    • el: Name of the element.
    • fmt: Pointer (const char *) to the format string.
    • variable: Address of a variable.

  • Format Options

    • f: Select a font. This might have an effect on the icon size.
    • r: r1 read-only field, default is r0 (v1.01 and above)
    • x, y: Position of the element, if the parent element is a XYLIST.

  • Picture: See M2_RADIO

TSK

TSKP

  • Protoype

    M2_TSK(el,fmt,str,key)
M2_TSKP(el,fmt,strp,key)

  • Forward Declaration

    M2_EXTERN_TSK(el)
M2_EXTERN_TSKP(el)

  • Available: v1.10

  • Description

    A TSK (touch screen key) element generates a key event. It is only useful together with the m2_eh_4bsts or m2_eh_6bsts event handler. The key argument can be one of the following constants: M2_KEY_SELECT, M2_KEY_EXIT, M2_KEY_NEXT, M2_KEY_PREV, M2_KEY_DATA_UP, M2_KEY_DATA_DOWN, M2_KEY_HOME.

    str is displayed as active area for the touch screen.

  • Arguments

    • el: Name of the element.
    • fmt: Pointer (const char *) to the format string.
    • str: This string will be displayed on the screen.
    • strp: This string will be displayed on the screen (PROGMEM).

  • Format Options

    • f: Select a font, default is f0
    • x, y: Position of the element, if the parent element is a XYLIST.
    • w: Width. Default: Width of the string.
    • h: Height. Default: Height of the selected font.

  • See also: Tutorial 10 (Touch Screen Support)

U32NUM

U32NUMFN

  • Protoype

    M2_U32NUM(el,fmt,number)
M2_U32NUMFN(el,fmt,u32numcb)

  • Forward Declaration

    M2_EXTERN_U32NUM(el)
M2_EXTERN_U32NUMFN(el)

  • Available: U32NUMFN v1.05

  • Description

    This element allows to enter a 32bit unsigned integer value.

  • Arguments

    • el: Name of the element.
    • fmt: Pointer (const char *) to the format string.
    • number: Pointer to a 32bit variable.
    • u32numcb: Pointer to a callback procedure.
    uint32_t u32numcb(m2_rom_void_p element, uint8_t msg, uint32_t val);

  • Format Options

    • a: auto-down option
      • "a0": The user has to select the number and can cycle within the digits of the number (default behavior).
      • "a1": The user does not need to select the number. The focus cycles between the digits of the number and all other elements of the parent.
    • c: Number of digits, e.g. "c4" allows numbers between "0000" and "9999".
    • f: Select a font, default is f0
    • r: r1 read-only field, default is r0 (v1.01 and above). Note: Option a1 has precedence over r1.
    • x, y: Position of the element, if the parent element is a XYLIST.
    • .: Provide position of the . character. This option does not affect the number itself. It just shows a dot at the screen at the specified position, counting from right side. Value "123" with option ".1" will appear as "12.3".

  • Callback Procedure

    U32NUMFN requires a callback procedre.

    • msg == M2_U32_MSG_SET_VALUE: The new value (val) for the variable must be set. This message also indicates a change of the value. The return value is ignored.
    • msg == M2_U32_MSG_GET_VALUE: The current value must be returned by the callback procedure. Example code:
    uint32_t global_value = 0;
 
uint32_t u32_cb(m2_rom_void_p element, uint8_t msg, uint32_t val)
{
  if ( msg == M2_U32_MSG_SET_VALUE )
    global_value = val;
  return global_value;
}

M2_U32NUMFN(el_u8_cb, "a1c4", u32_cb);

  • Picture

    Arduino Hardware with KS0066 16x4 LCD

    http://wiki.m2tklib.googlecode.com/hg/pic/lcd/U32.jpg

    Arduino Hardware with DOGS102 Display

    http://wiki.m2tklib.googlecode.com/hg/pic/dogm128/dogm_u32.jpg

  • Example: The user can enter a number between "0000" and "9999". The auto-down option is enabled.

    uint32_t number = 1234;

void fn_ok(m2_el_fnarg_p fnarg) {
  /* do something with the number */
}

M2_LABEL(el_label, NULL, "Num: ");
M2_U32NUM(el_text, "a1c4", &number);
M2_BUTTON(el_ok, "", " ok ", fn_ok);
M2_LIST(list) = { &el_label, &el_text, &el_ok };
M2_HLIST(list_element, NULL, list);
M2tk m2(&list_element, m2_es_arduino, m2_eh_2bs, m2_gh_dogm_fbs);

U8NUM

U8NUMFN

  • Protoype

    M2_U8NUM(el,fmt,min,max,number)
M2_U8NUMFN(el,fmt,min,max,u8numcb)

  • Forward Declaration

    M2_EXTERN_U8NUM(el)
M2_EXTERN_U8NUMFN(el)

  • Available: U8NUMFN v1.05

  • Description

    This element allows to enter a 8bit unsigned integer value.

  • Arguments

    • el: Name of the element.
    • fmt: Pointer (const char *) to the format string.
    • min: Lowest possible value.
    • max: Highest possible value.
    • number: Pointer to a 8bit variable.
    • u8numcb: Pointer to a callback procedure.
    uint8_t u8numcb(m2_rom_void_p element, uint8_t msg, uint8_t val);

  • Format Options

    • c: Number of digits, e.g. "c2" allows numbers between "00" and "99". Note, that this setting must fit to the min and max value.
    • f: Select a font, default is f0
    • r: r1 read-only field, default is r0 (v1.01 and above).
    • x, y: Position of the element, if the parent element is a XYLIST.

  • Callback Procedure

    U8NUMFN requires a callback procedre.

    • msg == M2_U8_MSG_SET_VALUE: The new value (val) for the variable must be set. This message also indicates a change of the value. The return value is ignored.
    • msg == M2_U8_MSG_GET_VALUE: The current value must be returned by the callback procedure.

    Example code:

    uint8_t global_value = 0;

uint8_t u8_cb(m2_rom_void_p element, uint8_t msg, uint8_t val)
{
  if ( msg == M2_U8_MSG_SET_VALUE )
    global_value = val;
  return global_value;
}

M2_U8NUMFN(el_u8_cb, NULL, 0, 10, u8_cb);

  • Picture: U8 and U32 elements (DOGS102 display). Focus is on the U8 field.

    http://wiki.m2tklib.googlecode.com/hg/pic/dogm128/dogm_de_u8.jpg

  • Example: See the BUTTON element.

VLIST

  • Protoype

    M2_VLIST(el,fmt,list)

  • Forward Declaration

    M2_EXTERN_VLIST(el)

  • Description

    VLIST is a container element. All sub-elements are put in one column from top to down.

  • Arguments

    • el: Name of the element.
    • fmt: Pointer (const char *) to the format string.
    • list: A list, defined with M2_LIST. Do NOT use '&' on the list argument.

  • Format Options

    • x, y: Position of the element, if the parent element is a XYLIST.

  • Example: See also TEXT

    M2_LABEL(el_label, NULL, "Enter Text:");
M2_TEXT(el_text, NULL, text, TEXT_LEN);
M2_BUTTON(el_ok, "", " ok ", fn_text_ok);
M2_LIST(list) = { &el_label, &el_text, &el_ok };
M2_VLIST(list_element, NULL, list);

VSB

  • Protoype

    M2_VSB(el,fmt,first,cnt)

  • Forward Declaration

    M2_EXTERN_VSB(el)

  • Available: v1.03

  • Description

    The vertical scroll bar is an element which is usually used together with STRLIST or INFO elements. VSB will display a vertical scroll bar.

  • Arguments

    • el: Name of the element.
    • fmt: Pointer (const char *) to the format string.
    • first: Pointer to uint8_t, which contains the index number of the first element which is visible (range is from 0 to cnt - l).
    • cnt: Pointer to the total number of elements (Pointer to uint8_t).

  • Format Options

    • w: Width (required).
    • h: Height
    • l: Number of visible lines (required).
    • x, y: Position of the element, if the parent element is a XYLIST.
    • t: Enable touch screen support (available with v1.11). Selecting VSB via touch screen will do a "page down" on the connected list.

  • Example: See STRLIST

  • Picture: VSB element on a 16x4 LCD

    http://wiki.m2tklib.googlecode.com/hg/pic/lcd/lc_strlist.jpghttp://wiki.m2tklib.googlecode.com/hg/pic/lcd/lc_rapunzel.jpg

X2LMENU

  • Protoype

    M2_X2LMENU(el,fmt,first,cnt,xmenu_data,menu_char,expanded_char,submenu_char)

  • Forward Declaration

    M2_EXTERN_X2LMENU(el)

  • Description

    This element defines a scrollable menu with expandable submenus. The state of the menu entry is shown in the first column (e or E option). The vertical scroll bar can be connected to this element.

    The menu is defined by a list of menu entries:

      struct _m2_xmenu_entry
  {
    const char *label;
    m2_rom_void_p element;
    m2_strlist_cb_fnptr cb;
  };
  typedef struct _m2_xmenu_entry m2_xmenu_entry;

    Compared to M2_2LMENU, the M2_X2LMENU

    menu data structure has an additional callback procedure cb. The prototype of cb is:

    const char *el_strlist_getstr(uint8_t idx, uint8_t msg)

    The message argument are:

    • M2_STRLIST_MSG_GET_STR: Return string for the provided idx. This message is only send if label equals """ or ".".
    • M2_STRLIST_MSG_SELECT: The user has selected the line with idx. This message is sent, if the user selects the corresponding line.

  • Available: v1.10

  • Arguments

    • el: Name of the element.
    • fmt: Pointer (const char *) to the format string.
    • first: Pointer to uint8_t, which contains the index number of the first string which is visible (range is from 0 to cnt - l).
    • cnt: Pointer to the total number of strings (Pointer to uint8_t).
    • menu_data: List of menu entries (pointer to m2_xmenu_entry).
    • menu_char: Character (icon) for the non-expanded menu entry. Visible only with e or E option.
    • expanded_char: Character (icon) for the expanded menu entry. Visible only with e or E option.
    • submenu_char: Character (icon) for the sub-menu entry. Visible only with e or E option.

  • Format Options

    • e / E: Pixel/char space of the first colunn / relative space of the first column.
    • f: Font
    • F: Font of the first (extra) column (Default: Same value as f).
    • w: Width, value is interpreted as number of pixels.
    • W: Value is relative width according to the total width of the display (W64 = total display width, W32 = half display width, ...)
    • h: Height
    • l: Number of visible lines (required).
    • x, y: Position of the element, if the parent element is a XYLIST.

  • See also: 2LMENU

  • Example: From the Arduino MenuX2L example:

    uint8_t value = 0;
char buf[20];

const char *xmenu_value(uint8_t idx, uint8_t msg)
{  
  if ( msg == M2_STRLIST_MSG_GET_STR ) {
    strcpy(buf, " Value: ");
    itoa((int)value, buf+strlen(buf), 10);
    return buf;
  }
  return "";
}

// define callback procedures which increment and decrement a value
const char *xmenu_inc(uint8_t idx, uint8_t msg) {
  if ( msg == M2_STRLIST_MSG_SELECT  ) {
      value++;
  }
  return "";
}

const char *xmenu_dec(uint8_t idx, uint8_t msg) {
  if ( msg == M2_STRLIST_MSG_SELECT  ) {
      value--;
  }
  return "";
}

m2_xmenu_entry xmenu_data[] = 
{
  { "Menu 1", NULL, NULL },		/* expandable main menu entry */
  { ".", NULL, xmenu_value },		/* The label of this menu line is returned by the callback procedure */
  { ". Inc", NULL, xmenu_inc },		/* This callback increments the value */
  { ". Dec", NULL, xmenu_dec },		/* This callback decrements the value */
  { "Menu 2", NULL, NULL },
  { ". Sub 2-1", &top_el_mnu1_sel, NULL },
  { ". Sub 2-2", &top_el_mnu2_sel, NULL},
  { ". Sub 2-3", &top_el_mnu3_sel, NULL },
  { NULL, NULL, NULL },
};

// The first visible line and the total number of visible lines.
// Both values are written by M2_X2LMENU and read by M2_VSB
uint8_t el_x2l_first = 0;
uint8_t el_x2l_cnt = 3;

// Option l4 = four visible lines
// Option e15 = first column has a width of 15 pixel
// Option W43 = second column has a width of 43/64 of the display width
M2_X2LMENU(el_x2l_strlist, "l4e15W43", &el_x2l_first, &el_x2l_cnt, xmenu_data, '+','-','\0');

XBMBUTTONP

XBMROOTP

  • Protoype

    M2_XBMBUTTONP(el,fmt,w,h,data,element)
M2_XBMROOTP(el,fmt,w,h,data,cb_fn)

  • Forward Declaration

    M2_EXTERN_XBMBUTTONP(el)
M2_EXTERN_XBMROOTP(el)

  • Available: v1.09, U8glib variant only

  • Description

    Same as M2\_BUTTON/M2\_ROOT, but will display a XBM bitmap instead of a string. If the w and/or h format options provide larger values than the XBM bitmap size, then the bitmap is centered into this direction.

  • Arguments

    • el: Name of the element.
    • fmt: Pointer (const char *) to the format string.
    • w: Width of the XBM bitmap data.
    • h: Height of the XBM bitmap data.
    • data: Pointer to the XBM bitmap data (PROGMEM area).
    • element: Pointer to a root element. This element will be assigned as new root element if XBMROOTP is selcted by the user.
    • cb_fn: Callback procedure, will be called if the user selects the XBMBUTTONP element.
      void my_cb_fn(m2_el_fnarg_p fnarg)

  • Format Options

    • n: Change inital focus. Simulate n NEXT events. Default is 0 (first writable element) (Available with v1.09).
    • h: Absolute pixel height (defaults to height of the picture, larger value will center the picture).
    • H: Relative height according to the total height of the display (H64 = total display height, H32 = half display height, ...)
    • v: "Change root" value, will be the third argument to the "change root" callback procedure (change value, v1.09 and above).
    • w: Absolute pixel width (defaults to width of the picture, larger value will center the picture).
    • W: Relative width according to the total width of the display (W64 = total display width, W32 = half display width, ...)
    • r: r1 read-only field, default is r0 (v1.01 and above)
    • x, y: Position of the element, if the parent element is a XYLIST.

  • Example:

    http://wiki.m2tklib.googlecode.com/hg/pic/u8g/u8g_select_xbm.png

    static char memory_card_28_bits[] U8G_PROGMEM = {
  0xF8, 0xFF, 0x3F, 0x00, 0xFC, 0xFF, 0x7F, 0x00, 0xFC, 0xFF, 0xFF, 0x00, 
  0x3C, 0xE7, 0xFC, 0x01, 0x3C, 0xE7, 0xFC, 0x03, 0x3C, 0xE7, 0xFC, 0x03, 
  0x3C, 0xE7, 0xFC, 0x03, 0x3C, 0xE7, 0xFC, 0x03, 0x3C, 0xE7, 0xFC, 0x03, 
  0x3C, 0xE7, 0xFC, 0x03, 0xFC, 0xFF, 0xFF, 0x03, 0xFC, 0xFF, 0xFF, 0x01, 
  0xFC, 0xFF, 0xFF, 0x01, 0xFC, 0xFF, 0xFF, 0x01, 0xFC, 0xFF, 0xFF, 0x01, 
  0xFC, 0xFF, 0xFF, 0x01, 0xFC, 0xFF, 0xFF, 0x03, 0xFC, 0xFF, 0xFF, 0x03, 
  0xFC, 0xFF, 0xFF, 0x03, 0x3C, 0x00, 0xE0, 0x03, 0x1C, 0x00, 0xC0, 0x03, 
  0x1C, 0x00, 0xC0, 0x03, 0x1C, 0x00, 0xC0, 0x03, 0x1C, 0x00, 0xC0, 0x03, 
  0x3C, 0x00, 0xE0, 0x03, 0xFC, 0xFF, 0xFF, 0x03, 0xFC, 0xFF, 0xFF, 0x03, 
  0xF8, 0xFF, 0xFF, 0x01, };
static char tools_28_bits[] U8G_PROGMEM = {
  0x00, 0x00, 0x0E, 0x00, 0x00, 0x80, 0x0F, 0x00, 0x04, 0xC0, 0x0F, 0x00, 
  0x0E, 0xE0, 0x07, 0x00, 0x1F, 0xE0, 0x03, 0x00, 0x3F, 0xF0, 0x03, 0x00, 
  0x3E, 0xF0, 0x03, 0x00, 0x7C, 0xF0, 0x03, 0x00, 0xF0, 0xF0, 0x03, 0x0E, 
  0xE0, 0xF1, 0x07, 0x0F, 0xC0, 0xF3, 0xFF, 0x0F, 0x80, 0xFF, 0xFF, 0x07, 
  0x00, 0xFF, 0xFF, 0x07, 0x00, 0xFE, 0xFF, 0x03, 0x00, 0xFF, 0xFF, 0x01, 
  0x80, 0xFF, 0x7F, 0x00, 0xC0, 0xFF, 0x01, 0x00, 0xE0, 0xFF, 0x01, 0x00, 
  0xF0, 0xFF, 0x03, 0x00, 0xF8, 0xBF, 0x0F, 0x00, 0xFC, 0x1F, 0x3F, 0x00, 
  0xFE, 0x0F, 0x7F, 0x00, 0xCF, 0x07, 0xFF, 0x00, 0xC7, 0x03, 0xFE, 0x01, 
  0xE7, 0x01, 0xFE, 0x01, 0xFF, 0x00, 0xFC, 0x01, 0x7E, 0x00, 0xF8, 0x01, 
  0x3C, 0x00, 0xE0, 0x00, };
void fn_xbm_select_sd(m2_el_fnarg_p fnarg) {
  /* ... */
}
void fn_xbm_select_tools(m2_el_fnarg_p fnarg) {
  /* ... */
}
M2_XBMBUTTONP(el_xbm_mc, "W30H60", 28, 28, memory_card_28_bits, fn_xbm_select_sd);
M2_XBMBUTTONP(el_xbm_tools, "W30H60", 28, 28, tools_28_bits, fn_xbm_select_tools);
M2_LIST(el_xbm_list) = { &el_xbm_mc, &el_xbm_tools };
M2_HLIST(el_xbm, NULL, el_xbm_list);

XBMLABELP

  • Protoype

    M2_XBMLABELP(el,fmt,w,h,data)

  • Forward Declaration

    M2_EXTERN_XBMLABELP(el)

  • Available: v1.09, U8glib variant only

  • Description

    Same as M2\_LABEL, but will display a XBM bitmap instead of a string. If the w and/or h format options provide larger values than the XBM bitmap size, then the bitmap is centered into this direction.

  • Arguments

    • el: Name of the element.
    • fmt: Pointer (const char *) to the format string.
    • w: Width of the XBM bitmap data.
    • h: Height of the XBM bitmap data.
    • data: Pointer to the XBM bitmap data (PROGMEM area).

  • Format Options

    • b: no border ("b0") or additional space at top and bottom ("b1")
    • h: Absolute pixel height (defaults to height of the picture).
    • H: Relative height according to the total height of the display (H64 = total display height, H32 = half display height, ...)
    • w: Absolute pixel width (defaults to width of the picture).
    • W: Relative width according to the total width of the display (W64 = total display width, W32 = half display width, ...)
    • x, y: Position of the element, if the parent element is a XYLIST.

XBMTSKP

  • Protoype

    M2_XBMTSKP(el,fmt,w,h,data,key)

  • Forward Declaration

    M2_EXTERN_XBMTSKP(el)

  • Available: v1.10, U8glib variant only

  • Description

    A TSK (touch screen key) element generates a key event. It is only useful together with the m2_eh_4bsts or m2_eh_6bsts event handler. The key argument can be one of the following constants: M2_KEY_SELECT, M2_KEY_EXIT, M2_KEY_NEXT, M2_KEY_PREV, M2_KEY_DATA_UP, M2_KEY_DATA_DOWN, M2_KEY_HOME.

    The M2_XBMTSKP element shows a XBM bitmap as active area for the touch screen. If the w and/or h format options provide larger values than the XBM bitmap size, then the bitmap is centered.

  • Arguments

    • el: Name of the element.
    • fmt: Pointer (const char *) to the format string.
    • w: Width of the XBM bitmap data.
    • h: Height of the XBM bitmap data.
    • data: Pointer to the XBM bitmap data (PROGMEM area).
    • key: Key event value (see above)

  • Format Options

    • h: Absolute pixel height (defaults to height of the picture).
    • H: Relative height according to the total height of the display (H64 = total display height, H32 = half display height, ...)
    • w: Absolute pixel width (defaults to width of the picture).
    • W: Relative width according to the total width of the display (W64 = total display width, W32 = half display width, ...)
    • x, y: Position of the element, if the parent element is a XYLIST.

  • See also: Tutorial 10 (Touch Screen Support)

XYLIST

  • Protoype

    M2_XYLIST(el,fmt,list)

  • Forward Declaration

    M2_EXTERN_XYLIST(el)

  • Description

    XYLIST is a container element. All sub-elements are put at a specified x-y position on the screen. The x-y position is described in the format string of the sub-elements. The units for x-y values are defined by the graphics handler (see M2tk) and might be pixels (Graphics LCD) or character position (Character LCD).

  • Arguments

    • el: Name of the element.
    • fmt: Pointer (const char *) to the format string.
    • list: A list, defined with M2_LIST. Do NOT use '&' on the list argument.

  • Format Options

    • x, y: Position of the element, if the parent element is also a XYLIST.

  • Example: The sub-elements have x and y format options in their format string to describe the position within the XYLIST. The complete example is show at the button element.

    M2_U8NUM(el_u8num, "x15y20", 0, 255, &value);
M2_BUTTON(el_plus10, "x0y1", "-10", fn_minus10);
M2_BUTTON(el_minus10, "x30y1", "+10", fn_plus10);
M2_LIST(list) = { &el_u8num, &el_plus10, &el_minus10 };
M2_XYLIST(list_element, NULL,list);

Links