Inheritance diagram

Collaboration diagram

Description

SFYMenu is the abstract base class to define and implement a user-defined container.

For instance, a menu such as SFZTextMenu, SFZGridMenu or SFZFlexListMenu is implemented by inheriting from SFYMenu.

In SFYMenu, there are functions to close itself after the specified period, implement some default handlers(virtual functions), and handle key events of menu operation, ESCAPE, and scroll keys.

The selection key is set with the SFYMenu::SetSelectUpKey / SFYMenu::SetSelectDownKey / SFYMenu::SetSelectRightKey / SFYMenu::SetSelectLeftKey functions. By default, selection keys are set to the UP key, the DOWN key, the RIGHT key, the LEFT key respectively.

In the default implementation, the abstract menu[SFYMenu] will receive the following result events[SFEVT_RESPONDER_RESULT].

The developer can register handlers for these events.

If no handler is registered, the default handler will be booted up when one of the above result events is received. The default handler only closes the menu.

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

The ESCAPE key is set with the SFYMenu::SetEscapeKey function. By default, the ESCAPE key is set to the CLEAR key.

	Note
	The timer processing callback scheduled with the SFYMenu::ScheduleTimer function will be canceled automatically when the operation key of the menu or the ESCAPE key is pressed.

Reference: Result Event[SFEVT_RESPONDER_RESULT] | SFYMenu::HandleOperateKey | SFYMenu::HandleEscapeKey | SFYMenu::HandleSelectUpKey | SFYMenu::HandleSelectDownKey | SFYMenu::HandleSelectRightKey | SFYMenu::HandleSelectLeftKey

The handlers(virtual functions) below for key events on the menu operation, ESCAPE, and selection keys, region event[SFEVT_RESPONDER_BOUND], drawing event[SFEVT_RESPONDER_RENDER] are registered into SFYMenu.

In a menu inheriting from SFYMenu, the following handlers(virtual functions) will be booted up first when the event is received.

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

NOTE

*1. Execute SFYResponder::InvokeForward(SFXEvent(SFEVT_RESPONDER_RESULT, SFP16_RESULT_CANCEL, 0), false). Just before the SFYMenu::HandleOperateKey function is called, the timer processing callback scheduled with the SFYMenu::ScheduleTimer function will be canceled internally. *2. Execute SFYResponder::InvokeForward(SFXEvent(SFEVT_RESPONDER_RESULT, SFP16_RESULT_ESCAPE, 0), false). Just before the SFYMenu::HandleEscapeKey function is called, the timer processing callback scheduled with the SFYMenu::ScheduleTimer function will be canceled internally. *3. Execute SFYResponder::SetVirtualBound(SFXRectangle(SFXGrid::ZeroInstance(), GetRealBound().GetSize())).

The following is the code necessary to make a user-defined menu.

SFMTYPEDEFRESPONDER(USRMenu)
class USRMenu: public SFYMenu {
    SFMSEALRESPONDER(USRMenu)
    SFMRESPONDERINSTANTIATETHREE(USRMenu, SFYMenu, 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', 'M', 'N', 'U')
    };
    SFMTYPEDEFTYPE(CodeEnum)

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

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

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

        // set the responder type
 SetType(CODE_TYPE);

        // here describe the initialization
    }
}

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

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

Void USRMenu::HandleOperateKey(Void)
{
    // here describe processing necessary when the operation key is pressed
    // in general, send event as below
    // "_select" variable represents number of selected item
    InvokeForward(SFXEvent(SFEVT_RESPONDER_RESULT, SFP16_RESULT_OK, _select), false);
    return;
}

Void USRMenu::HandleSelectUpKey(Void)
{
    // here describe processing necessary when UP key is pressed
    // example: move selected item up by one
    return;
}

Void USRMenu::HandleSelectDownKey(Void)
{
    // here describe processing necessary when DOWN key is pressed
    // example: move selected item down by one
    return;
}

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

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

Void USRMenu::HandleBoundReal(Void)
{
    // here describe the size recalculation if necessary when the real region is changed
    return;
}

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

