Inheritance diagram

Collaboration diagram

Description

How to use

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

In SFYButtonControl, functions to draw the button and manage the operation key are implemented by default. Several handlers with default behaviour are also implemented as virtual functions.

The operation key is set with the SFYButtonControl::SetOperateKey function. By default, the operation key is set to the SELECT key.

Structure of the button control

The button control consists of the bevel region, the content region, and the shadow region.

The content region is the one surrounded by the frame("focus frame") of 2 pixels width within the bevel region.

* In case of the radio button control, it consists of not rectangular but circular regions.

In the default implementation, the button control is drawn as below depending on its state.

Figure 278. Expanded figure of the button control in the "active" or "enable" state

The bevel region is drawn in the bevel color(SFXBevelColor) set with the SFYButtonControl::SetButtonColor function. The shadow region is drawn in the color(SFXRGBColor) set with the SFYButtonControl::SetShadowColor function.

* The background of button control will be never drawn in the color set with the SFYWidget::SetBackgroundColor function.

In the "inactive" or "focus" state, the colors of the frame("focus frame"), the content region, and the shadow region change.

Figure 279. Expanded figure of the button control in the "inactive" state

In the "inactive" state, the light color and the dark color of the bevel region is set to the base color of bevel color(SFXBevelColor). As a result, the bevel region within the button control looks 2 dimensional.

The shadow region is drawn in the color which is calculated for the "inactive" state using the color set with the SFYButtonControl::SetShadowColor function.

For more details, refer to SFYButtonControl::SetShadowColor.

* The background of button control will be never drawn in the color set with the SFYWidget::SetBackgroundColor function.

Figure 280. Expanded figure of the button control in the "focus" state when not pressed

In the focused state, the frame region("focus frame") of 2 pixels width of the bevel region is drawn in the bevel color set with the SFYButtonControl::SetFocusColor function.

The content region surrounded by this frame("focus frame") is filled in the base color of the bevel color set with the SFYButtonControl::SetButtonColor function.

Since the operation key set with the SFYButtonControl::SetOperateKey function is not pressed, the bottom edge and the right edge is drawn in the color set with the SFYButtonControl::SetShadowColor function.

* The background of button control will be never drawn in the color set with the SFYWidget::SetBackgroundColor function.

Figure 281. Expanded figure of the button control in the "focus" state when pressed

In the "focus" and "pressed" state, the frame region("focus frame") of 2 pixels width of the bevel region is drawn in the bevel color which is calculated for the "focus" and "pressed" state using the bevel color set with the SFYButtonControl::SetFocusColor function.

The content region surrounded by this frame("focus frame") is filled in the color which is calculated for the "focus" and "pressed" state using the base color of the bevel color set with the SFYButtonControl::SetButtonColor function.

Since the operation key set with the SFYButtonControl::SetOperateKey function is pressed, the top edge and the left edge is drawn in the color set with the SFYButtonControl::SetShadowColor function.

For more details, refer to SFYButtonControl::SetFocusColor and SFYButtonControl::SetButtonColor.

* The background of button control will be never drawn in the color set with the SFYWidget::SetBackgroundColor function.

Events and their handlers

In SFYButtonControl, the following handlers(virtual functions) are registered for the key event[SFEVT_KEY/SFEVT_KEY_PRESS/SFEVT_KEY_RELEASE] on the operation key, the region event[SFEVT_RESPONDER_BOUND], and the drawing event[SFEVT_RESPONDER_RENDER].

In a button control inheriting from SFYButtonControl, the following handlers(virtual functions) are booted up first.

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

	NOTE
	*1. Execute SFYResponder::InvokeForward(SFXEvent(SFEVT_RESPONDER_RESULT, SFP16_RESULT_OK, GetCurrentValue()), false). *2. Execute SFYResponder::SetVirtualBound(SFXRectangle(SFXGrid::ZeroInstance(), GetRealBound().GetSize())). In other words, equalize the virtual region with the real region.

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

