Inheritance diagram

Collaboration diagram

Description

How to use

SoftKey control(SFZSoftKeyControl) is a control to handle the key events from SoftKey, and there are 2 types of the SoftKey controls depending on the number of labels which constitute its SoftKey menu as follows:

	Note
	Default is the standard style.

Figure 381. Standard style

Standard style: Labels for 3 soft keys constitute its SoftKey menu.

Figure 382. Extention style

Extention style: Labels for 5 soft keys and 4 cursor keys constitute its SoftKey menu.

The below is the layout of SoftKey control.

Standard style:

Extention style:

	Background color of the SoftKey control
	The default background color of the SoftKey control(SFZSoftKeyControl) is set to SFXRGBColor(0xCC, 0xCC, 0xCC, 0x00) [gray color]. This background color can be changed with the SFYWidget::SetBackgroundColor function.

Functions of the SoftKey control(SFZSoftKeyControl) are as follows:

	About the focused responder
	For more details on the focused responder, refer to State.

	About the elements of text, image, and 3-Color for each label
	The elements of text, image, and 3-Color for each label can be shared with different labels and each is managed by this unique key at the registration. The frame color, the foreground color, and the background color are grouped together into 3-Color using the same unique color key at the registration. Conversely, 3-Color represents the frame color, the foreground color, and the background color.

How to use the SFZSoftKeyControl class

In the following description, the application class called "application" which contains two windows called "window1" and "window2" is supposed.

Mechanism of the SoftKey control

In the SoftKey control, the SoftKey menu can be associated with more than one responder. The SoftKey control is defined as "active" if any of the responders bound with the SoftKey control is in the "focus" state. And the foremost responder among them is defined as "active responder". At this time, the SoftKey menu associated with "active responder" will be displayed on the device screen. This menu is defined as "active menu". The SoftKey control will transfer the key event[SFEVT_KEY] from SoftKey as SoftKey event[SFEVT_RESPONDER_SOFTKEY] to "active responder". If the SoftKey control is not "active", the SoftKey event[SFEVT_RESPONDER_SOFTKEY] will be sent to no responder. And, the SoftKey menu whose menu key is "0", called "default menu", will be displayed on the device screen.

Default menu

Default menu is the SoftKey menu which will be displayed on the screen when any responder bound with the SoftKey control is in the "unfocus" state, i.e., "active responder" does not exist. The default menu is automatically created and registered with the menu key "0" into the SoftKey control when its instance is created. The initial settings of the default menu (menu key "0") is as follows: Foreground color: SFXRGBColor(0xFF, 0xFF, 0xFF, 0x00)[white color] Background color: SFXRGBColor(0x77, 0x77, 0x77, 0x00)[gray color] Frame color: SFXRGBColor(0xDD, 0xDD, 0xDD, 0xDD)[light gray color] Label text: SFXWideString::EmptyInstance() Label image: SFBImageSmp::EmptyInstance() *1 These value can be changed by updating each value for the menu key "0" with the functions of SFZSoftKeyControl. *2 Since the enable flag of each label in the SoftKey menu is set to "true" by default, the label region will be displayed as it is. To undisplay a label region, set its enable flag to "false" with the SFZSoftKeyControl::SetEnable function.

About the SoftKey event

When the SoftKey control is used, the dispatching rule below will be automatically registered into the tracer of the application class by the internal processing of the SoftKey control as follows: // when set SoftKey control's parent responder to application class // dispatching rule below will be registered into the tracer application->RegisterTracer( SFXEventRange(SFEVT_KEY, SFEVT_KEY, AVK_SOFT1, AVK_SOFT4), SFYTracer::ORDER_FORWARD, SFYTracer::STATE_ALL, false ); The meaning of this dispatching rule is as follows: Distribute the key event from SoftKey to all child responders regardless of their state from foreground to background. If the event is handled, event handling will stop there(the event will not be handled duplicately). Since the SoftKey control is the child responder placed foremost of the application class[root (SFZRoot class)], the key event of SoftKey is always handled in the SoftKey control. If the SoftKey control is "active", the key event of SoftKey will be transferred as the SoftKey event[SFEVT_RESPONDER_SOFTKEY] to the "active responder" defined above. If the SoftKey control is not "active", the SoftKey event will not be sent to any responder. Reference: Tracer | Handler | Root(Basic) | SFZRoot

// define screensaver_sfy application class
SFMTYPEDEFCLASS(screensaver_sfy)
class screensaver_sfy: public SFYApplication {
    SFMSEALCOPY(screensaver_sfy)
private:
    SFZSoftKeyControlSmp _softkey;  // SoftKey control must be contained as global variable by application class
    MainWindowSmp _main;
public:
    static SFCInvokerPtr Factory(Void);
    static SFZSoftKeyControlSmp GetSoftKey(Void);
private:
    explicit screensaver_sfy(Void) static_throws;
    virtual ~screensaver_sfy(Void);
    XANDLER_DECLARE_VOIDRENDER(OnRenderRequest)
};

// constructor of screensaver_sfy application class
screensaver_sfy::screensaver_sfy(Void) static_throws
{
    SFCError error;

    if (static_try()) {

        // .................

        if (static_try()) {

           // make SoftKey control
           // application class can have only one SoftKey control
           _softkey = SFZSoftKeyControl::NewInstance(&error);

           if (_softkey != null) {

                // set parent responder to application class(root)
                // * SoftKey control must be root's child responder
                error = _softkey->SetParent(GetThis());

                // at this time, SoftKey control is automatically placed foremost among child responders of root by internal processing
                // key events of SoftKey are all handled in SoftKey control


                if (error == SFERR_NO_ERROR) {

                    // set menu style to "extention style"
                    _softkey->SetStyle(SFZSoftKeyControl::EXTENSION);

                    // set real region to region automatically calculated from device screen size and SoftKey control style
                    // (to be set at the bottom in the device screen)
                    // *** CAUTION on specification of GetSuitableBound() only for SFZSoftKeyControl: 
                    // *** 1. A rectangular region will be ignored if specified in the argument and 
                    // ***    the suitable size will be calculated from the full screen region of the mobile phone gotten by calling SFXDevice::GetScreenSize().
                    // ***    In general, the argument is not specified since it has no meaning.
                    // *** 2. This function will return not only the suitable rectangle size but also the suitable origin position.
                    // ***    Therefore, there is no need to set the position of the real region after calling this function.
                    _softkey->SetRealBound(_softkey->GetSuitableBound());

                    // set SoftKey control's state to "visible" + "active" + "disable" + "unfocus" together
                    _softkey->SetState(true, true, false, false);

                    // move SoftKey control foremost
                    // _softkey->ToFront();  // this can be omitted since SoftKey control is always moved foremost by internal processing

                    // register each element (i.e., text, image, 3 colors) for SoftKey label
                    // before they are used for SoftKey menu
                    // * since image and 3 colors are not registered here, default setting are used for these elements
                    _softkey->RegisterText(KEY_TEXT_EXIT,   SFXWideString("End"));
                    _softkey->RegisterText(KEY_TEXT_EDIT,   SFXWideString("Set"));
                    _softkey->RegisterText(KEY_TEXT_ADD,    SFXWideString("Add"));
                    _softkey->RegisterText(KEY_TEXT_CHANGE, SFXWideString("Update"));
                    _softkey->RegisterText(KEY_TEXT_REMOVE, SFXWideString("Delete"));

                    // * all elements can be registered together from the resource file
                    // _softkey->RegisterTextRange(
                    //   IDS_SK_EXIT, SFXPath(SCREENSAVER_SFY_RES_FILE), IDS_SK_EXIT, IDS_SK_REMOVE
                    // );
                }
            }
        }

        // make MainWindow
        if (error == SFERR_NO_ERROR) {
            _main = MainWindow::NewInstance(&error);

                .................

        }


        .................
    }
}


// implementation of function to get instance of SoftKey control
SFZSoftKeyControlSmp screensaver_sfy::GetSoftKey(Void)
{
    return static_cast<screensaver_sfyPtr>(GetInstance())->_softkey;
}

// define MainWindow
SFMTYPEDEFRESPONDER(MainWindow)
class MainWindow: public SFZWindow {
    SFMSEALRESPONDER(MainWindow)
    SFMRESPONDERINSTANTIATEFOUR(MainWindow, SFZWindow, SFYContainer, SFYWidget, SFYResponder)
public:

        ................

private:
    SFZSoftKeyControlSmp _softkey;// SoftKey control

        ................

private:
    XANDLER_DECLARE_VOIDEVENT(OnKey)     // key handler
    XANDLER_DECLARE_VOIDEVENT(OnSoftkey) // SoftKey handler

        ................

};