Void USRMenu::HandleRenderRequest(SFXGraphicsPtr graphics) const
{
    // draw menu
    return;
}

Reference

Menu(Basic) | SFZTextMenu | SFZGridMenu | SFZFlexListMenu | SFZRoot | 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 SFYMenu, the corresponding handler will be called when one of the above events occurs.

Internal Implementation

Internal implementation of this constructor is as follows:

/*protected */SFYMenu::SFYMenu(Void) static_throws : _state(STATE_IDLE)
{
    static SFXRGBColor::AtomRecConst            rgb[] = {
        {{{0x00, 0xEE, 0xEE, 0xEE}}}
    };
    static SFXEventRange::AtomRecConst          trange[] = {
        {     SFEVT_APP_RESUME,       SFEVT_APP_RESUME,           SFP16_BEGIN,            SFP16_END},
        {     SFEVT_APP_SUSPEND,      SFEVT_APP_SUSPEND,          SFP16_BEGIN,            SFP16_END},
        #if TARGET_VERSION_GE(3, 0, 0)
        {       SFEVT_KEY_PRESS,      SFEVT_KEY_RELEASE,          SFP16_BEGIN,            SFP16_END},
        #else
        {       SFEVT_KEY_PRESS,         SFEVT_KEY_HELD,          SFP16_BEGIN,            SFP16_END},
        #endif
        {             SFEVT_KEY,              SFEVT_KEY,          SFP16_BEGIN,            SFP16_END},
        {             SFEVT_KEY,              SFEVT_KEY,          SFP16_BEGIN,            SFP16_END},
        { SFEVT_RESPONDER_STATE,  SFEVT_RESPONDER_STATE,    SFP16_STATE_VALID,    SFP16_STATE_VALID},
        {SFEVT_RESPONDER_RESULT, SFEVT_RESPONDER_RESULT,          SFP16_BEGIN,            SFP16_END}
    };
    SFYHandler::RuleRec                         trule[lengthof(trange)];

    if (static_try()) {
        SetType(CODE_TYPE);
        trule[0].spp = XANDLER_FUNCTION(OnAppResume);
        trule[0].reference = this;
        trule[1].spp = XANDLER_FUNCTION(OnAppSuspend);
        trule[1].reference = this;
        trule[2].spp = XANDLER_FUNCTION(OnShield);
        trule[2].reference = this;
        trule[3].spp = XANDLER_FUNCTION(OnKey);
        trule[3].reference = this;
        trule[4].spp = XANDLER_FUNCTION(OnRewind);
        trule[4].reference = this;
        trule[5].spp = XANDLER_FUNCTION(OnStateValid);
        trule[5].reference = this;
        trule[6].spp = XANDLER_FUNCTION(OnMenuResult);
        trule[6].reference = this;
        static_throw(RegisterHandler(atomic_cast(trange), trule, lengthof(trange)));
        if (static_try()) {
            SetBackgroundColor(rgb[0]);
            _timer.Set(XALLBACK_INTERNAL(OnTimer));
            _msec = 0;
            _key.operate = AVK_SELECT;
            _key.escape = AVK_CLR;
            _key.up = AVK_UP;
            _key.down = AVK_DOWN;
            _key.left = AVK_LEFT;
            _key.right = AVK_RIGHT;
        }
    }
}// SFYMenu::SFYMenu //

/*private */XANDLER_IMPLEMENT_VOIDRESUME(SFYMenu, OnAppResume, invoker, environment)
{
    unused(invoker);
    unused(environment);
    if (_state == STATE_FIRE) {
        _timer.Schedule(_msec);
    }
    return;
}// XANDLER_IMPLEMENT_VOIDRESUME(SFYMenu, OnAppResume) //

/*private */XANDLER_IMPLEMENT_VOIDSUSPEND(SFYMenu, OnAppSuspend, invoker, reason, info)
{
    unused(invoker);
    unused(reason);
    unused(info);
    if (_state != STATE_IDLE) {
        _timer.Cancel();
    }
    return;
}// XANDLER_IMPLEMENT_VOIDSUSPEND(SFYMenu, OnAppSuspend) //

