Inheritance diagram

Collaboration diagram

Description

How to use

SFYResponder is the kernel of the SFY responder system, which is constituted by SFYResponder and responders inheriting from this class.

The SFY responder system is a GUI framework to automatically dispatch an event sent from the BREW environment(BREW-defined event) and draw the screen only by placing GUI components called "Responder".

The various functions are equipped with the SFY responder system as below.

Such user interface components include window, menu, dialog, control, frame and so on.

The inheritance relationship and the owner relationship as below exist among these GUI components called "Responder". This hierarchy automates event handling and rendering the GUI components in the BREW environment.

Figure 301. Inheritance relationship

Figure 302. Owner relationship

Figure 303. Owner and parent-child relationship around frame

Dialog and menu is positioned in the same layer with window.

Container is designed to manage controls or other containers(only container), and be managed by control or other containers(container/window/dialog) exceptionally.

	About frame
	A frame(frame) that has border or title can be attached to a responder such as a window, a dialog, or a menu. A framed responder owns a frame. The frame is not a parent or a child of the responder. A parent of the frame is the same as a responder's parent. However, the frame is not a child of the parent.

In SFYResponder, elements and functions common among various responders are implemented by default.

SFYResponder is the most abstract base class to define and implement a user-defined responder class.

The minimum code necessary to make user-defined responder is as follows.

SFMTYPEDEFRESPONDER(USRResponder)
class USRResponder: public SFYResponder {
    SFMSEALRESPONDER(USRResponder)
    SFMRESPONDERINSTANTIATEONE(USRResponder, 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', 'R', 'S', 'P')
    };
    SFMTYPEDEFTYPE(CodeEnum)

public:
    static USRResponderSmp NewInstance(SFCErrorPtr exception = null);
protected:
    explicit USRResponder(Void) static_throws;
    virtual ~USRResponder(Void);
};

Example 879. Implementation

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

        // set the responder type
 SetType(CODE_TYPE);

        // describe initialization processing
    }
}

// destructor
USRResponder::~USRResponder(Void)
{
    // describe termination processing
}

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

	The return statement in constructor and destructor
	In general, the return statement should not be written in constructor and destructor with C++. The bug has been confirmed in GCC. It is that compiler will freeze if the return statement is written in constructor and destructor under some particular inheritance relationship.

Reference

Responder(Basic) | SFY Responder System | Development with SFY GUI Framework | SFY Responder Window | Dialog | Menu | Control | Frame | BREW-Defined Event

Member

Description

This constructor performs the initializations as follows:

	Tip
	This function may carry out the exception. It is necessary to judge the exception at the begining of the constructor of classes that inherit from this class. Type of a responder needs to be set in the constructor.

Example

The following is the code to write the constructor of the USRWindow class.

USRWindow::USRWindow(Void)
{
    if (static_try()) {

        // type must be set here
        // with this setting, 
        // parent class type is set when error occurs in the parent class's constructor, 
        // while this class type is set when error occurs in this constructor
        // therefore easy to determine where error occurs in using this class externally
 SetType(four_char_code('U', 'W', 'N', 'D'));

        // here describe the initialization
        ...
    }
}

Reference

SFYResponder::SetType | SFYResponder::CodeEnum | SFYResponder::SetState | SFYResponder::SetPropertyTransparent | SFYResponder::SetID | SFYResponder::SetRealBound | SFYResponder::SetVirtualBound | SFXRectangle | SFYDistributer | SFYRenderer | Attribute | State | Type | ID | Real Region | Virtual Region

Description

This destructor performs the finalizations as follows:

Reference

SFYResponder::SFYResponder | SFYDistributer | SFYRenderer

Description

This function unregisters all handlers from this responder.

Reference

SFYResponder::RegisterHandler | SFYResponder::UnregisterHandler | Handler

Description

This function unregisters all dispatching rules from the tracer of this responder.

Reference

SFYResponder::RegisterTracer | SFYResponder::UnregisterTracer | SFYTracer | Tracer

Return value

Description

This function distributes an event of the distribute type to this responder.

If the return value is "true", it is necessary to call the SFYResponder::Render function for redrawing the screen since the contents of some responders may be changed.

This function boots up the distributer to distribute the specified event of the distribute type to this responder according to the rules registered into the tracer. As a result, the corresponding handlers will be called.

Tip

In case of the BREW-defined event, when an applet receives an event dispatched from the BREW environment, the SFYApplication::HandleEvent function will be called automatically and then the SFYResponder::Distribute function is called in this function. Therefore, there is no need to call the SFYResponder::Distribute function explicitly. In case of the user-defined event, the SFYResponder::Distribute function needs to be explicitly called since the SFYApplication::HandleEvent function will not be booted up.

	Important
	Though the SFYResponder::InvokeForward / SFYResponder::InvokeBackward functions will send an event of the callback type to a responder to call handlers, the event will not be distributed to its child responders. The event dispatched using this function may be distributed to the child responders of the target responder depending on the rules registered into the tracer.

Example

The below is the usage example in the implementation of the SFYApplication::HandleEvent function.

// virtual function that will be called when the event dispatched from the BREW environment needs to be handled
/*protected virtual */Bool SFYApplication::HandleEvent(SFXEventConstRef event)
{
    // here describe the handling of the event dispatched from the BREW environment

    SFCError  error;
    Bool      result(false);

    // boot up the distributer to distribute the event using the tracer
    // first of all, the SFYDistributer instance bound with the root will receive the event
    // then, the event will be distributed to the responders in the responder tree according to the dispatching rules of the tracer
    // * _root is the root(SFZRoot)
    if ((error = _root->Distribute(event, &result)) == SFERR_NO_ERROR) {

        if (event.GetType() != SFEVT_APP_STOP && event.GetType() != SFEVT_APP_SUSPEND)) {  // if redrawing is necessary

            if (IsRenderable()) {  // if the screen can be redrawn (i.e., if no highest priority event handler is registered)

                 // boot up the renderer to redraw the responder tree below the root
                error = _root->Render();
            }
        }
    }
    if (error != SFERR_NO_ERROR) {

        // call HandleError() in case the fatal error such as insufficient memory during the initialization of the distributer or the renderer occurs
        if (HandleError(event, error)) {

            result = true;
        }
    }
    if ((event.GetType() == SFEVT_APP_SUSPEND) && IsRendererIntermissive()) {
        // if the back-up bitmap inside the renderer is released when an application suspends

        // terminate the renderer
        _renderer.Terminate();
    }
    return result;  // return "true" if the event has been handled, otherwise return "false"
}// SFYApplication::HandleEvent //

Reference: SFCApplication::HandleEvent | SFCApplication::IsRenderable | SFCApplication::HandleError | SFYApplication::IsRendererIntermissive | SFYResponder::Distribute | SFYResponder::Render | SFYRenderer::Initialize | SFYRenderer::Terminate | SFZRoot | Root | Tracer | Distributer | Renderer Drawing Event | Drawing Handler | Event Loop

Reference

SFYResponder::InvokeForward | SFYResponder::InvokeBackward | SFXEvent | Event | Distribute Type | Callback Type | Event Loop | Handler | Tracer | BREW-Defined Event | Responder-Defined Event

Argument

Return value

Description

This function is used to implement the NewInstance function which is necessary to define the concrete class of a responder newly.

With this function, the NewInstance function for the concrete class of a responder can be implemented easily.

	static_pointer_cast operator
	Since the SFYResponder::Factory function returns the value of the SFYResponderSmp type, it is necessary to downcast it into the type of the newly created responder class with the static_pointer_cast operator.

Example

The following is the code to implement the NewInstance function of the USRWindow class.

USRWindowSmp USRWindow::NewInstance(SFCErrorPtr exception)
{
    return static_pointer_cast<USRWindow>(Factory(::new USRWindow, exception));
}

Implementation of the SFYResponder::Factory function is as follows:

/*protected static */SFYResponderSmp SFYResponder::Factory(SFYResponderPtr responder, SFCErrorPtr exception)
{
    SFCError                                    error;
    SFYResponderSmp                             result;

    error = SFERR_NO_ERROR;
    if (responder != null) {
        if ((error = responder->static_catch()) == SFERR_NO_ERROR) {
            responder->Initialize();  initialize the responder
            result.Set(responder, false);
        }
        else {
            ::delete responder;
        }
    }
    else {
        error = SFERR_NO_MEMORY;
    }
    if (exception != null) {
        *exception = error;
    }
    return result;
}// SFYResponder::Factory //

Reference

SFYResponder::Initialize

Return value

Backmost child responder of this responder.

"null" will be returned if it does not exist.

Description

This function gets the backmost child responder of this responder, which matches the specified search condition. If there is no child responder, "null" will be returned.

	Tip
	The child responders to be searched can be limited by specifying the ID and the conditions of visible, active, enable, or focus state.

	Tip
	The attachment-frames are not included in the searching.

Example

SFYResponderSmp child;

get the backmost responder among all child responders
child = GetChildBack();

get the backmost responder among all child responders with ID = 128
child = GetChildBack(128);

get the backmost responder among visible child responders (not care about the enable state and focus state)
child = GetChildBack(true, true, false, false);

get the backmost responder among visible and enable child responders (not care about the focus state)
child = GetChildBack(true, true, true, false);

Reference

SFYResponder::GetChildFront | SFYResponder::GetChildBackward | SFYResponder::GetNthBackward | ID | State | Child Responder

Return value

Child responder of this responder at the specified position from the back side.

"null" will be returned if it does not exist.

Description

This function gets the child responder of this responder at the specified position from the back side. If there is no child responder, "null" will be returned.

	Tip
	The child responders to be searched can be limited by specifying the ID and the conditions of visible, active, enable, or focus state.

	Tip
	The attachment-frames are not included in the searching.

Example

SFYResponderSmp child;

get the responder at the 3rd position among all child responders from the back side
child = GetChildBackward(2);

get the responder at the 3rd position among all child responders with ID = 128 from the back side
child = GetChildBackward(2, 128);

get the responder at the 3rd position among all visble child responders from the back side (not care about the enable state and focus state) 
child = GetChildBackward(2, true, true, false, false);

get the responder at the 3rd position among all visble and enable child responders from the back side (not care about the focus state) 
child = GetChildBackward(2, true, true, true, false);

Reference

SFYResponder::GetChildForward | SFYResponder::GetNthBackward | SFYResponder::GetChildBack | ID | State | Child Responder

