PrevNextUpHome SophiaFramework UNIVERSE 5.3

9.23. Handler List

For a responder to receive and handle an event, make a handler using the handler macro below.

There are 2 types of handlers from the purpose point of view:

  1. General purpose handler
  2. Special purpose handler for a particular event

Each handler has its own handler macro to make itself.

There are 2 types of handlers from the return value point of view:

  1. Handler of the VOID type: The return value can be omitted. It is regarded as "true".
  2. Handler of the BOOL type: The return value of "true" or "false" must be specified.

Reference: Handler | SFXEvent | SFXEventRange | SFCEventEnum

9.23.1. General Purpose Handler without Arguments [XANDLER_DECLARE_VOIDVOID or XANDLER_DECLARE_BOOLVOID]

Example 9.205. Handler declaration

XANDLER_DECLARE_VOIDVOID(FUNCTION)

// or

XANDLER_DECLARE_BOOLVOID(FUNCTION)

Table 9.80. Declaration macro argument

Number Content Description
1 Function name Function name for the handler.

Example 9.206. Handler implementation

XANDLER_IMPLEMENT_VOIDVOID(CLASS, FUNCTION, invoker)
{
    return;
}

// or

XANDLER_IMPLEMENT_BOOLVOID(CLASS, FUNCTION, invoker)
{
    return false;
}

Table 9.81. Implementation macro argument

Number Content Description
1 Class name The handler is registered into this calss.
2 Function name Name of the handler function.
3 Variable name of the SFYResponderPtr type Responder which will boot up the handler.

9.23.2. General Purpose Handler with Arguments [XANDLER_DECLARE_VOIDEVENT or XANDLER_DECLARE_BOOLEVENT]

Example 9.207. Handler declaration

XANDLER_DECLARE_VOIDEVENT(FUNCTION)

// or

XANDLER_DECLARE_BOOLEVENT(FUNCTION)

Table 9.82. Declaration macro argument

Number Content Description
1 Function name Name of the handler function.

Example 9.208. Handler implementation

XANDLER_IMPLEMENT_VOIDEVENT(CLASS, FUNCTION, invoker, event)
{
    return;
}

// or

XANDLER_IMPLEMENT_BOOLEVENT(CLASS, FUNCTION, invoker, event)
{
    return false;
}

Table 9.83. Implementation macro argument

Number Content Description
1 Class name The handler is registered into this calss.
2 Function name Name of the handler function.
3 Variable name of the SFYResponderPtr type Responder which will boot up the handler.
4 Variable name of the SFXEventConstRef type. Event.

Reference: Key Event[from SFEVT_KEY to SFEVT_KEY_HOOK_RELEASE] | Control Event[from SFEVT_COMMAND to SFEVT_CTL_TEXT_MODECHANGED] | Dialog Event[from SFEVT_DIALOG_INIT to SFEVT_COPYRIGHT_END] | Shell Event[from SFEVT_ALARM to SFEVT_NOTIFY_FAILURE] | Device Event[from SFEVT_FLIP to SFEVT_SCR_ROTATE] | Clipboard Event[from SFEVT_CB_CUT to SFEVT_CB_PASTE] | Other Applet Event[from SFEVT_APP_CONFIG to SFEVT_APP_START_WINDOW] | SoftKey Event[SFEVT_RESPONDER_SOFTKEY]

9.23.3. Handler for the Applet-Bootup Event[XANDLER_DECLARE_VOIDSTART or XANDLER_DECLARE_BOOLSTART]

Example 9.209. Handler declaration

XANDLER_DECLARE_VOIDSTART(FUNCTION)

// or

XANDLER_DECLARE_BOOLSTART(FUNCTION)

Table 9.84. Declaration macro argument

Number Content Description
1 Function name Name of the handler function.

Example 9.210. Handler implementation

XANDLER_IMPLEMENT_VOIDSTART(CLASS, FUNCTION, invoker, environment)
{
    return;
}

// or

XANDLER_IMPLEMENT_BOOLSTART(CLASS, FUNCTION, invoker, environment)
{
    return false;
}

Table 9.85. Implementation macro argument

Number Content Description
1 Class name The handler is registered into this calss.
2 Function name Name of the handler function.
3 Variable name of the SFYResponderPtr type Responder which will boot up the handler.
4 Variable name of the AEEAppStart* type Information on booting up.