SFMTYPEDEFRESPONDER(USRButtonControl)
class USRButtonControl: public SFYButtonControl {
    SFMSEALRESPONDER(USRButtonControl)
    SFMRESPONDERINSTANTIATEFOUR(USRButtonControl, SFYButtonControl, 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', 'B', 'T', 'N')
    };
    SFMTYPEDEFTYPE(CodeEnum)

public:
    static USRButtonControlSmp NewInstance(SFCErrorPtr exception = null);
protected:
    explicit USRButtonControl(Void) static_throws;
    virtual ~USRButtonControl(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;
};

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

        // set the responder type
 SetType(CODE_TYPE);

        // here describe the initialization
    }
}

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

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

Void USRButtonControl::HandleBoundRequest(SFXRectanglePtr rectangle) const
{
    // in case of using function of SFYButtonControl class to draw button and shadow [i.e., SFYButtonControl::DrawButton()/DrawShadow()],
    // deflate rectangle by size of button and shadow
    rectangle->Deflate(GetShadowMargin());
    rectangle->Deflate(GetButtonMargin());

    // calculate the suitable button size
    // set the rectangle argument to the calculated suitable button size
    // for the rectangle argument, it is recommended to set only its size and not to change its origin in this function

    // in case of using function of SFYButtonControl class to draw button and shadow [i.e., SFYButtonControl::DrawButton()/DrawShadow()],
    // inflate rectangle by size of button and shadow
    rectangle->Inflate(GetButtonMargin());
    rectangle->Inflate(GetShadowMargin());

    return;
}

Void USRButtonControl::HandleBoundOptimize(SFXRectanglePtr rectangle) const
{
    // in case of using function of SFYButtonControl class to draw button and shadow [i.e., SFYButtonControl::DrawButton()/DrawShadow()],
    // deflate rectangle by size of button and shadow
    rectangle->Deflate(GetShadowMargin());
    rectangle->Deflate(GetButtonMargin());

    // calculate the suitable button size within rectangular region given by the rectangle argument
    // set the rectangle argument to the calculated suitable button size
    // for the rectangle argument, it is recommended to set only its size and not to change its origin in this function

    // in case of using function of SFYButtonControl class to draw button and shadow [i.e., SFYButtonControl::DrawButton()/DrawShadow()],
    // inflate rectangle by size of button and shadow
    rectangle->Inflate(GetButtonMargin());
    rectangle->Inflate(GetShadowMargin());

    return;
}

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

Void USRButtonControl::HandleRenderRequest(SFXGraphicsPtr graphics) const
{
    // in case of using function of SFYButtonControl class to draw button and shadow [i.e., SFYButtonControl::DrawButton()/DrawShadow()],
    // draw button and shadow as below
    DrawButton(graphics, DrawShadow(graphics, GetLocalBound()));

    // draw inside button

    return;
}

Reference

Member

Description

This constructor performs the initializations as follows:

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

Reference

SFYResponder::SetType | SFYButtonControl::CodeEnum | SFYButtonControl::SetStatePress | SFYButtonControl::SetButtonColor | SFYButtonControl::SetButtonColor | SFYButtonControl::SetFocusColor | SFYButtonControl::SetShadowColor | SFYButtonControl::HandleOperateKey | SFYButtonControl::HandleOperateKeyPress | SFYButtonControl::HandleOperateKeyRelease | SFXEvent | SFXBevelColor | SFXRGBColor | Type | State | Event | Key Event[SFEVT_KEY/SFEVT_KEY_PRESS/SFEVT_KEY_RELEASE] | State Event[SFEVT_RESPONDER_STATE] | Applet-Suspend Event[SFEVT_APP_SUSPEND]

Description

This destructor does nothing.

Description

This function draws the bevel region of this button control which includes the content region.

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

	Tip
	This function will be called in the HandleRender() function of the concrete class inheriting from SFYButtonControl.

