Inheritance diagram

Collaboration diagram

Description

How to use

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

In SFYBoxControl, functions to draw the box 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 SFYBoxControl::SetOperateKey function. By default, the operation key is set to the SELECT key.

Structure of the box control

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

Figure 271. Expanded figure of the box control in the "active" or "enable" state

The outer frame is drawn in the bevel color(SFXBevelColor) set with the SFYBoxControl::SetBevelColor function.

The middle frame("frame") is drawn in the color (SFXRGBColor) set with the SFYBoxControl::SetFrameColor function.

The inner frame("focus frame") is drawn in the color set with the SFYWidget::SetBackgroundColor function(same with that of the content region).

The content region is filled in the color set with the SFYWidget::SetBackgroundColor function.

Figure 272. Expanded figure of the box control in the "inactive" state

The outer frame is drawn in the bevel color(SFXBevelColor) which is calculated for the the "inactive" state using the bevel color set with the SFYBoxControl::SetBevelColor function.

The middle frame("frame") is drawn in the color(SFXRGBColor) which is calculated for the "inactive" state using the color set with the SFYBoxControl::SetFrameColor function.

In the "inactive" state, the outer frame is drawn only in the base color of bevel color set with the SFYBoxControl::SetBevelColor function. As a result, it looks 2 dimensional.

The inner frame("focus frame") is drawn in the color set with the SFYWidget::SetBackgroundColor function(same with that of the content region).

The content region is filled in the color set with the SFYWidget::SetBackgroundColor function.

Figure 273. Expanded figure of the box control in the "focus" state

The outer frame is drawn in the bevel color which is calculated for the the "focus" state using the bevel color set with the SFYBoxControl::SetBevelColor function.

The middle frame("frame") is drawn in the color which is calculated for the "focus" state using the color set with the SFYBoxControl::SetFocusColor function.

The inner frame("focus frame") is drawn in the color set with the SFYBoxControl::SetFocusColor function.

The content region is filled in the color set with the SFYWidget::SetBackgroundColor function.

	Color of the frame in the "focus" state
	In the focused state, the middle frame("frame") is drawn in the color which is calculated using the brightness of color set with the SFYBoxControl::SetFocusColor function. Therefore, it will not be drawn in the color set with the SFYBoxControl::SetFrameColor function.

Events and their handlers

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

In a box control inheriting from SFYBoxControl, 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 box control is as follows:

SFMTYPEDEFRESPONDER(USRBoxControl)
class USRBoxControl: public SFYBoxControl {
    SFMSEALRESPONDER(USRBoxControl)
    SFMRESPONDERINSTANTIATEFOUR(USRBoxControl, SFYBoxControl, 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', 'O', 'X')
    };
    SFMTYPEDEFTYPE(CodeEnum)

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

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

        // set the responder type
 SetType(CODE_TYPE);

        // here describe the initialization
    }
}

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

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

Void USRBoxControl::HandleBoundRequest(SFXRectanglePtr rectangle) const
{
    // in case of using function of SFYBoxControl class to draw box [i.e., SFYBoxControl::DrawBox()],
    // deflate rectangle by size of box
    rectangle->Deflate(GetBoxMargin());

    // calculate the suitable box size
    // set the rectangle argument to the calculated suitable box 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 SFYBoxControl class to draw box [i.e., SFYBoxControl::DrawBox()],
    // inflate rectangle by size of box
    rectangle->Inflate(GetBoxMargin());

    return;
}

Void USRBoxControl::HandleBoundOptimize(SFXRectanglePtr rectangle) const
{
    // in case of using function of SFYBoxControl class to draw box [i.e., SFYBoxControl::DrawBox()],
    // deflate rectangle by size of box
    rectangle->Deflate(GetBoxMargin());

    // calculate the suitable box size within rectangular region given by the rectangle argument
    // set the rectangle argument to the calculated suitable box 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 SFYBoxControl class to draw box [i.e., SFYBoxControl::DrawBox()],
    // inflate rectangle by size of box
    rectangle->Inflate(GetBoxMargin());

    return;
}

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

Void USRBoxControl::HandleRenderRequest(SFXGraphicsPtr graphics) const
{
    // in case of using function of SFYBoxControl class to draw box [i.e., SFYBoxControl::DrawBox()],
    // draw box as below
    DrawBox(graphics, GetLocalBound());

    // draw inside box

    return;
}

Reference

Abstract Class that Represents a Box Control[SFYBoxControl] | State | SFYControl | SFZSingleTextBoxControl | SFZSingleEditBoxControl | SFZMultipleTextBoxControl | SFZMultipleEditBoxControl | SFZImageBoxControl | Key Event[SFEVT_KEY] | Region Event[SFEVT_RESPONDER_BOUND] | Drawing Event[SFEVT_RESPONDER_RENDER]

Member

Description

This constructor performs the initializations as follows:

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

Reference