Reference: Applet-Bootup Event[SFEVT_APP_START] | AEEAppStart | BREW API AEEEvent

9.23.4. Handler for the Applet-Terminate Event[XANDLER_DECLARE_VOIDSTOP or XANDLER_DECLARE_BOOLSTOP]

Example 9.211. Handler declaration

XANDLER_DECLARE_VOIDSTOP(FUNCTION)

// or

XANDLER_DECLARE_BOOLSTOP(FUNCTION)

Table 9.86. Declaration macro argument

Number Content Description
1 Function name Name of the handler function.

Example 9.212. Handler implementation

XANDLER_IMPLEMENT_VOIDSTOP(CLASS, FUNCTION, invoker, quitable)
{
    return;
}

// or

XANDLER_IMPLEMENT_BOOLSTOP(CLASS, FUNCTION, invoker, quitable)
{
    return false;
}

Table 9.87. Implementation macro argument

Number Content Description
1 Class name The handler is registered into this calss.
2 Function name Name of the handler function.
3 Variable name of the SFYResponderPtr type Responder which will boot up the handler.
4 Variable name of the BoolPtr type Confirmation for termination.

Reference: Applet-Terminate Event[SFEVT_APP_STOP]

9.23.5. Handler for the Applet-Resume Event[XANDLER_DECLARE_VOIDRESUME or XANDLER_DECLARE_BOOLRESUME]

Example 9.213. Handler declaration

XANDLER_DECLARE_VOIDRESUME(FUNCTION)

// or

XANDLER_DECLARE_BOOLRESUME(FUNCTION)

Table 9.88. Declaration macro argument

Number Content Description
1 Function name Name of the handler function.

Example 9.214. Handler implementation

XANDLER_IMPLEMENT_VOIDRESUME(CLASS, FUNCTION, invoker, environment)
{
    return;
}

// or

XANDLER_IMPLEMENT_BOOLRESUME(CLASS, FUNCTION, invoker, environment)
{
    return false;
}

Table 9.89. Implementation macro argument

Number Content Description
1 Class name The handler is registered into this calss.
2 Function name Name of the handler function.
3 Variable name of the SFYResponderPtr type Responder which will boot up the handler.
4 Variable name of the AEEAppStart* type Information on resuming.

Reference: Applet-Resume Event[SFEVT_APP_RESUME] | AEEAppStart | BREW API AEEEvent

9.23.6. Handler for the Applet-Suspend Event[XANDLER_DECLARE_VOIDSUSPEND or XANDLER_DECLARE_BOOLSUSPEND]

Example 9.215. Handler declaration

XANDLER_DECLARE_VOIDSUSPEND(FUNCTION)

// or

XANDLER_DECLARE_BOOLSUSPEND(FUNCTION)

Table 9.90. Declaration macro argument

Number Content Description
1 Function name Name of the handler function.

Example 9.216. Handler implementation

XANDLER_IMPLEMENT_VOIDSUSPEND(CLASS, FUNCTION, invoker, reason, info)
{
    return;
}

// or

XANDLER_IMPLEMENT_BOOLSUSPEND(CLASS, FUNCTION, invoker, reason, info)
{
    return false;
}

Table 9.91. Implementation macro argument

Number Content Description
1 Class name The handler is registered into this calss.
2 Function name Name of the handler function.
3 Variable name of the SFYResponderPtr type Responder which will boot up the handler.
4 Variable name of the AEESuspendReason type Reason for suspending.
5 Variable name of the AEESuspendInfo* type Information on suspending.

Reference: Applet-Suspend Event[SFEVT_APP_SUSPEND]

9.23.7. Handler for the Parent Child Event[XANDLER_DECLARE_VOIDOWNER]

Example 9.217. Handler declaration

XANDLER_DECLARE_VOIDOWNER(FUNCTION)

Table 9.92. Declaration macro argument

Number Content Description
1 Function name Name of the handler function.

Example 9.218. Handler implementation

XANDLER_IMPLEMENT_VOIDOWNER(CLASS, FUNCTION, invoker, reason, responder)
{
    return;
}

Table 9.93. Implementation macro argument

Number Content Description
1 Class name The handler is registered into this calss.
2 Function name Name of the handler function.
3 Variable name of the SFYResponderPtr type Responder which will boot up the handler.
4 Variable name of the UInt16 type P16 parameter of the event.
5 Variable name of the SFYResponderPtr type Notified responder.

