Getting messages

How to receive touch / key / timer messages.

For the full list see "UI development". Each call below comes with a one-line usage note and an example; signatures come from Lib/c/vml_ui.h (the authoritative source).

ui_msg_get_a(void)

The first argument of the current message (the touch x, the key code, the timer id...).

int x = ui_msg_get_a();

ui_msg_get_b(void)

The second argument of the current message (the touch y...).

int y = ui_msg_get_b();

ui_msg_clear(void)

Empties the message queue (use it when switching scenes or starting a new round, so keystrokes from the previous round are not eaten by this one).

ui_msg_clear();

ui_msg_get_count(void)

How many messages are still queued (a glance at it tells you when to drop a backlog).

if (ui_msg_get_count() > 8) ui_msg_clear();

ui_msg_get_type(void)

The type of the current message (so you do not have to keep msg[0] in your head).

if (ui_msg_get_type() == VML_MSG_TOUCHDOWN) { /* handle it */ }

ui_msg_read(int* msg)

Does not wait: returns VML_MSG_NONE when there is no message. Use this for continuous animation (with your own pacing); event-driven programs use ui_msg_wait (which saves power the rest of the time). Note: it takes only int* msg - there is no timeout, so do not write it the way you write ui_msg_wait.

int m[4];
while (ui_win_is_closed() == 0) {
    if (ui_msg_read(m) == VML_MSG_TOUCHDOWN) { /* handle it */ }
    /* draw a frame */
    ui_2d_present();
}

ui_msg_read_ex(int* msg, int keep)

The version of ui_msg_read that lets you choose whether the message is kept or consumed after reading.

int m[4];
ui_msg_read_ex(m, VML_MSG_CONSUME);

ui_msg_fetch(void)

The pointer-free version (for languages that cannot get an array pointer): returns VML_MSG_NONE when there is nothing, and the arguments are read with ui_msg_get_a() / ui_msg_get_b().

if (ui_msg_fetch() == VML_MSG_TOUCHDOWN) { int x = ui_msg_get_a(); int y = ui_msg_get_b(); }

ui_msg_wait(int* msg, int timeout_ms)

Waits for one message; the argument is int msg[4]. Returns the message type (see the table below); timeout=0 means wait forever.

int m[4];
int t = ui_msg_wait(m, 0);   /* wait forever */

ui_msg_wait_ex(int* msg, int timeout_ms, int keep)

The same; the third argument decides whether the message is kept or consumed after it is read (VML_MSG_KEEP / VML_MSG_CONSUME).

int m[4];
ui_msg_wait_ex(m, 0, VML_MSG_KEEP);   /* do not pop it after reading */

ui_msg_fetch_wait(int timeout_ms)

The pointer-free waiting version: returns the type when one arrives, or VML_MSG_NONE on timeout.

if (ui_msg_fetch_wait(500) == VML_MSG_TIMER) { /* one tick has passed */ }