SFYResponder::SetType | SFYBoxControl::CodeEnum | SFYBoxControl::SetFocusColor | SFYBoxControl::SetFrameColor | SFYBoxControl::SetBevelColor | SFYBoxControl::HandleOperateKey | SFXEvent | SFXBevelColor | SFXRGBColor | Type | Event | Key Event[SFEVT_KEY]

Description

This destructor does nothing.

Description

This function draws this box control in case you want to perform your own drawing.

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 SFYBoxControl.

The default implementation is as follows:

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

Structure of the box control

Figure 274. Expanded figure of the box control in the "active" or "enable" state

The outer frame is drawn in the bevel color(SFXBevelColor) set with the SFYBoxControl::SetBevelColor function.

The middle frame("frame") is drawn in the color (SFXRGBColor) set with the SFYBoxControl::SetFrameColor function.

The inner frame("focus frame") is drawn in the color set with the SFYWidget::SetBackgroundColor function(same with that of the content region).

The content region is filled in the color set with the SFYWidget::SetBackgroundColor function.

Figure 275. Expanded figure of the box control in the "inactive" state

The outer frame is drawn in the bevel color(SFXBevelColor) which is calculated for the the "inactive" state using the bevel color set with the SFYBoxControl::SetBevelColor function.

The middle frame("frame") is drawn in the color(SFXRGBColor) which is calculated for the "inactive" state using the color set with the SFYBoxControl::SetFrameColor function.

In the "inactive" state, the outer frame is drawn only in the base color of bevel color set with the SFYBoxControl::SetBevelColor function. As a result, it looks 2 dimensional.

The inner frame("focus frame") is drawn in the color set with the SFYWidget::SetBackgroundColor function(same with that of the content region).

The content region is filled in the color set with the SFYWidget::SetBackgroundColor function.

Figure 276. Expanded figure of the box control in the "focus" state

The outer frame is drawn in the bevel color which is calculated for the the "focus" state using the bevel color set with the SFYBoxControl::SetBevelColor function.

The middle frame("frame") is drawn in the color which is calculated for the "focus" state using the color set with the SFYBoxControl::SetFocusColor function.

The inner frame("focus frame") is drawn in the color set with the SFYBoxControl::SetFocusColor function.

The content region is filled in the color set with the SFYWidget::SetBackgroundColor function.

	Color of the frame in the "focus" state
	In the focused state, the middle frame("frame") is drawn in the color which is calculated using the brightness of color set with the SFYBoxControl::SetFocusColor function. Therefore, it will not be drawn in the color set with the SFYBoxControl::SetFrameColor function.

Internal Implementation

Internal implementation of the SFYBoxControl::DrawBox function is as follows:

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

    lx.Set(rectangle);
    bevel.Set(_color.bevel);
    if (!GetStateActive(true)) {
        bevel.SetLight(bevel.GetBase());
        bevel.SetDark(bevel.GetBase());
    }
    graphics->DrawBevelRectangle(lx, bevel);
    lx.Deflate(1, 1);
    if (GetStateFocus(true)) {
        rgb.Set(_color.focus);
        if (GetStateActive(true)) {
            if (rgb.GetBrightness() > 0x7F) {
                rgb.SubRGB(0x55);
            }
            else {
                rgb.AddRGB(0x55);
            }
        }
        graphics->DrawRectangle(lx, rgb);
        lx.Deflate(1, 1);
        graphics->DrawRectangle(lx, _color.focus);
    }
    else {
        rgb.Set(_color.frame);
        if (!GetStateActive(true)) {
            if (rgb.GetBrightness() > 0x7F) {
                rgb.SubRGB(0x44);
            }
            else {
                rgb.AddRGB(0x44);
            }
        }
        graphics->DrawRectangle(lx, rgb);
        lx.Deflate(1, 1);
        graphics->DrawRectangle(lx, GetBackgroundColor());
    }
    lx.Deflate(1, 1);
    graphics->FillRectangle(lx, GetBackgroundColor());
    return;
}// SFYBoxControl::DrawBox //

Reference

SFYBoxControl::GetBoxMargin | SFYBoxControl::SetBevelColor | SFYBoxControl::SetFrameColor | SFYBoxControl::SetFocusColor | SFYWidget::SetBackgroundColor | SFXBevelColor | SFXRGBColor | State

Return value

Bevel color(SFXBevelColor) of outer frame of this box control.

Reference

SFYBoxControl::SetBevelColor | SFXBevelColor | SFXRGBColor

Return value

Margin region of this box control [SFXMargin(3, 3, 3, 3)].

Description

The margin region of the box control is the frame margin of 3 pixels width, 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 3 pixels width, i.e., SFXMargin(3, 3, 3, 3)], which is the local region of the box control.

Figure 277. Frame region of the box control in the "focus" state: Expanded Figure

The margin region of the box control is the frame margin of 3 pixels width, which consists of the outer frame, the middle frame, and the inner frame.

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

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

For more details, refer to SFYBoxControl::DrawBox.

Reference

SFXMargin | SFYBoxControl::DrawBox | Local Region