In the default implementation, the bevel region of this button control is drawn as below depending on its state.

Structure of the button control

The button control consists of the bevel region, the content region, and the shadow region.

The content region is the one surrounded by the frame("focus frame") of 2 pixels width within the bevel region.

* In case of the radio button control, it consists of not rectangular but circular regions.

Figure 282. Expanded figure of the button control in the "active" or "enable" state

The bevel region is drawn in the bevel color(SFXBevelColor) set with the SFYButtonControl::SetButtonColor function. The shadow region is drawn in the color(SFXRGBColor) set with the SFYButtonControl::SetShadowColor function.

* The background of button control will be never drawn in the color set with the SFYWidget::SetBackgroundColor function.

In the "inactive" or "focus" state, the colors of the frame("focus frame"), the content region, and the shadow region change.

Figure 283. Expanded figure of the button control in the "inactive" state

In the "inactive" state, the light color and the dark color of the bevel region is set to the base color of bevel color(SFXBevelColor). As a result, the bevel region within the button control looks 2 dimensional.

The shadow region is drawn in the color which is calculated for the "inactive" state using the color set with the SFYButtonControl::SetShadowColor function.

For more details, refer to SFYButtonControl::SetShadowColor.

* The background of button control will be never drawn in the color set with the SFYWidget::SetBackgroundColor function.

Figure 284. Expanded figure of the button control in the "focus" state when not pressed

In the focused state, the frame region("focus frame") of 2 pixels width of the bevel region is drawn in the bevel color set with the SFYButtonControl::SetFocusColor function.

The content region surrounded by this frame("focus frame") is filled in the base color of the bevel color set with the SFYButtonControl::SetButtonColor function.

Since the operation key set with the SFYButtonControl::SetOperateKey function is not pressed, the bottom edge and the right edge is drawn in the color set with the SFYButtonControl::SetShadowColor function.

* The background of button control will be never drawn in the color set with the SFYWidget::SetBackgroundColor function.

Figure 285. Expanded figure of the button control in the "focus" state when pressed

In the "focus" and "pressed" state, the frame region("focus frame") of 2 pixels width of the bevel region is drawn in the bevel color which is calculated for the "focus" and "pressed" state using the bevel color set with the SFYButtonControl::SetFocusColor function.

The content region surrounded by this frame("focus frame") is filled in the color which is calculated for the "focus" and "pressed" state using the base color of the bevel color set with the SFYButtonControl::SetButtonColor function.

Since the operation key set with the SFYButtonControl::SetOperateKey function is pressed, the top edge and the left edge is drawn in the color set with the SFYButtonControl::SetShadowColor function.

For more details, refer to SFYButtonControl::SetFocusColor and SFYButtonControl::SetButtonColor.

* The background of button control will be never drawn in the color set with the SFYWidget::SetBackgroundColor function.

Internal Implementation

Internal implementation of the SFYButtonControl::DrawButton function is as follows:

/*protected */Void SFYButtonControl::DrawButton(SFXGraphicsPtr graphics, SFXRectangleConstRef rectangle) const
{
    SFXRectangle                                lx;
    SFXBevelColor                               bevel;
    SFXRGBColor                                 rgb;

    lx.Set(rectangle);
    bevel.Set((GetStateFocus(true)) ? (_color.focus) : (_color.button));
    rgb.Set(_color.button.GetBase());
    if (!GetStateActive(true)) {
        bevel.SetLight(bevel.GetBase());
        bevel.SetDark(bevel.GetBase());
    }
    if (GetStatePress()) {
        (bevel.GetBase().GetBrightness() > 0x7F) ? bevel.SubRGB(0x11) : bevel.AddRGB(0x11);
        (rgb.GetBrightness() > 0x7F) ? rgb.SubRGB(0x11) : rgb.AddRGB(0x11);
    }
    graphics->FillBevelRectangle(lx, bevel);
    lx.Deflate(2, 2);
    graphics->FillRectangle(lx, rgb);
    return;
}// SFYButtonControl::DrawButton //

