Inheritance diagram

Collaboration diagram

Description

How to use

SFYContainer is the abstract base class to define and implement a user-defined container.

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

	Note
	Container is the responder designed to be placed in a control or another container(container/window /dialog ) with functions to move the focus, scroll its virtual region, and handle the key events for scrolling.

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.

Events and their handlers

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

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

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

	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 a user-defined container is as follows:

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;
};

// 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;
}

Reference

Abstract Class that Represents a Container[SFYContainer] | SFZContainer | SFZWindow | SFZDialog | SFZMessageDialog | SFZQuestionDialog | SFZTabPage | Virtual Region | Real Region | Local Region | SFYContainer::SetScrollDownKey | SFYContainer::SetScrollUpKey | SFYContainer::SetPageDownKey | SFYContainer::SetPageUpKey | SFYContainer::SetSnapDownKey | SFYContainer::SetSnapUpKey | Key Event[SFEVT_KEY] | Region Event[SFEVT_RESPONDER_BOUND] | Drawing Event[SFEVT_RESPONDER_RENDER]

Member

Description

This constructor performs the initializations as follows:

	Note
	In a responder inheriting from SFYContainer, the corresponding handler will be called when one of the above events occurs.

Reference

SFYResponder::SetType | SFYContainer::CodeEnum | SFYContainer::SetScrollStep | SFYContainer::DefaultEnum | SFYContainer::SetScrollRepeat | SFYContainer::SetScrollUpKey | SFYContainer::HandleScrollUpKey | SFYContainer::SetScrollDownKey | SFYContainer::HandleScrollDownKey | SFYContainer::SetPageUpKey | SFYContainer::HandlePageUpKey | SFYContainer::SetPageDownKey | SFYContainer::HandlePageDownKey | SFYContainer::SetSnapUpKey | SFYContainer::HandleSnapUpKey | SFYContainer::SetSnapDownKey | SFYContainer::HandleSnapDownKey | SFXEvent | Type | Event | Key Event[SFEVT_KEY]

Description

This destructor does nothing.

Reference

SFYContainer::SetPageDownKey

Reference

SFYContainer::SetPageUpKey

Reference

SFYContainer::SetScrollDownKey | SFYContainer::SetScrollStep

Return value

Description

When "true" is set to the repeat-scroll flag, the focus will jump to the top or bottom if the user tries to move the focus which is at the bottom or top respectively.

Reference

SFYContainer::SetScrollRepeat

Reference

SFYContainer::GetScrollDownKey | SFYContainer::SetScrollStep

Reference

SFYContainer::SetScrollUpKey | SFYContainer::SetScrollStep

Reference

SFYContainer::SetSnapDownKey

Reference

SFYContainer::SetSnapUpKey

Description

This function will be called when the SFEVT_KEY event(key event[SFEVT_KEY]) of the PageDown key set with the SFYContainer::SetPageDownKey function is received.

In case you want to perform your own processing, override this function.

The default implementation is to scroll down a page of the virtual region by calling the SFYContainer::PageDown function.

Internal Implementation

Internal implementation of the SFYContainer::HandlePageDownKey function is as follows:

/*protected virtual */Bool SFYContainer::HandlePageDownKey(Void)
{
    return PageDown();
}// SFYContainer::HandlePageDownKey //

Reference

SFYContainer::SetPageDownKey | SFYContainer::PageDown | Key Event[SFEVT_KEY]

Description

This function will be called when the SFEVT_KEY event(key event[SFEVT_KEY]) of the PageUp key set with the SFYContainer::SetPageUpKey function is received.

In case you want to perform your own processing, override this function.

The default implementation is to scroll up a page of the virtual region by calling the SFYContainer::PageUp function.

Internal Implementation

Internal implementation of the SFYContainer::HandlePageUpKey function is as follows:

/*protected virtual */Bool SFYContainer::HandlePageUpKey(Void)
{
    return PageUp();
}// SFYContainer::HandlePageUpKey //

Reference

SFYContainer::SetPageDownKey | SFYContainer::PageUp | Key Event[SFEVT_KEY]

Description

This function will be called when the SFEVT_KEY event(key event[SFEVT_KEY]) of the ScrollDown key set with the SFYContainer::SetScrollDownKey function is received.

In case you want to perform your own processing, override this function.

The default implementation is to scroll down the virtual region by calling the SFYContainer::ScrollDown function.

Internal Implementation

Internal implementation of the SFYContainer::HandleScrollDownKey function is as follows:

/*protected virtual */Bool SFYContainer::HandleScrollDownKey(Void)
{
    return ScrollDown();
}// SFYContainer::HandleScrollDownKey //

Reference

SFYContainer::SetScrollDownKey | SFYContainer::ScrollDown | Key Event[SFEVT_KEY]

Description

This function will be called when the SFEVT_KEY event(key event[SFEVT_KEY]) of the ScrollUp key set with the SFYContainer::SetScrollUpKey function is received.

In case you want to perform your own processing, override this function.

The default implementation is to scroll up the virtual region by calling the SFYContainer::ScrollUp function.

Internal Implementation

Internal implementation of the SFYContainer::HandleScrollUpKey function is as follows:

/*protected virtual */Bool SFYContainer::HandleScrollUpKey(Void)
{
    return ScrollUp();
}// SFYContainer::HandleScrollUpKey //

Reference

SFYContainer::SetScrollUpKey | SFYContainer::ScrollUp | Key Event[SFEVT_KEY]

Description