Return value

Number of child responders of this responder.

Description

This function gets the number of child responders of this responder, which match the specified search condition. If there is no child responder, 0 will be returned.

	Tip
	The child responders to be searched can be limited by specifying the ID and the conditions of visible, active, enable, or focus state.

	Tip
	The attachment-frames are not included in the searching.

Example

SInt32 count;

get the number of all child responders
count = GetChildCount();

get the number of all child responders with ID = 128
count = GetChildCount(128);

get the number of all visible child responders (not care about the enable state and focus state)
count = GetChildCount(true, true, false, false);

get the number of all visible and enable child responders (not care about the focus state)
count = GetChildCount(true, true, true, false);

Reference

ID | State | Child Responder

Return value

Child responder of this responder at the specified position from the front side.

"null" will be returned if it does not exist.

Description

This function gets the child responder of this responder at the specified position from the front side, which matches the specified search condition. If there is no child responder, "null" will be returned.

	Tip
	The child responders to be searched can be limited by specifying the ID and the conditions of visible, active, enable, or focus state.

	Tip
	The attachment-frames are not included in the searching.

Example

SFYResponderSmp child;

get the responder at the 3rd position among all child responders from the front side
child = GetChildForward(2);

get the responder at the 3rd position among all child responders with ID = 128 from the front side
child = GetChildForward(2, 128);

get the responder at the 3rd position among all visble child responders from the front side (not care about the enable state and focus state) 
child = GetChildForward(2, true, true, false, false);

get the responder at the 3rd position among all visble and enable child responders from the front side (not care about the focus state) 
child = GetChildForward(2, true, true, true, false);

Reference

SFYResponder::GetChildBackward | SFYResponder::GetNthForward | SFYResponder::GetChildFront | ID | State | Child Responder

Return value

Foremost child responder of this responder.

"null" will be returned if it does not exist.

Description

This function gets the foremost child responder of this responder, which matches the specified search condition. If there is no child responder, "null" will be returned.

	Tip
	The child responders to be searched can be limited by specifying the ID and the conditions of visible, active, enable, or focus state.

	Tip
	The attachment-frames are not included in the searching.

Example

SFYResponderSmp child;

get the foremost responder among all child responders
child = GetChildFront();

get the foremost responder among all child responders with ID = 128 
child = GetChildFront(128);

get the foremost responder among all visible child responders (not care about the enable state and focus state)
child = GetChildFront(true, true, false, false);

get the foremost responder among all visible and enable child responders (not care about the focus state)
child = GetChildFront(true, true, true, false);

Reference

SFYResponder::GetChildBack | SFYResponder::GetChildForward | SFYResponder::GetNthForward | ID | State | Child Responder

Return value

Distributer bound with this responder.

"null" will be returned if no distributer is bound with this responder.

Description

This function gets the distributer bound with this responder.

Reference

SFYResponder::SetDistributer | Distributer

Return value

Description

This function gets the frame(attachment-frame) which has been attached to this responder with the SFYResponder::SetFrame function.

Reference

SFYResponder::SetFrame | SFYFrame

Return value

Global region of this responder.

Description

This function gets the global region of this responder.

Reference

SFYResponder::GetLocalBound | SFYResponder::GetRealBound | SFXRectangle | Global Region

Return value

ID of this responder instance.

Description

This function gets the ID of this responder instance.

Reference

SFYResponder::SetID | ID

Return value

Local region of this responder.

Description

This function gets the local region of this responder.

Reference

SFYResponder::GetGlobalBound | SFYResponder::GetVirtualBound | SFXRectangle | Local Region

Return value

Position counted from the back side of this responder among a group of sibling responders.

Description

This function gets the position counted from the back side of this responder among a group of sibling responders, which match the specified search condition.

	Tip
	The sibling responders to be searched can be limited by specifying the ID and the conditions of visible, active, enable, or focus state.

	Tip
	The attachment-frames are not included in the searching.

Example

SInt32 index;

get the position counted from the back side of a responder among all sibling responders
index = GetNthBackward();

get the position counted from the back side of a responder among all sibling responders with ID = 128
index = GetNthBackward(128);

get the position counted from the back side of a responder among visible and active sibling responders (not care about the enable state and focus state)
index = GetNthBackward(true, true, false, false);

get the position counted from the back side of a responder among visible, active and enable sibling responders (not care about the focus state)
index = GetNthBackward(true, true, true, false);

Reference

SFYResponder::GetNthForward | SFYResponder::GetChildBackward | SFYResponder::GetChildBack | ID | Sibling Responder | State

Return value

Position counted from the front side of this responder among a group of sibling responders.

Description

This function gets the position counted from the front side of this responder among a group of sibling responders, which match the specified search condition.

	Tip
	The sibling responders to be searched can be limited by specifying the ID and the conditions of visible, active, enable, or focus state.

	Tip
	The attachment-frames are not included in the searching.

Example

SInt32 index;

get the position counted from the front side of a responder among all sibling responders
index = GetNthForward();

get the position counted from the front side of a responder among all sibling responders with ID = 128
index = GetNthForward(128);

get the position counted from the front side of a responder among visible and active sibling responders (not care about the enable state and focus state)
index = GetNthForward(true, true, false, false);

get the position counted from the front side of a responder among visible, active and enable sibling responders (not care about the focus state)
index = GetNthForward(true, true, true, false);

Reference

SFYResponder::GetNthBackward | SFYResponder::GetChildForward | SFYResponder::GetChildFront | ID | Sibling Responder | State

Return value

Description

This function gets the parent responder of this responder.

If this responder is an attachment-frame, this function returns the parent responder of the corresponding content-responder.

Reference

SFYResponder::SetParent| SFYResponder::SetFrame | Parent Responder

Description

This property gets the transparency attribute of this responder.

Reference

SFYResponder::SetPropertyTransparent | Attribute

Return value

Real region of this responder.

Description

This function gets the real region of this responder.

Reference

SFYResponder::SetRealBound | SFYResponder::GetVirtualBound | SFYResponder::GetGlobalBound | SFXRectangle | Real Region

Return value

Reference value of this responder.

"null" will be returned if no reference value is set.

Description

This function gets the reference value(4-byte) of this responder. If no reference value is set, "null" will be returned.

Example

The code to set a reference value as an identification number to text button controls and get it is as follows:

SFZTextButtonControlSmp _button;
SInt32 i;

// make 10 text button controls and set references(identification numbers) to them
for (i = 0; i < 10; ++i) {

    // create text button control
    if ((_button = SFZTextButtonControl::NewInstance(&error)) != null) {

        // set the text button control's parent responder to GetThis()
        error = _button->SetParent(GetThis());
        if (error == SFERR_NO_ERROR) {

            // set reference value as identification number to text button control
            _button->SetReference(reinterpret_cast<VoidPtr>(i));
        }
    }
}

...

// get identification number(reference value) for text button control
SInt32 number = reinterpret_cast<SInt32>(_button->GetReference());

Reference

SFYResponder::SetReference | Reference

Return value

Renderer bound with this responder.

"null" will be returned if no renderer is bound with this responder.

Description

This function gets the renderer bound with this responder.

Reference

SFYResponder::SetRenderer | Renderer

Return value

Root responder of the responder tree to which this responder belongs.

Description

This function gets the root responder of the responder tree to which this responder belongs.

Reference

SFYResponder::IsRoot | Responder Tree | Root Responder

Return value

Description

This function gets the active state of this responder.

If "true" is specified in the "inherit" argument, the ON/OFF value of the active state will be obtained. Otherwise(default), the flag value of the active state will be obtained.

When "true" is specified in the "inherit" argument, "true" will be returned if the active sate is "ON". Otherwise, "false" will be returned.

	Tip
	If this responder is an attachment-frame, this function will return the ON/OFF value of the corresponding content-responder. However, this premises that all the states of the attachment-frame are set to "true". About an Attachment-Frame and a Content-Responder Fore more details, see the description of the SFYResponder::SetFrame function.

	Behaviour of the active state
	The responder will be actually drawn as in the active state if the active state is "ON". The responder will not be drawn as in the active state if the active state is "OFF", even if the active state flag is set to "true".

Reference

SFYResponder::SetStateActive | SFYResponder::SetFrame | State

Return value

Description

This function gets the enable state of this responder.

If "true" is specified in the "inherit" argument, the ON/OFF value of the enable state will be obtained. Otherwise(default), the flag value of the enable state will be obtained.

When "true" is specified in the "inherit" argument, "true" will be returned if the active sate is "ON". Otherwise, "false" will be returned.

	Tip
	If this responder is an attachment-frame, this function will return the ON/OFF value of the corresponding content-responder. However, this premises that all the states of the attachment-frame are set to "true".

	Behaviour of the enable state
	The responder can be focused if the enable state is "ON". The responder cannot be focused if the enable state is "OFF", even if the enable state flag is set to "true".

	About ON/OFF of the state
	For more details on ON/OFF of the state, see State.

Reference

SFYResponder::SetStateEnable | SFYResponder::SetFrame | State

Return value

Description

This function gets the focus state of this responder.

If "true" is specified in the "inherit" argument, the ON/OFF value of the focus state will be obtained. Otherwise(default), the flag value of the focus state will be obtained.

When "true" is specified in the "inherit" argument, "true" will be returned if the active sate is "ON". Otherwise, "false" will be returned.

	Tip
	If this responder is an attachment-frame, this function will return the ON/OFF value of the corresponding content-responder. However, this premises that all the states of the attachment-frame are set to "true".

	Behaviour of the focus state
	The responder is focused if the focus state is "ON". The responder is not focused if the focus state is "OFF", even if the focus state flag is set to "true".

	About ON/OFF of the state
	For more details on ON/OFF of the state, see State.

Reference

State | SFYResponder::SetFrame | SFYResponder::SetStateFocus

Return value

Description

This function gets the valid state of this responder.

If "true" is specified in the "inherit" argument, the ON/OFF value of the valid state will be obtained. Otherwise(default), the flag value of the valid state will be obtained.

When "true" is specified in the "inherit" argument, "true" will be returned if the active sate is "ON". Otherwise, "false" will be returned.

	Tip
	If this responder is an attachment-frame, this function will return the ON/OFF value of the corresponding content-responder. However, this premises that all the states of the attachment-frame are set to "true".

	Behaviour of the valid state
	The responder can receive an event if the valid state is "ON". The responder cannot receive an event if the valid state is "OFF", even if the valid state flag is set to "true".

	About ON/OFF of the state
	For more details on ON/OFF of the state, see State.