Reference

SFYButtonControl::DrawShadow | SFYButtonControl::SetButtonColor | SFYButtonControl::SetFocusColor | SFYButtonControl::SetShadowColor | SFXRGBColor::GetBrightness | SFYWidget::SetBackgroundColor | SFXBevelColor | SFXRGBColor | State

Description

This function draws the shadow region of this button control.

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

	Tip
	This function will be called in the HandleRender() function of the concrete class inheriting from SFYButtonControl.

The default implementation is as follows:

Figure 286. Expanded figure of the button control when not pressed

In the "not-pressed" state of the button control, the region of the bottom edge and the right edge is the shadow region, which is drawn in the color(SFXRGBColor) set with the SFYButtonControl::SetShadowColor function.

Figure 287. Expanded figure of the button control in the "focus" state when pressed

In the "pressed" state of the button control, the region of the top edge and the left edge is the shadow region, which is drawn in the color(SFXRGBColor) set with the SFYButtonControl::SetShadowColor function.

At this time, the bevel region of this button control is moved and drawn by (1, 1) compared with that in the "not-pressed" state.

For the drawing of the bevel region of this button control, refer to SFYButtonControl::DrawButton.

Internal Implementation

Internal implementation of the SFYButtonControl::DrawShadow function is as follows:

/*protected */SFXRectangle SFYButtonControl::DrawShadow(SFXGraphicsPtr graphics, SFXRectangleConstRef rectangle) const
{
    SFXRGBColor                                 rgb;
    SFXRectangle                                result(rectangle);

    rgb.Set(_color.shadow);
    if (!GetStateActive(true)) {
        (rgb.GetBrightness() > 0x7F) ? rgb.SubRGB(0x44) : rgb.AddRGB(0x44);
    }
    graphics->SetForeColor(rgb);
    if (GetStatePress()) {
        graphics->DrawLine(result.GetEdgeLeft());
        graphics->DrawLine(result.GetEdgeTop());
        result.AddLeftTop(1, 1);
    }
    else {
        graphics->DrawLine(result.GetEdgeRight());
        graphics->DrawLine(result.GetEdgeBottom());
        result.SubRightBottom(1, 1);
    }
    return result;
}// SFYButtonControl::DrawShadow //

Reference

SFYButtonControl::SetShadowColor | SFXRGBColor | SFYButtonControl::DrawButton

Description

This function gets the bevel color(SFXBevelColor) to draw the bevel region within this button control.

Reference

SFYButtonControl::SetButtonColor | SFYButtonControl::SetFocusColor | SFXRGBColor::GetBrightness | SFXBevelColor | SFXRGBColor | State

Return value

Margin region of this button control [SFXMargin(2, 2, 2, 2)].

Description

The margin region of the button control is the frame margin of 2 pixels width of the bevel region within the button control, which surrounds the content region where to draw a text or an image. Concretely, it is the margin region [left, top, right, and bottom edges of 2 pixels width, i.e., SFXMargin(2, 2, 2, 2)] of the bevel region, which is the local region of the button control excluded its shadow region.

Figure 288. Frame region of the button control in the "focus" state: Expanded Figure

The margin region of the button control is the frame margin of 2 pixels width of the bevel region, which is the region of the button control excluded its shadow region.

The content region of the button control is the region which is surrounded by this frame region.

A text or an image is drawn in this content region.

For the drawing of this region, refer to SFYButtonControl::DrawButton.

Reference

SFXMargin | SFYButtonControl::DrawButton | SFYButtonControl::GetShadowMargin | Local Region

Reference

SFYButtonControl::SetFocusColor | SFXBevelColor | SFXRGBColor | State

Reference

SFYButtonControl::SetOperateKey

Return value

Value of the press offset of this button control.