Return value

Color (SFXRGBColor) of inner frame region("focus frame") of this box control in the "focus" state.

Reference

SFYBoxControl::SetFocusColor

Return value

Color(SFXRGBColor) of middle frame("frame") of this box control.

Reference

SFYBoxControl::SetFrameColor

Return value

Operation key of the box control.

Reference

SFYBoxControl::SetOperateKey

Description

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

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

The default implementation is to send the result event [SFXEvent(SFEVT_RESPONDER_RESULT, SFP16_RESULT_OK, SFYControl::GetCurrentValue())] to itself.

Internal Implementation

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

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

Reference

SFYBoxControl::SetOperateKey | SFYControl::GetCurrentValue | SFXEvent | Key Event[SFEVT_KEY] | Result Event[SFEVT_RESPONDER_RESULT]

Description

This function sets the bevel color (SFXBevelColor) to the specified value in which to draw the outer frame of this box control, which looks three dimensional.

Default: SFXBevelColor(SFXRGBColor(0x99, 0x99, 0x99, 0x00), SFXRGBColor(0xEE, 0xEE, 0xEE, 0x00), SFXRGBColor(0xFF, 0xFF, 0xFF, 0x00))

For more details, refer to SFYBoxControl::DrawBox.

	Outer frame of the box control in the "active", "enable", or "focus" state
	The left edge and top edge are drawn in the light color of this bevel color, the right edge and bottom edge are drawn in the dark color, and the left-top vertex and right-bottom vertex is drawn in the base color. As a result, the looking of this box control is 3D.

	Box control in the "inactive" state
	The light color and the dark color is set to the base color of bevel color(SFXBevelColor). All the outer frame of the box control is drawn only in the base color. As a result, the looking of this box control is 2D.

Reference

SFYBoxControl::GetBevelColor | SFYBoxControl::DrawBox | SFYBoxControl::SetFocusColor SFYBoxControl::DrawBox | SFXBevelColor | SFXRGBColor | State

Description

This function sets the color(SFXRGBColor) of inner frame region("focus frame") of this box control in the "focus" state to the specified value.

Default: SFXRGBColor(0xAA, 0xAA, 0xAA, 0x00)[gray color]

For more details, refer to SFYBoxControl::DrawBox.

Color of the middle farme("frame") in the "focus" state

In the focused state, the middle frame("frame") is drawn in the color which is calculated using the brightness of color set with the SFYBoxControl::SetFocusColor function. Therefore, it will not be drawn in the color set with the SFYBoxControl::SetFrameColor function. Concretely, it will be drawn in the inner frame's color of which each RGB value is subtracted 0x55 from the color set with this function if the brightness of color is greater than 0x7F. Otherwise it will be drawn in the color of which each RGB value is added 0x55 on the color set with this function. The outer frame is drawn in the bevel color(SFXBevelColor) set with the SFYBoxControl::SetBevelColor function. The color of inner frame is set with this function. The brightness of color can be obtained by calling the SFXRGBColor::GetBrightness function.

Reference

SFYBoxControl::GetFocusColor | SFYBoxControl::DrawBox | SFYBoxControl::SetFrameColor | SFYBoxControl::SetBevelColor | SFXRGBColor::GetBrightness | SFXBevelColor | SFXRGBColor | State

Description

This function sets the color(SFXRGBColor) of middle frame("frame") of this box control to the specified value.

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

For more details, refer to SFYBoxControl::DrawBox.

Color of the middle farme("frame") in the "inactive" state

In the "inactive" state, the middle frame("frame") is drawn in the color which is calculated using the brightness of color set with the SFYBoxControl::SetFrameColor function. Concretely, it 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 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.

Color of the middle farme("frame") in the "focus" state

In the focused state, the middle frame("frame") is drawn in the color which is calculated using the brightness of color set with the SFYBoxControl::SetFocusColor function. Therefore, it will not be drawn in the color set with the SFYBoxControl::SetFrameColor function. Concretely, it will be drawn in the inner frame's color of which each RGB value is subtracted 0x55 from the color set with this function if the brightness of color is greater than 0x7F. Otherwise it will be drawn in the color of which each RGB value is added 0x55 on the color set with this function. The outer frame is drawn in the bevel color(SFXBevelColor) set with the SFYBoxControl::SetBevelColor function. The color of inner frame is set with this function. The brightness of color can be obtained by calling the SFXRGBColor::GetBrightness function.

Reference

SFYBoxControl::GetFrameColor | SFYBoxControl::DrawBox | SFYBoxControl::SetFocusColor | SFYBoxControl::SetFrameColor | SFYBoxControl::DrawBox | SFXRGBColor::GetBrightness | SFXRGBColor | State

Description

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

The SFYBoxControl::HandleOperateKey function will be called when this key is pressed.

Default: AVK_SELECT

Reference

SFYBoxControl::GetOperateKey | SFYBoxControl::HandleOperateKey

Reference

SFYResponder::GetType | SFYResponder::SetType