/*private */XANDLER_IMPLEMENT_BOOLEVENT(SFYMenu, OnShield, invoker, event)
{
    unused(invoker);
    return (event.GetP16() == _key.operate || event.GetP16() == _key.escape || event.GetP16() == _key.up || event.GetP16() == _key.down || event.GetP16() == _key.left || event.GetP16() == _key.right);
}// XANDLER_IMPLEMENT_BOOLEVENT(SFYMenu, OnShield) //

/*private */XANDLER_IMPLEMENT_BOOLEVENT(SFYMenu, OnKey, invoker, event)
{
    Bool                                        result(false);

    unused(invoker);
    if (event.GetP16() == _key.operate) {
        CancelTimer();
        HandleOperateKey();
        result = true;
    }
    else if (event.GetP16() == _key.escape) {
        CancelTimer();
        HandleEscapeKey();
        result = true;
    }
    else if (event.GetP16() == _key.up) {
        HandleSelectUpKey();
        result = true;
    }
    else if (event.GetP16() == _key.down) {
        HandleSelectDownKey();
        result = true;
    }
    else if (event.GetP16() == _key.left) {
        HandleSelectLeftKey();
        result = true;
    }
    else if (event.GetP16() == _key.right) {
        HandleSelectRightKey();
        result = true;
    }
    return result;
}// XANDLER_IMPLEMENT_BOOLEVENT(SFYMenu, OnKey) //

/*private */XANDLER_IMPLEMENT_BOOLEVENT(SFYMenu, OnRewind, invoker, event)
{
    unused(invoker);
    unused(event);
    RewindTimer();
    return false;
}// XANDLER_IMPLEMENT_BOOLEVENT(SFYMenu, OnRewind) //

/*private */XANDLER_IMPLEMENT_VOIDSTATE(SFYMenu, OnStateValid, invoker, reason, state)
{
    unused(invoker);
    unused(reason);
    if (!state) {
        CancelTimer();
    }
    return;
}// XANDLER_IMPLEMENT_VOIDSTATE(SFYMenu, OnStateValid) //

/*private */XANDLER_IMPLEMENT_VOIDRESULT(SFYMenu, OnMenuResult, invoker, reason, result)
{
    unused(invoker);
    unused(reason);
    unused(result);
    Terminate();
    return;
}// XANDLER_IMPLEMENT_VOIDRESULT(SFYMenu, OnMenuResult) //

/*private */XALLBACK_IMPLEMENT_SFXTIMER(SFYMenu, OnTimer)
{
    SFYResponderSmp                             root;
    SFCError                                    error;

    error = SFERR_NO_ERROR;
    if ((root = GetRoot()) != null) {
        if (_state == STATE_FIRE) {
            _state = STATE_IDLE;
            _msec = 0;
            Invalidate();
            HandleEscapeKey();
            error = root->Render();
        }
    }
    else {
        error = SFERR_FAILED;
    }
    if (error != SFERR_NO_ERROR) {
        // internal fault!
    }
    return;
}// XALLBACK_IMPLEMENT_SFXTIMER(SFYMenu, OnTimer) //

Reference

SFYResponder::SetType | SFYMenu::CodeEnum | SFYMenu::SetOperateKey | SFYMenu::HandleOperateKey | SFYMenu::SetEscapeKey | SFYMenu::HandleEscapeKey | SFYMenu::SetSelectUpKey | SFYMenu::HandleSelectUpKey | SFYMenu::SetSelectDownKey | SFYMenu::HandleSelectDownKey | SFYMenu::SetSelectLeftKey | SFYMenu::HandleSelectLeftKey | SFYMenu::SetSelectRightKey | SFYMenu::HandleSelectRightKey | SFYMenu::ScheduleTimer | SFXRGBColor | SFXEvent | Type | Event | Key Event[SFEVT_KEY] | Applet-Suspend Event[SFEVT_APP_SUSPEND] | Applet-Resume Event[SFEVT_APP_RESUME] | Result Event[SFEVT_RESPONDER_RESULT]

