PrevNextUpHome SophiaFramework UNIVERSE 5.3

9.10. Container(Basic)

Container is the responder designed to be placed in a control or another container(container/window /dialog ).

All containers inherit from the SFYContainer which provides functions to move the focus among responders in the container 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.

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

[Caution] Caution
Though a window or dialog is a kind of container, it differs from container in being placed in the root.

Table 9.8. Type of concrete container

Class name Description
SFZContainer General purpose container to place controls and/or containers.
SFZWindow General purpose window to place controls and/or containers.
SFZDialog General purpose dialog to place controls and/or containers.
SFZTabPage Concrete container to add to SFZTabControl.
[Important] IMPORTANT

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

Other functions are optionally called.

Table 9.9. Type of abstract container

Class name Description
SFYContainer Abstract class which represents a container.
SFZWindow Abstract class which represents a window.
SFZDialog Abstract class which represents a dialog.

9.10.1. General Purpose Container to Place a Control or Container. [SFZContainer]

SFZContainer is the general purpose container to place various controls and/or containers.

When controls and/or containers are placed in the container, the focus can be moved among the child responders of the container 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 container. At this time, scrolling is performed in cooperation with moving the focus.

Figure 9.30. Execution Result

Execution Result

Example 9.48. Declaration

SFMTYPEDEFRESPONDER(USRWindow)
class USRWindow: public SFZWindow {
    SFMSEALRESPONDER(USRWindow)
    SFMRESPONDERINSTANTIATEFOUR(USRWindow, SFZWindow, SFYContainer, SFYWidget, SFYResponder)
private:
    SFZContainerSmp _container;

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

Example 9.49. Implementation

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


    // create container
    if ((_container = SFZContainer::NewInstance(&error)) != null) {

        // set container's parent responder to USRWindow
        error = _container->SetParent(GetThis());
        if (error == SFERR_NO_ERROR) {

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

            // set container's real region to region obtained by deflating USRWindow's region by (10, 10)
            _container->SetRealBound(GetLocalBound().Deflate(10, 10));

            // set container's state to "visible" + "active" + "enable" + "focus" together
            _container->SetState(true, true, true, true);
        }
    }

    return error;
}

9.10.2. Abstract Class that Represents a Container [SFYContainer]

SFYContainer is the abstract base class for all containers.

For instance, containers such as SFZContainer, SFZWindow, or SFZDialog are implemented by inheriting from SFYContainer.

SFYContainer provides functions to handle the key events for moving the focus among responders in the container 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 container, the focus can be moved among the child responders of the container using the scroll key set with SFYContainer::SetScrollDownKey / SFYContainer::SetScrollUpKey / SFYContainer::SetPageDownKey / SFYContainer::SetPageUpKey / SFYContainer::SetSnapDownKey / SFYContainer::SetSnapUpKey functions.

In SFYContainer, the following handlers(virtual functions) are registered for the key event[SFEVT_KEY] for scrolling or moving the focus,

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

Table 9.10. 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 container is as follows:

Example 9.50. Declaration

SFMTYPEDEFRESPONDER(USRContainer)
class USRContainer: public SFYContainer {
    SFMSEALRESPONDER(USRContainer)
    SFMRESPONDERINSTANTIATETHREE(USRContainer, 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', 'N', 'T', 'N')
    };
    SFMTYPEDEFTYPE(CodeEnum)

public:
    static USRContainerSmp NewInstance(SFCErrorPtr exception = null);
protected:
    explicit USRContainer(Void) static_throws;
    virtual ~USRContainer(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.51. Implementation

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

        // set the responder type
        SetType(CODE_TYPE);

        // here describe the initialization
    }
}

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

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

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

    return;
}

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

    return;
}

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

    return;
}

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

    return;
}

Void USRContainer::HandleRenderRequest(SFXGraphicsPtr graphics) const
{
    // draw container

    return;
}