t01lc - olikraus/m2tklib GitHub Wiki

Tutorial 1 (`LiquidCrystal` library): Hello World Example

This tutorial will show:

How to display some text on the LCD
The three parts in your program to setup m2tklib for the LiquidCrystal library within the Arduino Environment

Theory

The purpose of the m2tklib is to interact with the user. M2tklib reads button events (see also Tutorial 2) and displays something on an output device. This first example will display a small text on the LCD. Three parts are required:

Define the output for the (Graphics-/Character) LCD. This is called an element tree.
Assign the root element of this element tree to the library and define the type of the output device
Draw the element hierarchy on the output device.

Example

Reference: HelloWorld example.

The following example is simplified and only includes code, which is related to the m2tklib itself:

// ...
#include "M2tk.h"
// ...
LiquidCrystal lcd(12, 11, 5, 4, 3, 2);
// ...

M2_LABEL(hello_world_label, NULL, "Hello World");

M2tk m2(&hello_world_label, NULL, NULL, m2_gh_lc);

void setup() {
  m2_SetLiquidCrystal(&lcd, 16, 2);
  // ...
}

void loop() {
  // ...
  m2.draw();
  // ...
}

In order to work with the library, please include "M2tk.h". The line

M2_LABEL(hello_world_label, NULL, "Hello World");

defines an element which is later displayed and shown to the user. M2_LABEL is a simple read-only element. The first argument for M2_LABEL defines the name (hello_world_label) of the element. The text (third argument) assigned to M2_LABEL will appear on the output device. Elements could be nested, but in this example, the single element M2_LABEL already defindes the complete element tree. So, the element hello_world_label is also the root element and will be assigned to the m2tklib (first argument of the constructor):

M2tk m2(&hello_world_label, NULL, NULL, m2_gh_lc);

As usual within the Arduino Environment, there is a class M2tk, which defines the access to the m2tklib. In this example m2 is defined as an object for this class.

Note: It is not allowed to define more than one M2tk object.

The constructor for m2 accepts several arguments, two of them are important for this example:

First argument: The root element of the element tree.
Last argument: The graphics handler (a procedure called m2_gh_lc) for the output device (LiquidCrystal library)

A graphics handler not only defines the output devices itself. A graphics handler is also responsible how elements are rendered and displayed on the LCD. The M2tklib graphics handler needs to be informed about the LiquidCrystal object and the actual size of the display. This is done with the following command (setup for 16x2 character LCD):

  m2_SetLiquidCrystal(&lcd, 16, 2);

Here is the HelloWorld example for LiquidCrystal library.

#include <LiquidCrystal.h>
#include "M2tk.h"
#include "utility/m2ghlc.h"

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

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

void setup() {
  m2_SetLiquidCrystal(&lcd, 16, 2);
}

void loop() {
  m2.draw();
  delay(500);
}

Result (16x4 LCD, green background):

Conclusion

There can be only one object of class M2tk. This means, that only one output device is allowed.
The content of the display is build by a hierarchical structure of elements.
Any references to elements must use the adress operator &.
Each output device has a special callback procedure.