PrevNextUpHome SophiaFramework UNIVERSE 5.3

10.11. Tracer

In general, when using the Standard Tracer of SophiaFramework for the application development, this chapter can be skipped.

10.11.1. Standard Tracer

Tracer of each Responder holds the rules by which the events will be dispatched to other Responders.

More precisely speaking, Tracer controls how the events will be dispatched to the Child Responder from their Parent Responder.

For instance, the SFEVT_KEY event is set to dispatch to the focused Responders in a given order, while the SFEVT_RESUME event is set to dispatch to all the Responders.

As Tracer is inherited from the Parent Responder, most of the Tracer rules are registered in the SFRApplication class by default. Likewise, most of the Tracer rules for the events related with menu or control are registered in the SFRMenu and SFRControl classes by default, respectively.

Tracer inheriting from the Parent Responder can be overridden at its Child Responder. To override some of the Tracer rules, you have only to register new Tracer rules.

The following are the default rules of dispatching events set as the Standard Tracer of SophiaFramework.

Tracer Rules

  1. Event type and the first parameter: same as those of BREW event
  2. Tracing order: rule of dispatching events to the Child Responders
  3. Forced dispatching: flag indicating whether or not the Parent Responder continues to dispatch the event to the Child Responders, even after some other class has already processed the event
  4. Status filter: filter that the event will only be received under certain status, such as visible or enabled

Table 10.21. Settings for the Standard Tracer of SophiaFramework

  Tracer elements
1:
Event range: from SFEVT_APPLICATION_CLASS_BEGIN to SFEVT_APPLICATION_CLASS_END
Trace order: no
Forced dispatching: no
Status filter: all statuses
2:
Event range: SFEVT_APP_SUSPEND
Trace order: from foreground to background
Forced dispatching: yes
Status filter: all statuses
3:
Event range: SFEVT_APP_RESUME
Trace order: from foreground to background
Forced dispatching: yes
Status filter: all statuses
4:
Event range: from SFEVT_KEY_CLASS_BEGIN to SFEVT_KEY_CLASS_END
Trace order: focused
Forced dispatching: no
Status filter: the statuses visible, enabled, focused, and targeting are set
5:
Event range: from SFEVT_CONTROL_CLASS_BEGIN to SFEVT_CONTROL_CLASS_END
Trace order: focused
Forced dispatching: no
Status filter: the statuses visible, enabled, focused, and targeting are set
6:
Event range: from SFEVT_DIALOG_CLASS_BEGIN to SFEVT_DIALOG_CLASS_END
Trace order: focused
Forced dispatching: no
Status filter: the statuses visible, enabled, focused, and targeting are set
7:
Event range: from SFEVT_SHELL_CLASS_BEGIN to SFEVT_SHELL_CLASS_END
Trace order: no
Forced dispatching: yes
Status filter: all statuses
8:
Event range: from SFEVT_DEVICE_CLASS_BEGIN to SFEVT_DEVICE_CLASS_END
Trace order: no
Forced dispatching: yes
Status filter: all statuses
9:
Event range: from SFEVT_CLIPBOARD_CLASS_BEGIN to SFEVT_CLIPBOARD_CLASS_END
Trace order: no
Forced dispatching: yes
Status filter: all statuses
10:
Event range: SREVT_RESPONDER_RENDER
Trace order: no
Forced dispatching: yes
Status filter: visible status
11.1:
Event range: SREVT_RESPONDER_TERMINATE
Trace order: no
Forced dispatching: yes
Status filter: all statuses
11.2:
Event range: SREVT_RESPONDER_TERMINATE, SRP16_TERMINATE_TRY
Trace order: from foreground to background
Forced dispatching: yes
Status filter: all statuses
12:
Event range: SREVT_MENU
Trace order: no
Forced dispatching: no
Status filter: all statuses
13:
Event range: SREVT_DIALOG
Trace order: no
Forced dispatching: no
Status filter: all statuses
14 :
Event range: SREVT_CONTROL
Trace order: no
Forced dispatching: no
Status filter: all statuses
[Note] Note

For the SFEVT_KEY event, the forced dispatching flag is not set since there is no need to notify the other Responder instances after one Responder instance handles the SFEVT_KEY event.

The events like SFEVT_RESUME should be dispatched to all the Responder instances, so the forced dispatching flag is set.

[Note] Note

In general, the application can be developed without problem by using this Standard Tracer settings. Standard Tracer settings usually need not to be changed.

10.11.2. Customizing Standard Tracer

To customize the Standard Tracer of SophiaFramework, you have only to register the event dispatching rule to Tracer.

To register the event dispatching rule to Tracer, use the RegisterTracer function. To cancel the event dispatching rule being registered to Tracer, use the UnregisterTracer function.

Example 10.83. Registering the SREVT_CONTROL event dispatching rule: to the visible Responders, notifying Child Responders from foreground to background, forced dispatching. 

SFRResponderPtr responder;
SFCError        error;

error = responder->RegisterTracer(SREVT_CONTROL, 
                                  STATUS_VISIBLE | TRACER_PROVIDE, 
                                  TRACER_FORWARD);

Example 10.84. Registering the rule of dispatching the events from SFEVT_KEY to SFEVT_KEY_RELEASE: to the enabled and visible Responders, not notifying Child Responders, not forced dispatching.

SFRResponderPtr responder;
SFCError        error;

error = responder->RegisterTracer(SFEVT_KEY, 
                                  SFEVT_KEY_RELEASE, 
                                  STATUS_VISIBLE | STATUS_ENABLE, 
                                  TRACER_NONE);

More than one dispatching rules for the same event have been registered to Tracer, the last registration of event dispatching rule is effective.

[Note] Note
The result of registering the following two event dispatching rules is different.

Example 10.85. 1. Registering the event dispatching rule to Tracer

SFRResponderPtr responder;

responder->RegisterTracer(SFEVT_KEY, 
                          STATUS_VISIBLE | STATUS_ENABLE, 
                          TRACER_NONE);
responder->RegisterTracer(SFEVT_KEY, 
                          SFEVT_KEY_RELEASE, 
                          STATUS_VISIBLE | STATUS_ENABLE, 
                          TRACER_NONE);
responder->RegisterTracer(SFEVT_KEY, 
                          SFEVT_KEY_RELEASE, 
                          STATUS_VISIBLE | STATUS_ENABLE, 
                          TRACER_FOCUS);

Example 10.86. 2. Registering the event dispatching rule to Tracer

SFRResponderPtr responder;

responder->RegisterTracer(SFEVT_KEY, 
                          SFEVT_KEY_RELEASE, 
                          STATUS_VISIBLE | STATUS_ENABLE, 
                          TRACER_NONE);
responder->RegisterTracer(SFEVT_KEY, 
                          SFEVT_KEY_RELEASE, 
                          STATUS_VISIBLE | STATUS_ENABLE, 
                          TRACER_FOCUS);
responder->RegisterTracer(SFEVT_KEY, 
                          STATUS_VISIBLE | STATUS_ENABLE, 
                          TRACER_NONE);
Copyright(c) 2002 - 2024
Sophia Cradle Incorporated
All Rights Reserved. 		PrevNextUpHome