Description

The press offset is the offset value by which the region of this button control excluded its shadow region will be moved when this button is pressed. The concrete value of the press offset is 1 pixel in the X coordinate and 1 pixel in the Y coordinate.

To the contrary, the region of this button control excluded its shadow region will be moved back to the origin when this button is released. In other words, it will be moved by "-1" in the X coordinate and "-1" in the Y coordinate.

Reference

SFYButtonControl::GetButtonMargin | SFYButtonControl::GetShadowMargin

Reference

SFYButtonControl::SetShadowColor | SFXRGBColor

Return value

Margin of the shadow region of this button control [SFXMargin(0, 0, 1, 1)].

Description

The button control has the shadow region, which is the margin region of SFXMargin(0, 0, 1, 1), i.e., 0 pixel from left edge, 0 pixel from top edge, 1 pixel from right edge, and 1 pixel from bottom edge of its local region.

Figure 289. The shadow region of the button control when not pressed: Expanded Figure

The right edge and the bottom edge of 1 pixel width will be the shadow region when the button control is not pressed.

Figure 290. The shadow region of the button control when pressed: Expanded Figure

The left edge and the top edge of 1 pixel width will be the shadow region when the button control is pressed.

For more details, refer to SFYButtonControl::DrawShadow function.

Reference

SFXMargin | SFYButtonControl::DrawShadow | SFYButtonControl::GetButtonMargin | SFYButtonControl::GetPressOffset

Reference

SFYButtonControl::SetStatePress

Description

This function will be called when the SFEVT_KEY event(key event[SFEVT_KEY]) of the operaion key set with the SFYButtonControl::SetOperateKey function is received.

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

The default implementation does nothing.

Internal Implementation

Internal implementation of the SFYButtonControl::HandleOperateKey function is as follows:

/*protected virtual */Void SFYButtonControl::HandleOperateKey(Void)
{
    return;
}// SFYButtonControl::HandleOperateKey //

Reference

SFYButtonControl::SetOperateKey | Key Event[SFEVT_KEY]

Description

This function will be called when the SFEVT_KEY_PRESS event(key event[SFEVT_KEY_PRESS]) of the operaion key set with the SFYButtonControl::SetOperateKey function is received.

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

The default implementation does nothing.

Internal Implementation

Internal implementation of the SFYButtonControl::HandleOperateKeyPress function is as follows:

/*protected virtual */Void SFYButtonControl::HandleOperateKeyPress(Void)
{
    return;
}// SFYButtonControl::HandleOperateKeyPress //

Reference

SFYButtonControl::SetOperateKey | Key Event[SFEVT_KEY_PRESS]

Description

This function will be called when the SFEVT_KEY_RELEASE event(key event[SFEVT_KEY_RELEASE]) of the operaion key set with the SFYButtonControl::SetOperateKey function is received.

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

The default implementation is to send the SFXEvent(SFEVT_RESPONDER_RESULT, SFP16_RESULT_OK, current value) event, of which the current value can be obtained by calling the SFYControl::GetCurrentValue function.

Internal Implementation

Internal implementation of the SFYButtonControl::HandleOperateKeyRelease function is as follows:

/*protected virtual */Void SFYButtonControl::HandleOperateKeyRelease(Void)
{
    InvokeForward(SFXEvent(SFEVT_RESPONDER_RESULT, SFP16_RESULT_OK, GetCurrentValue()), false);
    return;
}// SFYButtonControl::HandleOperateKeyRelease //

Reference

SFYButtonControl::SetOperateKey | SFYControl::GetCurrentValue | SFXEvent | Key Event[SFEVT_KEY_RELEASE]

Description

This function sets the bevel color(SFXBevelColor) of the bevel region within this button to the specified value.

In the focused state, the margin region [i.e., SFXMargin(2, 2, 2, 2)] of the bevel region within this button control, which is obtained by calling the SFYButtonControl::GetButtonMargin function, that is to say, the frame margin of 2 pixels width is drawn in the bevel color set with the SFYButtonControl::SetFocusColor function.