// constructor of MainWindow
MainWindow::MainWindow(Void) static_throws
{
    static SFXEventRange::AtomRecConst range[] = {
        { SFEVT_APP_SUSPEND,SFEVT_APP_SUSPEND,SFP16_BEGIN,   SFP16_END },
        { SFEVT_APP_RESUME, SFEVT_APP_RESUME, SFP16_BEGIN,   SFP16_END },

        // normal key event
        { SFEVT_KEY,        SFEVT_KEY,        SFP16_BEGIN,   SFP16_END },

        // SoftKey event[SFEVT_RESPONDER_SOFTKEY] which SoftKey control will transfer
        // key event of SoftKey will be converted into SoftKey event[SFEVT_RESPONDER_SOFTKEY]
        { SFEVT_RESPONDER_SOFTKEY, SFEVT_RESPONDER_SOFTKEY, AVK_SOFT1,     AVK_SOFT4 }
    };
    SFYHandler::RuleRec rule[lengthof(range)];

    if (static_try()) {
 SetType(CODE_TYPE);

        rule[0].spp = XANDLER_FUNCTION(OnSuspend);
        rule[0].reference = this;
        rule[1].spp = XANDLER_FUNCTION(OnResume);
        rule[1].reference = this;

        // key handler
        rule[2].spp = XANDLER_FUNCTION(OnKey);
        rule[2].reference = this;

        // SoftKey handler
        rule[3].spp = XANDLER_FUNCTION(OnSoftkey);
        rule[3].reference = this;

        // register handlers
        static_throw(RegisterHandler(atomic_cast(range), rule, lengthof(range)));

        // get instance of SoftKey control
        if ((_softkey = screensaver_sfy::GetSoftKey()) != null) {

            if (!_softkey->ContainsMenuKey(MENUID_MAIN)) {
                // if SoftKey menu which corresponds to unique menu key "MENUID_MAIN" is not created

                // create SoftKey menu
                _softkey->CreateMenu(MENUID_MAIN);

                // set each element key to SoftKey menu above
                // * elements have already been registered in constructor of application class
                // keys below correspond to labels for SELECT, SOFTKEY_1, SOFTKEY_2, SOFTKEY_3, SOFTKEY_4 from left respectively
                UInt32 keyText[] = {
                    IDS_SK_EDIT, IDS_SK_EXIT, IDS_SK_ADD, IDS_SK_CHANGE, IDS_SK_REMOVE
                };
                _softkey->SetTextKey(MENUID_MAIN, keyText, lengthof(keyText));
           }

           // bind MainWindow with SoftKey menu of SoftKey control
           _softkey->Bind(this, MENUID_MAIN); 
           // or "_softkey->Bind(GetThis(), MENUID_MAIN);" *The former yields better performance than the latter.
        }
    }
}