Reference

SFYResponder::SetDistributer | SFYResponder::Initialize | SFYResponder::Terminate | SFYResponder::SetFrame | State

Return value

Description

This function gets the visible state of this responder.

If "true" is specified in the "inherit" argument, the ON/OFF value of the visible state will be obtained. Otherwise(default), the flag value of the visible state will be obtained.

When "true" is specified in the "inherit" argument, "true" will be returned if the active sate is "ON". Otherwise, "false" will be returned.

	Tip
	If this responder is an attachment-frame, this function will return the ON/OFF value of the corresponding content-responder. However, this premises that all the states of the attachment-frame are set to "true".

	Behaviour of the visible state
	The responder will be visible if the visible state is "ON". The responder will not be visible if the visible state is "OFF", even if the visible state flag is set to "true".

	About ON/OFF of the state
	For more details on ON/OFF of the state, see State.

Reference

State | SFYResponder::SetFrame | SFYResponder::SetStateVisible

Return value

Suitable region of this responder.

Description

This function gets the suitable region of this responder. This function is used to set the suitable real region of this responder

If this is an attaching frame, this delegates the calculation of suitable region to the attached responder.

If the rectangle argument of the hint region is specified, the suitable region is calculated as the region within this hint region.

If the rectangle argument of the hint region and the alignment arguments are specified, the suitable region is calculated as the region within this hint region, and it is aligned with the alignments within the hint region.

The origin of the return value of the suitable region is as follows:

When you set the real region of a responder with this function, place the suitable region at the suitable position if necessary.

	Tip
	In case of the SFZSoftKeyControl class, the suitable region will be placed at the bottom of the device screen.

	Tip
	In case of the responder such as a label or a button, the suitable region will be gotten by calling SFYResponder::GetSuitableBound() after a text or an image is set. Since the origin of the return value of the suitable region is (0, 0), the real region will be set after placing it at the suitable position with the function such as SFXRectangle::SetOrigin or SFXRectangle::Offset.

	Region event[(SFEVT_RESPONDER_BOUND, SFP16_BOUND_OPTIMIZE) event]
	If the rectangle argument of the hint region is specified, the SFYResponder::GetSuitableBound function will send the region event [SFXEvent(SFEVT_RESPONDER_BOUND, SFP16_BOUND_OPTIMIZE, rectangle)] to this responder. Then, the SFYWidget::HandleBoundOptimize virtual function will be called. The rectangle element (P32 parameter) of the region event is set to the hint region as an initial value.

Region event[(SFEVT_RESPONDER_BOUND, SFP16_BOUND_REQUEST) event]

If the rectangle argument of the hint region is not specified, the SFYResponder::GetSuitableBound function will send the region event [SFXEvent(SFEVT_RESPONDER_BOUND, SFP16_BOUND_REQUEST, rectangle)] to this responder. Then, the SFYWidget::HandleBoundRequest virtual function will be called. The rectangle element (P32 parameter) of the region event is set to the real region as an initial value. Tip Default value of the real region: SFXRectangle(0, 0, 0, 0)

	CAUTION
	The actual calculation will be performed by the SFYWidget::HandleBoundRequest / SFYWidget::HandleBoundOptimize virtual function. For the responder where the above functions are not implemented, this function will only return the hint region specified in the argument or the real region as it is.

Example

The code to set the suitable real region of the text button control is as follows:

SFZTextButtonControlSmp button;

...

// set button's text
button->SetText("sample");

// 1. calculate button's suitable region based on this text
// 2. relocate button's suitable region with SetOrigin() and set button's real region to it
button->SetRealBound(button->GetSuitableBound().SetOrigin(10, 10));

...

Reference

SFYWidget::HandleBoundRequest | SFYWidget::HandleBoundOptimize | SFYResponder::SetRealBound | SFXRectangle | Real Region | Region Event[SFEVT_RESPONDER_BOUND]

Return value

Description

This function gets the frame margin region(SFXMargin) of this responder. The outer frame or/and the title of this responder will be drawn in this frame margin.

This function will send the margin event [SFXEvent(SFEVT_RESPONDER_MARGIN, SFP16_MARGIN_REQUEST, margin)] to this responder.

When the concrete frame responder inheriting from SFYFrame receives the margin event, the SFYFrame::HandleMarginRequest virtual function will be called to calculate the frame margin region.

	Warning
	When a frame is attached to a responder with the SFYResponder::SetFrame function, the real region of the attachment-frame or the content-responder will be automatically calculated by using this function. Therefore, it is a rare chance that a developer will call this function.

Reference

SFYFrame::HandleMarginRequest | SFYResponder::SetFrame | SFYFrame | SFXMargin | Frame | Margin Event[SFEVT_RESPONDER_MARGIN]

Return value

"this" pointer maintained by smart pointer of this responder.

Description

This function gets the smart pointer of this responder.

Internal Implementation

Internal implementation of the SFYResponder::GetThis function is as follows:

/*protected */SFYResponderSmp SFYResponder::GetThis(Void)
{
    return SFYResponderSmp(this);
}// SFYResponder::GetThis //

Reference

SFXResponderPointer

Return value

Type of this responder class.

If the type is not set for this responder class, the type of the parent responder class which this responder class inherits from will be returned.

Description

This function gets the type of this responder class.

使用例

Void USRApplication::PrintType(SFYResponderSmpConstRef param) Const
{
    switch (param->GetType()) {
        case SFZWindow::CODE_TYPE:
            TRACE("This responder is of the SFZWindow class.");
            break;
        case SFZDialog::CODE_TYPE:
            TRACE("This responder is of the SFZDialog class.");
            break;
        case SFZTextButtonControl::CODE_TYPE:
            TRACE("This responder is of the SFZTextButtonControl class.");
            break;
        default:
            TRACE("This responder is of the unknown class.");
            break;
    }
    return;
}

Reference

SFYResponder::SetType | Type | Type List

Return value

Virtual region of this responder.

Description

This function gets the virtual region of this responder.

Reference

SFYResponder::SetVirtualBound | SFYResponder::GetRealBound | SFYResponder::GetLocalBound | SFXRectangle | Virtual Region

Return value

Description

This function checks whether or not this responder is a content-responder.

	About an Content-Responder
	Fore more details, see the description of the SFYResponder::SetFrame function.

Reference

SFYResponder::IsFrame | SFYResponder::SetFrame | SFYFrame

Description

This function sets the valid state flag of this responder to "true".

	Caution
	There is no need for developer to call this function explicitly since it has already been called in the SFYResponder::Factory function.

	Caution
	It is prohibited to reinitialize the responder terminated by the SFYResponder::Terminate function with this function.

Example

The below is the example code to implement the SFYResponder::Factory function with the SFYResponder::Initialize function. In general, the SFYResponder::Initialize function is called only in the SFYResponder::Factory function.

/*protected static */SFYResponderSmp SFYResponder::Factory(SFYResponderPtr responder, SFCErrorPtr exception)
{
    SFCError                                    error;
    SFYResponderSmp                             result;

    error = SFERR_NO_ERROR;
    if (responder != null) {
        if ((error = responder->static_catch()) == SFERR_NO_ERROR) {
            responder->Initialize();  initialize the responder
            result.Set(responder, false);
        }
        else {
            ::delete responder;
        }
    }
    else {
        error = SFERR_NO_MEMORY;
    }
    if (exception != null) {
        *exception = error;
    }
    return result;
}// SFYResponder::Factory //

Reference

SFYResponder::Terminate | SFYResponder::Factory | SFXEvent | State | State Event[SFEVT_RESPONDER_STATE]

Description

This function registers the specified rectangular region in the local region of this responder as the redraw region.

	Tip
	If nothing is specified in the argument, the real region of this responder will be regarded as specified.

This function is used when redrawing of this responder is necessary as a result of changing of its visual elements such as a text or an image.

When the SFYResponder::Render() function is called with no argument specified, only drawing handers of the responders whose region are registered with this function and need to be redrawn will be booted up.

	Note
	If this responder is in the "invisible" state or the registered redraw region is hidden by other responders, its drawing handler will not be called even if the SFYResponder::Render function is called.

Tip

In general, SFYResponder::Render() needs not to be called in the event loop processing since the SFYResponder::Render() function of the root(SFZRoot) which this application contains by default will be automatically called at the end of each event loop. (For more details, see the default implementation of the SFYApplication::HandleEvent function.) TheSFYResponder::Render() function is not automatically called in the callback outside the event loop such as a network or timer callback. To redraw the screen in the callback processing, the renderer needs to be booted up by calling the SFYResponder::Render() function explicitly.

	Optimize drawing processing
	The Invalidate() function has the overload function with the rectangle argument. If a subset rectangle of responder is specified as the redraw region, drawing performance may improve since there is more possibility that it will be included in the union of the responders placed foreground.

	Caution
	The Invalidate() function only registers the redraw region. Actual drawing is performed in the drawing handler.

Example

The code to redraw a text when it changes is as follows:

SFXWideString _my_text;

...

Void USRWindow::SetText(SFXWideStringConstRef param)
{
    if (param != _my_text) {

        _my_text = param;
        
        Invalidate();  // register USRWindow's real region into the Renderer as the redraw region
    }
    return;
}

// drawing hander: booted up in the Render() called at the end of the event loop
XANDLER_IMPLEMENT_VOIDRENDER(USRWindow, OnRender, invoker, reason, graphics)
{
    // actually draw _my_text in black at the center of USRWindow's real region
    graphics->DrawSingleText(_my_text, GetLocalBound(), SFXRGBColor(0x00, 0x00, 0x00, 0x00));

    return;
}

Reference

SFYResponder::Render | SFZRoot | Local Region | Real Region | State | Drawing | Drawing Hander | Event Loop | Root(Basic)

Description

This function sends the specified event of the callback type to this responder.

The handlers are booted up in the order to be registerd into the handler list of this responder.

In case "false" is specified in the "overload" argument(i.e., duplicate processing condition), event handling will end if the handler function handles the event and returns "true".