Reference: Parent Child Event[SFEVT_RESPONDER_OWNER]

9.23.8. Handler for Frame Event[XANDLER_DECLARE_VOIDFRAME]

Example 9.219. Handler declaration

XANDLER_DECLARE_VOIDOWNER(FUNCTION)

Table 9.94. Declaration macro argument

Number Content Description
1 Function name Name of the handler function.

Example 9.220. Handler implementation

XANDLER_IMPLEMENT_VOIDFRAME(CLASS, FUNCTION, invoker, reason, responder)
{
    return;
}

Table 9.95. Implementation macro argument

Number Content Description
1 Class name The handler is registered into this calss.
2 Function name Name of the handler function.
3 Variable name of the SFYResponderPtr type Responder which will boot up the handler.
4 Variable name of the UInt16 type P16 parameter of the event.
5 Variable name of the SFYResponderPtr type Notified responder.

Reference: Parent Child Event[SFEVT_RESPONDER_FRAME]

9.23.9. Handler for the Region Event[XANDLER_DECLARE_VOIDBOUND]

Example 9.221. Handler declaration

XANDLER_DECLARE_VOIDBOUND(FUNCTION)

Table 9.96. Declaration macro argument

Number Content Description
1 Function name Name of the handler function.

Example 9.222. Handler implementation

XANDLER_IMPLEMENT_VOIDBOUND(CLASS, FUNCTION, invoker, reason, rectangle)
{
    return;
}

Table 9.97. Implementation macro argument

Number Content Description
1 Class name The handler is registered into this calss.
2 Function name Name of the handler function.
3 Variable name of the SFYResponderPtr type Responder which will boot up the handler.
4 Variable name of the UInt16 type P16 parameter of the event.
5 Variable name of the SFXRectanglePtr type Notified rectangle.

Reference: Region Event[SFEVT_RESPONDER_BOUND]

9.23.10. Handler for the Margin Event[XANDLER_DECLARE_VOIDMARGIN]

Example 9.223. Handler declaration

XANDLER_DECLARE_VOIDMARGIN(FUNCTION)

Table 9.98. Declaration macro argument

Number Content Description
1 Function name Name of the handler function.

Example 9.224. Handler implementation

XANDLER_IMPLEMENT_VOIDMARGIN(CLASS, FUNCTION, invoker, reason, margin)
{
    return;
}

Table 9.99. Implementation macro argument

Number Content Description
1 Class name The handler is registered into this calss.
2 Function name Name of the handler function.
3 Variable name of the SFYResponderPtr type Responder which will boot up the handler.
4 Variable name of the UInt16 type P16 parameter of the event.
5 Variable name of the SFXMarginPtr type Notified margin.

Reference: Margin Event[SFEVT_RESPONDER_MARGIN]

9.23.11. Handler for the State Event[XANDLER_DECLARE_VOIDSTATE]

Example 9.225. Handler declaration

XANDLER_DECLARE_VOIDSTATE(FUNCTION)

Table 9.100. Declaration macro argument

Number Content Description
1 Function name Name of the handler function.

Example 9.226. Handler implementation

XANDLER_IMPLEMENT_VOIDSTATE(CLASS, FUNCTION, invoker, reason, state)
{
    return;
}

Table 9.101. Implementation macro argument

Number Content Description
1 Class name The handler is registered into this calss.
2 Function name Name of the handler function.
3 Variable name of the SFYResponderPtr type Responder which will boot up the handler.
4 Variable name of the UInt16 type P16 parameter of the event.
5 Variable name of the Bool type Notified state.

Reference: State Event[SFEVT_RESPONDER_STATE]

9.23.12. Handler for the Focus Event[XANDLER_DECLARE_VOIDFOCUS]

Example 9.227. Handler declaration

XANDLER_DECLARE_VOIDFOCUS(FUNCTION)

Table 9.102. Declaration macro argument

Number Content Description
1 Function name Name of the handler function.

Example 9.228. Handler implementation

XANDLER_IMPLEMENT_VOIDFOCUS(CLASS, FUNCTION, invoker, reason, focus)
{
    return;
}

Table 9.103. Implementation macro argument

Number Content Description
1 Class name The handler is registered into this calss.
2 Function name Name of the handler function.
3 Variable name of the SFYResponderPtr type Responder which will boot up the handler.
4 Variable name of the UInt16 type P16 parameter of the event.
5 Variable name of the Bool type Focus state.

