Skip to content

fnref

Jump to bottom Edit New page
olikraus edited this page Oct 24, 2016 · 3 revisions

Function Reference

checkKey

  • C++ Prototype
void M2tk::checkKey(void)
  • C Prototype
void m2_CheckKey(void)
  • Description

Calls the event source to check hardware events. The event source is applied during the startup procedure of the library. The internal debounce algorithm requires this procedure to be called as often as possible.

This procedure also polls the incremental rotary encoder (see Tutorial 9).

clear

  • C++ Prototype
void M2tk::clear(void)
  • C Prototype
void m2_Clear(void)
  • Description

Remove the entire element hierarchy from m2tklib. This will remove the menu from the output device and also stops the event processing. However, events are still queued. Use setRoot() to apply another menu and enable event processing again.

draw

  • C++ Prototype
void M2tk::draw(void)
  • C Prototype
void m2_Draw(void)
  • Description

Traverse the menu and draw all menu elements on the output device. The graphics handler for the output devices applied during the startup procedure of the library.

  • Example:

Output a menu on the dogm128 library.

#include "Dogm.h"
#include "M2tk.h"
#include "m2ghdogm.h"
int a0Pin = 9;
Dogm dogm(a0Pin);
M2_LABEL(hello_world_label, "", "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() );
}

getKey

  • C++ Prototype
uint8_t M2tk::getKey(void)
  • C Prototype
uint8_t m2_GetKey(void)
  • Description