Default: SFXBevelColor(SFXRGBColor(0xFF, 0xFF, 0xFF, 0x00), SFXRGBColor(0xDD, 0xDD, 0xDD, 0x00), SFXRGBColor(0x88, 0x88, 0x88, 0x00)).

For more details, refer to SFYButtonControl::DrawButton.

Reference

SFYButtonControl::GetButtonColor | SFYButtonControl::GetButtonMargin | SFXMargin | SFYButtonControl::DrawButton | SFYButtonControl::DrawShadow | SFYButtonControl::SetFocusColor | SFYButtonControl::SetShadowColor | SFXRGBColor::GetBrightness | SFXBevelColor | SFXRGBColor | State

Description

This function sets the bevel color to draw the frame margin of this button control in the "focus" state to the specified value. The frame region is the frame of 2 pixels width which consists of the left, top, right, and bottom edges of the region of the button control excluded its shadow region.

In the focused state, the margin region [i.e., SFXMargin(2, 2, 2, 2)] of the bevel region within this button control, which is obtained by calling the SFYButtonControl::GetButtonMargin function, that is to say, the frame margin of 2 pixels width is drawn in the bevel color set with this function.

Default: SFXBevelColor(SFXRGBColor(0xCC, 0xCC, 0xCC, 0x00), SFXRGBColor(0xAA, 0xAA, 0xAA, 0x00),

For more details, refer to SFYButtonControl::DrawButton.

Reference

SFYButtonControl::GetFocusColor | SFYButtonControl::GetButtonMargin | SFYButtonControl::DrawButton | SFYButtonControl::SetButtonColor | SFYButtonControl::SetOperateKey | SFXRGBColor::GetBrightness | SFXBevelColor | SFXRGBColor | State

Description

This function sets the operation key of this button control to the specified value.

The SFYButtonControl::HandleOperateKey and SFYButtonControl::HandleOperateKeyPress or SFYButtonControl::HandleOperateKeyRelease function will be called when this key is pressed or released respectively.

Default: AVK_SELECT

Reference

SFYButtonControl::GetOperateKey | SFYButtonControl::HandleOperateKey | SFYButtonControl::HandleOperateKeyPress | SFYButtonControl::HandleOperateKeyRelease

Description

This function sets the color(SFXRGBColor) to draw the shadow region of this button control to the specified value.

Default:SFXRGBColor(0x00, 0x00, 0x00, 0x00)[black color]

In the "inactive" state, the shadow will be drawn in the color of which each RGB value is subtracted 0x44 from the color set with this function if the brightness of this color is greater than 0x7F. Otherwise it will be drawn in the color of which each RGB value is added 0x44 on the color set with this function.

The brightness of color can be obtained by calling the SFXRGBColor::GetBrightness function.

In the focused state, the shadow will be drawn in the left edge and the top edge of this button control when the operation key set with the SFYButtonControl::SetOperateKey function is pressed. Otherwise it will be drawn in the bottom edge and the right edge.

For more details, refer to SFYButtonControl::DrawButton.

Reference

SFYButtonControl::GetShadowColor | SFYButtonControl::DrawShadow | SFYButtonControl::DrawButton | SFYButtonControl::SetButtonColor | SFYButtonControl::SetFocusColor | SFXRGBColor::GetBrightness | SFXRGBColor | State

Description

This function sets the flag indicating whether or not this button is pressed to the specified value if both of them are different, and sends the state event[SFXEvent(SFEVT_RESPONDER_STATE, SFP16_STATE_PRESS, "value to be set")]. [* Nothing will happen if they are the same.]

Default: false

Reference

SFYButtonControl::GetStatePress | Event | State Event[SFEVT_RESPONDER_STATE]

Reference

SFYResponder::GetType | SFYResponder::SetType