PrevNextUpHome SophiaFramework UNIVERSE 5.3

10.8. Searching for Responder

Type and Attribute are used to distinguish and search for the Responder instance.

10.8.1. Type

Type is used to distinguish the Responder type. ( Responder Type )

[Note] Caution

When defining new Responder class that inherits from the SFRResponder class, type can be set as "4-character literal" by using four_char_code macro function.

However, the 4-character literals of lower-case alphabet are reserved for SophiaFramework.

The SFRResponder::GetType function is used to get the Responder type.

Example 10.49. Process according to the Responder type.

// get topmost Responder
SFRResponderPtr responder = GetFront();

// processing according to Responder type
switch (responder->GetType()) {
    case TYPE_SFRAPPLICATION: // Application
        ...
    case TYPE_SFRWINDOW:      // Window
        ...
    case TYPE_SFRDIALOG:      // Dialog
        ...
    case TYPE_SFRMENU:        // Menu
        ...
    case TYPE_SFRCONTROL:     // Control
        ...
    case TYPE_SFRPANE:        // Pane
        ...
}

10.8.2. Attribute

Attribute set when creating the Responder instance is used to distinguish the Responder instance.

Table 10.11. Can acquire attribute

Attribute Description
ATTRIBUTE_SFRAPPLICATION Application
ATTRIBUTE_SFRWINDOW Window
ATTRIBUTE_SFRPLAINWINDOW PlainWindow
ATTRIBUTE_SFRFRAMEWINDOW FrameWindow
ATTRIBUTE_SFRTITLEWINDOW TitleWindow
ATTRIBUTE_SFRDIALOG Dialog
ATTRIBUTE_SFRPLAINDIALOG PlainDialog
ATTRIBUTE_SFRFRAMEDIALOG FrameDialog
ATTRIBUTE_SFRTITLEDIALOG TitleDialog
ATTRIBUTE_SFRMESSAGEDIALOG MessageDialog
ATTRIBUTE_SFRMULTIDIALOG MultiDialog
ATTRIBUTE_SFRMENU Menu
ATTRIBUTE_SFRPLAINMENU PlainMenu
ATTRIBUTE_SFRFRAMEMENU FrameMenu
ATTRIBUTE_SFRTITLEMENU TitleMenu
ATTRIBUTE_SFRTEXTMENU TextMenu
ATTRIBUTE_SFRPANE Pane
ATTRIBUTE_SFRPLAINPANE PlainPane
ATTRIBUTE_SFRTABPANE TabPane
ATTRIBUTE_SFRCONTROL Control
ATTRIBUTE_SFRBUTTONCONTROL Button control
ATTRIBUTE_SFRCHECKBOXCONTROL Checkbox control
ATTRIBUTE_SFRRADIOBUTTONCONTROL Radiobutton control
ATTRIBUTE_SFRLABELCONTROL Label control
ATTRIBUTE_SFRCOMBOBOXCONTROL Combobox control
ATTRIBUTE_SFREDITBOXCONTROL Editbox control
ATTRIBUTE_SFRTABCONTROL Tab control
ATTRIBUTE_SFRBROWSERCONTROL HTML Browser control

Figure 10.47. Example of default attributes

Example of default attributes

Example 10.50. How to Use Attribute

// Processing according to the Responder attribute
switch (responder->GetAttribute()) {
    case ATTRIBUTE_SFRTITLEWINDOW:        // Window
        ...
    case ATTRIBUTE_SFRBUTTONCONTROL:      // Button
        ...
    case ATTRIBUTE_SFRRADIOBUTTONCONTROL: // Radiobutton
        ...
}

The SFRResponder::GetAttribute function is used to get the Responder attribute.

If the Responder attribute is set, the Responder instance can be distinguished with other Responder instances of same Type.

Example 10.51. Define the Attribute

// defining attribute
// 1st arg: attribute name, 2nd arg: four_char_code macro function used with arbitrary values.
SFMRESPONDERATTRIBUTE(MYBUTTON1, four_char_code('B', 't', 'n', '1'))
[Note] What is four_char_code macro function?

The four_char_code macro function is a macro function that creates "4 character literal" from four 1-byte characters. To avoid duplicating with other "4 character literals", 4 alphanumeric characters are used.

The 4-character literals of lower-case alphabet are reserved for SophiaFramework.

Example 10.52. Set the Attribute

// setting attribute when creating SFRButtonControl instance
SFRButtonControlPtr button1 = new SFRButtonControl(window,
                                                   SFXRectangle(10, 40, 120, 25),
                                                   "button1", 
                                                   ALIGN_CENTER,
                                                   BEHAVIOR_SFRBUTTONCONTROL,
                                                   ATTRIBUTE_MYBUTTON1);

Example 10.53. How to Use Attribute

// processing according to Responder attribute
switch (button->GetAttribute()) {
    case ATTRIBUTE_MYBUTTON1:
        ...
    case ATTRIBUTE_MYBUTTON2:
        ...
}

