Detecting Events

Throughout the execution of your program, the MoSync SDK can supply it with events.  These are typically things which is happening to the phone.  For instance, a button has been pressed or the screen has been touched.  They also cover more advanced functions such as 'nothing has happened for a few seconds' or 'the phone has a new location from the GPS'.

This example is a simple "Hello World!" program.  Console-type applications that exit when they finish are quite uncommon on mobile devices, so we show in this example how provide an event loop that keeps the application running until the user presses a key, in this case the zero (0) key.

It waits for an event to occur using the maWait() function.  It then creates an MAEvent struct.  These MAEvent objects contain the details of the event which has occurred.  You can query them to see the type of event that has occurred, and also for any relevant data to that event, such as which key has been pressed, where the screen has been touched and what the new location is.

This example also shows how to detect close events.  A close event is an event that is generated when a user attempts to forcibly terminate the application in some (platform-dependent) way, commonly by using some type of task manager. The purpose of the close event is to notify the application that it will be closed down very shortly (the exact amount of time being platform-dependent) and that it should perform emergency shutdown operations, such as saving critical data.

Here is an example in C:

/**
* This program shows that how can we handle events in MoSync. 
* Here we are handling Close event using the C code.
* 
* @file EventHandlingCProgram.C
*
* @author Chris Hughes
*/

#include <ma.h>   // the standard MoSync header
#include <conprint.h>   // provides printf()

int MAMain() 
{
    printf("Hello world!\n");
	
    // Declare a MoSync event struct.
    MAEvent MyEvent;
    while(1) 
    {
        // Wait for an event
        maWait(0);
	
        // Store the latest event in the event struct.
        maGetEvent(&MyEvent);

        // determine whether or not it is a key press
        if(MyEvent.type == EVENT_TYPE_KEY_PRESSED) 
        {
            // ...and whether it was the '0' key.
            if(MyEvent.key == MAK_0)
            {
                // ...in which case we exit.
                maExit(0);
            }
        }
        else if(MyEvent.type == EVENT_TYPE_CLOSE) 
        {
            // ...and also if we get a close event.
            maExit(0);
        }
    }
    return 0;
}

The function maGetEvent() populates your MAEvent object with the relevant data.  You can then test the property type to see what is the event which has occurred.  The values in type are defined in maapi.h, and cover key presses, screen touching, location, your application being sent to the background, the phone changing from landscape to portrait (and vice versa) and closing.  By testing the type of the event, you only have to code for the events you are interested in.

Event handling in C++ can be quite different.  You can make use of these C functions if you wish in C++ code, but if you are building an application on the MoSync SDK in C++ then there is an event-based framework already available to you.

The basis of this framework is the Moblet class, which is a C++ class which can handle your main application loop.  The Moblet class already has virtual methods built in for handling common system events. including key presses, key releases, screen touches, screen movement and screen releases as well close events and 'custom events' for location and other events in the future.

If you are using Moblet to build your application, then you will create a new class which inherits from the Moblet base class.  Moblet only provides virtual methods for event handling, so you'll have to supply your own code, but it is a much cleaner way of processing these system events.

For instance, if you want to capture the key presses from the C example above, you would implement keyPressEvent(int keycode, int nativeCode).  You can then compare the value of button pressed with the value you are looking for.

As an aside, when you capture key presses you get two values.  The first (referred to as keyCode) is a platform independent value.  There is a long list of keys which you can handle in this way defined in maapi.h.  In the example below, we are looking for the 0 key, so we can compare it with MAK_0.  This way, we don't need to have code to check the key value for the 0 key on each platform.  There are also some keys which may be implemented on just a few handsets.  The Android 'back' key, or volume keys on a phone are not implemented in the platform independent way as their are so few phones which support them.  You can still handle key presses from these buttons through, by accessing the nativeCode value of the button, which is platform specific.

And here is a similar example in C++ which makes use of MoSync's moblet framework:

/**
* This is another program for handling events using C++ syntax.
* 
* @file EventHandlingCPPProgram.cpp
*
* @author Chris Hughes
*/

#include <MAUtil/Moblet.h>

using namespace MAUtil;

// Moblet class declaration.
class MyMoblet : public Moblet 
{
public:
    MyMoblet() 
    {
        maSetColor(0xFFFFFF);
        maDrawText(0, 32, "Hello World!");
        maUpdateScreen();
    }
    
    // Handles key press event.
    void keyPressEvent(int keyCode, int nativeCode) 
    {
        if(keyCode == MAK_0) 
        {
            closeEvent();
            close();
        }
    }
    
        // Handles key release event.
        void keyReleaseEvent(int keyCode, int nativeCode) 
        {
	
        }
};

/*
* Programs main functionality starts here.
*/
extern "C" int MAMain() 
{
    Moblet::run(new MyMoblet());
    return 0;
}