This function will be called when the SFEVT_KEY event(key event[SFEVT_KEY]) of the SnapDown key set with the SFYContainer::SetSnapDownKey function is received.

In case you want to perform your own processing, override this function.

The default implementation is to scroll up to the top of the virtual region by calling the SFYContainer::SnapDown function.

Internal Implementation

Internal implementation of the SFYContainer::HandleSnapDownKey function is as follows:

/*protected virtual */Bool SFYContainer::HandleSnapDownKey(Void)
{
    return SnapDown();
}// SFYContainer::HandleSnapDownKey //

Reference

SFYContainer::SetSnapDownKey | SFYContainer::SnapDown | Key Event[SFEVT_KEY]

Description

This function will be called when the SFEVT_KEY event(key event[SFEVT_KEY]) of the SnapUp key set with the SFYContainer::SetSnapUpKey function is received.

In case you want to perform your own processing, override this function.

The default implementation is to scroll down to the bottom of the virtual region by calling the SFYContainer::SnapUp function.

Internal Implementation

Internal implementation of the SFYContainer::HandleSnapUpKey function is as follows:

/*protected virtual */Bool SFYContainer::HandleSnapUpKey(Void)
{
    return SnapUp();
}// SFYContainer::HandleSnapUpKey //

Reference

SFYContainer::SetSnapUpKey | SFYContainer::SnapUp | Key Event[SFEVT_KEY]

Return value

false.

Description

This function is called in the SFYContainer::HandlePageDownKey function.

In case you want to perform your own processing, override this function.

The default implementation is only to return "false".

Reference

SFYContainer::HandlePageDownKey | SFYContainer::PageUp

Return value

false.

Description

This function is called in the SFYContainer::HandlePageUpKey function.

In case you want to perform your own processing, override this function.

The default implementation is only to return "false".

Reference

SFYContainer::HandlePageUpKey | SFYContainer::PageDown

Return value

Description

This function is called in the SFYContainer::HandleScrollDownKey function.

In case you want to perform your own processing, override this function.

The default implementation is to scroll down the virtual region as below.

Reference

SFYContainer::HandleScrollDownKey | SFYContainer::ScrollUp | SFYContainer::SetScrollStep

Return value

Description

This function is called in the SFYContainer::HandleScrollUpKey function.

In case you want to perform your own processing, override this function.

The default implementation is to scroll up the virtual region as below.

Reference

SFYContainer::HandleScrollUpKey | SFYContainer::ScrollDown | SFYContainer::SetScrollStep

Description

This function sets the PageDown key to scroll down a page of the virtual region of this responder to the specified value.

The SFYContainer::HandlePageDownKey function will be called when this key event occurs.

Default: AVK_TXPGDOWN

Reference

SFYContainer::HandlePageDownKey | SFYContainer::GetPageDownKey

Description

This function sets the PageUp key to scroll up a page of the virtual region of this responder to the specified value.

The SFYContainer::HandlePageUpKey function will be called when this key event occurs.

Default: AVK_TXPGUP

Reference

SFYContainer::HandlePageUpKey | SFYContainer::GetPageUpKey

Description

This function sets the ScrollDown key to scroll down the virtual region of this responder to the specified value.

The SFYContainer::HandleScrollDownKey function will be called when this key event occurs.

Default: AVK_DOWN

Reference

SFYContainer::HandleScrollDownKey | SFYContainer::GetScrollDownKey | SFYContainer::SetScrollStep

Description

When the repeat-scroll flag is set to"true" , the focus will jump to the top or bottom if the user tries to move the focus which is at the bottom or top respectively.

Reference

SFYContainer::GetScrollRepeat

Description

This function sets the scroll-step [pixel unit] to scroll using the SFYContainer::ScrollUp function and the SFYContainer::ScrollUp function to the specified value.

Default: DEFAULT_STEP(20 pixels)

Reference

SFYContainer::GetScrollStep | SFYContainer::DefaultEnum

Description

This function sets the ScrollUp key to scroll up the virtual region of this responder to the specified value.

The SFYContainer::HandleScrollUpKey function will be called when this key event occurs.

Default: AVK_UP

Reference

SFYContainer::HandleScrollUpKey | SFYContainer::GetScrollUpKey | SFYContainer::SetScrollStep

Description

This function sets the SnapDown key to scroll down to the bottom of the virtual region of this responder to the specified value.

The SFYContainer::HandleSnapDownKey function will be called when this key event occurs.

Default: AVK_TXEND

Reference

SFYContainer::HandleSnapDownKey | SFYContainer::GetSnapDownKey

Description

This function sets the SnapUp key to scroll up to the top of the virtual region of this responder to the specified value.

The SFYContainer::HandleSnapUpKey function will be called when this key event occurs.

Default: AVK_TXHOME

Reference

SFYContainer::HandleSnapUpKey | SFYContainer::GetSnapUpKey

Return value

false.

Description

This function is called in the SFYContainer::HandleSnapDownKey function.

In case you want to perform your own processing, override this function.

The default implementation is only to return "false".

Reference

SFYContainer::HandleSnapDownKey | SFYContainer::SnapUp

Return value

false.

Description

This function is called in the SFYContainer::HandleSnapUpKey function.

In case you want to perform your own processing, override this function.

The default implementation is only to return "false".

Reference

SFYContainer::HandleSnapUpKey | SFYContainer::SnapDown

Reference

SFYResponder::GetType | SFYResponder::SetType

Reference

SFYContainer::SetScrollStep