Reference: Focus Event[SFEVT_RESPONDER_FOCUS]

9.23.13. Handler for the Drawing Event[XANDLER_DECLARE_VOIDRENDER]

Example 9.229. Handler declaration

XANDLER_DECLARE_VOIDRENDER(FUNCTION)

Table 9.104. Declaration macro argument

Number Content Description
1 Function name Name of the handler function.

Example 9.230. Handler implementation

XANDLER_IMPLEMENT_VOIDRENDER(CLASS, FUNCTION, invoker, reason, graphics)
{
    return;
}

Table 9.105. Implementation macro argument

Number Content Description
1 Class name The handler is registered into this calss.
2 Function name Name of the handler function.
3 Variable name of the SFYResponderPtr type Responder which will boot up the handler.
4 Variable name of the UInt16 type P16 parameter of the event.
5 Variable name of the SFXGraphicsPtr type Graphics object.

Reference: Drawing Event[SFEVT_RESPONDER_RENDER]

9.23.14. Handler for the Style Event[XANDLER_DECLARE_VOIDSTYLE]

Example 9.231. Handler declaration

XANDLER_DECLARE_VOIDSTYLE(FUNCTION)

Table 9.106. Declaration macro argument

Number Content Description
1 Function name Name of the handler function.

Example 9.232. Handler implementation

XANDLER_IMPLEMENT_VOIDSTYLE(CLASS, FUNCTION, invoker, reason)
{
    return;
}

Table 9.107. Implementation macro argument

Number Content Description
1 Class name The handler is registered into this calss.
2 Function name Name of the handler function.
3 Variable name of the SFYResponderPtr type Responder which will boot up the handler.
4 Variable name of the UInt16 type P16 parameter of the event.

Reference: Style Event[SFEVT_RESPONDER_STYLE]

9.23.15. Handler for the Value Event[XANDLER_DECLARE_VOIDVALUE]

Example 9.233. Handler declaration

XANDLER_DECLARE_VOIDVALUE(FUNCTION)

Table 9.108. Declaration macro argument

Number Content Description
1 Function name Name of the handler function.

Example 9.234. Handler implementation

XANDLER_IMPLEMENT_VOIDVALUE(CLASS, FUNCTION, invoker, reason, value)
{
    return;
}

Table 9.109. Implementation macro argument

Number Content Description
1 Class name The handler is registered into this calss.
2 Function name Name of the handler function.
3 Variable name of the SFYResponderPtr type Responder which will boot up the handler.
4 Variable name of the UInt16 type P16 parameter of the event.
5 Variable name of the SInt32 type Notified value.

Reference: Value Event[SFEVT_RESPONDER_VALUE]

9.23.16. Handler for the Result Event[XANDLER_DECLARE_VOIDRESULT]

Example 9.235. Handler declaration

XANDLER_DECLARE_VOIDRESULT(FUNCTION)

Table 9.110. Declaration macro argument

Number Content Description
1 Function name Name of the handler function.

Example 9.236. Handler implementation

XANDLER_IMPLEMENT_VOIDRESULT(CLASS, FUNCTION, invoker, reason, result)
{
    return;
}

Table 9.111. Implementation macro argument

Number Content Description
1 Class name The handler is registered into this calss.
2 Function name Name of the handler function.
3 Variable name of the SFYResponderPtr type Responder which will boot up the handler.
4 Variable name of the UInt16 type P16 parameter of the event.
5 Variable name of the SInt32 type Notified result.

Reference: Result Event[SFEVT_RESPONDER_RESULT]

9.23.17. Handler for the Scroll Bar Event[XANDLER_DECLARE_VOIDSCROLLBAR]

Example 9.237. Handler declaration

XANDLER_DECLARE_VOIDSCROLLBAR(FUNCTION)

Table 9.112. Declaration macro argument

Number Content Description
1 Function name Name of the handler function.

Example 9.238. Handler implementation

XANDLER_IMPLEMENT_VOIDSCROLLBAR(CLASS, FUNCTION, invoker, reason)
{
    return;
}

Table 9.113. Implementation macro argument

Number Content Description
1 Class name The handler is registered into this calss.
2 Function name Name of the handler function.
3 Variable name of the SFYResponderPtr type Responder which will boot up the handler.
4 Variable name of the UInt16 type P16 parameter of the event.