// implement handler for SoftKey event: handler for key events from SoftKey1 to SoftKey4
// this handler will be booted up only if MainWindow is "active responder"
XANDLER_IMPLEMENT_VOIDEVENT(MainWindow, OnSoftkey, invoker, event)
{

                .................


    switch (event.GetP16()) {
        case AVK_SOFT1:
            // make the dialog which confirms termination

                .................

            break;
        case AVK_SOFT2:
            // make menu

                .................

}

Execution result

Standard style:

Extention style:

Reference

SFYControl

Member

Return value

This constructor performs the initializations as follows:

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

Reference

SFYResponder::SetType | SFZSoftKeyControl::CodeEnum | SFZSoftKeyControl::SetFont | SFZSoftKeyControl::SetStyle | SFZSoftKeyControl::StyleEnum | SFZSoftKeyControl::SetBaseSpace | SFZSoftKeyControl::SetArrowBaseLength | SFZSoftKeyControl::SetArrowHeight | SFYWidget::SetBackgroundColor | SFZSoftKeyControl::SetDefaultFrameColor | SFZSoftKeyControl::SetDefaultForeColor | SFZSoftKeyControl::SetDefaultBackColor | SFZSoftKeyControl::HandleStyle | SFZSoftKeyControl::RegisterFrameColor | SFZSoftKeyControl::RegisterForeColor | SFZSoftKeyControl::RegisterBackColor | SFZSoftKeyControl::RegisterImage | SFZSoftKeyControl::RegisterText | SFZSoftKeyControl::SetColorKey | SFZSoftKeyControl::SetImageKey | SFZSoftKeyControl::SetTextKey | SFZSoftKeyControl::SetEnable | SFZSoftKeyControl::CreateMenu | SFXEvent | SFXRGBColor | Type | Tracer | Event | Key Event[SFEVT_KEY] | SoftKey Event[SFEVT_RESPONDER_SOFTKEY] | Parent Child Event[SFEVT_RESPONDER_OWNER] | Style Event[SFEVT_RESPONDER_STYLE]

Description

This destructor performs the finalization on this SoftKey control as follows:

Reference

SFZSoftKeyControl::UnBind | SFZSoftKeyControl::CreateMenu | SFZSoftKeyControl::DestroyMenu | SFZSoftKeyControl::RegisterImage | SFZSoftKeyControl::RegisterImageRange | SFZSoftKeyControl::UnregisterImage | SFZSoftKeyControl::RegisterBackColor | SFZSoftKeyControl::RegisterBackColor | SFZSoftKeyControl::RegisterFrameColor | SFZSoftKeyControl::UnregisterColor | SFZSoftKeyControl::RegisterText | SFZSoftKeyControl::RegisterTextRange | SFZSoftKeyControl::UnregisterText

Return value

Description

This function binds the specified responder with the specified SoftKey menu.

If this responder becomes "active", the corresponding SoftKey menu will be displayed.

	About "active"
	The foremost responder among the focused responder bound with the SoftKey control is defined as "active".

Mechanism of the SoftKey control

In the SoftKey control, the SoftKey menu can be associated with more than one responder. The SoftKey control is defined as "active" if some responders bound with the SoftKey control are in the "focus" state. And the foremost responder among them is defined as "active responder". At this time, the SoftKey menu associated with "active responder" will be displayed on the screen. This menu is defined as "active menu". The SoftKey control will receive the key event[SFEVT_KEY] from SoftKey and send it as the SoftKey event[SFEVT_RESPONDER_SOFTKEY] to "active responder". If the SoftKey control is not "active", the SoftKey event[SFEVT_RESPONDER_SOFTKEY] will be sent to no responder. And, the SoftKey menu whose menu key is "0", called "default menu", will be displayed on the screen.

Reference

SFZSoftKeyControl::UnBind

Return value

Description

This function checks whether or not the specified color key is registered into this SoftKey control.

Reference

SFZSoftKeyControl::GetColorKey SFZSoftKeyControl::SetColorKey

Return value

Description

This function checks whether or not the specified image key is registered into this SoftKey control.

Reference

SFZSoftKeyControl::GetImageKey SFZSoftKeyControl::SetImageKey

Return value

Description

This function checks whether or not the specified menu key is registered into this SoftKey control.

Reference

SFZSoftKeyControl::GetMenuKey

Return value

Description

This function checks whether or not the specified responder is bound with this SoftKey control.

Reference

SFZSoftKeyControl::Bind SFZSoftKeyControl::UnBind

Return value

Description

This function checks whether or not the specified text key is registered into this SoftKey control.

Reference

SFZSoftKeyControl::GetTextKey SFZSoftKeyControl::SetTextKey

Return value

Description

This function creates the SoftKey menu of this SoftKey control for the specified menu key.

If this function succeeds, the handler of SFZSoftKeyControl::HandleSoftMenuCreate will be booted up immediately.

The SoftKey menu whose menu key value is INVALID_KEY (= UINT32_MAXIMUM) cannot be created.

If the SoftKey menu of the specified menu key value has already existed, it will be destroyed and the newly created SoftKey menu will replace it.

In this case, the handler of SFZSoftKeyControl::HandleSoftMenuDestroy will be booted up just before the existing SoftKey menu is destroyed.

Immediately after creation of the SoftKey menu, each of its label is valid [i.e., its enable flag is set to "true", therefore it will be displayed on the screen] and each element key of text, image, and 3-Color is set to "0".

	SoftKey menu of the menu key "0"
	The SoftKey menu of the menu key "0" is automatically created when the instance of the SoftKey control is created. The SoftKey menu of the menu key "0" is used as the default menu.

Default menu

Default menu is the SoftKey menu which is displayed when any responder bound with the SoftKey control is in the "unfocus" state, i.e., there is no "active responder". The default menu is automatically created and registered with the menu key "0" into the SoftKey control when its instance is created. The initial settings of the default menu of the menu key "0" is as follows: Foreground color : SFXRGBColor(0xFF, 0xFF, 0xFF, 0x00)[white color] Background color: SFXRGBColor(0x77, 0x77, 0x77, 0x00)[gray color] Frame color : SFXRGBColor(0xDD, 0xDD, 0xDD, 0xDD)[light gray color] Label text : SFXWideString::EmptyInstance() Label image : SFBImageSmp::EmptyInstance() *1 These value can be changed by updating each value for the menu key "0" with the functions of SFZSoftKeyControl. *2 Since the enable flag of each label in the SoftKey menu is set to "true" by default, the label region will be displayed as it is. To undisplay a label region, set its enable flag to "false" using the SFZSoftKeyControl::SetEnable function.

Reference

SFZSoftKeyControl::HandleSoftMenuCreate | SFZSoftKeyControl::HandleSoftMenuDestroy | SFZSoftKeyControl::DestroyMenu | SFXWideString::EmptyInstance | SFXBrewPointer::EmptyInstance | SFXWideString | SFBImage

Description

This function destroys the SoftKey menu for the specified menu key.

The handler of SFZSoftKeyControl::HandleSoftMenuDestroy will be booted up just before the SoftKey menu is destroyed.

If the specified SoftKey menu does not exist, nothing will happen.

Reference

SFZSoftKeyControl::HandleSoftMenuDestroy | SFZSoftKeyControl::CreateMenu

Description

This function draws the specified label image at the specified rectangular region.

At this time, the center of the rectangular region equalizes with that of the label image.

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

	Tip
	This function is called in the SFZSoftKeyControl::HandleBoundRequest function

Internal Implementation

Internal implementation of the SFZSoftKeyControl::DrawImage function is as follows:

/*protected */Void SFZSoftKeyControl::DrawImage(SFXGraphicsPtr graphics, SFXRectangleConstRef rectangle, SFBImageSmpConstRef image) const
{
    SFXRectangle                        rcImage(rectangle);
    AEEImageInfo                        info;
    SInt16                              dx;
    SInt16                              dy;

    if (image != null) {
        image->GetInfo(&info);
        if (info.cx > 0 && info.cy > 0) {
            dx = (rcImage.GetWidth() - info.cx) / 2;
            dy = (rcImage.GetHeight() - info.cy) / 2;
            rcImage.SetSize(info.cx, info.cy);
            graphics->DrawImage(image, rcImage.GetOrigin() + SFXGrid(dx, dy));
        }
    }
    return;
}// SFZSoftKeyControl::DrawImage //

Reference

SFZSoftKeyControl::DrawRectangularFrame | SFZSoftKeyControl::HandleBoundRequest

Return value

Content region surrounded by the frame.

Description

This function draws the frame in the specified frame color and the specified background color in the specified rectangular region. Then the content region surrounded by the frame will be returned.

In general, a text or an image is drawn within this content region, which is filled in the background color.

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

	Tip
	This function is called in the SFZSoftKeyControl::DrawRectangularFrame function

Internal Implementation

Internal implementation of the SFYWidget::HandleRenderRequest function is as follows:

enum {
    ARROW_BASE_LENGTH   = 6,
    ARROW_HEIGHT        = 3,
    BASE_SPACE          = 2,
    RING_MARGIN         = 3,
    RING_SIZE           = 1
};

/*protected */SFXRectangle SFZSoftKeyControl::DrawRectangularFrame(SFXGraphicsPtr graphics, SFXRectangleConstRef rectangle, SFXRGBColorConstRef back, SFXRGBColorConstRef frame) const
{
    SFXRectangle                        result(rectangle);

    graphics->DrawRoundRectangle(result, SFXSize(9, 9), back);
    result.Deflate(RING_SIZE, RING_SIZE);
    graphics->FillRoundRectangle(result, SFXSize(7, 7), back);
    graphics->DrawRoundRectangle(result, SFXSize(7, 7), frame);
    result.Deflate(RING_MARGIN - RING_SIZE, RING_MARGIN - RING_SIZE);
    return result;
}// SFZSoftKeyControl::DrawRectangularFrAme //

Reference

SFZSoftKeyControl::DrawImage | SFZSoftKeyControl::HandleBoundRequest

Description

This function gets the menu key of the active menu of this SoftKey control.

	What is an active menu?
	The SoftKey menu which is currently displayed is called "active menu".

Reference

SFZSoftKeyControl::GetMenuKey

Return value

Length of the base of the triangle label in the SoftKey menu with the "extention" style. [pixels]

Description

This function gets the length of the base of the triangle label in the SoftKey menu with the "extention" style. [pixels]

Reference

SFZSoftKeyControl::SetArrowBaseLength

Return value

Height of the triangle in this SoftKey control. [pixels]

Description

This function gets the height of the triangle label in the SoftKey menu with the "extention" style. [pixels]

Reference

SFZSoftKeyControl::SetArrowHeight

Return value

Description

This function gets the background color of a label which corresponds to the specified color key.

If the color key is not registered, the default background color set with the SFZSoftKeyControl::SetDefaultBackColor function will be returned.

Reference

SFZSoftKeyControl::RegisterBackColor | SFZSoftKeyControl::UnregisterColor | SFZSoftKeyControl::SetDefaultBackColor | SFZSoftKeyControl::GetFrameColor | SFZSoftKeyControl::GetForeColor | SFZSoftKeyControl::GetText | SFZSoftKeyControl::GetImage

Return value

Value(Base space) of the space between the label and the border of this SoftKey control. [pixels]

Description

This function gets the value of space between the label and the border of this SoftKey control. [pixels]

	Note
	The value of the space between the labels is same with this return value.

Reference

SFZSoftKeyControl::SetBaseSpace

Return value

Background color of the specified active label of this SoftKey control.

Description

This function gets the background color of the specified active label of this SoftKey control from the cashe.

	What is an active label?
	The label on the active menu is called "active label".

	What is an active menu?
	The SoftKey menu which is currently displayed is called "active menu".

	Cashe of the SoftKey control
	In the SoftKey control, the content of the active menu is saved in the cashe.

Reference

SFZSoftKeyControl::SoftkeyEnum | SFZSoftKeyControl::GetCacheFrameColor | SFZSoftKeyControl::GetCacheForeColor

Return value

Foreground color of the specified active label of this SoftKey control.

Description

This function gets the foreground color of the specified active label of this SoftKey control from the cashe.

	What is an active label?
	The label on the active menu is called "active label".

	What is an active menu?
	The SoftKey menu which is currently displayed is called "active menu".

	Cashe of the SoftKey control
	In the SoftKey control, the content of the active menu is saved in the cashe.

Reference

SFZSoftKeyControl::SoftkeyEnum | SFZSoftKeyControl::GetCacheFrameColor | SFZSoftKeyControl::GetCacheBackColor

Return value

Frame color of the specified active label of this SoftKey control.

Description

This function gets the frame color of the specified active label of this SoftKey control from the cashe.

	What is an active label?
	The label on the active menu is called "active label".

	What is an active menu?
	The SoftKey menu which is currently displayed is called "active menu".

	Cashe of the SoftKey control
	In the SoftKey control, the content of the active menu is saved in the cashe.

Reference

SFZSoftKeyControl::SoftkeyEnum | SFZSoftKeyControl::GetCacheForeColor | SFZSoftKeyControl::GetCacheBackColor

Argument

Return value

Image of the specified active label of this SoftKey control

Description

This function gets the image of the specified active label of this SoftKey control from the cashe.

If a cursor label is specified, "null" will be returned.

	What is an active label?
	The label on the active menu is called "active label".

	What is an active menu?
	The SoftKey menu which is currently displayed is called "active menu".

	Cashe of the SoftKey control
	In the SoftKey control, the content of the active menu is saved in the cashe.

Reference

SFZSoftKeyControl::SoftkeyEnum | SFZSoftKeyControl::GetCacheText

Return value

Value of the enable flag of the specified active label of this SoftKey control.

Description

This function gets the value of enable flag of the specified active label of this SoftKey control from the cashe.

If the enable flag is set to "false", the corresponding label will not be drawn.

	What is an active label?
	The label on the active menu is called "active label".

	What is an active menu?
	The SoftKey menu which is currently displayed is called "active menu".

	Cashe of the SoftKey control
	In the SoftKey control, the content of the active menu is saved in the cashe.

Reference

SFZSoftKeyControl::SoftkeyEnum | SFZSoftKeyControl::GetEnable

Argument

Return value

Press state of the specified active label of this SoftKey control

Description

This function gets the press state of the specified active label of this SoftKey control from the cashe.

If the index of the label othe than cursor label is specified, "false" will be returned.

If the enable flag is set to "false", the corresponding label will not be drawn.

	What is an active label?
	The label on the active menu is called "active label".

	What is an active menu?
	The SoftKey menu which is currently displayed is called "active menu".

	Cashe of the SoftKey control
	In the SoftKey control, the content of the active menu is saved in the cashe.

Reference

SFZSoftKeyControl::SoftkeyEnum

Argument

Return value

Text of the specified active label of this SoftKey control

Description

This function gets the text of the specified active label of this SoftKey control from the cashe.

If a cursor label is specified, "null" will be returned.

	What is an active label?
	The label on the active menu is called "active label".

	What is an active menu?
	The SoftKey menu which is currently displayed is called "active menu".

	Cashe of the SoftKey control
	In the SoftKey control, the content of the active menu is saved in the cashe.

Reference

SFZSoftKeyControl::SoftkeyEnum | SFZSoftKeyControl::GetCacheImage

Return value

Description

This function gets the color key of the specified label of the specified menu of this SoftKey control.

If the invalid menu key or label index is specified, "INVALID_KEY(= UINT32_MAXIMUM)" will be returned.

Reference

SFZSoftKeyControl::SetColorKey

Description

This function gets the default background color for label of this SoftKey control, which will be used when the invalid color key is specified.

The background of label or the triangle when the cursor key is not pressed is filled in this color.

Reference

SFZSoftKeyControl::SetDefaultBackColor

Description

This function gets the default foreground color for label of this SoftKey control, which will be used when the invalid color key is specified.

The label text or the triangle when the cursor key is pressed is drawn in this color.

Reference

SFZSoftKeyControl::SetDefaultForeColor

Description

This function gets the default frame color for label of this SoftKey control, which will be used when the invalid color key is specified.

Reference

SFZSoftKeyControl::SetDefaultFrameColor

Return value

Description

This function gets the value of enable flag of the specified label of the specified menu of this SoftKey control.

If the specified menu key or label number is invalid, "false" will be returned.

	Note
	If the value of enable flag is "false", the corresponding label will not be drawn.

Reference

SFZSoftKeyControl::SetEnable

Description

This function gets the font to draw the label text of this SoftKey control.

Reference

SFZSoftKeyControl::SetFont

Return value

Description

This function gets the foreground color(text color) for label of this SoftKey control, which corresponds to the specified color key.

If the key is not registered, the default foreground color set with the SFZSoftKeyControl::SetDefaultForeColor function will be returned.

Reference

SFZSoftKeyControl::RegisterForeColor | SFZSoftKeyControl::UnregisterColor | SFZSoftKeyControl::SetDefaultForeColor | SFZSoftKeyControl::GetFrameColor | SFZSoftKeyControl::GetBackColor | SFZSoftKeyControl::GetText | SFZSoftKeyControl::GetImage

Return value

Description

This function gets the frame color for label of this SoftKey control, which corresponds to the specified color key.

If the key is not registered, the default frame color set with the SFZSoftKeyControl::SetDefaultFrameColor function will be returned.

Reference

SFZSoftKeyControl::RegisterFrameColor | SFZSoftKeyControl::UnregisterColor | SFZSoftKeyControl::SetDefaultFrameColor | SFZSoftKeyControl::GetForeColor | SFZSoftKeyControl::GetBackColor | SFZSoftKeyControl::GetText | SFZSoftKeyControl::GetImage

Return value

Description

This function gets the label image of this SoftKey control, which corresponds to the specified image key.

If the key is not registered, SFBImageSmp::EmptyInstance() will be returned.

Reference

SFZSoftKeyControl::RegisterImage | SFZSoftKeyControl::UnregisterImage | SFZSoftKeyControl::GetText | SFZSoftKeyControl::GetBackColor | SFZSoftKeyControl::GetForeColor | SFZSoftKeyControl::GetFrameColor | SFXBrewPointer::EmptyInstance | SFBImage

Return value

Description

This function gets the image key of the specified label of the specified menu of this SoftKey control.

If the invalid menu key or label index is specified, "INVALID_KEY(= UINT32_MAXIMUM)" will be returned.

Reference

SFZSoftKeyControl::SetImageKey

Description

This function gets the rectangular region of the specified label of this SoftKey control.

	Note
	This function is called to get the rectangular region of the label in such a case that the developer's own drawing of this control is performed.

Reference

SFZSoftKeyControl::SoftkeyEnum | SFZSoftKeyControl::SetLabelRectangle | SFZSoftKeyControl::DrawRectangularFrame

Return value

Reference

SFZSoftKeyControl::CreateMenu SFZSoftKeyControl::DestroyMenu

Description

This function gets the menu style of this SoftKey control.

Default: SFZSoftKeyControl::DEFAULT_STYLE (standard style)

Reference

SFZSoftKeyControl::SetStyle | SFZSoftKeyControl::StyleEnum

Return value

Description

This function gets the label text of this SoftKey control, which corresponds to the specified text key.

If the key is not registered, SFXWideString::EmptyInstance() will be returned.

Reference

SFZSoftKeyControl::RegisterText | SFZSoftKeyControl::UnregisterText | SFZSoftKeyControl::GetImage | SFZSoftKeyControl::GetBackColor | SFZSoftKeyControl::GetForeColor | SFZSoftKeyControl::GetFrameColor | SFXWideString::EmptyInstance | SFXWideString

Return value

Description

This function gets the text key of the specified label of the specified menu of this SoftKey control.

If the invalid menu key or label index is specified, "INVALID_KEY(= UINT32_MAXIMUM)" will be returned.

Reference

SFZSoftKeyControl::SetTextKey

Description

This function will be called when the region event [SFXEvent(SFEVT_RESPONDER_BOUND, SFP16_BOUND_OPTIMIZE, rectangle)] is received.

This function calculates the suitable rectangle size and origin position of this responder.

In the default implementation, the suitable rectangle size in the device screen is stored into the size element of the rectangle argument as a result of calculation depending on its style. Value passed via the "rectangle" argument will be ignored.

The suitable rectangle size is stored into the size element of the rectangle argument as a result of calculation. It is recommended not to change the origin of the rectangle argument in this function.

CAUTION

Implementation of this function is the same with that of the SFZSoftKeyControl::HandleBoundRequest function. The rectangular region will be ignored if specified in the "rectangle" argument and the suitable size will be calculated from the full screen region of the mobile phone. In general, the HandleBoundOptimize() function will return only the suitable rectangle size, but the SFZSoftKeyControl::HandleBoundOptimize function will return not only the size but also the origin position of the suitable rectangular region via the "rectangle" argument which will be passed as the P32 parameter of the region event. Therefore, you don't have to set the origin position after calling the SFYResponder::GetSuitableBound function regarding to the SFZSoftKeyControl class.

	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.

Internal Implementation

Internal implementation of the SFZSoftKeyControl::HandleBoundOptimize function is as follows:

enum {
     ARROW_BASE_LENGTH   = 6,
     ARROW_HEIGHT        = 3,
     BASE_SPACE          = 2,
     RING_MARGIN         = 3,
     RING_SIZE           = 1
};

enum StyleEnum {
     STANDARD                            = 0,
     EXTENSION,
     DEFAULT_STYLE                       = STANDARD
};

/*protected virtual */Void SFZSoftKeyControl::HandleBoundOptimize(SFXRectanglePtr rectangle) const
{
    BoundImpl(rectangle);
    return;
}// SFZSoftKeyControl::HandleBoundOptimize //

/*private */Void SFZSoftKeyControl::BoundImpl(SFXRectanglePtr rectangle) const
{
    SFXDevice                           device;
    SInt16                              h;
    SInt16                              H;

    rectangle->Set(SFXGrid::ZeroInstance(), device.GetScreenSize());
    h = SFXGraphics::GetFontHeight(_font);
    h += RING_MARGIN * 2;
    if (_style == STANDARD) {
        H = h + (_size.baseSpace * 2);
    }
    else {
        H = h * 2 + (_size.baseSpace * 3);
    }
    rectangle->SetTop(rectangle->GetBottom() - H);
    return;
}// SFZSoftKeyControl::BoundImpl //

Reference

SFZSoftKeyControl::HandleBoundRequest | SFYResponder::GetSuitableBound | SFXEvent | Region Event[SFEVT_RESPONDER_BOUND] | Handler for the Region Event[XANDLER_DECLARE_VOIDBOUND]

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 SFZSoftKeyControl::HandleBoundReal function is as follows:

enum SoftkeyEnum {
    SELECT,
    SOFTKEY_1,
    SOFTKEY_2,
    STANDARD_LIMIT,
    SOFTKEY_3 = STANDARD_LIMIT,
    SOFTKEY_4,
    EXTENSION_LIMIT,
    UP = EXTENSION_LIMIT,
    DOWN,
    LEFT,
    RIGHT,
    SOFTKEY_LIMIT
};

enum StyleEnum {
    STANDARD                            = 0,
    EXTENSION,
    DEFAULT_STYLE                       = STANDARD
};

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

/*private */Void SFZSoftKeyControl::BoundImpl(SFXRectanglePtr rectangle) const
{
    SFXDevice                           device;
    SInt16                              h;
    SInt16                              H;

    rectangle->Set(SFXGrid::ZeroInstance(), device.GetScreenSize());
    h = SFXGraphics::GetFontHeight(_font);
    h += RING_MARGIN * 2;
    if (_style == STANDARD) {
        H = h + (_size.baseSpace * 2);
    }
    else {
        H = h * 2 + (_size.baseSpace * 3);
    }
    rectangle->SetTop(rectangle->GetBottom() - H);
    return;
}// SFZSoftKeyControl::BoundImpl //

Reference

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

Description

This function will be called when the region event [SFXEvent(SFEVT_RESPONDER_BOUND, SFP16_BOUND_REQUEST, rectangle)] is received.

This function calculates the suitable rectangle size and origin position of this responder.

In the default implementation, the suitable rectangle size in the device screen is stored into the size element of the rectangle argument as a result of calculation depending on its style.

CAUTION

Implementation of this function is the same with that of the SFZSoftKeyControl::HandleBoundOptimize function. The rectangular region will be ignored if specified in the "rectangle" argument and the suitable size will be calculated from the full screen region of the mobile phone. In general, the HandleBoundRequest() function will return only the suitable rectangle size, but the SFZSoftKeyControl::HandleBoundRequest function will return not only the size but also the origin position of the suitable rectangular region via the "rectangle" argument which will be passed as the P32 parameter of the region event. Therefore, you don't have to set the origin position after calling the SFYResponder::GetSuitableBound function regarding to the SFZSoftKeyControl class.

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)