Description

This destructor cancels the timer processing.

Reference

SFYMenu::CancelTimer

Description

If this function is called, the menu will not be closed after the time set with the SFYMenu::ScheduleTimer function elapses.

Reference

SFYMenu::ScheduleTimer | SFYMenu::RewindTimer

Description

This function gets the ESCAPE key of this menu set with the SFYMenu::SetEscapeKey function.

Reference

SFYMenu::SetEscapeKey

Description

This function gets the operation key of this menu set with the SFYMenu::SetOperateKey function.

Reference

SFYMenu::SetOperateKey

Description

This function gets the DOWN key of this menu set with the SFYMenu::SetSelectDownKey function.

Reference

SFYMenu::SetSelectDownKey

Description

This function gets the LEFT key of this menu set with the SFYMenu::SetSelectLeftKey function.

Reference

SFYMenu::SetSelectLeftKey

Description

This function gets the RIGHT key of this menu set with the SFYMenu::SetSelectRightKey function.

Reference

SFYMenu::SetSelectRightKey

Description

This function gets the UP key of this menu set with the SFYMenu::SetSelectUpKey function.

Reference

SFYMenu::SetSelectUpKey

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

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

Reference

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

Description

This function will be called when the SFEVT_KEY event(key event[SFEVT_KEY]) of the ESCAPE key set with the SFYMenu::SetEscapeKey function is received or the time scheduled by the SFYMenu::ScheduleTimer elapses without the operation nor ESCAPE key press.

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_ESCAPE, 0)], which will boot up the result handler.

	Note
	Implementation of the default result handler is only to close this menu.

Internal Implementation

Internal implementation of the SFYMenu::HandleEscapeKey function is as follows:

/*protected virtual */Void SFYMenu::HandleEscapeKey(Void)
{
    InvokeForward(SFXEvent(SFEVT_RESPONDER_RESULT, SFP16_RESULT_ESCAPE, 0), false);
    return;
}// SFYMenu::HandleEscapeKey //

Reference

SFYMenu::SetEscapeKey | SFYMenu::ScheduleTimer | SFYMenu::SetOperateKey | SFXEvent | Result Event[SFEVT_RESPONDER_RESULT] | Key Event[SFEVT_KEY]

Description

This function will be called when the SFEVT_KEY event(key event[SFEVT_KEY]) of the operaion key set with the SFYMenu::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_CANCEL, 0)], which will boot up the result handler.

	Note
	Implementation of the default result handler is only to close this menu.

Internal Implementation

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

/*protected virtual */Void SFYMenu::HandleOperateKey(Void)
{
    InvokeForward(SFXEvent(SFEVT_RESPONDER_RESULT, SFP16_RESULT_CANCEL, 0), false);
    return;
}// SFYMenu::HandleOperateKey //

Reference

SFYMenu::SetOperateKey | SFXEvent | Result Event[SFEVT_RESPONDER_RESULT] | Key Event[SFEVT_KEY]

Description

This function will be called when the SFEVT_KEY event(key event[SFEVT_KEY]) of the DOWN key set with the SFYMenu::SetSelectDownKey function is received.

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

The default implementation does nothing.

Internal Implementation

Internal implementation of the SFYMenu::HandleSelectDownKey function is as follows:

/*protected virtual */Void SFYMenu::HandleSelectDownKey(Void)
{
    return;
}// SFYMenu::HandleSelectDownKey //

Reference

SFYMenu::SetSelectDownKey | SFXEvent | Key Event[SFEVT_KEY]

Description

This function will be called when the SFEVT_KEY event(key event[SFEVT_KEY]) of the LEFT key set with the SFYMenu::SetSelectLeftKey function is received.

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

The default implementation does nothing.

Internal Implementation

Internal implementation of the SFYMenu::HandleSelectLeftKey function is as follows:

/*protected virtual */Void SFYMenu::HandleSelectLeftKey(Void)
{
    return;
}// SFYMenu::HandleSelectLeftKey //

Reference

SFYMenu::SetSelectLeftKey | SFXEvent | Key Event[SFEVT_KEY]

Description

This function will be called when the SFEVT_KEY event(key event[SFEVT_KEY]) of the RIGHT key set with the SFYMenu::SetSelectRightKey function is received.

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

The default implementation does nothing.

Internal Implementation

Internal implementation of the SFYMenu::HandleSelectRightKey function is as follows:

/*protected virtual */Void SFYMenu::HandleSelectRightKey(Void)
{
    return;
}// SFYMenu::HandleSelectRightKey //

Reference

SFYMenu::SetSelectRightKey | SFXEvent | Key Event[SFEVT_KEY]

Description

This function will be called when the SFEVT_KEY event(key event[SFEVT_KEY]) of the UP key set with the SFYMenu::SetSelectUpKey function is received.

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

The default implementation does nothing.

Internal Implementation

Internal implementation of the SFYMenu::HandleSelectUpKey function is as follows:

/*protected virtual */Void SFYMenu::HandleSelectUpKey(Void)
{
    return;
}// SFYMenu::HandleSelectUpKey //

Reference

SFYMenu::SetSelectUpKey | SFXEvent | Key Event[SFEVT_KEY]

Description

This function resets the time until this menu is automatically closed, which has been set with the SFYMenu::ScheduleTimer function.

Reference

SFYMenu::ScheduleTimer | SFYMenu::CancelTimer

Description

This function schedules the timer that the SFYMenu::HandleEscapeKey function will be called and the screen will be redrawn when neither the operation key nor the ESCAPE key has been pressed for the specified time. [milliseconds]

Scheduling of timer processing callback

This function registers the timer processing callback that the SFYMenu::HandleEscapeKey function will be called and the screen will be redrawn when the specified time elapses. If the operation key set with the SFYMenu::SetOperateKey function or the ESCAPE key set with the SFYMenu::SetEscapeKey function is pressed before the specified time elapses, this timer processing callback will be canceled. If this timer processing callback is scheduled at the suspend time, it will be canceled and re-scheduled at the resume time automatically. When the valid state of this menu becomes invalid, if this timer processing callback is scheduled, it will be canceled automatically.

Reference

SFYMenu::HandleEscapeKey | SFYMenu::CancelTimer | SFYMenu::RewindTimer | SFYMenu::SetOperateKey | SFYMenu::SetEscapeKey | State

Description

This function sets the ESCAPE key of this menu to the specified value.

The SFYMenu::HandleEscapeKey function will be called when this key is pressed.

Default: AVK_CLR

Reference

SFYMenu::HandleEscapeKey | SFYMenu::GetEscapeKey

Description

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

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

Default: AVK_SELECT

Reference

SFYMenu::HandleOperateKey | SFYMenu::GetOperateKey

Description

This function sets the DOWN key of this menu to the specified value.

The SFYMenu::HandleSelectDownKey function will be called when this key is pressed.

Default: AVK_DOWN

Reference

SFYMenu::HandleSelectDownKey | SFYMenu::GetSelectDownKey

Description

This function sets the LEFT key of this menu to the specified value.

The SFYMenu::HandleSelectLeftKey function will be called when this key is pressed.

Default: AVK_LEFT

Reference

SFYMenu::HandleSelectLeftKey | SFYMenu::GetSelectLeftKey

Description

This function sets the RIGHT key of this menu to the specified value.

The SFYMenu::HandleSelectRightKey function will be called when this key is pressed.

Default: AVK_RIGHT

Reference

SFYMenu::HandleSelectRightKey | SFYMenu::GetSelectRightKey

Description

This function sets the UP key of this menu to the specified value.

The SFYMenu::HandleSelectUpKey function will be called when this key is pressed.

Default: AVK_UP

Reference

SFYMenu::HandleSelectUpKey | SFYMenu::GetSelectUpKey

Reference

SFYResponder::GetType | SFYResponder::SetType