10.8.3. Behaviour

The Responder instance has a number of flags for managing its Status, Appearance and Property.

Staus :

     BEHAVIOR_NONE           : The behaviour of Responder instance is not considered if this flag is set
     STATUS_VISIBLE          : Whether the Responder instance is visible or not. It will be rendered only if this flag is set. 
     STATUS_ENABLE           : Whether the Responder instance is enabled or not. It can respond to key or other events only if this flag is set. 
     STATUS_FOCUS            : Whether the Responder instance is being focused or not.
     STATUS_TARGET           : Whether the Responder instance is being targeted or not. ( It can receive the key or other events only if this flag is set. )
[Note] Note

The STATUS_TARGET flag will be set if the PROPERTY_DIRECT flag is set.

Appearance :

    APPEARANCE_TRANSPARENT  : Whether the Responder instance has any transparent region or not. If this flag is set, the transparency-aware algorithm is used in the rendering process.
[Warning] Warning
The transparent rendering can be applied to some of the controls such as checkbox, radiobutton, etc. It can be also applied to Window or other types of UI Component, but the rendering process will get extremely slow.

Property :

    PROPERTY_DIRECT         : Whether the Responder instance can receive an event or not if not targeted.
    PROPERTY_SELECT         : Whether the Responder instance on the background will be brought to the foreground or not when targeted.
    PROPERTY_CLOSABLE       : Whether the Responder instance is destroyed or not when the "CLEAR" key is pressed.
    PROPERTY_MOVABLE        : Whether the Responder instance is movable or not.
    PROPERTY_SCROLLABLE     : Whether the Virtual Region of Responder instance can be scrolled the or not.
[Note] Note

If the PROPERTY_DIRECT flag is set, the STATUS_TARGET flag is also set. The Responder instance like Control may have this flag set.

In case of Responder instance like Window, the PROPERTY_SELECT flag is set.

In all Responder instances, the PROPERTY_CLOSABLE flag is not set by default.

By default, all Responder instances are immovable because the PROPERTY_MOVABLE flag is not set.

By default, all Responder instances except the SFRApplication class are not scrollable because the PROPERTY_SCROLLABLE flag is not set.

The PROPERTY_CLOSABLE and PROPERTY_MOVABLE flags are effective when the STATUS_TARGET flag is set.

State Transition :

  1. When the STATUS_VISIBLE flag is set, the STATUS_ENABLE flag is enabled.
  2. When the STATUS_ENABLE flag is set, the STATUS_FOCUS flag is enabled.
  3. When the STATUS_FOCUS flag is set, the STATUS_TARGET flag is enabled.
  4. When the STATUS_TARGET flag is set, the Responder instance can be locked as the target to be operated.

Figure 10.48. Focus and Targetting

Focus and Targetting

10.8.4. Searching for Responder

The Responder instance can be searched for by specifying the Type, Attribute, and Status.

For example, from the drawing handler of Window A, one can get the pointer to the Checkbox in Window B by specifying the Type and Attribute.

[Note] Note
If the status is not specified, only the visible Responder instance can be retrieved. Moreover, if Type and Attribute are set as (TYPE_WILDCARD, ATTRIBUTE_WILDCARD), the Responder instance of all Types can be retrieved.

Table 10.12. Functions for searching the Responder instances

Function Name Description
GetFront Get the topmost Responder instance among the child Responder instances.
GetBack Get the backmost Responder instance among the child Responder instances.
GetNthForward Get the Nth Responder starting from the topmost Responder instance among the child Responder instances. (topmost N = 0, 2nd topmost N = 1, ...)
GetNthBackward Get the Nth Responder starting from the backmost Responder instance among the child Responder instances. (backmost N = 0, 2nd backmost N = 1,... )
GetLeft Get the sibling Responder instance at one more left-hand that matches the specified search condition.
GetRight Get the sibling Responder at one more right-hand that matches the specified search condition.
GetNext Get the sibling Responder instance at one more background that matches the specified search condition.
GetPrevious Get the sibling Responder instance at one more foreground that matches the specified search condition.

Figure 10.49. Searching for the Responder instances

Searching for the Responder instances

Example 10.54. Create the Responder instances in the above figure

// 1st argument of constructor: parent Responder
SFRTitleWindowPtr window1 = new SFRTitleWindow(SFRApplication::GetInstance(),
                                               SFXRectangle(5, 10, 180, 200), 
                                               "Window 1");

SFRTitleWindowPtr window2 = new SFRTitleWindow(SFRApplication::GetInstance(),
                                               SFXRectangle(20, 50, 180, 200), 
                                               "Window 2");

SFRTitleWindowPtr window3 = new SFRTitleWindow(SFRApplication::GetInstance(), 
                                               SFXRectangle(35, 200, 200, 80), 
                                               "Window 3");

