EV_eventLoop Function (ROM Call 0x158)

events.h

void EV_eventLoop (void);

Enters the loop in which main event messages are collected and dispatched.

EV_eventLoop enters the (endless) loop in which main events are collected and dispatched to the current application. In the normal operation of the calculator (i.e. when no user program is running), the TIOS is just in this loop. Calling this function in the user program makes sense (and may be very useful if you are happy with set of events which are processed in this function) only if the program installs a custom event handler using EV_captureEvents function, so the events may be trapped by the user program.

Here is the exact description what happens in the each iteration of this loop (not in exact order, but this is not important):


Note that when an user ASM program is started, the current application is always "Home screen", until the user changes the current application using EV_startApp or installs thier own event driven "task" using EV_captureEvents. So, if you simply call EV_eventLoop in the your program, without previous usage of EV_captureEvents or EV_startApp, you will have an illusion that you are not in the your program but in the home screen, because all collected events will be dispatched to the "Home screen" application. Note that in this case, there is no way to exit this loop, and your program will stay "resident" and "locked" in the memory forever, although you will not be aware of the fact that your program is still "running" - you will be able to execute everything, including running other programs etc.

As EV_eventLoop enters the endless loop, the only method (and this is the proposed method in TIOS) to exit the loop is to throw an error from the user event handler installed using EV_captureEvents. This is possible because in the event loop there are no error handlers in place, so ER_throw passes control to the previous level of error handler. In terms of normal operation (i.e. while you are typing in the home screen) this is handled by EV_centralDispatcher, which restarts the event loop. However, in custom event handling it is used to return from the event loop to the calling code. To achieve this, you need to catch errors using ER_catch or using TRY...ONERR...ENDTRY construction. So, the typical usage of EV_eventLoop function in user programs is:
EV_captureEvents (UserHandler);
TRY
  EV_eventLoop ();                // The only way to exit from this is
ONERR                             // to throw an error from the event handler!
  EV_captureEvents (NULL);
ENDTRY
Of course, user handler must decide what to do with events dispatched by EV_eventLoop. Very nice example of usage of this methodology is given in textedit.h header file. Another example may be found with the description of CAT_dialog function. These principles are used often in the TIOS. For example, error dialogs are principally implemented as follows (although there are no obvious reasons why events are used in this example):
void ERD_EventHandler(EVENT *ev)
{
  if (ev->Type == CM_KEYPRESS)
    switch (ev->Key.Code)
      {
        case KEY_ENTER: ER_throw (1);
          // Exit from event loop: ENTER key pressed
        case KEY_ESC: ER_throw (2);
          // Another exit: ESC key pressed
        case KEY_OFF: EV_defaultHandler (ev);
          // OFF key pressed: allow the machine to be switched off
      }
}

short ERD_dialog(short err_no, short prog_flag)
{
  EV_captureEvents (ERD_EventHandler);
  // Display the dialog
  TRY
    EV_eventLoop();
  ONERR
    switch(errCode)
      {
        case 1: // Restore the screen and return KEY_ENTER code
        case 2: // Restore the screen and return KEY_ESC code
      }
  ENDTRY
}
To exit from EV_eventLoop, the best idea is to throw error codes less than 8, as they are never used as error codes in normal error handling.


Uses: EV_paintOneWindow, EV_sendEvent, EV_sendEventSide, ERD_dialog, HToESI, kbhit, ngetchx, ST_busy, CU_cursorState, idle, off, OSClearBreak, OSEnableBreak, OSTimerExpired, OSTimerRestart, XR_stringPtr, ERD_dismissNotice, ERD_notice, EV_currentApp, EV_errorCode, LoadSymFromFindHandle, OO_firstACB, SymDelTwin, SymFindFirst, SymFindNext, ROM Call 0x424, ROM Call 0x471
Used by: EV_centralDispatcher, EV_defaultHandler, cmd_input, cmd_inputstr, cmd_prompt, Dialog, ERD_dialog, EV_quit, GT_Trace