PrevNextUpHome SophiaFramework UNIVERSE 5.3

10.10. Event Handling

10.10.1. Event

With SophiaFramework, developers can use both the standard BREW events and the extended events for SophiaFramework. Moreover, their own specific events can be defined.

The SophiaFramework equivalent for BREW AEEEvent is defined as SFCEventEnum.

In SophiaFramework, the BREW standard event names such as EVT_KEY and EVT_APP_START are replaced with events of which names start with SF like SFEVT_KEY and SFEVT_APP_START.

The event "Type" used by GUI Framework are of SFCEventEnum event types, "P16" is the first parameter of UInt16 type, "P32" is the second parameter of UInt32 type.

The event type name related with GUI Framework starts with SREVT_.

Table 10.14. Typical Events for Standard BREW

Event Name Description
SFEVT_APP_START Application start
SFEVT_APP_STOP Application stop
SFEVT_APP_RESUME Application resume
SFEVT_APP_SUSPEND Application suspend
SFEVT_KEY Key input event
SFEVT_KEY_PRESS Key press event
SFEVT_KEY_RELEASE Key release event
SFEVT_CHAR Character input event
SFEVT_ALARM Alarm event
SFEVT_COMMAND Application specific event
SFEVT_APP_CONFIG Application start: indicating config screen
SFEVT_APP_HIDDEN_CONFIG Application start: indicating hidden config screen
SFEVT_APP_MESSAGE SMS message receiving event
SFEVT_ASYNC_ERROR Asynchronous error notificating (only effective with BREW SDK version 2.1 or later)
SFEVT_APP_TERMINATE Application terminate (only effective with BREW SDK version 2.1 or later)
SFEVT_EXIT BREW exit (only effective with BREW SDK version 2.1 or later)
SFEVT_USER User defined event

Table 10.15. Typical Events for SophiaFramework

Event Types Description
Type: SREVT_RESPONDER_RENDER
P16: SRP16_RENDER_INVOKE
P32: Bool type
The event for redrawing the Responder instance.
P32 is passed as true when redrawing the Responder instance that is not registered as object for redrawing.
*1. It is possible to dispatch to the instance of the application class
*2. This event cannot be handled.
Type: SREVT_RESPONDER_RENDER
P16: SRP16_RENDER_BASE
P32: SFXGraphicsPtr Type
The event for redrawing the base region of Responder instance.
P32 is pointer to the SFXGraphics instance. This instance is used to redraw it.
* To handle this event, registered the handler function.
Type: SREVT_RESPONDER_RENDER
P16: SRP16_RENDER_CONTENT
P32: SFXGraphicsPtr Type
The event for redrawing the content region of Responder instance.
P32 is pointer to the SFXGraphics instance. This instance is used to redraw it.
* To handle this event, registered the handler function.
Type: SREVT_RESPONDER_TERMINATE
P16: SRP16_TERMINATE_INVOKE
P32: Bool type
The event for destroying the Responder instance.
P32 is true in case of destroying it forcedly.
* This event must not be handled.
Type: SREVT_RESPONDER_TERMINATE
P16: SRP16_TERMINATE_TRY
P32: Bool type
The event notified before the Responder instance is destroyed.
P32 indicates whether it is destroyed forcedly or not.
When handling this event, return true to cancel, false to continue.
This event is also dispatched to all the child Responder instances of Responder instance being destroyed. If any child Responder instance returns true, the destroying is canceled.
Type: SREVT_DIALOG
P16: UInt16 type
P32: SFRDialogPtr type
The event for the Dialog such as key event on the Dialog.
P16 indicates the reason why the Dialog is closed. SRP16_OK is set if the OK button is pressed, SRP16_ESCAPE if the CLEAR key is pressed.
P32 is a pointer to the Dialog instance.
Type: SREVT_MENU
P16: UInt16 Type
P32: SFRMenuPtr Type
The event for the Menu such as key event on the Menu item.
P16 indicates the reason why the Menu is closed. SRP16_OK is set if the OK button is pressed, SRP16_ESCAPE if the CLEAR key is pressed. and the index of Menu item if a Menu item is selected.
P32 is a pointer to the Menu instance.
Type: SREVT_CONTROL
P16: UInt16 type
P32: SFRControlPtr type
The event for the Control such as key event on the control.
P16 is the value of Control instance.
P32 is a pointer to the Control instance.