Internal Implementation

Internal implementation of the SFZSoftKeyControl::HandleBoundRequest function is as follows:

enum {
     ARROW_BASE_LENGTH   = 6,
     ARROW_HEIGHT        = 3,
     BASE_SPACE          = 2,
     RING_MARGIN         = 3,
     RING_SIZE           = 1
};

enum StyleEnum {
     STANDARD                            = 0,
     EXTENSION,
     DEFAULT_STYLE                       = STANDARD
};

/*protected virtual */Void SFZSoftKeyControl::HandleBoundRequest(SFXRectanglePtr rectangle) const
{
    BoundImpl(rectangle);
    return;
}// SFZSoftKeyControl::HandleBoundRequest //

/*private */Void SFZSoftKeyControl::BoundImpl(SFXRectanglePtr rectangle) const
{
    SFXDevice                           device;
    SInt16                              h;
    SInt16                              H;

    rectangle->Set(SFXGrid::ZeroInstance(), device.GetScreenSize());
    h = SFXGraphics::GetFontHeight(_font);
    h += RING_MARGIN * 2;
    if (_style == STANDARD) {
        H = h + (_size.baseSpace * 2);
    }
    else {
        H = h * 2 + (_size.baseSpace * 3);
    }
    rectangle->SetTop(rectangle->GetBottom() - H);
    return;
}// SFZSoftKeyControl::BoundImpl //