Reference: Scroll Bar Event[SFEVT_RESPONDER_SCROLLBAR]

9.23.18. Other Macros

9.23.18.1. XANDLER_FUNCTION Macro

XANDLER_FUNCTION is a macro to get the entry name for the specified handler.

Example 9.239. Definition of the XANDLER_FUNCTION Macro

#define    XANDLER_FUNCTION(FUNCTION)    FUNCTION##SHP

Table 9.114. Macro argument

Number Content Description
1 Function name Function name to get the entry name of a handler.
[Tip] How to use the XANDLER_FUNCTION macro

This macro is used to register more than one handler together at the same time. 

static SFXEventRange::AtomRecConst range[] = {
    {             SFEVT_KEY,            SFEVT_KEY,        SFP16_BEGIN,          SFP16_END},
    {       SFEVT_KEY_PRESS,      SFEVT_KEY_PRESS,        SFP16_BEGIN,          SFP16_END},
    {     SFEVT_KEY_RELEASE,    SFEVT_KEY_RELEASE,        SFP16_BEGIN,          SFP16_END}
};
SFYHandler::RuleRec rule[lengthof(range)];
SFCError error;

rule[0].spp = XANDLER_FUNCTION(OnKey);
rule[0].reference = this;
rule[1].spp = XANDLER_FUNCTION(OnKeyPress);
rule[1].reference = this;
rule[2].spp = XANDLER_FUNCTION(OnKeyRelease);
rule[2].reference = this;

error = RegisterHandler(atomic_cast(range), rule, lengthof(range));

9.23.18.2. XANDLER_INTERNAL Macro

XANDLER_INTERNAL is a macro to get the handler referring to the "this" instance.

This macro is used to register a handler into a responder with the arguments of the pointer to the handler function and the reference to the "this" instance.

Example 9.240. Definition of the XANDLER_INTERNAL Macro

#define    XANDLER_INTERNAL(FUNCTION)    (XANDLER_FUNCTION(FUNCTION)), (this)

Table 9.115. Macro argument

Number Content Description
1 Function name Function name to get the handler. 
SFCError error;

error = RegisterHandler(SFXEventRange(SFEVT_KEY, SFEVT_KEY, SFP16_BEGIN, SFP16_END), XANDLER_INTERNAL(OnKey));

9.23.18.3. XANDLER_EXTERNAL Macro

XANDLER_EXTERNAL is a macro to get the handler referring to the instance specified in the argument.

This macro is used to register a handler into a responder with the arguments of the pointer to the handler function and the reference to the specified instance.

Example 9.241. Definition of the XANDLER_EXTERNAL Macro

#define    XANDLER_EXTERNAL(FUNCTION, REFERENCE)    (XANDLER_FUNCTION(FUNCTION)), ((REFERENCE))

Table 9.116. Macro argument

Number Content Description
1 Function name Function name to get the handler.
2 Variable name of the instance Variable name which will contain the external instance.
[Note] XANDLER_INTERNAL macro and XANDLER_EXTERNAL macro

The XANDLER_INTERNAL macro is used to get the handler referring to the "this" instance. With this macro, the handler is automatically expanded into the sentence structure including the "this" variable.

The XANDLER_EXTERNAL macro is used to get the handler referring to the specified instance. With this macro, the handler is automatically expanded into the sentence structure including the specified instance in the argument.

Since the handler refers to the "this" instance in almost all cases, usually the XANDLER_INTERNAL macro is used.

The "this" variable is not available in the static function. The instance to pass may not be the "this" variable but the external responder. The XANDLER_EXTERNAL macro is used in these cases.

9.23.18.4. XANDLER_NULL Macro

XANDLER_NULL is a macro to get the null handler.

In case the null handler is registered, though the null handler is not booted up actually, it is assumed to have handled an event.

Example 9.242. Definition of the XANDLER_NULL Macro

#define    XANDLER_NULL    (null), (null)

For instance, the code to handle and invalidate(do nothing) all key events is as follows: 

SFCError error;

error = RegisterHandler(SFXEventRange(SFEVT_KEY, SFEVT_KEY, SFP16_BEGIN, SFP16_END), XANDLER_NULL);
Copyright(c) 2002 - 2024
Sophia Cradle Incorporated
All Rights Reserved. 		PrevNextUpHome