PrevNextUpHome SophiaFramework UNIVERSE 5.3

9.12. Window(Basic)

Window is the responder designed to be placed in the root[SFZRoot].

All windows inherit from SFZWindow, which provides functions to move the focus among responders in the window and scroll up and down the virtual region larger than the real region. At this time, scrolling is performed in cooperation with moving the focus.

An applet with controls uses a window as a container for placing them.

[Tip] Tip
In general, whether controls are used or not, a user interface is described into not an application class but a window.

The concrete window is the part class which can be used as it is in the applet development. On the other hand, the abstract window is the base class to define and implement the user-defined window.

Table 9.11. Type of concrete window

Class name Description
SFZWindow General purpose window to place a control or container.
[Important] IMPORTANT

In the concrete window, the SFYResponder::SetParent, SFYResponder::SetState, and SFYResponder::SetRealBound functions must be always called.

Other functions are optionally called.

* When a frame is attached to a window with the SFYResponder::SetFrame function, calling the SFYResponder::SetRealBound function of the window can be omitted by setting the real region of the frame with the SFYResponder::SetRealBound function since that of the window will be internally set to the region obtained by deflating it by the frame margin.

Table 9.12. Type of abstract window

Class name Description
SFZWindow Abstract class which represents a window.

9.12.1. General Purpose Window to Place a Control or Container. [SFZWindow]

SFZWindow is the general purpose window in which controls and/or containers are placed.

When controls and/or containers are placed in the window, the focus can be moved among responders in the window using the scroll key set with the SFYContainer::SetScrollDownKey / SFYContainer::SetScrollUpKey / SFYContainer::SetPageDownKey / SFYContainer::SetPageUpKey / SFYContainer::SetSnapDownKey / SFYContainer::SetSnapUpKey functions.

The virtual region larger than the real region can be scrolled up and down, and the focus can be moved among responders in the window. At this time, scrolling is performed in cooperation with moving the focus.

Figure 9.32. Execution Result

Execution Result

Example 9.54. Declaration

SFMTYPEDEFCLASS(USRApplication)
class USRApplication: public SFYApplication {
    SFMSEALCOPY(USRApplication)
private:
    SFZWindowSmp _window;

    ...
private:
    SFCError Make(Void);
};

Example 9.55. Implementation

SFCError USRApplication::Make(Void)
{
    SFCError error(SFERR_NO_ERROR);

    // make window
    if ((_window = SFZWindow::NewInstance(&error)) != null) 

        // set window's parent responder to USRApplication
        error = _window->SetParent(GetThis());
        if (error == SFERR_NO_ERROR) {

            // set window's background color to light green color
            // * window's background is automatically drawn by SFYWidget
            _window->SetBackgroundColor(SFXRGBColor(0xCC, 0xFF, 0xCC, 0x00));

            // set window's real region
            _window->SetRealBound(GetLocalBound().Deflate(10, 10));

            // set the window's state to "visible" + "active" + "enable" + "focus" together
            _window->SetState(true, true, true, true);

            // move window foremost
            _window->ToFront();
        }
    }

    return error;
}

Figure 9.33. Window with a border and a title [SFZWindow]


Window with a border and a title [SFZWindow]

For the sample code to attach a frame with a border and/or a title to a window [SFZWindow], see SFZWindow.

9.12.2. General Purpose Window as Abstract Class that Represents a Window [SFZWindow]

SFZWindow is the abstract base class for all windows in which controls and/or containers are placed.

SFZWindow provides functions to handle the key events for moving the focus among responders in the window and scrolling up and down the virtual region larger than the real region. At this time, scrolling is performed in cooperation with moving the focus.

When controls and/or containers are placed in the window, the focus can be moved among the child responders of the window using the scroll key set with the SFYContainer::SetScrollDownKey / SFYContainer::SetScrollUpKey / SFYContainer::SetPageDownKey / SFYContainer::SetPageUpKey / SFYContainer::SetSnapDownKey / SFYContainer::SetSnapUpKey functions.

The virtual region larger than the real region can be scrolled up and down, and the focus can be moved among responders in the window. At this time, scrolling is performed in cooperation with moving the focus.

In SFZWindow, the following handlers(virtual functions) are registered for the key event[SFEVT_KEY] for scrolling, the region event[SFEVT_RESPONDER_BOUND], and the drawing event[SFEVT_RESPONDER_RENDER].

In a window inheriting from SFZWindow, the following handlers(virtual functions) will be booted up first when the event is received.

Table 9.13. Events and their Handlers