In case "true" is specified in the "overload" argument, event handling will continue while next handler to be executed exists even if the handler function handles the event and returns "true".

	Responder-Defined Event
	Responder-defined event is sent using the InvokeBackward() or InvokeForward() function.

	Case study
	In the implementation of a responder such as a button control or a dialog, this function will be used to send the style event when a text or an image inside responder is changed.

	SFYResponder::InvokeForward function
	To call the handler function in the reverse order to be registered into the handler list, use the SFYResponder::InvokeForward function.

	Target of the event
	Different from Type 1 of the SFYResponder::Distribute function, the event sent with the SFYResponder::InvokeBackward function will not be dispatched to any child responder of the target responder.

	Sending an event in the destructor
	Since the valid state of a responder is "invalid" immediately before executing the destructor, any event must not be sent to itself in the destructor.

	Sending an event in the callback
	When an event is sent with the SFYResponder::InvokeBackward function in the callback outside the event loop, it is necessary to wrap the event sending with Type 2 of the SFYResponder::Distribute function. For more details, see the description of Type 2 of the SFYResponder::Distribute function.

Example

The code to send the style event when a text is changed is as follows:

SFXWideString _my_text;

...

USRWindow::SetText(SFXWideStringConstRef param)
{
    if (param != _my_text) {

       // set _my_text to param
       _my_text = param;

       // register the real region of this responder as the redraw region
       Invalidate();

       // send the style event
       InvokeBackward(SFXEvent(SFEVT_RESPONDER_STYLE, SFP16_STYLE_TEXT, 0), true);
    }

    return;
}

Reference

SFYResponder::InvokeForward | SFYResponder::Distribute | SFXEvent | Responder-Defined Event | Callback Type | Handler | Handler List | Style Event[SFEVT_RESPONDER_STYLE] | Event Loop

Description

This function sends the specified event of the callback type to this responder.

The handlers are booted up in the reverse order to be registerd into the handler list of this responder.

In case "false" is specified in the "overload" argument(i.e., duplicate processing condition), event handling will end if the handler function handles the event and returns "true".

In case "true" is specified in the "overload" argument, event handling will continue while next handler to be executed exists even if the handler function handles the event and returns "true".

	Responder-Defined Event
	Responder-defined event is sent using the InvokeBackward() or InvokeForward() function.

	Case study
	In the implementation of a responder such as a button control or a dialog, this function will be used to send the result event when operation is done agaist it.

	SFYResponder::InvokeBackward function
	To call the handler function in the order to be registered into the handler list, use the SFYResponder::InvokeBackward function.

	Target of the event
	Different from Type 1 of the SFYResponder::Distribute function, the event sent with the SFYResponder::InvokeForward function will not be dispatched to any child responder of the target responder.

	Sending an event in the destructor
	Since the valid state of a responder is "invalid" immediately before executing the destructor, any event must not be sent to itself in the destructor.

	Sending an event in the callback
	When an event is sent with the SFYResponder::InvokeForward function in the callback outside the event loop, it is necessary to wrap the event sending with Type 2 of the SFYResponder::Distribute function. For more details, see the description of Type 2 of the SFYResponder::Distribute function.

Example

The code to send the result event when a button is operated is as follows:

// handler for the key-release event of the operation key
Void USRControl::HandleOperateKeyRelease(Void)
{

    // send the result event
    InvokeForward(SFXEvent(SFEVT_RESPONDER_RESULT, SFP16_RESULT_OK, GetCurrentValue()), false);

    return;
}

Reference

SFYResponder::InvokeBackward | SFYResponder::Distribute | SFXEvent | Callback Type | Responder-Defined Event | Handler | Handler List | Result Event[SFEVT_RESPONDER_RESULT] | Event Loop

Return value

Description

This function checks whether or not this responder is the backmost responder among a group of the sibling responders which match the specified search condition.

	Tip
	The sibling responders to be checked can be limited by specifying the ID and the conditions of visible, active, enable, or focus state.

	Tip
	The attachment-frames are not included in the searching.

Example

check whether or not this responder is the backmost among all sibling responders
if (IsBack()) {
    ...
}

check whether or not this responder is the backmost among all sibling responders with ID = 128 
if (IsBack(128)) {
    ...
}

check whether or not this responder is the backmost among visible responders (not care about the enable state and focus state)
if (IsBack(true, true, false, false)) {
    ...
}

check whether or not this responder is the backmost among visible enable responders (not care about the focus state)
if (IsBack(true, true, true, false)) {
    ...
}

Reference

SFYResponder::IsFront | SFYResponder::IsNthBackward | ID | Sibling Responder | State

Return value

Description

This function checks whether or not this responder is an attachment-frame.

	About an Attachment-Frame
	Fore more details, see the description of the SFYResponder::SetFrame function.

Reference

SFYResponder::HasFrame | SFYResponder::SetFrame | SFYFrame

Return value

Description

This function checks whether or not this responder is the foremost responder among a group of the sibling responders which match the specified search condition.

	Tip
	The sibling responders to be checked can be limited by specifying the ID and the conditions of visible, active, enable, or focus state.

	Tip
	The attachment-frames are not included in the searching.

Example

check whether or not this responder is the foremost among all sibling responders
if (IsFront()) {
    ...
}

check whether or not this this responder is the foremost among all sibling responders with ID = 128
if (IsFront(128)) {
    ...
}

check whether or not this responder is the foremost among visible responders (not care about the enable state and focus state)
if (IsFront(true, true, false, false)) {
    ...
}

check whether or not this responder is the foremost among visible and enable responders (not care about the focus state)
if (IsFront(true, true, true, false)) {
    ...
}

Reference

SFYResponder::IsBack | SFYResponder::IsNthForward | ID | Sibling Responder | State

Return value

Description

This function checks whether or not this responder is at the specified position from the back side among a group of the sibling responders which match the specified search condition.

	Tip
	The sibling responders to be checked can be limited by specifying the ID and the conditions of visible, active, enable, or focus state.

	Tip
	The attachment-frames are not included in the searching.

Example

check whether or not this responder is at 3rd position from the back side among all sibling responders
if (IsNthBackward(2)) {
    ...
}

check whether or not this responder is at 3rd position from the back side among all sibling responders with ID = 128
if (IsNthBackward(2, 128)) {
    ...
}

check whether or not this responder is at 3rd position from the back side among visible and active sibling responders (not care about the enable state and focus state)
if (IsNthBackward(2, true, true, false, false)) {
    ...
}

check whether or not this responder is at 3rd position from the back side among visible, active and enable sibling responders (not care about the focus state)
if (IsNthBackward(2, true, true, true, false)) {
    ...
}

Reference

SFYResponder::IsNthForward | SFYResponder::IsBack | ID | Sibling Responder | State

Return value

Description

This function checks whether or not this responder is at the specified position from the front side among a group of the sibling responders which match the specified search condition.

	Tip
	The sibling responders to be checked can be limited by specifying the ID and the conditions of visible, active, enable, or focus state.

	Tip
	The attachment-frames are not included in the searching.

Example

check whether or not this responder is at 3rd position from the front side among all sibling responders
if (IsNthForward(2)) {
    ...
}

check whether or not this responder is at 3rd position from the front side among all sibling responders with ID = 128
if (IsNthForward(2, 128)) {
    ...
}

check whether or not this responder is at 3rd position from the front side among visible and active sibling responders (not care about the enable state and focus state)
if (IsNthForward(2, true, true, false, false)) {
    ...
}

check whether or not this responder is at 3rd position from the front side among visible, active and enable sibling responders (not care about the focus state)
if (IsNthForward(2, true, true, true, false)) {
    ...
}

Reference

SFYResponder::IsNthBackward | SFYResponder::IsFront | ID | Sibling Responder | State

Return value

Description

This function checks whether or not this responder is the root responder.

Root responder is the responder which is located at the topmost position of the responder tree.

	Caution
	Responder with no parent is considered as the root responder.

Reference

SFYResponder::GetRoot | Responder Tree | Root Responder | Root | SFZRoot

Return value

Description

This function recovers the the intersection region between this responder and the responder space by using the saved bitmap to restore the device bitmap.

	Note
	This function will return SFERR_INVALID_STATE if this responder is not the root responder set with the renderer (SFYRenderer). And, if there is no saved bitmap to restore the device bitmap, SFERR_INVALID_STATE will be return and the intersection region will not be restored.

Reference

SFYResponder::IsRoot | SFYResponder::SetRenderer | SFYResponder::Render | SFYRenderer | Responder Space | Root Responder | Root | Responder Tree | Drawing | Renderer

Argument

Return value

Description

This function registers specified handlers into this responder.

It is possible to register more than one handler for the same event. At this time, handlers are called in the registered order or vice versa. If an event is handled by a handler, whether or not to boot up the next handler as long as it exists depends on the settings.

Method to receive the BREW-defined event whose dispatching rule is registered into the standard tracer with "distributing condition: None[SFYTracer::STATE_NONE]"

The BREW-defined event whose dispatching rule is registered into the standard tracer with "distributing condition: None[SFYTracer::STATE_NONE] will be distributed to no responder including the root(SFZRoot) which the SFYApplication class contains by default. This is because the rules of the standard tracer are registered into the SFYDistributer instance. To receive this event, you have to register its handler directly into the SFYDistributer instance as follows: Get the SFYDistributer instance using the SFYApplication::GetDistributer function. Register the handler for this event using the SFYDistributer::RegisterHandler function. Though this handler may be defined anywhere, not pointer to a responder but "null" will be passed via the "invoker" parameter. Note this matter in case the invoker parameter will be used.

Example

SFCError error;

register one handler at a time
error = RegisterHandler(SFXEventRange(SFEVT_KEY, SFEVT_KEY, SFP16_BEGIN, SFP16_END), 
                        XANDLER_INTERNAL(OnKey)
        );


register more than one handler at a time together
static SFXEventRange::AtomRecConst range[] = {
    {      SFEVT_KEY,       SFEVT_KEY,   SFP16_BEGIN,     SFP16_END},
    {SFEVT_KEY_PRESS, SFEVT_KEY_PRESS,   SFP16_BEGIN,     SFP16_END},
    {     SFEVT_KEY_RELEASE,      SFEVT_KEY_RELEASE,   SFP16_BEGIN,     SFP16_END}
};
SFYHandler::RuleRec rule[lengthof(range)];