Returns an event (for example key press events). This procedure returns immediately. M2_KEY_NONE is returned, if there are no events.

  • Return: M2_KEY_NONE if there are no events. Other values are M2_KEY_SELECT, M2_KEY_SELECT2 (v1.11), M2_KEY_EXIT, M2_KEY_NEXT, M2_KEY_PREV, M2_KEY_DATA_UP, M2_KEY_DATA_DOWN, M2_KEY_REFRESH`.
  • Note: This procedure should not be called if there is a visible menu. Calling this procedure will remove the key from the event queue. The event will have no effect on the menu any more. There is only one application, where this procedure might be usefull. Usually keys are handled by handleKey().
  • See also: handleKey

getRoot

  • C++ Prototype
m2_rom_void_p M2tk::getRoot(void)
  • C Prototype
m2_rom_void_p m2_GetRoot(void)
  • Description

Return the current root element. This will return the element which was passed to the constructor or to m2_Init(). The root element might be changed by the ROOT button or by setRoot()

Init

handleKey

  • C++ Prototype
uint8_t M2tk::handleKey(void)
  • C Prototype
uint8_t m2_HandleKey(void)
  • Description

A pending event from the hardware is mapped on some action on the current menu element. The menu should be redrawn if this procedure returns a none-zero value. Events are not handled if the current root element is equal to &m2_null_element. In this case, use getKey() to get the events manually.

  • Example:

A typical "loop" within the Arduino environment. The m2_CheckKey() procedure is called much more often than the m2_HandleKey(). This example uses the C version of the M2TKLIB procedures.

void loop() {
  m2_CheckKey();
  if ( m2_HandleKey() != 0 )
  {
    dogm.start();
    do{
      m2_CheckKey();
      m2_Draw();
    } while( dogm.next() );
  }
}

M2tk

  • C++ Prototype
M2tk::M2tk(m2_rom_void_p element, m2_es_fnptr es, m2_eh_fnptr eh, m2_gfx_fnptr gh)
  • C Prototype
void m2_Init(m2_rom_void_p element, m2_es_fnptr es, m2_eh_fnptr eh, m2_gfx_fnptr gh);
  • Description

Constructor for the M2tk class.

  • Arguments
    • element: Root element of the menu.
    • es: Event source, which connects the menu to hardware buttons.
    • eh: Event handler, which maps hardware events to some specific actions on the manu.
    • gh: Graphics handler, which writes the menu to an output device.
  • See also:
  • Notes

Event source

m2_es_sdl Event source for the SDL library.
m2_es_arduino Event source for Arduino environment. One button per pin.
m2_es_arduino_rotary_encoder m2_es_arduino with additional support for incremental rotary encoder (Tutorial 9) v1.09
m2_es_arduino_serial Reads input from Arduino Serial Monitor (Tutorial 7)
m2_es_avr_u8g Event source for AVR environment. One button per pin.
m2_es_avr_rotary_encoder_u8g Event source m2_es_avr_u8g with support for incremental rotary encoder. v1.09

The event source reads input from external pins to generate key events. The external pin number is assigned with setPin(). External pin number can be assigned to:

  • M2_KEY_SELECT: Event sources m2_es_arduino, m2_es_arduino_rotary_encoder and m2_es_avr_u8g will generate a M2_KEY_SELECT if the corresponding pin is low.
  • M2_KEY_SELECT2: Identical to M2_KEY_SELECT (v1.11)
  • M2_KEY_EXIT: Event sources m2_es_arduino, m2_es_arduino_rotary_encoder and m2_es_avr_u8g will generate a M2_KEY_EXIT if the corresponding pin is low.
  • M2_KEY_NEXT: Event sources m2_es_arduino, m2_es_arduino_rotary_encoder and m2_es_avr_u8g will generate a M2_KEY_NEXT if the corresponding pin is low.
  • M2_KEY_PREV: Event sources m2_es_arduino, m2_es_arduino_rotary_encoder and m2_es_avr_u8g will generate a M2_KEY_PREV if the corresponding pin is low.
  • M2_KEY_DATA_UP: Event sources m2_es_arduino, m2_es_arduino_rotary_encoder and m2_es_avr_u8g will generate a M2_KEY_DATA_UP if the corresponding pin is low.
  • M2_KEY_DATA_DOWN: Event sources m2_es_arduino, m2_es_arduino_rotary_encoder and m2_es_avr_u8g will generate a M2_KEY_DATA_DOWN if the corresponding pin is low.
  • M2_KEY_HOME: Event sources m2_es_arduino, m2_es_arduino_rotary_encoder and m2_es_avr_u8g will generate a M2_KEY_HOME if the corresponding pin is low.
  • M2_KEY_HOME2: Same as M2_KEY_HOME, introduced in "v1.11"
  • M2_KEY_ROT_ENC_A, M2_KEY_ROT_ENC_B: Attach rotary encoder to these two pins. Event source m2_es_arduino_rotary_encoder will generate a M2_KEY_NEXT or M2_KEY_PREV.
  • M2_KEY_Q1 ... M2_KEY_Q4 (v1.11): Quick keys (format option "q1" ... "q4")

Event handler

Event Handler Description Supported Events
m2_eh_2bs Two button handler M2_KEY_SELECT, M2_KEY_NEXT, M2_KEY_HOME, M2_KEY_HOME2
m2_eh_4bs Four button handler M2_KEY_SELECT, M2_KEY_NEXT, M2_KEY_PREV, M2_KEY_EXIT, M2_KEY_HOME, M2_KEY_HOME2
m2_eh_4bd Four button handler (explicit data entry) M2_KEY_SELECT, M2_KEY_NEXT, M2_KEY_PREV, M2_KEY_EXIT, M2_KEY_HOME, M2_KEY_HOME2
m2_eh_6bs Six button handler M2_KEY_SELECT, M2_KEY_NEXT, M2_KEY_PREV, M2_KEY_EXIT, M2_KEY_DATA_UP, M2_KEY_DATA_DOWN, M2_KEY_HOME, M2_KEY_HOME2, M2_KEY_Q1 ... M2_KEY_Q4

The M2_KEY_HOME event is available with version 1.09. The M2_KEY_HOME will activate the home menu, which can be set with setHome(). The M2_KEY_HOME2 event is available with version 1.11.

Quick keys M2_KEY_Q1 ... M2_KEY_Q4 are available with version 1.11.

The M2_KEY_SELECT2 key event is supported by all handlers. M2_KEY_SELECT2 is mapped to M2_KEY_SELECT (M2_KEY_SELECT2 is available with v1.11).

Graphics handler

Handler Library Include Focus Highlight Font Description
m2_gh_dogm_bf Dogm-Lib m2ghdogm.h Box Frame setFont B/W Handler
m2_gh_dogm_bfs Dogm-Lib m2ghdogm.h Box Shadow Frame setFont B/W Handler
m2_gh_dogm_fb Dogm-Lib m2ghdogm.h Frame Box setFont B/W Handler
m2_gh_dogm_fbs Dogm-Lib m2ghdogm.h Shadow Frame Box setFont B/W Handler
m2_gh_dogm_ffs Dogm-Lib m2ghdogm.h Shadow Frame Shadow Frame setFont B/W Handler
m2_gh_dogxl160 Dogm-Lib m2ghdogm.h setFont Handler for DOGXL160 GR mode
m2_gh_glcd_bf GLCD m2ghglcd.h Box Frame fixed B/W Handler
m2_gh_glcd_ffs GLCD m2ghglcd.h Shadow Frame Shadow Frame fixed B/W Handler
m2_gh_glcd_ubf GLCD m2ghglcd.h Box Frame setFont B/W Handler
m2_gh_glcd_uffs GLCD m2ghglcd.h Shadow Frame Shadow Frame setFont B/W Handler
m2_gh_lc Liquid Crystal m2ghlc.h [ ] fixed Character LCD Handler
m2_gh_u8g_bf U8glib m2ghu8g.h Box Frame setFont B/W Handler
m2_gh_u8g_bfs U8glib m2ghu8g.h Box Shadow Frame setFont B/W Handler
m2_gh_u8g_fb U8glib m2ghu8g.h Frame Box setFont B/W Handler
m2_gh_u8g_ffs U8glib m2ghu8g.h Shadow Frame Shadow Frame setFont B/W Handler
m2_gh_u8g_cffs U8glib m2ghu8g.h Shadow Frame Shadow Frame setFont 332 Color Handler
m2_gh_arduino_serial Arduino Serial Monitor m2.h [ ] fixed Simulation of 4x20 Character LCD

Graphic handlers are described in more detail on the Graphics Handler Wiki Page and U8glib Graphics Handler Wiki.

setFont

  • C++ Prototype
void M2tk::setFont(uint8_t font_idx, const void *font_ptr)
  • C Prototype
void m2_SetFont(uint8_t font_idx, const void *font_ptr)
  • Description

Apply a font to the menu system. The font_ptr is passed to the graphics handler without modification. It depends on the graphcis handler how this pointer is interpreted. The graphics handler for the dogm128 library accept fonts from the dogm128 library (setFont). Up to four different fonts can be specified (font_idx 0 to 3). A default font at font_idx 0 should be applied. The font index is later used as argument for the font option.

  • Arguments
    • font_idx: A number between 0 and 3.
    • font_ptr: Pointer, which is passed to the graphics handler.
  • Example dogm128
M2tk m2(&hello_world_label, NULL, NULL, m2_gh_dogm_fbs);

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

Note: Use m2_Arial14 and m2_System5x7 for the system fonts.

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

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

setHome

setHome2

  • C++ Prototype
void M2tk::setHome(m2_rom_void_p element)
void M2tk::setHome2(m2_rom_void_p element)
  • C Prototype
void m2_SetHome(m2_rom_void_p element)
void m2_SetHome2(m2_rom_void_p element)
  • Description

Define the menu which gets activated by the M2_KEY_HOME event.

  • Arguments
    • element: Root element of a menu structure.
  • Note: setHome procedure is available with v1.09. setHome2 procedure is available with v1.11.
  • See also: M2tk

setKey

  • C++ Prototype
void M2tk::setKey(uint8_t key)
  • C Prototype
void m2_SetKey(uint8_t key)
  • Description

Put a key event into the queue. It is safe to call this procedure inside an interrupt procedure (ISR).

  • Arguments
    • key: A key event (M2_KEY_NEXT, M2_KEY_PREV, ...).
  • See also: M2tk

SetLiquidCrystal

  • Include
#include "M2tk.h"
#include "m2ghlc.h"
  • C++ Prototype
void m2_SetLiquidCrystal(LiquidCrystal *lc_ptr, uint8_t cols, uint8_t rows)
  • Description

Apply the address of the Liquid Crystal object to the graphics handler m2_gh_lc. A call to this procedure is only useful if m2_gh_lc is passed as an argument to M2tk.

  • Arguments
    • lc_ptr: Address of the lcd object.
    • cols: Number of columns of the character display.
    • rows: Number of rows of the character display.
  • Example
LiquidCrystal lcd(12, 11, 5, 4, 3, 2);

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

setPin

  • C++ Prototype
void M2tk::setPin(uint8_t key, uint8_t pin)
  • C Prototype
void m2_SetPin(uint8_t key, uint8_t pin);
  • Description

Connect an external pin of the hardware to an event. Events are M2_KEY_SELECT, M2_KEY_EXIT, M2_KEY_NEXT, M2_KEY_PREV, ... . The event source defines the interpretation of the argument pin. The event source for Arduino environment assumes same pin numbers as required for digitalRead(). Pin values for M2_KEY_ROT_ENC_A and M2_KEY_ROT_ENC_B are used to connect the incremental rotary encoder.

  • Arguments
    • key: Key event: M2_KEY_SELECT, M2_KEY_EXIT, M2_KEY_NEXT, M2_KEY_PREV, M2_KEY_DATA_UP, M2_KEY_DATA_DOWN, M2_KEY_HOME, M2_KEY_HOME2, M2_KEY_ROT_ENC_A, M2_KEY_ROT_ENC_B, v1.11: M2_KEY_Q1 ... M2_KEY_Q4
    • pin: Specific value for the event source to identify the hardware pin,
  • Example
    • A typical setup sequence with C statements.
void setup() {  
  m2_Init(&top_el, m2_es_arduino, m2_eh_2bs, m2_gh_dogm_fbs);	
  m2_SetFont(0, font_7x13);
  m2_SetPin(M2_KEY_SELECT, 2);
  m2_SetPin(M2_KEY_NEXT, 3);
}

* A complete example is [here](elref#button).
  • Note: M2_KEY_HOME is available with v1.09.
  • See also: M2tk

setRoot

  • C++ Prototype
void M2tk::setRoot(m2_rom_void_p element, uint8_t next_cnt = 0, uint8_t change_value = 0)
  • C Prototype
void m2_SetRoot(m2_rom_void_p element)
void m2_SetRootExtended(m2_rom_void_p element, uint8_t next_cnt, uint8_t change_value)
  • Description

Change and apply a new menu structure. The new root element is assigned within the next call to handleKey(). The focus cursor in the new menu structure will be placed at the first selectable or writable element if next_cnt is not provided or zero. For any other value of next_cnt, the focus cursor will be moved forward (next_cnt steps).

  • Arguments
    • element: The new root element of the menu.
    • next_cnt: Number of NEXT events, send to the new root element.
    • change_value: This value will be passed to the "root change" callback
  • Note: The next_cnt and change_value arguments are available with v1.09.
  • Example: See ROOT element
  • See also: M2tk, handleKey

setRootChangeCallback

  • C++ Prototype
void M2tk::setRootChangeCallback(m2_root_change_fnptr cb)
  • C Prototype
void m2_SetRootChangeCallback(m2_root_change_fnptr cb)
  • Description

Change and apply a new callback procedure. This procedure will be called if the root element is changed. The argument cb must be a procedure with the following arguments:

void root_change_cb(m2_rom_void_p new_root, m2_rom_void_p old_root, uint8_t change_value);
  • Arguments
    • cb: A callback procdure.
  • Note: This procedure is available with v1.09.

Links

Add a custom footer
Add a custom sidebar
Clone this wiki locally