Event Handler(Virtual function) Default behaviour Override
SFEVT_KEY event of the ScrollUp key set with SFYContainer::SetScrollUpKey SFYContainer::HandleScrollUpKey Scroll up the virtual region *1 Optional
SFEVT_KEY event of the ScrollDown key set with SFYContainer::SetScrollDownKey SFYContainer::HandleScrollDownKey Scroll down the virtual region *2 Optional
SFEVT_KEY event of the PageUp key set with SFYContainer::SetPageUpKey SFYContainer::HandlePageUpKey Scroll up the virtual region by 1 page *3 Optional
SFEVT_KEY event of the PageDown key set with SFYContainer::SetPageDownKey SFYContainer::HandlePageDownKey Scroll down the virtual region by 1 page *4 Optional
SFEVT_KEY event of the SnapUp key set with SFYContainer::SetSnapUpKey SFYContainer::HandleSnapUpKey Scroll up the virtual region to the top *5 Optional
SFEVT_KEY event of the SnapDown key set with SFYContainer::SetSnapDownKey SFYContainer::HandleSnapDownKey Scroll down the virtual region to the bottom *6 Optional
(SFEVT_RESPONDER_BOUND, SFP16_BOUND_REQUEST) event SFYWidget::HandleBoundRequest - Recommended
(SFEVT_RESPONDER_BOUND, SFP16_BOUND_OPTIMIZE) event SFYWidget::HandleBoundOptimize - Recommended
(SFEVT_RESPONDER_BOUND, SFP16_BOUND_REAL) event SFYWidget::HandleBoundReal - Optional
(SFEVT_RESPONDER_BOUND, SFP16_BOUND_VIRTUAL) event SFYWidget::HandleBoundVirtual - Optional
(SFEVT_RESPONDER_BOUND, SFP16_BOUND_GLOBAL) event SFYWidget::HandleBoundGlobal - Optional
(SFEVT_RESPONDER_RENDER, SFP16_RENDER_REQUEST) event SFYWidget::HandleRenderRequest - Optional

* "-" in the default behaviour column represents that nothing is implemented.

[Note] NOTE

*1. Execute the SFYContainer::ScrollUp function.

*2. Execute the SFYContainer::ScrollDown function.

*3. Execute the SFYContainer::PageUp function.

*4. Execute the SFYContainer::PageDown function.

*5. Execute the SFYContainer::SnapUp function.

*6. Execute the SFYContainer::SnapDown function.

The minimum code necessary to make the user-defined window is as follows:

Example 9.56. Declaration

SFMTYPEDEFRESPONDER(USRWindow)
class USRWindow: public SFZWindow {
    SFMSEALRESPONDER(USRWindow)
    SFMRESPONDERINSTANTIATEFOUR(USRWindow, SFZWindow, SFYContainer, SFYWidget, SFYResponder)
public:

    // define responder type
    // small alphabet and symbol must not be used since they are reserved for SophiaFramework UNIVERSE
    enum CodeEnum {
        CODE_TYPE = four_char_code('U', 'W', 'N', 'D')
    };
    SFMTYPEDEFTYPE(CodeEnum)

public:
    static USRWindowSmp NewInstance(SFCErrorPtr exception = null);
protected:
    explicit USRWindow(Void) static_throws;
    virtual ~USRWindow(Void);

    // virtual functions defined in the parent class and recommended to be implemented
    virtual Void HandleBoundRequest(SFXRectanglePtr rectangle) const;
    virtual Void HandleBoundOptimize(SFXRectanglePtr rectangle) const;
    virtual Void HandleBoundReal(Void);
    virtual Void HandleBoundVirtual(Void);
    virtual Void HandleRenderRequest(SFXGraphicsPtr graphics) const;
};

Example 9.57. Implementation

// constructor
USRWindow::USRWindow(Void) static_throws
{
    if (static_try()) {

        // set the responder type
        SetType(CODE_TYPE);

        // here describe the initialization
    }
}

// destructor
USRWindow::~USRWindow(Void)
{
    // here describe the finalization
}

// function to create instance managed by smart pointer
USRWindowSmp USRWindow::NewInstance(SFCErrorPtr exception)
{
    return static_pointer_cast<USRWindow>(Factory(::new USRWindow, exception));
}

Void USRWindow::HandleBoundRequest(SFXRectanglePtr rectangle) const
{
    // calculate the suitable window size
    // set the rectangle argument to the calculated suitable window size
    // for the rectangle argument, it is recommended to set only its size and not to change its origin in this function

    return;
}

Void USRWindow::HandleBoundOptimize(SFXRectanglePtr rectangle) const
{
    // calculate the suitable window size within rectangular region given by the rectangle argument
    // set the rectangle argument to the calculated suitable window size
    // for the rectangle argument, it is recommended to set only its size and not to change its origin in this function

    return;
}

Void USRWindow::HandleBoundReal(Void)
{
    // here describe the size recalculation if necessary when the real region is changed

    return;
}

Void USRWindow::HandleBoundVirtual(Void)
{
    // here describe the size recalculation if necessary when the virtual region is changed

    return;
}

Void USRWindow::HandleRenderRequest(SFXGraphicsPtr graphics) const
{
    // draw window

    return;
}