PrevNextUpHome SophiaFramework UNIVERSE 5.3

10.2. What is Responder?

The standard UI component of SophiaFramework such as Window, Button, Menu, Dialog etc. is called "Responder(SFRResponder)".

By default, SophiaFramework provides event handling engine for events such as the key event and rendering engine for drawing the Responder instances.

The code for the Responder class can be easily reused in the other projects. Moreover, the Responder class with your own special design or behavior can be implemented with ease.

Reference: SophiaFramework GUI FRAMEWORK

10.2.1. Responder Type

The Responder classes are classified into 6 categories as follows

Table 10.1. Responder Type

Base Class Name Description
SFRApplication Responder which represents an application
SFRWindow Responder which represents a window
SFRDialog Responder which represents a dialog
SFRMenu Responder which represents a menu
SFRControl Responder which represents a control
SFRPane Responder which represents a pane

10.2.2. Responder Hierarchy

UI components are organized into the hierarchy where Application (SFRApplication) manages Window (SFRWindow) and Menu (SFRMenu), and then Window (SFRWindow) manages Control (SFRControl) and Pane (SFRPane).

An application must have only one Application class that inherits from the SFRApplication class. The programming of SophiaFramework application starts from this class.

There is no limitation for the number of Window, Menu, Dialog, Control, or Pane to be defined.

Figure 10.1. Responder Ownership Diagram

Responder Ownership Diagram

All the Responder classes such as Application, Window, Menu etc. must inherit from the SFRResponder class.

Figure 10.2. Responder Class Diagram

Responder Class Diagram

10.2.3. Type and Attribute of Responder

The following are the types and attributes of Responder classes.

Table 10.2. Types of Responder

Class Name Type Attribute Description
SFRApplication TYPE_SFRAPPLICATION (Application) ATTRIBUTE_SFRAPPLICATION Application base class
SFRWindow TYPE_SFRWINDOW (Window) ATTRIBUTE_SFRWINDOW Window base class
SFRPlainWindow TYPE_SFRWINDOW (Window) ATTRIBUTE_SFRPLAINWINDOW Plain window without frame
SFRFrameWindow TYPE_SFRWINDOW (Window) ATTRIBUTE_SFRFRAMEWINDOW Plain window with a frame
SFRTitleWindow TYPE_SFRWINDOW (Window) ATTRIBUTE_SFRTITLEWINDOW Three-dimensional window with a frame and title bar
SFRDialog TYPE_SFRDIALOG (Dialog) ATTRIBUTE_SFRDIALOG Dialog base class
SFRPlainDialog TYPE_SFRDIALOG (Dialog) ATTRIBUTE_SFRPLAINDIALOG Plain dialog without frame
SFRFrameDialog TYPE_SFRDIALOG (Dialog) ATTRIBUTE_SFRFRAMEDIALOG Plain dialog with a frame
SFRTitleDialog TYPE_SFRDIALOG (Dialog) ATTRIBUTE_SFRTITLEDIALOG Three-dimensional dialog with a frame and title bar
SFRMessageDialog TYPE_SFRDIALOG (Dialog) ATTRIBUTE_SFRMESSAGEDIALOG Message Dialog with maximum 1 button
SFRMultiDialog TYPE_SFRDIALOG (Dialog) ATTRIBUTE_SFRMULTIDIALOG Selection Dialog with maximum 3 buttons
SFRMenu TYPE_SFRMENU (Menu) ATTRIBUTE_SFRMENU Menu base class
SFRPlainMenu TYPE_SFRMENU (Menu) ATTRIBUTE_SFRPLAINMENU Plain menu without frame
SFRFrameMenu TYPE_SFRMENU (Menu) ATTRIBUTE_SFRFRAMEMENU Plain menu with a frame
SFRTitleMenu TYPE_SFRMENU (Menu) ATTRIBUTE_SFRTITLEMENU Three-dimensional menu with a frame and title bar
SFRTextMenu TYPE_SFRMENU (Menu) ATTRIBUTE_SFRTEXTMENU Menu with text items
SFRPane TYPE_SFRPANE (Pane) ATTRIBUTE_SFRPANE Pane base class
SFRPlainPane TYPE_SFRPANE (Pane) ATTRIBUTE_SFRPLAINPANE Plane pane without frame
SFRTabPane TYPE_SFRPANE (Pane) ATTRIBUTE_SFRTABPANE Pane used only by tab control (SFRTabControl)
SFRControl TYPE_SFRCONTROL (Control) ATTRIBUTE_SFRCONTROL Control base class
SFRButtonControl TYPE_SFRCONTROL (Control) ATTRIBUTE_SFRBUTTONCONTROL Button control
SFRCheckboxControl TYPE_SFRCONTROL (Control) ATTRIBUTE_SFRCHECKBOXCONTROL Checkbox control
SFRRadiobuttonControl TYPE_SFRCONTROL (Control) ATTRIBUTE_SFRRADIOBUTTONCONTROL Radiobutton control
SFRLabelControl TYPE_SFRCONTROL (Control) ATTRIBUTE_SFRLABELCONTROL Label control
SFRComboboxControl TYPE_SFRCONTROL (Control) ATTRIBUTE_SFRCOMBOBOXCONTROL Combobox control
SFREditboxControl TYPE_SFRCONTROL (Control) ATTRIBUTE_SFREDITBOXCONTROL Text input control
SFRTabControl TYPE_SFRCONTROL (Control) ATTRIBUTE_SFRTABCONTROL Tab control
SFRBrowserControl TYPE_SFRCONTROL (Control) ATTRIBUTE_SFRBROWSERCONTROL HTML browser control