Reference

SFZSoftKeyControl::HandleBoundOptimize | SFYResponder::GetSuitableBound | SFXEvent | Real Region Region Event[SFEVT_RESPONDER_BOUND] | Handler for the Region Event[XANDLER_DECLARE_VOIDBOUND]

Description

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

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

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

	Sending the (SFEVT_RESPONDER_BOUND, SFP16_BOUND_VIRTUAL) event
	The (SFEVT_RESPONDER_BOUND, SFP16_BOUND_VIRTUAL) event will occur when the virtual region is changed by calling the SFYResponder::SetRealBound or SFYResponder::SetVirtualBound function.

Another method when the virtual region is changed

Other than overriding this virtual function, it is possible to define and implement the handler for region event[XANDLER_DECLARE_VOIDBOUND], and register it into the responder. In the processing when the virtual region is updated, this virtual function is executed first, and next the handlers for 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 region event can be omitted.

Internal Implementation

Internal implementation of the SFZSoftKeyControl::HandleBoundVirtual function is as follows:

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

Reference

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

Description

This function will be called when the (SFEVT_RESPONDER_RENDER, SFP16_RENDER_REQUEST) event is received.

In case you want to perform your own drawing of this responder, override this function.

The default implementation is to draw this responder.

The method to darw a responder

In addition to overriding this virtual function, it is possible to define and implement the handler for drawing event(drawing handler)[XANDLER_DECLARE_VOIDRENDER], and register it into the responder. Then, the overridden virtual function will be called first, and next the drawing handlers registered into the responder will be booted up in the registered order. In almost all cases, the method to override this function is used to draw the responder since there is no need to declare and register the drawing handler.

Procedure of drawing a responder

The drawing handler will be booted up when the drawing event(SFEVT_RESPONDER_RENDER) occurs. And then the drawing handler draw the responder actually. The drawing event will be sent to only the responders including the region to be redrawn out of the redraw regions registered into the renderer using the SFYResponder::InvokeBackward function after the SFYResponder::Render function boots up the renderer. Here, the SFYResponder::Render function will be called at the following situations: At the end of the event loop At the applet start / resume or the end of a highest priority event handler In the callback, which is outside the event loop. If calling the SFYResponder::Render function with specifying "true" as an argument, the drawing event will be sent to all the responders to be actually displayed on the screen which are located below the responder in the responder tree, regardless of the registration of redraw region.

Internal Implementation

Internal implementation of the SFZSoftKeyControl::HandleRenderRequest function is as follows:

enum SoftkeyEnum {
    SELECT,
    SOFTKEY_1,
    SOFTKEY_2,
    STANDARD_LIMIT,
    SOFTKEY_3 = STANDARD_LIMIT,
    SOFTKEY_4,
    EXTENSION_LIMIT,
    UP = EXTENSION_LIMIT,
    DOWN,
    LEFT,
    RIGHT,
    SOFTKEY_LIMIT
};

enum StyleEnum {
    STANDARD                            = 0,
    EXTENSION,
    DEFAULT_STYLE                       = STANDARD
};


/*protected virtual */Void SFZSoftKeyControl::HandleRenderRequest(SFXGraphicsPtr graphics) const
{
    UInt32                              i;
    SFCError                            error(SFERR_NO_ERROR);

    if (!IsCacheValid()) {
        error = RebuildCache();
    }
    if (error == SFERR_NO_ERROR) {
        if (GetStyle() == STANDARD) {
            for (i = 0; i < STANDARD_LIMIT; ++i) {
         SoftkeyEnumConst            si(static_cast<SoftkeyEnum>(i));

                if (GetCacheLabelEnable(si)) {
             SFXRectangle temp = DrawRectangularFrame(graphics, GetLabelRectangle(si), GetCacheBackColor(si), GetCacheFrameColor(si));
                    DrawImage(graphics, temp, GetCacheImage(si));
                    DrawText(graphics, temp, GetCacheText(si), GetCacheForeColor(si));
                }
            }
        }
        else {
            for (i = 0; i < EXTENSION_LIMIT; ++i) {
         SoftkeyEnumConst            si(static_cast<SoftkeyEnum>(i));

                if (GetCacheLabelEnable(si)) {
             SFXRectangle temp = DrawRectangularFrame(graphics, GetLabelRectangle(si), GetCacheBackColor(si), GetCacheFrameColor(si));
                    DrawImage(graphics, temp, GetCacheImage(si));
                    DrawText(graphics, temp, GetCacheText(si), GetCacheForeColor(si));
                }
            }
            for (; i < SOFTKEY_LIMIT; ++i) {
         SoftkeyEnumConst            si(static_cast<SoftkeyEnum>(i));

                if (GetCacheLabelEnable(si)) {
                    graphics->FillTriangle(
                        InscribedTriangle(GetLabelRectangle(si), si),
                        GetCachePress(si) ? GetCacheForeColor(si) : GetCacheBackColor(si)
                    );
                }
            }
        }
    }
    return;
}// SFZSoftKeyControl::HandleRenderRequest //

/*private */Void SFZSoftKeyControl::DrawText(SFXGraphicsPtr graphics, SFXRectangleConstRef rectangle, SFXWideStringConstRef text, SFXRGBColorConstRef fore) const
{
    SFXRectangle                        rcText(rectangle);

    graphics->SetFont(_font);
    rcText.AddY(graphics->GetFontDescent() / 2);
    graphics->DrawSingleText(text, rcText, fore);
    return;
}// SFZSoftKeyControl::DrawText //

Reference