rule[0].spp = XANDLER_FUNCTION(OnKey);
rule[0].reference = this;
rule[1].spp = XANDLER_FUNCTION(OnKeyPress);
rule[1].reference = this;
rule[2].spp = XANDLER_FUNCTION(OnKeyRelease);
rule[2].reference = this;

error = RegisterHandler(atomic_cast(range), rule, lengthof(range));

Reference

SFYResponder::UnregisterHandler | SFYResponder::ClearHandler | SFXEvent | SFXEventRange | SFYDistributer | SFYApplication::GetDistributer | SFYDistributer::RegisterHandler | Handler | Standard Tracer

Argument

Return value

Description

This function registers specified dispatching rules into the tracer of this responder.

If more than one dispatching rule for the same event are registered, only the last registered dispatching rule will be effective.

Example

SFCError error;

register one dispatching rule into the tracer of a responder at a time
error = RegisterTracer(SFXEventRange(SFEVT_APP_START, SFEVT_APP_START, SFP16_BEGIN, SFP16_END), SFYTracer::ORDER_BACKWARD, SFYTracer::STATE_ALL, true);


register more than one dispatching rule into the tracer of a responder at a time
static SFXEventRange::AtomRecConst range[] = {
    {     SFEVT_APP_START,    SFEVT_APP_START, SFP16_BEGIN, SFP16_END},
    {      SFEVT_APP_STOP,     SFEVT_APP_STOP, SFP16_BEGIN, SFP16_END},
    {    SFEVT_APP_RESUME,   SFEVT_APP_RESUME, SFP16_BEGIN, SFP16_END},
    {   SFEVT_APP_SUSPEND,  SFEVT_APP_SUSPEND, SFP16_BEGIN, SFP16_END}
};
static SFYTracer::RuleRecConst rule[lengthof(range)] = {
    {  SFYTracer::ORDER_BACKWARD,      SFYTracer::STATE_ALL,        true},
    {   SFYTracer::ORDER_FORWARD,      SFYTracer::STATE_ALL,        true},
    {  SFYTracer::ORDER_BACKWARD,      SFYTracer::STATE_ALL,        true},
    {   SFYTracer::ORDER_FORWARD,      SFYTracer::STATE_ALL,        true}
};

error = RegisterTracer(atomic_cast(range), rule, lengthof(range));

Reference

SFYResponder::UnregisterTracer | SFYResponder::ClearTracer SFXEventRange | SFXEvent | SFYTracer Tracer

Return value

Description

This function boots up the renderer for redrawing this responder and its descendant responders.

Render(false) or Render(): "false" or nothing is specified in the argument

Only this responder or responders below this responder in the responder tree which include the actually redraw region registered using the Invalidate() function before executing this function will receive the drawing event [SFXEvent(SFEVT_RESPONDER_RENDER, SFP16_RENDER_REQUEST, *)]. This drawing event will boot up the corresponding drawing handler.

	Note
	Only the drawing handlers for the registered redraw region will be called.

Render(true): "true" is specified in the argument

Only this responder or responders below this responder in the responder tree which include the actually redraw region will receive the drawing event [SFXEvent(SFEVT_RESPONDER_RENDER, SFP16_RENDER_REQUEST, *)]. This drawing event will boot up the corresponding drawing handler.

	Note
	The drawing handlers will be called regardless of the registered redraw region.

	Tip
	In general, Render(true) will be executed when all the responder tree needs to be redrawn in the responder space. This processing is automatically performed at the end of the event loop when applet boots up, resumes, or gets the control after text input.

	Caution
	In both cases, if the responder is in the "invisible" state or hidden by other responders on the screen, its drawing handler will not be called.

Tip

In general, this function needs not to be called in the event loop processing since the Render() function of the root(SFZRoot) which this application contains by default will be automatically called at the end of each event loop. (For more details, see the default implementation of the SFYApplication::HandleEvent function.) The Render() function is not automatically called in the callback outside the event loop such as a network or timer callback. To redraw the screen in the callback processing, the renderer needs to be booted up by calling the Render() function explicitly.

Redrawing when a highest priority event handler is registered

If a highest priority event handler to handle the standard BREW control such as a native text input control ( BREW API ITextCtl Interface) which will occupy the full screen is registered, the full screen will be occupied by this highest priority event handler. In this case, no redrawing will be performed even if the SFYResponder::Render function is called. For more details on a highest priority event handler, see the description of the SFCApplication::RegisterBypass function.

Example

The code to perform the redrawing in the timer callback is as follows:

SInt16 _something;

...

XALLBACK_IMPLEMENT_SFXTIMER(USRApplication, OnTimer)
{
    ++_something;

    Invalidate();  // register USRWindow's real region as redraw region

    Render();      // redraw responders below USRWindow (including USRWindow)

    _timer.Schedule(1000);

    return;
}

Reference

SFYResponder::Invalidate | SFYApplication::HandleEvent | SFXEvent | SFZRoot | Renderer | Drawing | Drawing Handler | Event Loop | Callback Type | Responder Tree | Responder Space | State | Drawing Event[SFEVT_RESPONDER_RENDER] | Handler for the Drawing Event[XANDLER_DECLARE_VOIDRENDER] | Root(Basic)

Description

This function binds this responder with the specified distributer.

	Note
	Every responder tree needs one distributer, which is bound with the root responder when constructing the responder tree newly. * This function is used with the root responder when creating the responder space newly.

	Note
	When an applet with an application class inheriting from SFYApplication is developed, there is no need to call this function explicitly since the distributer will be bound with the root(SFZRoot) in the SFYApplication::SFYApplication constructor.

Changing of the valid state

If the distributer is set to the root responder, the valid state of the root responder will be from OFF to ON. As a result, the states of each responder on the responder tree will change from OFF to ON depending on the settings of the state flags. And it will receive the state events below. if the valid state changes from OFF to ON: SFXEvent(SFEVT_RESPONDER_STATE, SFP16_STATE_VALID, true) if the visible state changes from OFF to ON: SFXEvent(SFEVT_RESPONDER_STATE, SFP16_STATE_VISIBLE, true) if the active state changes from OFF to ON: SFXEvent(SFEVT_RESPONDER_STATE, SFP16_STATE_ACTIVE, true) if the enable state changes from OFF to ON: SFXEvent(SFEVT_RESPONDER_STATE, SFP16_STATE_ENABLE, true) if the focus state changes from OFF to ON: SFXEvent(SFEVT_RESPONDER_STATE, SFP16_STATE_FOCUS, true)

Reference

SFYResponder::GetDistributer | SFYApplication::SFYApplication | SFYApplication | SFZRoot | Distributer | Root | Responder Tree | Root Responder | State

Return value

Description

This function attaches the frame specified in the argument to this responder. At this time, the frame which is attached to the responder is called as the "attachment-frame". And, the responder to which the frame is attached is called as the "content-responder".

In the param argument, the instance of the concrete frame class inheriting from SFYFrame with no parent responder should be specified.

This responder to which the specified frame will be attached is one of the followings:

Inside the SFYResponder::SetFrame function, the processing that the real region of the attachment-frame will be set to the region obtained by inflating that of the content-responder by the frame margin. Therefore, the setting of the content-responder's real region can be performed before calling the SFYResponder::SetFrame function.

In general, the flag values of the frame's four states of "visible", "active", "enable", and "focus" are set to "true" with the SFYResponder::SetState function.

Each responder will receive the frame event as follows:

If an attachment-frame has already been attached to this responder before this function is executed, it will be restored to the normal frame which can be attached to other responder.

Tip

To clear the attachment-frame from a content-responder, specify SFYResponderSmp::EmptyInstance() in the argument of SFYResponder::SetFrame function, or close the attachment-frame by calling the SFYResponder::Terminate function. Then, this responder will receive the frame event [SFXEvent(SFEVT_RESPONDER_FRAME, SFP16_FRAME_FRAME, null)]. On the other hand, the previous attachment-frame will receive the frame event [SFXEvent(SFEVT_RESPONDER_FRAME, SFP16_FRAME_CONTENT, null)].

About an Attachment-Frame and a Content-Responder

Neither a parent responder nor a child responder can be set to an attachment-frame explicitlt with the SFYResponder::SetParent function. And no frame cannot be attached to an attachment-frame, and an attachment-frame cannot be attached to any responder other than the corresponding content-responder. These relations are set automatically and internally. the attachment-frame and the content-responder are the sibling responders which have the same parent responder. Concretely, The content-responder is managed so as to be always the direct elder sister responder of the attachment-frame. As a result, the attachment-frame will be rendered as the frame of the content-responder. If the real region of either of the attachment-frame or the content-responder is set with the with the SFYResponder::SetRealBound function, that of the other side will be automatically calculated using the frame margin region of the attachment-frame and set. If the content-responder is moved foremost with the SFYResponder::ToFront function, the attachment-frame will be automatically moved foremost together with it too. On the contrary, even if this function of the attachment-frame is called to move it foremost, nothing will happen. To check whether or not a responder is an attachment-frame / a content-responder, call the SFYResponder::IsFrame / SFYResponder::HasFrame function respectively. From the point of view of the state and the distributer, the attachment-frame behaves as the child responder of the content-responder. That is to say, the attachment-frame inherits the state from the content-responder. For instance, if the visible state of the content-responder is changed from ON to OFF, that of the linked attachment-frame will be changed from ON to OFF. And, an event will be distributed on the premise that the attachment-frame is the first child responder of the content-responder. If a content-responder will be closed with the SFYResponder::Terminate function, the corresponding attachment-frame will be detached from it, become invisible, and restore to the normal frame which can be attached to other responder.

Example

The code to attach/clear a frame to/from a window is as follows:

SFZWindowSmp          _window; // window
SFZTitleBevelFrameSmp _frame;  // frame
SFCError              error;   // error value


   // create a frame
   if ((_frame = SFZTitleBevelFrame::NewInstance(&error)) != null) {

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

      ...

   }

   // create a window
   if ((_window = SFZWindow::NewInstance(&error)) != null) {

      ...

      // attach the frame to the window
      if ((error = _window->SetFrame(_frame)) == SFERR_NO_ERROR) {

         ...
      }

      // clear the frame from the window
      if ((error = _window->SetFrame(SFYResponderSmp::EmptyInstance())) == SFERR_NO_ERROR) {

         ...
      }

   }

Reference

