t02dogm - olikraus/m2tklib GitHub Wiki

Tutorial 2 (dogm128 Library): User Input

This tutoral will show how to read and process input from the user.

Theory

This is how m2tklib works:

Detect a user input and convert the input into an internal m2tklib "event". This step depends on the hardware.
Process the "event". This is independent from the hardware
Display the result (see previous Tutorial)

All three steps are handled by "callback" procedures.

Event Source: Translate Hardware events into m2tklib "events". Within the Arduino Environment this is usually m2_es_arduino (Others are m2_es_arduino_rotary_encoder or m2_es_arduino_serial).
Event Handler: The event handler defines which and how events are handled. Bigger event handlers like the m2_eh_6bs can handle many events (hardware buttons) but also need more memory than small event handlers like the m2_eh_2bs which supports two buttons. In principle all event handlers can be used with all input fields. But if there is only a very limited number of hardware buttons, than it might be less comfortable for the user to enter data. On the other hand, sometimes it is required to build really small devices with only a view number of buttons.
Graphics Handler: The graphics handler allows m2tklib to operate independently from the underlaying output device. For each supported output device, there is at least one graphics handler. Additionally the graphics handler defines the style how the user input fields (elements) are displayed. Two nice handlers for the dogm128 are the m2_gh_dogm_bf (minimizes occupied space on the output device) and the m2_gh_dogm_ffs (it has a nice shadow-like frame). Finally m2_gh_dogxl160 can be used for the dogxl160 display (gray level support)

All available callback procedures (handlers) are listed here.

Example

The example uses the two button handler m2_eh_2bd:

M2tk m2(&el_num, m2_es_arduino, m2_eh_2bd, m2_gh_dogm_bf);

The setup part connects the pins of the Arduino hardware with the events:

  m2.setPin(M2_KEY_SELECT, 4);
  m2.setPin(M2_KEY_NEXT, 3);
  m2.setPin(M2_KEY_PREV, 5);
  m2.setPin(M2_KEY_EXIT, 2);

This is the complete example (U32Plain). The user can enter an unsigned 32bit variable (M2_U32NUM-Field).

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

int a0Pin = 9;
Dogm dogm(a0Pin);

uint32_t number = 1234;

M2_U32NUM(el_num, "a1c4", &number);
M2tk m2(&el_num, m2_es_arduino, m2_eh_2bs, m2_gh_dogm_fbs);

void setup() {
  m2.setFont(0, font_5x7);
  m2.setPin(M2_KEY_SELECT, 4);
  m2.setPin(M2_KEY_NEXT, 3);
  m2.setPin(M2_KEY_PREV, 5);
  m2.setPin(M2_KEY_EXIT, 2);  
}

void loop() {
  m2.checkKey();              // check hardware buttons and queue events
  if ( m2.handleKey() ) {     // get and handle event
    dogm.start();             // start the picture loop (see dogm128 library)
    do{
      m2.checkKey();          // check hardware buttons and queue events
      m2.draw();
    } while( dogm.next() );
  }
}

There are two more procedures in the main loop:

m2.checkKey(): Debounce and detect hardware buttons. Translate hardware events into internal events and put them into an event queue. checkKey() should be called as often as possible.
m2.handleKey(): This procedure will process one event from the queue. A non-zero will be returned if a refresh of the display is required. The first call to this procedure will return a non-zero value.

Conclusion