SFZSoftKeyControl::DrawImage | SFZSoftKeyControl::DrawRectangularFrame | SFYResponder::Invalidate | SFYResponder::Render | SFYResponder::InvokeBackward | Drawing Event[SFEVT_RESPONDER_RENDER] | Handler for the Drawing Event[XANDLER_DECLARE_VOIDRENDER] | Rendering | Event Loop | Responder Tree

Description

This function will be called immediately after the specified SoftKey menu is created.

In case you want to perform your own processing immediately after a SoftKey menu is created, override this virtual function.

The default implementation is to return "SFERR_NO_ERROR".

Internal Implementation

Internal implementation of the SFZSoftKeyControl::HandleSoftMenuCreate function is as follows:

/*protected virtual */SFCError SFZSoftKeyControl::HandleSoftMenuCreate(UInt32 key)
{
    unused(key);
    return SFERR_NO_ERROR;
}// SFZSoftKeyControl::HandleSoftMenuCreate //

Reference

SFZSoftKeyControl::CreateMenu | SFZSoftKeyControl::HandleSoftMenuDestroy

Description

This function will be called just before the specified SoftKey menu is destroyed.

In case you want to perform your own processing just before a SoftKey menu is destroyed, override this virtual function.

The default implementation is to do nothing.

Internal Implementation

Internal implementation of the SFZSoftKeyControl::HandleSoftMenuDestroy function is as follows:

/*protected virtual */Void SFZSoftKeyControl::HandleSoftMenuDestroy(UInt32 key)
{
    unused(key);
    return;
}// SFZSoftKeyControl::HandleSoftMenuDestroy //

Reference

SFZSoftKeyControl::DestroyMenu | SFZSoftKeyControl::HandleSoftMenuCreate

Description

This function will be called when the style event is revceived.

The style event will occur if one of the following items is changed:

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

The default implementation is to calculate the position and the size of the label and the real region of this SoftKey control.

Internal Implementation

Internal implementation of the SFZSoftKeyControl::HandleStyle function is as follows:

enum {
     ARROW_BASE_LENGTH   = 6,
     ARROW_HEIGHT        = 3,
     BASE_SPACE          = 2,
     RING_MARGIN         = 3,
     RING_SIZE           = 1
};

enum StyleEnum {
     STANDARD                            = 0,
     EXTENSION,
     DEFAULT_STYLE                       = STANDARD
};

/*protected virtual */Void SFZSoftKeyControl::HandleStyle(UInt16 style)
{
    SFXRectangle                            rectangle;

    unused(style);
    BoundImpl(&rectangle);
    SetRealBound(rectangle);
    return;
}// SFZSoftKeyControl::HandleStyle //

/*private */Void SFZSoftKeyControl::BoundImpl(SFXRectanglePtr rectangle) const
{
    SFXDevice                           device;
    SInt16                              h;
    SInt16                              H;

    rectangle->Set(SFXGrid::ZeroInstance(), device.GetScreenSize());
    h = SFXGraphics::GetFontHeight(_font);
    h += RING_MARGIN * 2;
    if (_style == STANDARD) {
        H = h + (_size.baseSpace * 2);
    }
    else {
        H = h * 2 + (_size.baseSpace * 3);
    }
    rectangle->SetTop(rectangle->GetBottom() - H);
    return;
}// SFZSoftKeyControl::BoundImpl //

Reference

SFZSoftKeyControl::SetStyle | SFZSoftKeyControl::SetArrowBaseLength | SFZSoftKeyControl::SetArrowHeight | SFZSoftKeyControl::SetBaseSpace | SFZSoftKeyControl::SetFont | SFXEvent | Style Event[SFEVT_RESPONDER_STYLE]

Description

In the SoftKey control, the content of the active menu is saved in the cashe of this SoftKey control.

This function invalidates this cashe.

In overriding the drawing function, never forget to check whether or not the cashe is valid by calling the SFZSoftKeyControl::IsCacheValid function.

In this case, you have to rebuild the cashe by calling the SFZSoftKeyControl::RebuildCache function if the cashe is invalid.

Reference

SFZSoftKeyControl::IsCacheValid | SFZSoftKeyControl::RebuildCache

Return value

Description

In the SoftKey control, the content of the active menu is saved in the cashe of this SoftKey control.

This function checks whether or not the cashe is valid.

In overriding the drawing function, you have to rebuild the cashe by calling the SFZSoftKeyControl::RebuildCache function if the cashe is invalid.

Example

Void CustomSoftKeyControl::HandleRenderRequest(SFXGraphicsPtr graphics) const
{
    SFCError error(SFERR_NO_ERROR);

    // if cashe is invalid
    if (!IsCacheValid()) {

        // rebuild cashe
        error = RebuildCache();
    }
    if (error == SFERR_NO_ERROR) {
        // drawing processing of your own
        // ...
    }
}

Reference

SFZSoftKeyControl::InvalidateCache | SFZSoftKeyControl::RebuildCache

Argument

Return value

Description

This function creates a new instance of this responder class.

If succeeds, a not null pointer will be returned, and the "exception" argument is SFERR_NO_ERROR. If fails such as insufficient memory, a null pointer will be returned, and the "exception" argument holds the error value.

Example

The code to create a new instance of this responder class is as follows:

SFZSoftKeyControlSmp _softkey;
SFCError error;

if ((_softkey = SFZSoftKeyControl::NewInstance(&error)) != null) {

    ...
}

Description

In the SoftKey control, the content of the active menu is saved in the cashe of this SoftKey control.

This function rebuilds this cashe.

In overriding the drawing function, never forget to check whether or not the cashe is valid by calling the SFZSoftKeyControl::IsCacheValid function.

In this case, you have to rebuild the cashe by calling this function if the cashe is invalid.

Example

Void CustomSoftKeyControl::HandleRenderRequest(SFXGraphicsPtr graphics) const
{
    SFCError error(SFERR_NO_ERROR);

    // if cashe is invalid
    if (!IsCacheValid()) {

        // rebuild cashe
        error = RebuildCache();
    }
    if (error == SFERR_NO_ERROR) {
        // drawing processing of your own
        // ...
    }
}

Reference

SFZSoftKeyControl::InvalidateCache | SFZSoftKeyControl::IsCacheValid

Return value

Description

This function registers the specified color as background color for label into this SoftKey control, which is associated with the specified color key.

The background of label or the triangle when the cursor key is not pressed is filled in this color.

The color whose key value is "INVALID_KEY(= UINT32_MAXIMUM)" cannot be made.

Once the background color is registered, it will remain in the heap until the SFZSoftKeyControl::UnregisterColor function or the destructor is called.

If the specified key already exists, only the specified background color will be overridden.

Background color for the color key "0"

By default, the background color of SFXRGBColor(0x77, 0x77, 0x77, 0x00)[gray color] has been registered for the color key "0". If no background color is set to the SoftKey menu with the SFZSoftKeyControl::SetColorKey function, this background color will be referred to. * This background color is referred to by the default menu of the menu key "0". Default menu For more details on the default menu of the menu key "0", see the description of SFZSoftKeyControl.

	3-Color
	The frame color, the foreground color, and the background color are grouped together into 3-Color using the same unique color key at the registration. Conversely, the color key groups the frame color, the foreground color, and the background color into 3-Color.

Reference

SFZSoftKeyControl::UnregisterColor | SFZSoftKeyControl::RegisterFrameColor | SFZSoftKeyControl::RegisterForeColor | SFZSoftKeyControl::RegisterText | SFZSoftKeyControl::RegisterImage | SFZSoftKeyControl::SetColorKey

Return value

Description

This function registers the specified color as foreground color for label into this SoftKey control, which is associated with the specified color key.

The label text or the triangle when the cursor key is pressed is drawn in this color.

The color whose key value is "INVALID_KEY(= UINT32_MAXIMUM)" cannot be made.

Once the foreground color is registered, it will remain in the heap until the SFZSoftKeyControl::UnregisterColor function or the destructor is called.

If the specified key already exists, only the specified foreground color will be overridden.

Foreground color for the color key "0"

By default, the foreground color of SFXRGBColor(0xFF, 0xFF, 0xFF, 0x00)[white color] has been registered for the color key "0". If no foreground color is set to the SoftKey menu with the SFZSoftKeyControl::SetColorKey function, this foreground color will be referred to. * This foreground color is referred to by the default menu of the menu key "0". Default menu For more details on the default menu of the menu key "0", see the description of SFZSoftKeyControl.

	3-Color
	The frame color, the foreground color, and the background color are grouped together into 3-Color using the same unique color key at the registration. Conversely, the color key groups the frame color, the foreground color, and the background color into 3-Color.

Reference