SFYResponder::GetFrame | SFYResponder::HasFrame | SFYResponder::IsFrame | SFYResponder::SetParent | SFYResponder::SetRealBound | SFYResponder::Terminate | SFYRenderer | SFYDistributer | SFYFrame | SFXEvent | Frame | Frame Event | Parent Responder | Child Responder | Real Region | State | Distributer

Description

This function sets the ID value of this responder to the specified value.

Default: 0.

Example

The code to set an ID value as identification number for text button control and search it using the ID value is as follows:

SFCError USRResponder::MakeButton(Void)
{
    SFZTextButtonControlSmp button;
    SFCError error(SFERR_NO_ERROR);

    if ((button = SFZTextButtonControl::NewInstance(&error)) != null) {

        if ((error = button->SetParent(GetThis())) == SFERR_NO_ERROR) {

            // set ID for text button control to 100
            button->SetID(100);
            ...
        }
    }
    return error;
}


SFZTextButtonControlSmp USRResponder::GetButton(Void) const
{
    // get child responder using ID value
    // this method release developer from managing child responder with class variable
    return static_pointer_cast<SFZTextButtonControl>(GetChildFront(100));
}

Reference

SFYResponder::GetID | ID

Return value

Description

This function sets the parent responder of this responder to the specified responder.

A parent responder cannot be set to an attachment-frame explicitly. And an attachment-frame cannot be specified as the parent responder.

	About an Attachment-Frame
	Fore more details, see the description of the SFYResponder::SetFrame function.

After this operation, this responder is connected to the responder tree which a specified parent responder belongs to.

Each responder will receive the parent child event as follows:

And if the state of this responder or its descendant responder changes, the corresponding responder will receive the state event as follows:

	About ON/OFF of the state
	For more details on ON/OFF of the state, see State.

	Tip
	Since this responder is placed backmost among the sibling responders immediately after setting the parent responder to it, the SFYResponder::ToFront function needs to be called in order to place it foremost.

Tip

To clear the parent responder from this responder, specify SFYResponderSmp::EmptyInstance() in the argument of SFYResponder::SetParent function, or close the parent responder by calling the SFYResponder::Terminate function. Then, this responder will be separated from the responder tree and receive the parent child event [SFXEvent(SFEVT_RESPONDER_OWNER, SFP16_OWNER_PARENT, null)]. On the other hand, the previous parent responder will receive the parent child event [SFXEvent(SFEVT_RESPONDER_OWNER, SFP16_OWNER_UNREGISTER, this responder)].

	Note
	This responder itself can not be set as a parent responder.

	Tip
	Though the current parent responder can be specified in the argument, no parent child event nor state event will occur since the parent-child relationship does not change.

About samrt pointer

After executing the SFYResponder::SetParent function, the reference count of this responder increments by 1. Therefore, as the exapmle below, even if the variable which contains a responder is assigned another responder's smart pointer to, that responder will not be released from memory by this assignment since the reference count is more than or equals 1. SFZWindowSmp window; SFCError error(SFERR_NO_ERROR); ..... window = SFZWindow::NewInstance(&error); // make responder A, and assign it to window[reference count of A is 1] window->SetParent(GetThis());// set parent responder of A[reference count of A is 2] if (error == SFERR_NO_ERROR) { window = SFZWindow::NewInstance(&error);// make responder B, and assign it to window[reference count of A is 1] } // since reference count of A is still 1, A will not be released // to release it, call Terminate() or wait until A's parent responder is released

	Note
	If this function is actually executed, this responder and its descendant responders whose states are visible will receive SFXEvent(SFEVT_RESPONDER_BOUND, SFP16_BOUND_GLOBAL, global region) at the end of the event loop.

Example

The code to set the parent responder is as follows:

SFCError USRResponder::SetButtonParent(Void)
{
    SFZWindowSmp window;
    SFZTextButtonControlSmp button;
    SFCError error(SFERR_NO_ERROR);

    ...

    // set button's parent responder to window
    if ((error = button->SetParent(window)) == SFERR_NO_ERROR) {

        ...
    }

    return error;
}

The code to clear the parent responder is as follows:

SFCError USRResponder::ClearButtonParent(Void)
{
    SFZTextButtonControlSmp button;
    SFCError error(SFERR_NO_ERROR);

    ...

    // to clear button's parent responder, set it to SFYResponderSmp::EmptyInstance()
    if ((error = button->SetParent(SFYResponderSmp::EmptyInstance())) == SFERR_NO_ERROR) {

        ...
    }

    return error;
}

Reference

SFYResponder::GetParent | SFYResponder::SetFrame | SFYResponder::ToFront | SFXEvent | Parent Responder | Sibling Responder | Responder Tree | Frame | State | Callback Type | Parent Child Event[SFEVT_RESPONDER_OWNER] | State Event[SFEVT_RESPONDER_STATE]

Description

This function sets the transparency attribute of this responder to the specified value.

Default: false

	Note
	Since there is no attribute other than the transparency attribute, this function is the same with the SFYResponder::SetPropertyTransparent function. The background of the responder whose tranparent attribute is set to "true" will not be filled in the color set with the SFYWidget::SetBackgroundColor function(default: white color).

Reference

SFYResponder::SetPropertyTransparent | SFYResponder::GetPropertyTransparent | SFYWidget::SetBackgroundColor | Attribute

Description

This property sets the transparency attribute of this responder to the specified value.

Default: false

	Note
	If transparent background is needed, set the transparency attribute of this responder to "true" using this function. If the transparency attribute is set to "true", the background of responder will not be fill in the color set with the SFYWidget::SetBackgroundColor function(default: white color).

	Classes whose transparency attribute is set to "true"
	In the following classes, the transparency attribute is set to "true". SFYImageWidget | SFYSingleTextWidget | SFYSingleEditWidget | SFYMultipleTextWidget | SFYMultipleEditWidget | SFZSingleTextLabelControl | SFZSingleEditLabelControl | SFZMultipleTextLabelControl | SFZMultipleEditLabelControl | SFZImageLabelControl | SFZCheckboxControl | SFZRadiobuttonControl

Reference

SFYResponder::GetPropertyTransparent | SFYResponder::SetProperty | SFYWidget::SetBackgroundColor| Attribute

Description

This function sets the real region of this responder to the specified region.

Default: SFXRectangle(0, 0, 0, 0)

This responder will receive the region event as follows:

If the real region is changed, this responder and its descendant responders whose states are visible will receive SFXEvent(SFEVT_RESPONDER_BOUND, SFP16_BOUND_GLOBAL, global region) at the end of the event loop.

Handling the region event(SFEVT_RESPONDER_BOUND)

The handler for SFXEvent(SFEVT_RESPONDER_BOUND, SFP16_BOUND_REAL, real region after update), SFXEvent(SFEVT_RESPONDER_BOUND, SFP16_BOUND_VIRTUAL, virtual region after update), or SFXEvent(SFEVT_RESPONDER_BOUND, SFP16_BOUND_GLOBAL, global region after update) is implemented by overriding the SFYWidget::HandleBoundReal, SFYWidget::HandleBoundVirtual, or SFYWidget::HandleBoundGlobal virtual function respectively. It is also possible to implement the handler for region event and register it into the responder.

When the real region is reduced

When the virtual region is the same with the real region, if the real region is reduced using the SFYResponder::SetRealBound function, the virtual region that is just as it was will be wider than the real region. Tip In case of the responder whose virtual region does not have to be larger than the real region, it is recommended to equalize the virtual region with the real region by overriding the SFYWidget::HandleBoundReal function. For instance, the default implementation of the SFYControl::HandleBoundReal function is to equalize the virtual region with the real region.

	In Case of an Attachment-Frame or a Content-Responder
	If the real region of either of an attachment-frame or a content-responder is set, that of the other side will be automatically calculated using the frame margin of the attachment-frame and set. Fore more details on the attachment-frame or the content-responder, see the description of the SFYResponder::SetFrame function.

Reference

SFYResponder::GetRealBound | SFYResponder::SetVirtualBound | SFYWidget::HandleBoundReal | SFYWidget::HandleBoundVirtual | SFYWidget::HandleBoundGlobal | SFYResponder::SetFrame | SFYResponder::GetSuitableMargin | SFXRectangle | SFXEvent | Real Region | Virtual Region | Local Region | Global Region | Frame | Region Event[SFEVT_RESPONDER_BOUND] | Handler for the Region Event[XANDLER_DECLARE_VOIDBOUND]

Description

This function sets the reference value of this responder to the specified value.

Default: null

Example

The code to set a reference value as an identification number to text button controls and get it is as follows:

SFZTextButtonControlSmp _button;
SInt32 i;

// make 10 text button controls and set references(identification numbers) to them
for (i = 0; i < 10; ++i) {

    // create text button control
    if ((_button = SFZTextButtonControl::NewInstance(&error)) != null) {

        // set the text button control's parent responder to GetThis()
        error = _button->SetParent(GetThis());
        if (error == SFERR_NO_ERROR) {

            // set reference value as identification number to text button control
            _button->SetReference(reinterpret_cast<VoidPtr>(i));
        }
    }
}

...

// get reference value as identification number for text button control
SInt32 number = reinterpret_cast<SInt32>(_button->GetReference());

Reference

SFYResponder::GetReference | Reference

Description

This function binds this responder with the specified renderer.

	Note
	When an applet with an application class inheriting from SFYApplication is developed, there is no need to call this function explicitly since the renderer will be bound with the root(SFZRoot) in the SFYApplication::SFYApplication constructor.

Reference

SFYResponder::GetRenderer | SFYApplication::SFYApplication | SFYApplication | SFZRoot | Renderer | Root

Description

This function sets all states(visible, active, enable, and focus states) of this responder to specified values together.

Default: false

Suppose that the focus state of this responder is set to "true". When the visible, active or enable state of this responder is changed from "true" to "false" by calling this function, the focus state of this responder will be also changed from "true" to "false" automatically.

The focus state flag can be set to "true" only if all the visible, active and enable states of this responder are set to "true". Otherwise, the focus state flag will remain "false" even if the param argument is specified as "true".

SetState() function

To call the SFYResponder::SetState function is almost same as to call all functions of SFYResponder::SetStateVisible, SFYResponder::SetStateActive, SFYResponder::SetStateEnable, and SFYResponder::SetStateFocus. With this function, the states are set more effectively. When the state changes between ON and OFF, this responder will receive the corresponding state event. For more details, see the description of SFYResponder::SetStateVisible / SFYResponder::SetStateActive / SFYResponder::SetStateEnable / SFYResponder::SetStateFocus. * The valid state is set to "true" or "false" by calling the SFYResponder::Initialize or SFYResponder::Terminate function.