Example 10.70. Redraw Forcedly

// get instance of Application class
SFRApplicationPtr app(SFRApplication::GetInstance());

// send redrawing event to instance of Application class
app->Invoke(SFXEvent(SREVT_RESPONDER_RENDER, 
                     SRP16_RENDER_INVOKE, 
                     true));

Example 10.71. Redraw the content region

// register content region redrawing handler
RegisterHandler(SREVT_RESPONDER_RENDER, 
                SRP16_RENDER_CONTENT, 
                HANDLER_BEFORE, 
                HANDLER_FUNCTION(OnRenderContent));

Example 10.72. Destroy the responder

SFRButtonControlPtr button;

// create and destroy button
if ((button = ::new SFRButtonControl(window, SFXRectangle(10, 10, 100, 20), "OK")) != null) {
    //checking errors in constructor
    if (button->static_catch() == SFERR_NO_ERROR) {  // If no error
        // send SREVT_RESPONDER_TERMINATE event to destroy button
        button->Invoke(SFXEvent(SREVT_RESPONDER_TERMINATE, 
                                SRP16_TERMINATE_INVOKE, 
                                true));
    }
    else {
        // if there is error, use delete operator to destroy button
        ::delete button;
    }

10.10.2. Event Handler

The events such as application start and stop, suspension, restart, or key input are notified to the appropriate responder by the Tracer.

Then, each event will be automatically processed by the function called Event Handler.

Reference: Tracer

10.10.2.1. Declaring an Event Handler

An event handler is declared by using the macro of which name starts with HANDLER_DECLARE_.

The handler name is passed as argument.

Reference: GUI Framework Macros: Macros for Declaring Event Handler

Table 10.16. Macros for Declaring Event Handler (Void type)

Macro Description
HANDLER_DECLARE_VOIDRENDER Drawing handler
HANDLER_DECLARE_VOIDSTART Application start handler
HANDLER_DECLARE_VOIDSTOP Application stop handler
HANDLER_DECLARE_VOIDRESUME Resume handler
HANDLER_DECLARE_VOIDSUSPEND Suspend handler
HANDLER_DECLARE_VOIDDIALOG Dialog handler
HANDLER_DECLARE_VOIDMENU Menu handler
HANDLER_DECLARE_VOIDCONTROL Control handler
HANDLER_DECLARE_VOIDVOID Generic handler
HANDLER_DECLARE_VOIDEVENT Generic handler

Example 10.73. Declare the drawing handler

// define MyWindow class
SFMTYPEDEFCLASS(MyWindow)
class MyWindow : public SFRTitleWindow {
    SFMSEALCOPY(MyWindow)
public:
    MyWindow(Void) static_throws;
    virtual ~MyWindow(Void)
    
    // declare drawing handler
    // handler name is passed as argument
    HANDLER_DECLARE_VOIDRENDER(OnRenderContent)
};

Table 10.17. Macros for Declaring an Event Handler (Bool type)

Macro Description
HANDLER_DECLARE_BOOLSTART Application start handler
HANDLER_DECLARE_BOOLSTOP Application stop handler
HANDLER_DECLARE_BOOLRESUME Resume handler
HANDLER_DECLARE_BOOLSUSPEND Suspend handler
HANDLER_DECLARE_BOOLDIALOG Dialog handler
HANDLER_DECLARE_BOOLMENU Menu handler
HANDLER_DECLARE_BOOLCONTROL Control handler
HANDLER_DECLARE_BOOLVOID Generic handler
HANDLER_DECLARE_BOOLEVENT Generic handler

Example 10.74. Declare the key handler

// define MyWindow class
SFMTYPEDEFCLASS(MyWindow)
class MyWindow : public SFRTitleWindow {
    SFMSEALCOPY(MyWindow)
public:
    MyWindow(Void) static_throws;
    virtual ~MyWindow(Void)
    
    // declare key handler
    // handler name is passed as argument
    HANDLER_DECLARE_BOOLEVENT(OnKey)
};
[Note] By Using the Handler Declaring Macro...

the pointer to the handler function and the identification number (reference value) are generated.

10.10.2.2. Implementing an Event Handler

An event handler is implemented by using the macro of which name starts with HANDLER_IMPLEMENT_.

1st argument: the class it belongs to, 2nd argument: handler name, 3rd argument: varies according to the handler.

Reference: GUI Framework Macros: Macros for implementing Event Handler

Table 10.18. Macros for Implementing an Event Handler (Void type)

Macro Description 1st argument 2nd argument 3rd argument
HANDLER_IMPLEMENT_VOIDRENDER Drawing handler graphics (graphic object) none none
HANDLER_IMPLEMENT_VOIDSTART Application start handler environment none none
HANDLER_IMPLEMENT_VOIDSTOP Application stop handler quitable none none
HANDLER_IMPLEMENT_VOIDRESUME Resume handler environment none none
HANDLER_IMPLEMENT_VOIDSUSPEND Suspend handler reason info none
HANDLER_IMPLEMENT_VOIDDIALOG Dialog handler result dialog (pointer to dialog) none
HANDLER_IMPLEMENT_VOIDMENU Menu handler result menu (pointer to menu) none
HANDLER_IMPLEMENT_VOIDCONTROL Control handler result control (pointer to control) none
HANDLER_IMPLEMENT_VOIDVOID Generic handler none none none
HANDLER_IMPLEMENT_VOIDEVENT Generic handler event (event object) none none

Example 10.75. Implement the drawing handler

// 1st argument: class it belongs to, 2nd argument: handler name, 3rd argument: graphic object
HANDLER_IMPLEMENT_VOIDRENDER(MyWindow, OnRenderContent, graphics)
{
    // draw "Hello World"
    graphics->DrawText("Hello World", GetContentWorld());
    return;
}

Table 10.19. Macros for Implementing an Event Handler (Bool type)

Macro Description 1st argument 2nd argument 3rd argument
HANDLER_IMPLEMENT_BOOLSTART Application start environment none none
HANDLER_IMPLEMENT_BOOLSTOP Application stop quitable none none
HANDLER_IMPLEMENT_BOOLRESUME Resume handler environment none none
HANDLER_IMPLEMENT_BOOLSUSPEND suspend handler reason info none
HANDLER_IMPLEMENT_BOOLDIALOG Dialog handler result dialog (pointer to dialog) none
HANDLER_IMPLEMENT_BOOLMENU Menu handler result menu (pointer to menu) none
HANDLER_IMPLEMENT_BOOLCONTROL Control handler result control (pointer to control) none
HANDLER_IMPLEMENT_BOOLVOID Generic handler none none none
HANDLER_IMPLEMENT_BOOLEVENT Generic handler event (event object) none none

Example 10.76. Implement the key handler

// a key is pressed on topmost window.
// 1st argument: class it belongs to, 2nd argument: handler name, 3rd argument: event value
HANDLER_IMPLEMENT_BOOLEVENT(MyWindow, OnKey, event)
{
    // processing according to type of pressed key.
    switch (event.GetP16()) {
        case AVK_CLR: // if "Clear" key has been pressed
           // close window
            return Invoke(SFXEvent(SREVT_RESPONDER_TERMINATE,
                                   SRP16_TERMINATE_INVOKE, true));

        case AVK_1:   // if "1" key has been pressed

            ...

            return true;  // if pressed key was processed, return true
    }
    return false;         // if pressed key was not processed, return false
}

10.10.2.3. Registering an Event Handler

An handler is registered by using the RegisterHandler function, and canceled by using the UnregisterHandler function.

If more than one handler functions are registered with the same event, only one handler function registered lastly is effective.

Setting information necessary when registering an event handler

  1. The event type and the first parameter: same as BREW event
  2. Timing for event handling: whether the event will be handled before(HANDLER_BEFORE) or after(HANDLER_AFTER) dispatching it to the Child Responders

Figure 10.56. Event Flow

Event Flow

Table 10.20. Timing for event handling

Processing the Event Description
HANDLER_BEFORE Handle the event at the Parent Responder, and then dispatch and handle it at the Child Responder.
HANDLER_AFTER Dispatch and handle the event at the Child Responder, and then handle it at the Parent Responder.
[Note] Timing for event handling

When drawing the Responders(UI components), it is necessary to draw them sequentially and recursively from backmost (Parant Responder) to foreground (Child Responders). Therefore, HANDLER_BEFORE is specified as the timing for event handling in registering the drawing handler.

As for the key handler, HANDLER_AFTER is specified since the key event need to be handled from topmost (Child Responder) to background (Parant Responder).

Since there is order relation between Parent and Child Responders regarding their construction and destruction, HANDLER_BEFORE and HANDLER_AFTER are specified when registering the handlers for the resume and suspend events respectively. Also as for the start and end events of application, HANDLER_BEFORE and HANDLER_AFTER are specified respectively for the same reason.

Example 10.77. Handler Types

Bool (*SFRResponderSPP) (SFXEventConstRef event, VoidPtr reference);

Example 10.78. Register the handler that is processed before dispatching the event to the child Responder

SFRResponderPtr responder;
SFCError error;

error = responder->RegisterHandler(SREVT_CONTROL, 
                                   HANDLER_BEFORE, 
                                   HANDLER_FUNCTION(OnControl));

Example 10.79. Register the handler that is processed after dispatching the event to the child Responder and receiving it from the child Responder

SFRResponderPtr responder;
SFCError error;

error = responder->RegisterHandler(SFEVT_KEY, 
                                   SFEVT_KEY_RELEASE, 
                                   AVK_SELECT, 
                                   HANDLER_AFTER, 
                                   HANDLER_FUNCTION(OnKey));
[Note] Role of HANDLER_FUNCTION

By making the argument of HANDLER_DECLARE_????? macro be that of HANDLER_FUNCTION macro, the pointer to the handler function and the handler identification number (reference value) are passed to the RegisterHandler function.

The code below describes how to make the key event handler be handled with doing nothing.

Example 10.80. Make the key handler as if it were handled with doing nothing

SFRResponderPtr responder;
SFCError error;

error = responder->RegisterHandler(SFEVT_KEY, 
                                   SFEVT_KEY_RELEASE, 
                                   HANDLER_BEFORE, 
                                   HANDLER_NULL);
[Warning] Warning
The Tracer setting also has the influence on whether this key event handler will be handled or not.

The handler registered lastly is effective. The behaviors of the following two codes are different.

Example 10.81. Register the key handlers (1)

SFRResponderPtr responder;

responder->RegisterHandler(SFEVT_KEY, 
                           HANDLER_AFTER, 
                           HANDLER_FUNCTION(OnKey));
responder->RegisterHandler(SFEVT_KEY, 
                           SFEVT_KEY_RELEASE, 
                           HANDLER_AFTER, 
                           HANDLER_FUNCTION(OnHeld1));
responder->RegisterHandler(SFEVT_KEY, 
                           SFEVT_KEY_RELEASE, 
                           HANDLER_AFTER, 
                           HANDLER_FUNCTION(OnHeld2));

Example 10.82. Register the key handlers (2)

SFRResponderPtr responder;

responder->RegisterHandler(SFEVT_KEY, 
                           SFEVT_KEY_RELEASE, 
                           HANDLER_AFTER, 
                           HANDLER_FUNCTION(OnHeld1));
responder->RegisterHandler(SFEVT_KEY, 
                           SFEVT_KEY_RELEASE, 
                           HANDLER_AFTER, 
                           HANDLER_FUNCTION(OnHeld2));
responder->RegisterHandler(SFEVT_KEY, 
                           HANDLER_AFTER, 
                           HANDLER_FUNCTION(OnKey));
Copyright(c) 2002 - 2024
Sophia Cradle Incorporated
All Rights Reserved. 		PrevNextUpHome