SFZSoftKeyControl::UnregisterColor | SFZSoftKeyControl::RegisterFrameColor | SFZSoftKeyControl::RegisterBackColor | SFZSoftKeyControl::RegisterText | SFZSoftKeyControl::RegisterImage | SFZSoftKeyControl::SetColorKey

Return value

Description

This function registers the specified color as frame color for label into this SoftKey control, which is associated with the specified color key.

The color whose key value is "INVALID_KEY(= UINT32_MAXIMUM)" cannot be made.

Once the frame color is registered, it will remain in the heap until the SFZSoftKeyControl::UnregisterColor function or the destructor is called.

If the specified key already exists, only the specified frame color will be overridden.

Frame color for the color key "0"

By default, the frame color of SFXRGBColor(0xDD, 0xDD, 0xDD, 0xDD)[light gray color] has been registered for the color key "0". If no frame color is set to the SoftKey menu with the SFZSoftKeyControl::SetColorKey function, this frame color will be referred to. * This frame color is referred to by the default menu of the menu key "0". Default menu For more details on the default menu of the menu key "0", see the description of SFZSoftKeyControl.

	3-Color
	The frame color, the foreground color, and the background color are grouped together into 3-Color using the same unique color key at the registration. Conversely, the color key groups the frame color, the foreground color, and the background color into 3-Color.

Reference

SFZSoftKeyControl::UnregisterColor | SFZSoftKeyControl::RegisterForeColor | SFZSoftKeyControl::RegisterBackColor | SFZSoftKeyControl::RegisterText | SFZSoftKeyControl::RegisterImage | SFZSoftKeyControl::SetColorKey

Return value

Description

This function registers the specified image as label image into this SoftKey control, which is associated with the specified image key.

The image whose key value is "INVALID_KEY(= UINT32_MAXIMUM)" cannot be made.

The image is set directly in the argument, or read from the resource file.

Once the image is registered, it will remain in the heap until the SFZSoftKeyControl::UnregisterImage function or the destructor is called.

If the specified key already exists, the existing image referred to by the key will be released and replaced by the specified image.

Image for the image key "0"

By default, the image of SFBImageSmp::EmptyInstance() has been registered for the image key "0". If no image key is set to the SoftKey menu with the SFZSoftKeyControl::SetImageKey function, this text will be referred to. * This image is referred to by the default menu of the menu key "0". Default menu For more details on the default menu of the menu key "0", see the description of SFZSoftKeyControl.

Reference

SFZSoftKeyControl::GetImage | SFZSoftKeyControl::RegisterImageRange | SFZSoftKeyControl::UnregisterImage | SFZSoftKeyControl::RegisterText | SFZSoftKeyControl::RegisterFrameColor | SFZSoftKeyControl::RegisterForeColor | SFZSoftKeyControl::RegisterBackColor | SFZSoftKeyControl::SetImageKey | SFXBrewPointer::EmptyInstance | SFBImage

Return value

Description

This function registers the images within the specified range as label images into this SoftKey control, which are associated with the image keys starting from the specified value.

The rage of the image key [key , key + (end - start)] corresponds to that of resource id [start, end].

It may be easy to equalize the value of key with that of start in the above statement.

Once the image is registered, it will remain in the heap until the SFZSoftKeyControl::UnregisterImage function or the destructor is called.

If the specified key already exists, the existing image referred to by the key will be released and replaced by the specified image.

Example

The below is the code to register the images in the range of resource id [IDI_START, IDI_END] of the resource file ("resource.bar"), which are associated with the image keys starting from KEY_IMAGE_ORIGIN.

// suppose the SoftKey control instance has already been created
SFZSoftKeyControlSmp softkey = USRApplication::GetSoftKey();
softkey->RegisterImageRange(KEY_IMAGE_ORIGIN, SFXPath("resource.bar"), IDI_START, IDI_END);

Reference

SFZSoftKeyControl::RegisterImage | SFZSoftKeyControl::UnregisterImage | SFZSoftKeyControl::RegisterTextRange | SFZSoftKeyControl::SetImageKey

Return value

Description

This function registers the specified image as label text into this SoftKey control, which is associated with the specified text key.

The text whose key value is "INVALID_KEY(= UINT32_MAXIMUM)" cannot be made.

The text is set directly in the argument, or read from the resource file.

Once the text is registered, it will remain in the heap until the SFZSoftKeyControl::UnregisterText function or the destructor is called.

If the specified key already exists, the existing text referred to by the key will be released and replaced by the specified text.

	Text for the text key "0"
	By default, the text of SFXWideString::EmptyInstance() has been registered for the text key "0". If no text key is set to the SoftKey menu with the SFZSoftKeyControl::SetTextKey function, this text will be referred to. * This text is referred to by the default menu of the menu key "0". Default menu For more details on the default menu of the menu key "0", see the description of SFZSoftKeyControl.

Reference

SFZSoftKeyControl::GetText | SFZSoftKeyControl::RegisterTextRange | SFZSoftKeyControl::UnregisterText | SFZSoftKeyControl::RegisterImage | SFZSoftKeyControl::RegisterFrameColor | SFZSoftKeyControl::RegisterForeColor | SFZSoftKeyControl::RegisterBackColor | SFZSoftKeyControl::SetTextKey | SFXWideString::EmptyInstance | SFXWideString

Return value

Description

This function registers the texts within the specified range as label texts of a a SoftKey menu into this SoftKey control, which are associated with the text keys starting from the specified value.

The rage of the text key [key , key + (end - start)] corresponds to that of resource id [start, end].

It may be easy to equalize the value of key with that of start in the above statement.

Once the text is registered, it will remain in the heap until the SFZSoftKeyControl::UnregisterText function or the destructor is called.

If the specified key already exists, the existing text referred to by the key will be released and replaced by the specified text.

Example

The below is the code to register the texts in the range of resource id [IDI_START, IDI_END] of the resource file ("resource.bar"), which are associated with the text keys starting from KEY_IMAGE_ORIGIN.

// suppose the SoftKey control instance has already been created
SFZSoftKeyControlSmp softkey = USRApplication::GetSoftKey();
softkey->RegisterTextRange(KEY_TEXT_ORIGIN, SFXPath("resource.bar"), IDS_START, IDS_END);

Reference

SFZSoftKeyControl::RegisterText | SFZSoftKeyControl::UnregisterText | SFZSoftKeyControl::RegisterImageRange | SFZSoftKeyControl::SetTextKey

Description

This function sets the length of the base of the triangle label in the SoftKey menu with the "extention" style to the specified value. [pixels]

If the length of the base of the triangle is changed, the style event of SFXEvent(SFEVT_RESPONDER_STYLE, SFP16_STYLE_ALIGN, 0) will occur.

Default: 6 pixels.

	Length of the base of the triangle label in the SoftKey menu
	It represents the width regarding to the up or down triangle, and the height regarding to the left or right triangle. These values are same in the SoftKey menu.

Reference

SFZSoftKeyControl::GetArrowBaseLength | SFZSoftKeyControl::SetArrowHeight | SFZSoftKeyControl::SetStyle | SFXEvent | Style Event[SFEVT_RESPONDER_STYLE]

Description

This function sets the height of the triangle label in the SoftKey menu with the "extention" style to the specified value. [pixels]

If the height of the base of the triangle is changed, the style event of SFXEvent(SFEVT_RESPONDER_STYLE, SFP16_STYLE_ALIGN, 0) will occur.

Default: 3 pixels.

	Height of the triangle label in the SoftKey menu with the "extention" style
	It represents the height regarding to the up or down triangle, and the width regarding to the left or right triangle. These values are same in the SoftKey menu.

Reference

SFZSoftKeyControl::GetArrowHeight | SFZSoftKeyControl::SetArrowBaseLength | SFZSoftKeyControl::SetStyle | SFXEvent | Style Event[SFEVT_RESPONDER_STYLE]

Description

This function sets the space between the label and the border of this SoftKey control to the specified value. [pixels]

If the height of the base space is changed, the style event of SFXEvent(SFEVT_RESPONDER_STYLE, SFP16_STYLE_ALIGN, 0) will occur.

Default: 2 pixels

	Note
	The value of the space between the labels is same with this return value.

Reference

SFZSoftKeyControl::GetBaseSpace | SFXEvent | Style Event[SFEVT_RESPONDER_STYLE]

Return value

Description

This function sets a specified label of the specified SoftKey menu of this SoftKey control to the specified color key.

	Tip
	The color keys can be set at a time using an array.

Default color key