Example

The code to set all states of a responder together is as follows:

Void USRResponder::SetState(Void)
{
    // set the USRResponder's state to "visible" + "active" + "enable" + "focus" together
    SetState(true, true, true, true);

    // set the visible state flag to "false"
    // * at this time, the values of the active and  enable state flags are still "true", 
    //   however, only the focus state flag will be automatically changed from "true" to "false"
    SetStateVisible(false);

    // when the visible state flag is set to "true" again, 
    // the value of the focus state flag is still "false"
    SetStateVisible(true);

    // in order to make USRResponder focused again,
    // you have to set the focus state flag to "true" explicitly as below
    SetStateFocus(true);

    return;
}

Reference

SFYResponder::SetStateVisible | SFYResponder::SetStateActive | SFYResponder::SetStateEnable | SFYResponder::SetStateFocus | SFYResponder::GetStateVisible | SFYResponder::GetStateActive | SFYResponder::GetStateEnable | SFYResponder::GetStateFocus | SFYResponder::Initialize | SFYResponder::Terminate | SFXEvent | State | State Event[SFEVT_RESPONDER_STATE]

Description

This function sets the active state flag of this responder to the specified value.

Default: false

Suppose that the focus state of this responder is set to "true". When the active state of this responder is changed from "true" to "false" by calling this function, the focus state of this responder will be also changed from "true" to "false" automatically.

	Behaviour of the active state
	The responder will be drawn as active if the active state is "ON". The responder will not be drawn as active if the active state is "OFF", even if the active state flag is set to "true".

	Condition that the active state of a responder becomes "ON"
	The active state is set to "true". The visible state is "ON". The active state of the parent responder, if any, is "ON".

If the state of this responder or its descendant responder changes by executing this function, the corresponding responder will receive the following state event.

	About ON/OFF of the state
	For more details on ON/OFF of the state, see State.

Reference

SFYResponder::SetState | SFYResponder::GetStateActive | SFXEvent | Root Responder | State | State Event[SFEVT_RESPONDER_STATE]

Description

This function sets the enable state flag of this responder to the specified value.

Default: false

Suppose that the focus state of this responder is set to "true". When the enable state of this responder is changed from "true" to "false" by calling this function, the focus state of this responder will be also changed from "true" to "false" automatically.

	Behaviour of the enable state
	The responder can be the target of operation if the enable state is "ON". The responder cannot be the target of operation if the enable state is "OFF", even if the enable state flag is set to "true".

	Condition that the enable state of a responder becomes "ON"
	The enable state is set to "true". The active state is "ON". The enable state of the parent responder, if any, is "ON".

If the state of this responder or its descendant responder changes by executing this function, the corresponding responder will receive the following state event.

	About ON/OFF of the state
	For more details on ON/OFF of the state, see State.

Reference

SFYResponder::GetStateEnable | SFYResponder::SetState | SFXEvent | Root Responder | State | State Event[SFEVT_RESPONDER_STATE]

Description

This function sets the focus state flag of this responder to the specified value.

Default: false

The focus state flag can be set to "true" only if all the visible, active and enable states of this responder are set to "true". Otherwise, the focus state flag will remain "false" even if the param argument is specified as "true".

	Behaviour of the focus state
	The responder is focused if the focus state is "ON". The responder is not focused if the focus state is "OFF", even if the focus state flag is set to "true".

	Condition that the focus state of a responder becomes "ON"
	The focus state flag is set to "true". The enable state is "ON". The focus state of the parent responder, if any, is "ON".

If the state of this responder or its descendant responder changes by executing this function, the corresponding responder will receive the following state event.

	About ON/OFF of the state
	For more details on ON/OFF of the state, see State.

Reference

SFYResponder::GetStateFocus | SFYResponder::SetState | SFXEvent | Root Responder | State | State Event[SFEVT_RESPONDER_STATE]

Description

This function sets the visible state flag of this responder to the specified value.

Default: false

Suppose that the focus state of this responder is set to "true". When the visible, active or enable state of this responder is changed from "true" to "false" by calling this function, the focus state of this responder will be also changed from "true" to "false" automatically.

	Behaviour of the visible state
	The responder is visible if the visible state is "ON". The responder is invisible if the visible state is "OFF", even if the visual state flag is set to "true".

	Condition that the visible state of a responder becomes "ON"
	The visible state flag is set to "true". The valid state is "ON". The visible state of the parent responder, if any, is "ON".

	Condition that the valid state of a responder becomes "ON"
	The valid state is set to "true". The valid state of the parent responder, if any, is "ON". If the responder is the root responder, the distributer is set.

If the state of this responder or its descendant responder changes by executing this function, the corresponding responder will receive the following state event.

	About ON/OFF of the state
	For more details on ON/OFF of the state, see State.

Reference

SFYResponder::GetStateVisible | SFYResponder::SetState | SFXEvent | Root Responder | State | Distributer | State Event[SFEVT_RESPONDER_STATE]

Description

This function sets the Type value of this responder to the specified 4-character value.

Example

The code to set the type of the USRResponder class is as follows:

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

        // type must be set here
        // with this setting, 
        // parent class type is set when error occurs in the parent class's constructor, 
        // while this class type is set when error occurs in this constructor
        // therefore easy to determine where error occurs in using this class externally
 SetType(four_char_code('U', 'R', 'S', 'P'));

        // here describe the initialization
        ...
    }
}

Reference

SFYResponder::GetType | Type | Type List

Description

This function sets the virtual region of this responder to the specified value.

Default: SFXRectangle(0, 0, 0, 0)

This responder will receive the region event as follows:

If the virtual region is changed, this responder and its descendant responders whose states are visible will receive SFXEvent(SFEVT_RESPONDER_BOUND, SFP16_BOUND_GLOBAL, global region) at the end of the event loop.

	Note
	Even if this function is executed, no real region of this responder or its descendant responder will change.

Handling the region event(SFEVT_RESPONDER_BOUND)

The handler for SFXEvent(SFEVT_RESPONDER_BOUND, SFP16_BOUND_VIRTUAL, virtual region after update) or SFXEvent(SFEVT_RESPONDER_BOUND, SFP16_BOUND_GLOBAL, global region after update) is implemented by overriding the SFYWidget::HandleBoundVirtual or SFYWidget::HandleBoundGlobal virtual function respectively. It is also possible to implement the handler for region event and register it into the responder.

Reference

SFYResponder::GetVirtualBound | SFYResponder::SetRealBound SFYWidget::HandleBoundReal | SFYWidget::HandleBoundVirtual | SFYWidget::HandleBoundGlobal | SFXRectangle | SFXEvent | Real Region | Virtual Region | Local Region | Global Region | Region Event[SFEVT_RESPONDER_BOUND] | Handler for the Region Event[XANDLER_DECLARE_VOIDBOUND]

Return value

Description

This function transfers the intersection region image between this responder and the responder space to the specified bitmap.

If other responders overlap the intersection regin, the image of them are also transfered to the bitmap.

Reference

SFYResponder::GetRenderer | Renderer

Description

This function terminates this responder as follows:

Termination of the Attachment-Frame or Content-Responder

If this responder is a content-responder which an attachment-frame is attached to with the SFYResponder::SetFrame function, the attachment-frame will be detached from the content-responder, become invisible, and restore to the normal frame which can be attached to other responder. There is no need to close the corresponding attachment-frame. On the contrary, if this responder is the attachment-frame, the content-responder will not be closed and only the attachment-frame will be closed and become invisible(hereafter the attachment-frame cannot be reused). At this time, each responder will receive the frame event as follows: Content-Responder: SFXEvent(SFEVT_RESPONDER_FRAME, SFP16_FRAME_FRAME, null)] Attachment-Frame: SFXEvent(SFEVT_RESPONDER_FRAME, SFP16_FRAME_CONTENT, null) Both of the attachment-frame and the content-responder will receive no parent child event. About an Attachment-Frame and a Content-Responder Fore more details, see the description of the Attachment-Frame and Content-Responder section.

Tip

The SFYResponder::Terminate function of a responder will be automatically called when the reference count becomes 0. Therefore, there is no need to call this function for almost all responders. This function is explicitly called when you want to terminate a responder such as a dialog or a menu before its reference count becomes 0. But the reference count is not 0 at this stage, the responder remains in the heap memory as it is. To release it completely from the heap memory, you have to make its reference count 0 by substituting another responder into the variable of the smart pointer, which refers to the terminated responder, or calling the SFXResponderPointer::Release function explicitly.

Occurrence of the state event

Before clearing the parent-child relationship between this responder and its child responders, the visible, active, enable, and focus state flags of the direct child responders are set to "false". As a result, the corresponding descendant responders will receive the following state events. if the visible state changes from ON to OFF: SFXEvent(SFEVT_RESPONDER_STATE, SFP16_STATE_VISIBLE, false) if the active state changes from ON to OFF: SFXEvent(SFEVT_RESPONDER_STATE, SFP16_STATE_ACTIVE, false) if the enable state changes from ON to OFF: SFXEvent(SFEVT_RESPONDER_STATE, SFP16_STATE_ENABLE, false) if the focus state changes from ON to OFF: SFXEvent(SFEVT_RESPONDER_STATE, SFP16_STATE_FOCUS, false) After clearing the parent-child relationship, the visible, active, enable, and focus state flags of the direct child responders are restored to the former value. As a result, a new responder tree with the child responder will be created. In general, the distributer is not set to the child responder, the valid state is OFF though the value of its valid flag is "true". Therefore, the descendant responders will receive no state events even if all the values of the state flags are restored. Next, since the valid state flag of this responder is set to "false", this responder will receive the state event [SFXEvent(SFEVT_RESPONDER_STATE, SFP16_STATE_VALID, false)]. If the state of this responder changes by executing this operation, the corresponding responder will receive the following state event. if the visible state changes from ON to OFF: SFXEvent(SFEVT_RESPONDER_STATE, SFP16_STATE_VISIBLE, false) if the active state changes from ON to OFF: SFXEvent(SFEVT_RESPONDER_STATE, SFP16_STATE_ACTIVE, false) if the enable state changes from ON to OFF: SFXEvent(SFEVT_RESPONDER_STATE, SFP16_STATE_ENABLE, false) if the focus state changes from ON to OFF: SFXEvent(SFEVT_RESPONDER_STATE, SFP16_STATE_FOCUS, false)

	Occurrence of the parent child event
	By clearing the parent-child relationship, each responder will receive the parent child event as follows: [SFXEvent(SFEVT_RESPONDER_OWNER, SFP16_OWNER_PARENT, null)]. Parent responder which loses a child responder: SFXEvent(SFEVT_RESPONDER_OWNER, SFP16_OWNER_UNREGISTER, child responder) Child responder which loses a parent responder: SFXEvent(SFEVT_RESPONDER_OWNER, SFP16_OWNER_PARENT, null)

