Inheritance diagram

Collaboration diagram

Description

How to use

SFYControl is the abstract base class to define and implement a user-defined control.

All controls inherit from SFYControl, which contains a maximum value, a minimum value, and a current value. The contents of these values differ depending on the type of a control.(*1)

The concrete control is the part class which can be used as it is in the applet development. On the other hand, the abstract control is the base class which a user-defined control inherits from to implement itself.

(*1)"minimum value ≦ current value ≦ maximum value" does not always stand up in all controls. For instance, the minimum value is always "0", and both of the current value and the maximum value are "-1" when no tab page exists in the SFYTabControl class.

Events and their handlers

In the SFYControl class, the following handlers(virtual functions) are registered for the region event[SFEVT_RESPONDER_BOUND] and the drawing event[SFEVT_RESPONDER_RENDER].

In a class inheriting from SFYControl, the following handlers(virtual functions) are booted up first.

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

	NOTE
	*1.SFYResponder::SetVirtualBound(SFXRectangle(SFXGrid::ZeroInstance(), GetRealBound().GetSize())) を実行します.In other words, equalize virtual region with real region.

The code to make a user-defined control is as follows:

SFMTYPEDEFRESPONDER(USRControl)
class USRControl: public SFYControl {
    SFMSEALRESPONDER(USRControl)
    SFMRESPONDERINSTANTIATETHREE(USRControl, SFYControl, SFYWidget, SFYResponder)
public:

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

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

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

USRControl::USRControl(Void) static_throws
{
    if (static_try()) {

        // set the responder type
 SetType(CODE_TYPE);

        // here describe the initialization
    }
}

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

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

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

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

Void USRControl::HandleBoundVirtual(Void)
{
    // here describe the size recalculation if necessary when the virtual region is changed
    return;
}

Void USRControl::HandleRenderRequest(SFXGraphicsPtr graphics) const
{
    // draw control
    return;
}

Reference

Control(Basic) | Region Event[SFEVT_RESPONDER_BOUND] | Drawing Event[SFEVT_RESPONDER_RENDER]

Member

Description

This constructor performs the initializations as follows:

Reference

SFYResponder::SetType | SFYControl::CodeEnum | SFYControl::SetMaximumValue | SFYControl::SetMinimumValue | SFYControl::SetCurrentValue | Type

Description

This destructor does nothing.

Reference

SFYControl::SetCurrentValue

Reference

SFYControl::SetMaximumValue

Reference

SFYControl::SetMinimumValue

Description

This function will be called when the (SFEVT_RESPONDER_BOUND, SFP16_BOUND_REAL) event is received.

In case you want to perform your own processing when the real region is updated, override this function.

The default implementation is to equalize the virtual region with the real region.

	Sending the (SFEVT_RESPONDER_BOUND, SFP16_BOUND_REAL) event
	The (SFEVT_RESPONDER_BOUND, SFP16_BOUND_REAL) event will occur when the real region is changed by calling the SFYResponder::SetRealBound function.

Processing when the real region is changed

Other than overriding this virtual function, there is another method to define and implement the handler for the region event[XANDLER_DECLARE_VOIDBOUND], and register it into the responder. In the processing when the real region is updated, this virtual function is executed first, and next the handlers for the region event are executed in the registered order. In almost all cases, the method to override this virtual function is adopted since defining, implementing and registering the handler for the region event can be omitted.

Internal Implementation

Internal implementation of the SFYControl::HandleBoundReal function is as follows:

/*protected virtual */Void SFYControl::HandleBoundReal(Void)
{
    SetVirtualBound(SFXRectangle(SFXGrid::ZeroInstance(), GetRealBound().GetSize()));
    return;
}// SFYControl::HandleBoundReal //

Reference

SFYResponder::SetRealBound | Real Region | Virtual Region | Region Event[SFEVT_RESPONDER_BOUND] | Handler for the Region Event[XANDLER_DECLARE_VOIDBOUND]

Description

This function sets the current value of this control to the specified value if both of them are different, and sends the value event[SFXEvent(SFEVT_RESPONDER_VALUE, SFP16_VALUE_CURRENT, "current value to be set")]. [* Nothing will happen if they are the same.]

Even if the value is out of the range of the minimum value and the maximum value, it is set as it is.

Default: 0.

Reference

SFYControl::GetCurrentValue | SFYControl::SetMaximumValue | SFYControl::SetCurrentValue | SFXEvent | Event | Value Event[SFEVT_RESPONDER_VALUE]

Description

This function sets the maximum value of the control to the specified value if both of them are different, and sends the value event[SFXEvent(SFEVT_RESPONDER_VALUE, SFP16_VALUE_MAXIMUM, "maximum value to be set")]. [* Nothing will happen if they are the same.]

Even if the value is less than the current value or the minimum value, it is set as it is.

Default: 0.

Reference

SFYControl::GetMaximumValue | SFYControl::SetMaximumValue | SFYControl::SetCurrentValue | SFXEvent | Event | Value Event[SFEVT_RESPONDER_VALUE]

Description

This function sets the minimum value of the control to the specified value if both of them are different, and sends the value event[SFXEvent(SFEVT_RESPONDER_VALUE, SFP16_VALUE_MINIMUM, "minimum value to be set")]. [* Nothing will happen if they are the same.]

Even if the value is greater than the current value or the maximum value, it is set as it is.

Default: 0.

Reference

SFYControl::GetMinimumValue | SFYControl::SetMaximumValue | SFYControl::SetCurrentValue | SFXEvent | Event | Value Event[SFEVT_RESPONDER_VALUE]

Reference

SFYResponder::GetType | SFYResponder::SetType