SFRButtonControlPtr button1 = new SFRButtonControl(window2,
                                                   SFXRectangle(10, 10, 120, 25), 
                                                   "button1");

SFRButtonControlPtr button2 = new SFRButtonControl(window2,
                                                   SFXRectangle(10, 40, 120, 25), 
                                                   "button2");

SFRButtonControlPtr button3 = new SFRButtonControl(window2,
                                                   SFXRectangle(10, 70, 120, 25), 
                                                   "button3");

SFRCheckboxControlPtr check1 = new SFRCheckboxControl(window2,
                                                      SFXRectangle(10, 100, 120, 25), 
                                                      "check1");

SFRRadiobuttonControlPtr radio1 = new SFRRadiobuttonControl(window3,
                                                            SFXRectangle(10, 5, 120, 20), 
                                                            "radio1");

SFRRadiobuttonControlPtr radio2 = new SFRRadiobuttonControl(window3,
                                                            SFXRectangle(10, 30, 120, 20), 
                                                            "radio2");

SFRCheckboxControlPtr check2 = new SFRCheckboxControl(window3,
                                                      SFXRectangle(100, 5, 120, 25), 
                                                      "check2");

Figure 10.50. Ownership Relation Diagram

Ownership Relation Diagram
[Note] The Front to Back Order about Responder instances

The last created window is at the topmost of windows, while the first created control is at the topmost of controls.

In the above example, the front to back order is: for windows: window3, window2, window1; for controls: button1, button2, button3, check 1.

Use the SFRApplication::GetInstance function to get the Application instance, and use the GetFront function in the Application instance to get the topmost Window instance(window3).

Example 10.55. Method to get the topmost Responder instance

SFRApplicationPtr appli = SFRApplication::GetInstance();

// get pointer to window3
// get topmost window among children of Application class
SFRWindowPtr window3 = static_cast<SFRWindowPtr>(appli)->GetFront();

There are two methods to get the second topmost Window instance(window2).

Example 10.56. Methods to get the second topmost window

SFRWindowPtr window2;

// get pointer to window2

// method 1: get second window start from topmost
window2 = static_cast<SFRWindowPtr>(appli)->GetNthForward(1);

// method 2: get sibling of window3
window2 = static_cast<SFRWindowPtr>(window3)->GetNext();

Lookup the children of window2 to get button1, button2, button3, and check1.

Example 10.57. Method to get the Control instances of window2

SFRButtonControlPtr button1;

// get pointer to button1
button1 = static_cast<SFRButtonControlPtr>(window2)->GetFront();
// or GetNthForward(0)

// get pointer to button2
button2 = static_cast<SFRButtonControlPtr>(window2)->GetNthForward(1);
// or button1->GetNext()

// get pointer to button3
button3 = static_cast<SFRButtonControlPtr>(window2)->GetNthForward(2);
// or button2->GetNext()

// get pointer to check1
check1 = static_cast<SFRCheckboxControlPtr>(window2)->GetNthForward(3);
// or button3->GetNext()

If the Responder instance is not found, return null.

Example 10.58. Responder not found

// since window1 has no child, responder = null
SFRResponderPtr responder = window1->GetFront();

Type and Attribute can be specified as the argument of function for searching for the Responder instance.

The Responder type to search for can be limited to the Window or particular Control.

Example 10.59. Search for the Responder instance

// Example1: search for the child Responder instance with type of TYPE_SFRWINDOW
// 	get topmost responder
responder->GetFront(TYPE_SFRWINDOW);

// Example 2: search for the child Responder instance with type of TYPE_SFRCONTROL and attribute of ATTRIBUTE_SFRBUTTONCONTROL
// 	get topmost responder
responder->GetFront(TYPE_SFRCONTROL, ATTRIBUTE_SFRBUTTONCONTROL);

// Example 3: search for the child Responder instance with attribute of ATTRIBUTE_SFRBUTTONCONTROL
// 	get topmost responder
responder->GetFront(TYPE_WILDCARD, ATTRIBUTE_SFRBUTTONCONTROL);

If the third parameter of searching function is set to BEHAVIOR_NONE "status", invisible Responder instances can be also retrieved regardless of their status.

Example 10.60. Search for the Responder instance

// Example1: search for the child Responder instance with type of TYPE_SFRWINDOW
// 	get topmost responder
//  	invisible and disabled Responder instances are not searched for (default)
responder->GetFront(TYPE_SFRWINDOW, ATTRIBUTE_WILDCARD);

// Example2: search for the child Responder instance with type of TYPE_SFRWINDOW
// 	get topmost responder
//  	Responder instances are searched for regardless of their status such as visible/invisible etc.
responder->GetFront(TYPE_SFRWINDOW, ATTRIBUTE_WILDCARD, BEHAVIOR_NONE);
[Note] Note
If the "status" of the third argument is not specified, the search function retrieves only the Responder instances with the visible status.