Figure 10.3. Window (SFRPlainWindow, SFRFrameWindow, SFRTitleWindow)

Window (, , )

Figure 10.4. Dialog ( SFRPlainDialog, SFRFrameDialog, SFRTitleDialog )

Dialog ( , , )

Figure 10.5. Dialog (SFRMessageDialog, SFRMultiDialog)

Dialog (, )

Figure 10.6. Menu (SFRTextMenu)

Menu ()

Figure 10.7. Pane and Tab Control (SFRPlainPane, SFRTabPane, SFRTabControl)

Pane and Tab Control (, , )

10.2.4. Defining and Implementing the Responder

The Responder class is defined and implemented by inheriting from anyone among the standard Responder classes provided with SophiaFramework.

Reference: Development with SFR GUI Framework: Window

Example 10.1. Define and Implement the TitleWindow ( SFRTitleWindow )

// coordinates: (20, 20), width: 200, height: 250, title: "my window"
SFMTYPEDEFCLASS(MyWindow)
class MyWindow : public SFRTitleWindow {
    SFMSEALCOPY(MyWindow)
public:
    MyWindow(Void);
    virtual ~MyWindow(Void);
};

// Constructor
MyWindow::MyWindow(Void) : SFRTitleWindow(SFRApplication::GetInstance(),
    SFXRectangle(20, 20, 200, 250), "my window")
{
    return;
}

MyWindowPtr window;

// create TitleWindow
window = new MyWindow();

10.2.5. Creating and Destroying the Responder

Create the responder using the new operator.

Example 10.2. Create the TitleWindow ( SFRTitleWindow )

MyWindowPtr window;

window = new MyWindow();

Example 10.3. Create the Button ( SFRButtonControl )

SFRButtonControlPtr button;   // pointer to button control
SFXSize devsize;              // screen size
SFXAnsiString str = "Button"; // name for button

SInt16 fontWidth = SFXGraphics::MeasureText(AEE_FONT_NORMAL, str);  // font width
SInt16 fontHeight = SFXGraphics::GetFontHeight(AEE_FONT_NORMAL);    // font height

devsize = SFXGraphics::GetDeviceSize();   // screen size of device
SInt16 devWidth = devsize.GetWidth();     // device width
SInt16 devHeight = devsize.GetHeight();   // device height

// create button
// coordinates: ((Device screen width - font width * 2 ) / 2, (Device screen height - font height * 2 ) / 2 )
// width: font width * 2
// height: font height * 2
// title : "Button"
button = ::new SFRButtonControl(this, 
                                SFXRectangle((devWidth - fontWidth * 2) / 2, 
                                (devHeight- fontHeight * 2) / 2, 
                                fontWidth * 2 , 
                                fontHeight * 2), 
                                str);

Figure 10.9. Execution Result

Execution Result

All the Responder instances are automatically destroyed when the application terminates.

* The following code shows how to explicitly destroy the Responder instance using the Invoke function to dispatch SREVT_RESPONDER_TERMINATE event. (delete operator must not be used.)

[Caution] delete operator

The delete operator must not be used to destroy the Responder instance after successfully created.

Example 10.4. Destroy the Responder

responder->Invoke(SFXEvent(SREVT_RESPONDER_TERMINATE, SRP16_TERMINATE_INVOKE, true));
[Warning] Warning

When creating the Responder instance using the new operator fails, use the delete operator to destroy it.

Example 10.5. Creating the Responder ( SFRPlainWindow )

SFRWindowPtr window;

// create PlainWindow using new operator
if ((window = new SFRPlainWindow(this, SFXRectangle(0, 0, 100, 100))) != null) {

    static_throw(*window);

    if (!static_try()) {   // if error has occured when creating window
         ::delete window;    
         // use delete operator to destroy PlainWindow 
    }

} else {
    static_throw(SFERR_NO_MEMORY);
}

10.2.6. Event Handler

The event handler is the function that handles and processes events such as application start or key press. For the events used with SophiaFramework, please refer to SFCEventEnum.

The event handler is defined by using the macro beginning with HANDLER_IMPLEMENT_.

Example 10.6. Define the Key Handler

// Key handler (executed when 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)
{
    // switch according to type of pressed key
    switch (event.GetP16()) {
        case AVK_CLR: // in case of clear key
            // close window
            return Invoke(SFXEvent(SREVT_RESPONDER_TERMINATE,
                                   SRP16_TERMINATE_INVOKE, true));

        case AVK_1:   // in case of 1 key

            ...

            return true;  // pressed key was handled, then return true
    }
    return false;         // pushed key was not handled, then return false 
}

The event handler is declared by using the macro beginning with HANDLER_DECLARE_.

Example 10.7. Declare the Key Handler

// Define MyWindow class
SFMTYPEDEFCLASS(MyWindow)
class MyWindow : public SFRTitleWindow {
    SFMSEALCOPY(MyWindow)
public:
    MyWindow(Void) static_throws;
    virtual ~MyWindow(Void) { return; }
    
    // declare event handler
    // argument is handler name
    HANDLER_DECLARE_BOOLEVENT(OnKey)
};

The event handler is registered by using the RegisterHandler function.

Example 10.8. Register the Key Handler

// Constructor
MyWindow::MyWindow(Void) : SFRTitleWindow(SFRApplication::GetInstance(),
    SFXRectangle(20, 20, 200, 250), "my window") 
{
    // register key handler
    RegisterHandler(SFEVT_KEY, HANDLER_AFTER, HANDLER_FUNCTION(OnKey));
    return;
}