Termination and release of the child responder

When the reference count of the child responder becomes 0, the SFYResponder::Terminate function will be automatically called to terminate it. And then, it will be released from the heap memory too. In general, since the child responder is contained in the variable of the parent responder class, the reference count of the child responder will become 0 when this responder is released from the heap memory.

	Caution
	It is prohibited to reinitialize the terminated responder with this function by calling the SFYResponder::Initialize function.

	About ON/OFF of the state
	For more details on ON/OFF of the state, see State.

Example

The code to close a dialog is as follows:

XANDLER_IMPLEMENT_VOIDRESULT(USRWindow, OnDialog, invoker, reason, result)
{
    // the dialog will be passed via the invoker argument
    // the P16 value of the result event will be passed via the reason argument
    // "0" will be passed via the result argument

    switch (reason) {

        case SFP16_RESULT_OK:

            // when the OK button or the operation key is pressed

            ...

            invoker->Terminate();  // close the dialog

            break;

        case SFP16_RESULT_CANCEL:

            // when the CANCEL button is pressed

        case SFP16_RESULT_ESCAPE:

            // when the ESCAPE key is pressed or the time scheduled with ScheduleTimer() elapses


            invoker->Terminate();  // close the dialog

            // here, dialog still remains in the heap memory
            // it will be released from the heap memory when the reference count becomes 0
            // to release it from the heap memory right now, 
            // make the reference count 0, 
            // by substituting another responder into the variable of the smart pointer which refers to this dialog
            // or calling the SFXResponderPointer::Release() explicitly

            break;

        default:

            break;
    }

    return;
}

Reference

SFYResponder::Initialize | SFYResponder::SetFrame | SFXEvent | Responder Tree | State | Distributer | State Event[SFEVT_RESPONDER_STATE] | Parent Child Event[SFEVT_RESPONDER_OWNER] | Frame Event

Description

This function moves this responder to the backmost position among a group of the sibling responders which match the specified search condition.

If this responder is a content-responder which an attachment-frame is attached to with the SFYResponder::SetFrame function, the corresponding attachment-frame will be moved together with it. On the contrary, if this responder is an attachment-frame, neither the attachment-frame nor the corresponding content-responder will be moved and nothing will happen.

	About an Attachment-Frame and a Content-Responder
	Fore more details, see the description of the SFYResponder::SetFrame function.

The parent responder will receive the parent child event [SFXEvent(SFEVT_RESPONDER_OWNER, SFP16_OWNER_ARRANGE, this responder)].

	Tip
	The sibling responders to be checked can be limited by specifying the ID and the conditions of visible, active, enable, or focus state.

	Tip
	The attachment-frames are not included in the searching.

	Note
	If this function is actually executed, this responder and its descendant responders whose states are visible will receive SFXEvent(SFEVT_RESPONDER_BOUND, SFP16_BOUND_GLOBAL, global region) at the end of the event loop.

Example

move a responder to the backmost position among all sibling responders
ToBack();

move a responder to the backmost position among sibling responders with ID = 128
ToBack(128);

move a responder to the backmost position among visible and active sibling responders (not care about the enable state and focus state)
ToBack(true, true, false, false);

move a responder to the backmost position among visible, active and enable sibling responders (not care about the focus state)
ToBack(true, true, true, false);

Reference

SFYResponder::ToFront | SFYResponder::ToNthBackward | SFYResponder::SetFrame | SFXEvent | ID | Sibling Responder | State | Parent Child Event[SFEVT_RESPONDER_OWNER]

Description

This function moves this responder to the foremost position among a group of the sibling responders which match the specified search condition.

Tip

If this responder is a content-responder which an attachment-frame is attached to with the SFYResponder::SetFrame function, the corresponding attachment-frame will be moved together with it. On the contrary, if this responder is an attachment-frame, neither the attachment-frame nor the corresponding content-responder will be moved and nothing will happen. About an Attachment-Frame and a Content-Responder Fore more details, see the description of the SFYResponder::SetFrame function.

The parent responder will receive the parent child event [SFXEvent(SFEVT_RESPONDER_OWNER, SFP16_OWNER_ARRANGE, this responder)].

	Tip
	The sibling responders to be checked can be limited by specifying the ID and the conditions of visible, active, enable, or focus state.

	Tip
	The attachment-frames are not included in the searching.

	Note
	If this function is actually executed, this responder and its descendant responders whose states are visible will receive SFXEvent(SFEVT_RESPONDER_BOUND, SFP16_BOUND_GLOBAL, global region) at the end of the event loop.

Example

move a responder to the foremost position among all sibling responders
ToFront();

move a responder to the foremost position among sibling responders with ID = 128
ToFront(128);

move a responder to the foremost position among visible and active sibling responders (not care about the enable state and focus state)
ToFront(true, true, false, false);

move a responder to the foremost position among visible, active and enable sibling responders (not care about the focus state)
ToFront(true, true, true, false);

Reference

SFYResponder::ToBack | SFYResponder::ToNthForward | SFYResponder::SetFrame | SFXEvent | ID | Sibling Responder | State | Parent Child Event[SFEVT_RESPONDER_OWNER]

Description

This function moves this responder to the specified position from the back side among a group of the sibling responders which match the specified search condition.

If this responder is a content-responder which an attachment-frame is attached to with the SFYResponder::SetFrame function, the corresponding attachment-frame will be moved together with it. On the contrary, if this responder is an attachment-frame, neither the attachment-frame nor the corresponding content-responder will be moved and nothing will happen.

	About an Attachment-Frame and a Content-Responder
	Fore more details, see the description of the SFYResponder::SetFrame function.

The parent responder will receive the parent child event [SFXEvent(SFEVT_RESPONDER_OWNER, SFP16_OWNER_ARRANGE, this responder)].

	Tip
	The sibling responders to be checked can be limited by specifying the ID and the conditions of visible, active, enable, or focus state.

	Tip
	The attachment-frames are not included in the searching.

	Note
	If this function is actually executed, this responder and its descendant responders whose states are visible will receive SFXEvent(SFEVT_RESPONDER_BOUND, SFP16_BOUND_GLOBAL, global region) at the end of the event loop.

Example

move a responder to the 3rd position from the back side among all sibling responders
ToNthBackward(2);

move a responder to the 3rd position from the back side among all sibling responders with ID = 128
ToNthBackward(2, 128);

move a responder to the 3rd position from the back side among visible and active sibling responders (not care about the enable state and focus state)
ToNthBackward(2, true, true, false, false);

move a responder to the 3rd position from the back side among visible, active and enable sibling responders (not care about the focus state)
ToNthBackward(2, true, true, true, false);

Reference

SFYResponder::ToNthForward | SFYResponder::ToBack | SFYResponder::SetFrame | SFXEvent | ID | Sibling Responder | State | Parent Child Event[SFEVT_RESPONDER_OWNER]

Description

This function moves this responder to the specified position from the front side among a group of the sibling responders which match the specified search condition.

If this responder is a content-responder which an attachment-frame is attached to with the SFYResponder::SetFrame function, the corresponding attachment-frame will be moved together with it. On the contrary, if this responder is an attachment-frame, neither the attachment-frame nor the corresponding content-responder will be moved and nothing will happen.

	About an Attachment-Frame and a Content-Responder
	Fore more details, see the description of the SFYResponder::SetFrame function.

The parent responder will receive the parent child event [SFXEvent(SFEVT_RESPONDER_OWNER, SFP16_OWNER_ARRANGE, this responder)].

	Tip
	The sibling responders to be checked can be limited by specifying the ID and the conditions of visible, active, enable, or focus state.

	Tip
	The attachment-frames are not included in the searching.

	Note
	If this function is actually executed, this responder and its descendant responders whose states are visible will receive SFXEvent(SFEVT_RESPONDER_BOUND, SFP16_BOUND_GLOBAL, global region) at the end of the event loop.

Example

move a responder to the 3rd position from the front side among all sibling responders
ToNthForward(2);

move a responder to the 3rd position from the front side among all sibling responders with ID = 128
ToNthForward(2, 128);

move a responder to the 3rd position from the front side among visible and active sibling responders (not care about the enable state and focus state)
ToNthForward(2, true, true, false, false);

move a responder to the 3rd position from the front side among visible, active and enable sibling responders (not care about the focus state)
ToNthForward(2, true, true, true, false);

Reference

SFYResponder::ToNthBackward | SFYResponder::ToFront | SFYResponder::SetFrame | SFXEvent | ID | Sibling Responder | State | Parent Child Event[SFEVT_RESPONDER_OWNER]

Argument

Description

This function unregisters the handler from this responder which matches the specified condition.

Only the handler which maches the specified condition on the event range and the handler rule will be unregistered.

If more than one handler of the same condition are registered, the last registered one will be unregistered.

Reference

SFYResponder::RegisterHandler | SFYResponder::ClearHandler | SFXEvent | SFXEventRange | Handler

Argument

Description

This function unregisters the dispatching rule from the tracer of this responder which matches the specified condition.

Only the dispatching rule which maches the specified condition on event range will be unregistered from the tracer.

If more than one dispatching rule of the same condition are registered, the last registered one will be unregistered.

Reference

SFYResponder::RegisterTracer | SFYResponder::ClearTracer | SFXEventRange | SFYTracer | Tracer

Reference

SFYResponder::GetType | SFYResponder::SetType

Description

For the horizontal alignment:

Reference

SFYResponder::VerticalEnum | SFYResponder::GetSuitableBound

Description

For the vertical alignment:

Reference

SFYResponder::HorizontalEnum | SFYResponder::GetSuitableBound