If the color key of a SoftKey menu of this SoftKey control is not set with the SFZSoftKeyControl::SetColorKey function, the color key "0" will be referred to as the default color key. The frame, foreground, and background colors of the color key "0" are initialized as follows: Frame color: SFXRGBColor(0xDD, 0xDD, 0xDD, 0x00)[light gray color] Foreground color: SFXRGBColor(0xFF, 0xFF, 0xFF, 0x00)[white color] Background color: SFXRGBColor(0x77, 0x77, 0x77, 0x00)[gray color] * In the default menu of the menu key "0", the color key "0" will be referred to by default. Default menu For more details on the default menu of the menu key "0", see the description of SFZSoftKeyControl.

Reference

SFZSoftKeyControl::GetColorKey SFZSoftKeyControl::RegisterForeColor | SFZSoftKeyControl::RegisterBackColor | SFZSoftKeyControl::RegisterFrameColor

Description

This function sets the default background color for label of this SoftKey control to the specified value, which will be used when the invalid color key is specified.

The background of label or the triangle when the cursor key is not pressed is filled in this color by default.

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

	Note
	The background color of the color key "0", which is referred to by the default menu of the menu key "0", is initialized with SFXRGBColor(0x77, 0x77, 0x77, 0x00)[gray color].

Reference

SFZSoftKeyControl::GetDefaultBackColor

Description

This function sets the default foreground color for label of this SoftKey control to the specified value, which will be used when the invalid color key is specified.

The label text or the triangle when the cursor key is pressed is drawn in this color by default.

Default: SFXRGBColor(0xFF, 0xFF, 0xFF, 0x00)[white color]

	Note
	The foreground color of the color key "0", which is referred to by the default menu of the menu key "0", is initialized with SFXRGBColor(0xFF, 0xFF, 0xFF, 0x00)[white color].

Reference

SFZSoftKeyControl::GetDefaultForeColor

Description

This function sets the default frame color for label of this SoftKey control to the specified value, which will be used when the invalid color key is specified.

Default: SFXRGBColor(0xDD, 0xDD, 0xDD, 0xDD)[light gray color]

	Note
	The frame color of the color key "0", which is referred to by the default menu of the menu key "0", is initialized with SFXRGBColor(0xDD, 0xDD, 0xDD, 0xDD)[light gray color].

Reference

SFZSoftKeyControl::GetDefaultFrameColor

Return value

Description

This function sets the enable flag of the specified label of the specified menu of this SoftKey control to the specified value.

When the enable flag of the label for a cursor key is set to "true", if the key-press event of the cursor key occurs, the color of corresponding triangle will change from the background color to the foreground color.

Default: All ebable flags will be set to "true"(enable) immediately when the SoftKey menu is created with the SFZSoftKeyControl::CreateMenu function.

	Undisplaying a label region
	The enable flag of each label in the SoftKey menu is set to "true" by default. Therefore the label region will be displayed as it is. To undisplay a label region, set its enable flag to "false" using the SFZSoftKeyControl::SetEnable function.

	Note
	The enable flags of the labels can be set at a time using an array.

Reference

SFZSoftKeyControl::GetEnable | SFZSoftKeyControl::CreateMenu

Description

This function sets the font of the label text of this SoftKey control to the specified value.

If the font is changed, the style event of SFXEvent(SFEVT_RESPONDER_STYLE, SFP16_STYLE_FONT, 0) will occur.

Default: AEE_FONT_NORMAL

Reference

SFZSoftKeyControl::GetFont | SFXEvent | Style Event[SFEVT_RESPONDER_STYLE]

Return value

Description

This function sets the specified label of the specified SoftKey menu of this SoftKey control to the specified image key.

	Tip
	The image keys can be set at a time using an array.

Default image key

If the image key of a SoftKey menu of this SoftKey control is not set with the SFZSoftKeyControl::SetImageKey function, the image key "0" will be referred to as the default image key. The image of the image key "0" is initialized with SFBImageSmp::EmptyInstance(). * In the default menu of the menu key "0", the image key "0" will be referred to by default. Default menu For more details on the default menu of the menu key "0", see the description of SFZSoftKeyControl.

Reference

SFZSoftKeyControl::GetImageKey

Description

This function sets the rectangular region of the specified label of this SoftKey control to the specified value.

	Note
	This function is called to recalculate the rectangular region of the label in such a case that the region of this control is changed.

Example

// handler called when the real region is changed
Void CustomSoftKeyControl::HandleBoundReal(Void)
{
    SFXRectangle local(GetLocalBound());
    SFXRectangle temp;
    SInt16 W(local.GetWidth());
    SInt16 H(local.GetHeight());
    SInt16 w, h;

    // in case of standard style
    if (GetStyle() == STANDARD) {
        w = (W - GetBaseSpace() * 4) / 3;
        h = (H - GetBaseSpace() * 2);
        temp = SFXRectangle(GetBaseSpace(), GetBaseSpace(), w, h);
        SetLabelRectangle(SOFTKEY_1, temp);
        SetLabelRectangle(SELECT, temp.Offset(w + GetBaseSpace(), 0));
        SetLabelRectangle(SOFTKEY_2, temp.Offset(w + GetBaseSpace(), 0));
    }
    // in case of extension style
    else {
        // ...
    }
    return;
}

Reference

SFZSoftKeyControl::SoftkeyEnum | SFZSoftKeyControl::GetLabelRectangle

Description

This function sets the menu style of this SoftKey control to the specified value.

The SoftKey menu with 3 labels called "standard style" or the one with 9 labels called "extension style" is available.

If the menu style is changed, the style event of SFXEvent(SFEVT_RESPONDER_STYLE, SFP16_STYLE_ALIGN, 0) will occur.

Default: SFZSoftKeyControl::DEFAULT_STYLE (standard style)

The style can be dynamically changed during the runtime of an applet.

Standard style:

Extension style:

Reference

SFZSoftKeyControl::GetStyle | SFZSoftKeyControl::StyleEnum | SFXEvent | Style Event[SFEVT_RESPONDER_STYLE]

Return value

Description

This function sets the specified label of the specified SoftKey menu of this SoftKey control to the specified text key.

	Tip
	The text keys can be set at a time using an array.

Default text key

If the text key of a SoftKey menu of this SoftKey control is not set with the SFZSoftKeyControl::SetTextKey function, the text key "0" will be referred to as the default text key. The text of the text key "0" is initialized with SFXWideString::EmptyInstance(). * In the default menu of the menu key "0", the text key "0" will be referred to by default. Default menu For more details on the default menu of the menu key "0", see the description of SFZSoftKeyControl.

Reference

SFZSoftKeyControl::GetTextKey | SFZSoftKeyControl::RegisterText | SFZSoftKeyControl::RegisterTextRange

Description

This function unbinds the specified responder with the corresponding SoftKey menu.

	Note
	This function will be automatically called when the state of the responder bound using the SFZSoftKeyControl::Bind function becomes "invalid" or its destructor(SFZSoftKeyControl::~SFZSoftKeyControl) is called.

Reference

SFZSoftKeyControl::Bind | SFZSoftKeyControl::~SFZSoftKeyControl | State

Description

This function unregisters the 3-Color(frame color, foreground color, and background color) associated with the specified color key from this SoftKey control.

At this time, the 3-Color(frame color, foreground color, and background color) will be also released.

If the not existing color key is specified, nothing will happen.

If a SoftKey menu refers to the unregistered color key, the corresponding label will be drawn in the default color set with SFZSoftKeyControl::SetDefaultBackColor / SFZSoftKeyControl::SetDefaultForeColor / SFZSoftKeyControl::SetDefaultFrameColor functions.

Reference

SFZSoftKeyControl::RegisterFrameColor | SFZSoftKeyControl::RegisterForeColor | SFZSoftKeyControl::RegisterBackColor | SFZSoftKeyControl::SetDefaultBackColor | SFZSoftKeyControl::SetDefaultForeColor | SFZSoftKeyControl::SetDefaultFrameColor

Description

This function unregisters the label image associated with the specified image key from this SoftKey control.

At this time, the label image will be also released.

If the not existing image key is specified, nothing will happen.

If a SoftKey menu refers to the unregistered image key, the corresponding label image will not be drawn.

Reference

SFZSoftKeyControl::RegisterImage

Description

This function unregisters the label text associated with the specified text key from this SoftKey control.

At this time, the label text will be also released.

If the not existing text key is specified, nothing will happen.

If a SoftKey menu refers to the unregistered text key, the corresponding label text will not be drawn.

Reference

SFZSoftKeyControl::RegisterText

Reference

SFYResponder::GetType | SFYResponder::SetType |

Description

The menu whose key value is DEFAULT_KEY (= 0) is called "default menu".

After creating the SoftKey menu, all the element keys(text, image, 3 colors) is set to DEFAULT_KEY.

INVALID_KEY cannot be registered as a menu key nor an element key.

Reference

SFZSoftKeyControl::CreateMenu

Description

These constants are used as label number.