SFCApplication

Base class for all applications.

#include <SFCApplication.h.hpp>

class SFCApplication : public SFCInvoker;

SFMTYPEDEFCLASS(SFCApplication)

Inheritance diagram

Collaboration diagram

Description

How to use

All application classes of SophiaFramework UNIVERSE inherit from SFCApplication.

Note

	Note
When an application class which inherits from `SFCApplication` directly is used, you cannot utilize the SFY responder system unless the necessary initialization of the SFY responder is performed. In general, in case of utilizing the SFY responder system, it is recommended to use an application class which inherits from `SFYApplication`, where the necessary initialization of the SFY responder is implemented in itself by default. For more details, see the description in Root.

When an application class which inherits from SFCApplication directly is used, you cannot utilize the SFY responder system unless the necessary initialization of the SFY responder is performed.

In general, in case of utilizing the SFY responder system, it is recommended to use an application class which inherits from SFYApplication, where the necessary initialization of the SFY responder is implemented in itself by default.

For more details, see the description in Root.

Event Handling [General Processing Flow]

The highest priority event handler, if registered, will be called to handle an event dispatched from the BREW environment(BREW-defined event) first of all.
The HandleRender() function will be called to redraw the full screen when the applet receives the SFEVT_APP_START or SFEVT_APP_RESUME event dispatched from the BREW environment or when a highest priority event handler ends.
The HandleEvent() function will be called to perform event handling when the applet receives the SFEVT_APP_START, SFEVT_APP_RESUME, SFEVT_APP_STOP, or SFEVT_APP_SUSPEND event dispatched from the BREW environment, or the BREW-defined event is not handled by a highest priority event handler.
The HandleError() function will be called to handle the fatal error such as insufficient memory when it occurs.

	Highest Priority Event Handler
	For more details, see the description of the `SFCApplication::RegisterBypass` function.

The actual codes in SophiaFramework UNIVERSE are as follows:

Example 777. Event loop in the SFCApplication class

/*private */Bool SFCApplication::Invoke(SFXEventConstRef event)
{
    Bool    overload(false); // flag indicating whether or not to handle the event duplicately
    Bool    render(false);   // flag indicating whether or not to redraw the full screen
    Bool    result(false);   // it fas been succeeded if "true"

    switch (event.GetType()) {

        case SFEVT_APP_START:
        case SFEVT_APP_RESUME:
            // if SFEVT_APP_START or SFEVT_APP_RESUME event
            render = true;   // redraw the full screen
        case SFEVT_APP_STOP:
        case SFEVT_APP_SUSPEND:
            // if SFEVT_APP_START, SFEVT_APP_RESUME, SFEVT_APP_STOP, or SFEVT_APP_SUSPEND event
            overload = true; // handle the event duplicately
            break;
        default:
            break;
    }

    if (_bypass != null) {  // if a highest priority event handler is registered

        // call the highest priority event handler
        result = (*_spp)(event, _reference);
    }

    if (render) {  // if it is necessary to redraw the device screen

        if (IsRenderable()) {  //  if no highest priority event handler is registered

            // redraw the full screen
            HandleRender(event);
        }
    }

    if (!result || overload) {  
        // if the event has not been handled by the highest priority event handler 
        // or it is one of SFEVT_APP_START / SFEVT_APP_RESUME / SFEVT_APP_STOP / SFEVT_APP_SUSPEND events

        // handle the event
        result = HandleEvent(event) || overload;
    }
    return result;

}// SFCApplication::Invoke //

	Change of the function name [to be planned]
	In the near future, the function name of "SFCApplication::Invoke(SFXEventConstRef event)" is planned to be changed. Therefore, see only the content in the above code.

Virtual Functions

Table 190. Virtual function name and its default behaviour

Virtual function name	Default behaviour	Override
`SFCApplication::HandleEvent`	-	Optional
`SFCApplication::HandleRender`	If no highest priority event handler is registered, this function will fill the device screen in white and return "true". Otherwise it will return "false" only without redrawing the screen. *1	Optional
`SFCApplication::HandleError`	-	Optional

	NOTE
	*1. Boot up the `SFCApplication::HandleError` function when the fatal error such as memory insufficiency occurs.

Make a user-defined application class

The code necessary to make a user-defined application class is as follows:

Example 778. Declaration

SFMTYPEDEFCLASS(USRApplication)
class USRApplication: public SFCApplication {
    SFMSEALCOPY(USRApplication)
public:
    static SFCInvokerPtr Factory(Void);
private:
    explicit USRApplication(Void) static_throws;
    virtual ~USRApplication(Void);
    virtual Bool HandleEvent(SFXEventConstRef event);                  // event handler[optional]
    virtual Bool HandleRender(SFXEventConstRef event);                 // full screen redrawing handler[optional]
    virtual Bool HandleError(SFXEventConstRef event, SFCError error);  // error handler[optional]
};

Example 779. Implementation

// boot loader: function first executed in BREW applet
SFCApplet::FactorySPP SFCApplet::Boot(AEECLSID id, SFXAnsiStringPtr license)
{
    // here place the license code
    *license = "heap://";

    return (id == AEECLSID_USRAPPLICATION) ? (&USRApplication::Factory): (null);
}

// factory function to create instance of user-defined application class
SFCInvokerPtr USRApplication::Factory(Void)
{
    return::new USRApplication;
}

// constructor
USRApplication::USRApplication(Void) static_throws
{
    if (static_try()) {

        // here describe the initialization
    }
}

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

// event handler[optional]
Bool USRApplication::HandleEvent(SFXEventConstRef event)
{
    Bool result(false);


    //  here describe various event handling


    return result; // return "true" if event has been handled, otherwise return "false"
}

// full screen redrawing handler[optional]
Bool USRApplication::HandleRender(SFXEventConstRef event)
{
    // here describe full screen redrawing when an applet starts or resumes

    SFXGraphicsPtr graphics;
    Bool           result(false);

    if (IsRenderable()) {  // if screen can be redrawn (i.e., if no highest priority event handler is registered)

        // get SFXGraphics instance
        graphics = SFXGraphics::GetInstance();
        if (graphics != null) {

            // fill device screen region in white
            // get device screen region with SFXGraphics::GetDeviceRectangle() 
            // SFXRGBColor(0xFF, 0xFF, 0xFF, 0x00) represents white color
            graphics->ClearRectangle(SFXGraphics::GetDeviceRectangle(), SFXRGBColor(0xFF, 0xFF, 0xFF, 0x00));


            // here describe other full screen redrawing


            // must update device screen region in case of applet without GUI framework
            graphics->Update();

            result = true;  // set result to "true" because device screen region has been redrawn
        }

        // if SFXGraphics instance cannot be gotten, call HandleError()
        else if (HandleError(event, SFERR_FAILED)) {

            result = true;  // set result to "true" because error has been handled
        }
    }

    return result; // return "true" if device screen region has been redrawn or error has been handled, otherwise return "false"
}

// error handler[optional]
Bool USRApplication::HandleError(SFXEventConstRef event, SFCError error)
{
    Bool result(false);

    // here describe error handling when fatal error occurs in HandleEvent() or HandleRender()

    return result; // return "true" if error has been handled, otherwise return "false"
}

	The return statement in the constructor or destructor
In general, the return statement should not be written in the constructor and destructor with C++. The bug has been confirmed in GCC. It is that compiler will freeze if the return statement is written in the constructor or destructor under some particular inheritance relationship.

The return statement in the constructor or destructor

In general, the return statement should not be written in the constructor and destructor with C++.

The bug has been confirmed in GCC. It is that compiler will freeze if the return statement is written in the constructor or destructor under some particular inheritance relationship.

Reference

Member

Constructor/Destructor
SFCApplication( `Void` ) Constructor of the SFCApplication class.
~SFCApplication( `Void` ) Destructor of the SFCApplication class.

Public Functions
static `AEECLSID`	GetClassID( `Void` ) Get the ClassID of this BREW applet.
static `SFCApplicationPtr`	GetInstance( `Void` ) Get the instance of this application.
`Bool`	IsHandlingEvent( `Void` ) Check whether or not an event is being processed.
`Bool`	IsRenderable( `Void` ) Check whether or not the screen can be drawn.
`SFCError`	RegisterBypass( `CallbackSPP` spp , `VoidPtr` reference ) Register the highest priority event handler.
`Bool`	RenderDeviceScreen( `Void` ) Redraw the device screen.
static `SFCError`	Terminate( `Bool` idle = false ) Terminate this application.
`Void`	UnregisterBypass( `CallbackSPP` spp , `VoidPtr` reference ) Unregister the highest priority event handler.

Protected Functions
`Bool`	HandleError( `SFXEventConstRef` event , `SFCError` error ) This is a virtual function that will be called when the fatal error occurs.
`Bool`	HandleEvent( `SFXEventConstRef` event ) This is a virtual function that will be called when an event dispatched from the BREW environment needs to be handled.
`Bool`	HandleRender( `SFXEventConstRef` event ) This is a virtual function that will be called when the full screen needs to be redrawn.
`Bool`	Invoke( `SFXEventConstRef` event ) This is a virtual function that will be called when an event dispatched from the BREW environment needs to be handled.

SFCApplication::SFCApplication

Constructor of the SFCApplication class.

[ protected, explicit ]
SFCApplication(Void);

Description

This constructor performs the initializations as follows:

Set "Event Handling .[General Processing Flow]" in the description of SFCApplication be called first in each event loop, which is the main loop of the SophiaFramework UNIVERSE applet.
Set no highest priority event handler registered.

	Highest Priority Event Handler
	For more details, see the description of the `SFCApplication::RegisterBypass` function.

Reference

SFCApplication | SFCApplication::RegisterBypass | Event Loop

SFCApplication::~SFCApplication

Destructor of the SFCApplication class.

[ protected, virtual ]
~SFCApplication(Void);

SFCApplication::GetClassID

Get the ClassID of this BREW applet.

[ public, static ]
AEECLSID GetClassID(Void);

SFCApplication::GetInstance

Get the instance of this application.

[ public, static ]
SFCApplicationPtr GetInstance(Void);

Return value

	Note
The SFCApplication::GetInstance function calls the GETAPPINSTANCE function of BREW API internally Therefore, when the return value of GETAPPINSTANCE function is null, that of SFCApplication::GetInstance function is also null.

Note

The SFCApplication::GetInstance function calls the GETAPPINSTANCE function of BREW API internally

Therefore, when the return value of GETAPPINSTANCE function is null, that of SFCApplication::GetInstance function is also null.

SFCApplication::HandleError

This is a virtual function that will be called when the fatal error occurs.

[ protected, virtual ]
Bool HandleError(
    SFXEventConstRef event   // event
    SFCError error           // error value
);

Return value

If event has been handled: true
Otherwise: false[default]

Description

SFCApplication::HandleError a virtual function that will be called when the fatal error such as insufficient memory during the bootup of the distributer or the renderer occurs.

If the error is handled, "true" will be returned. Otherwise, "false" will be returned.

The default implementation does nothing but returns "false".

	Note
Though this function return "true" when an event is handled. Otherwise "false" will be returned. You cannot prospect correctly whether or not processing will be done normally because it is an fatal error. In principle, the procedure to stop the applet will be described.

Note

Though this function return "true" when an event is handled. Otherwise "false" will be returned. You cannot prospect correctly whether or not processing will be done normally because it is an fatal error.

In principle, the procedure to stop the applet will be described.

Example

Internal implementation of the this function is as follows:

// virtual function that will be called when the fatal error occurs
/*protected virtual */Bool SFCApplication::HandleError(SFXEventConstRef /*event*/, SFCError /*error*/)
{
    return false;

}// SFCApplication::HandleError //

Reference

SFCApplication::HandleEvent | SFCApplication::HandleRender | Renderer | Distributer

SFCApplication::HandleEvent

This is a virtual function that will be called when an event dispatched from the BREW environment needs to be handled.

[ protected, virtual ]
Bool HandleEvent(
    SFXEventConstRef event   // event
);

Return value

If the specified event is handled: true
Otherwise: false[default]

Description

SFCApplication::HandleEvent is a virtual function that will be called when an event dispatched from the BREW environment(BREW-defined event) needs to be handled.

If the event is handled, "true" will be returned. Otherwise, "false" will be returned.

The default implementation does nothing but returns "false".

You can override this virtual function for your own processing.

Internal Implementation

Internal implementation of the this function is as follows:

// virtual function that will be called when an event dispatched from the BREW environment needs to be handled
/*protected virtual */Bool SFCApplication::HandleEvent(SFXEventConstRef /*event*/)
{
    // here describe the handling of the event dispatched from the BREW environment

    return false;

}// SFCApplication::HandleEvent //

Reference

BREW-Defined Event

SFCApplication::HandleRender

This is a virtual function that will be called when the full screen needs to be redrawn.

[ protected, virtual ]
Bool HandleRender(
    SFXEventConstRef event   // event
);

Return value

If the screen has been redrawn: true
Otherwise: false

Description

SFCApplication::HandleRender is a virtual function that will be called when the full screen needs to be redrawn.

If the full screen is redrawn, "true" will be returned. Otherwise, "false" will be returned.

When the HandleRender() function is called

	When the HandleRender() function is called
When an applet starts or resumes, or when a highest priority event handler ends, the full screen needs to be redrawn. The `SFCApplication::HandleRender` function is automatically called at these times. * The screen needs to be redrawn at the end of the highest priority event handler by calling the `SFCApplication::RenderDeviceScreen` function. In this case, HandleRender() will be called inside the `SFCApplication::RenderDeviceScreen` function.

When an applet starts or resumes, or when a highest priority event handler ends, the full screen needs to be redrawn.

The SFCApplication::HandleRender function is automatically called at these times.

* The screen needs to be redrawn at the end of the highest priority event handler by calling the SFCApplication::RenderDeviceScreen function. In this case, HandleRender() will be called inside the SFCApplication::RenderDeviceScreen function.

	Highest Priority Event Handler
	For more details, see the description of the `SFCApplication::RegisterBypass` function.

	Normal drawing processing
	Normal drawing processing has nothing to do with the `SFCApplication::HandleRender` function. This processing can be specified anywhere in the program.

You can override this virtual function for your own processing.

Internal Implementation

Internal implementation of the this function is as follows:

// virtual function that will be called when the full screen needs to be redrawn
/*protected virtual */Bool SFCApplication::HandleRender(SFXEventConstRef event)
{
    // here describe full screen redrawing when an applet starts / resumes or a highest priority event handler ends

    static SFXRGBColor::AtomRecConst            theme = {
        {{0x00, 0xFF, 0xFF, 0xFF}}  // SFXRGBColor(0xFF, 0xFF, 0xFF, 0x00) represents white color
    };
    SFXGraphicsPtr graphics;
    Bool           result(false);

    // get SFXGraphics instance
    if ((graphics = SFXGraphics::GetInstance()) != null) {

        // fill the device screen region in white
        // get the device screen region by calling SFXGraphics::GetDeviceRectangle() 
        graphics->ClearRectangle(SFXGraphics::GetDeviceRectangle(), theme);

        // call SFXGraphics::Update() to update the device screen
        // * device screen region will not be redrawn or updated if line below is NOT described
        graphics->Update();

        result = true;  // set result to "true" because device screen region is redrawn
    }

    // if the SFXGraphics instance cannot be gotten, call HandleError()
    else if (HandleError(event, SFERR_FAILED)) {

        result = true;  // set result to "true" because error has been handled
    }
    return result; // return "true" if device screen region has been redrawn or error has been handled, otherwise return "false"

}// SFCApplication::HandleRender //

Reference

SFCApplication::RenderDeviceScreen | SFCApplication::HandleError | SFCApplication::HandleEvent

SFCApplication::Invoke

This is a virtual function that will be called when an event dispatched from the BREW environment needs to be handled.

[ protected, virtual ]
Bool Invoke(
    SFXEventConstRef event   // event
);

Return value

If the specified event is handled: true
Otherwise: false

Description

This is a virtual function that will be called when an event dispatched from the BREW environment needs to be handled.

Internal Implementation

Internal implementation of this function is as follows:

/*protected virtual */Bool SFCApplication::Invoke(SFXEventConstRef event)
{
    Bool                                        overload;
    Bool                                        render;
    Bool                                        result(false);

    overload = false;
    render = false;
    switch (event.GetType()) {
        case SFEVT_APP_START:
        case SFEVT_APP_RESUME:
            render = true;
        case SFEVT_APP_STOP:
        case SFEVT_APP_SUSPEND:
            overload = true;
            break;
        default:
            break;
    }
    if (_bypass != null) {
        result = (*_bypass)(event, _reference);
    }
    if (render) {
        if (IsRenderable()) {
            HandleRender(event);
        }
    }
    if (!result || overload) {
        result = HandleEvent(event) || overload;
    }
    return result;
}// SFCApplication::Invoke //

Reference

SFCApplication::HandleEvent | SFCInvoker

SFCApplication::IsHandlingEvent

Check whether or not an event is being processed.

[ public, const ]
Bool IsHandlingEvent(Void);

Return value

When an event is being processed: true
Otherwise: false

Description

This function checks whether the current process is in the event loop (the SFCApplication::Invoke function).

Reference

SFCApplication::Invoke | BREW Event

SFCApplication::IsRenderable

Check whether or not the screen can be drawn.

[ public, const ]
Bool IsRenderable(Void);

Return value

If the screen can be drawn: true
Otherwise: false

Description

If a highest priority event handler to handle the standard BREW control such as a native text input control(BREW API ITextCtl Interface) which will occupy the full screen is registered, the full screen will be occupied by this highest priority event handler. Therefore, any function other than this highest priority event handler must not draw the screen while it is registered.

SFCApplication::IsRenderable is the function to check this status.

	Highest Priority Event Handler
	For more details, see the description of the `SFCApplication::RegisterBypass` function.

Example

The below is the usage example in implemetation of the SFCApplication::HandleRender function.

// virtual function that will be called when the full screen needs to be redrawn
/*protected virtual */Bool SFCApplication::HandleRender(SFXEventConstRef event)
{
    SFXGraphicsPtr  graphics;
    Bool            result(false);

    if (IsRenderable()) { // if screen can be redrawn (i.e., if no highest priority event handler is registered)

        // get SFXGraphics instance
        if ((graphics = SFXGraphics::GetInstance()) != null) {

            // fill device screen region in white
            // get device screen region with SFXGraphics::GetDeviceRectangle() 
            // SFXRGBColor(0xFF, 0xFF, 0xFF, 0x00) represents white color
            graphics->ClearRectangle(SFXGraphics::GetDeviceRectangle(), SFXRGBColor(0xFF, 0xFF, 0xFF, 0x00));

            // call SFXGraphics::Update() to redraw device screen region
            // * device screen region will not be redrawn or updated if line below is NOT described
            graphics->Update();

            result = true;  // set result to "true" because device screen region is redrawn
        }

        // If fails in getting SFXGraphics object, call HandleError()
        else if (HandleError(event, SFERR_FAILED)) {

            result = true;
        }
    }

    return result;
}// SFCApplication::HandleRender //

Reference

SFCApplication::RegisterBypass | BREW API ITextCtl | BREW-Defined Event | Renderer | Distributer

SFCApplication::RegisterBypass

[ public ]
SFCError RegisterBypass(
    CallbackSPP spp     // highest priority event handler
    VoidPtr reference   // user data
);

Description

SFCApplication::RegisterBypass is the function to register a highest priority event handler into the instance of an application class inheriting from SFCApplication.

Only one highest priority event handler can be registered into one instance of an application class inheriting from SFCApplication.

Highest Priority Event Handler

	Highest Priority Event Handler
For instance, when a standard BREW control such as the `BREW API ITextCtl` interface is running(or "active"), an event dispatched from the BREW environment(BREW-defined event) needs to be dispatched to this control first before the distributer or responders. The function that will handle the event first of all is called highest priority event handler. Event handling of the "active" `BREW API ITextCtl` interface will be performed inside this highest priority event handler. The highest priority event handler is registered with the `SFCApplication::RegisterBypass` function, and is unregistered with the `SFCApplication::UnregisterBypass` function. If a highest priority event handler is registered, the full screen will be occupied by this highest priority event handler. Therefore, it will be necessary to redraw the full screen when an event is handled by this highest priority event handler or highest priority event handler is unregistered with the `SFCApplication::UnregisterBypass` function. However, this redrawing will be done by the `SFCApplication::HandleRender` function, which will be called automatically.

For instance, when a standard BREW control such as the BREW API ITextCtl interface is running(or "active"), an event dispatched from the BREW environment(BREW-defined event) needs to be dispatched to this control first before the distributer or responders.

The function that will handle the event first of all is called highest priority event handler. Event handling of the "active" BREW API ITextCtl interface will be performed inside this highest priority event handler.

The highest priority event handler is registered with the SFCApplication::RegisterBypass function, and is unregistered with the SFCApplication::UnregisterBypass function.

If a highest priority event handler is registered, the full screen will be occupied by this highest priority event handler.

Therefore, it will be necessary to redraw the full screen when an event is handled by this highest priority event handler or highest priority event handler is unregistered with the SFCApplication::UnregisterBypass function.

However, this redrawing will be done by the SFCApplication::HandleRender function, which will be called automatically.

Example

The below is the usage example in implemetation of the SFXEditor::Open function.

------------------------------------------------------------------------------------------------------------
/**
***     File            : SFXEditor.f.hpp
**/

#ifndef __SOPHIAFRAMEWORK_SFXEDITOR_FHPP
#define __SOPHIAFRAMEWORK_SFXEDITOR_FHPP

#include <SFXGeneral/SFXEnvironment.h.hpp>

SFMTYPEDEFCLASS(SFXEditor)

#endif // __SOPHIAFRAMEWORK_SFXEDITOR_FHPP //
------------------------------------------------------------------------------------------------------------
/**
***     File            : SFXEditor.h.hpp
**/

#ifndef __SOPHIAFRAMEWORK_SFXEDITOR_HHPP
#define __SOPHIAFRAMEWORK_SFXEDITOR_HHPP

#include <SFXGeneral/SFXEnvironment.h.hpp>
#include <SFXGeneral/SFXBaseEditor.h.hpp>
#include <SFXGeneral/SFXEditor.f.hpp>
#include <SFXGeneral/SFXEditProperty.f.hpp>
#include <SFCCore/SFCApplication.h.hpp>
#include <SFBWrapper/SFBTextCtl.h.hpp>

class SFXEditor : public SFXBaseEditor {
    SFMSEALCOPY(SFXEditor)
    private:
                SFBTextCtlSmp                   _textctl;
                SFBMenuCtlSmp                   _menuctl;
                SFXEditPropertyPtr              _property;
                CallbackSPP                     _spp;
                VoidPtr                         _reference;

    public:
        explicit                                SFXEditor                       (Void);
        virtual                                 ~SFXEditor                      (Void);
        virtual SFCError                        Open                            (SFXEditPropertyPtr property, CallbackSPP spp, VoidPtr reference);
                Void                            Close                           (Void);
    private:
                XALLBACK_DECLARE_SFCAPPLICATION(OnBypass)
};

#include <SFXGeneral/SFXEditor.i.hpp>

#endif // __SOPHIAFRAMEWORK_SFXEDITOR_HHPP //
------------------------------------------------------------------------------------------------------------
/**
***     File            : SFXEditor.i.hpp
**/

#ifndef __SOPHIAFRAMEWORK_SFXEDITOR_IHPP
#define __SOPHIAFRAMEWORK_SFXEDITOR_IHPP

#endif // __SOPHIAFRAMEWORK_SFXEDITOR_IHPP //
------------------------------------------------------------------------------------------------------------
/**
***     File            : SFXEditor.i.cpp
**/

#include <SFXGeneral/SFXEditor.h.hpp>
#include <SFXGeneral/SFXDevice.h.hpp>
#include <SFXGeneral/SFXEditProperty.h.hpp>

#define     ITEM_NAME                 ("Done")
#define     LABEL_OK                  0

/*public */SFXEditor::SFXEditor(Void) : _property(null)
{
}// SFXEditor::SFXEditor //

/*public */SFXEditor::~SFXEditor(Void)
{
    Close();
}// SFXEditor::~SFXEditor //

/*public virtual*/SFCError SFXEditor::Open(SFXEditPropertyPtr property, CallbackSPP spp, VoidPtr reference)
{
    #if defined TARGET_ENVIRONMENT_SIMULATOR || defined TARGET_LANGUAGE_ENGLISH
    static SFXRGBColor::AtomRecConst            color[] = {
        {{{0x00, 0xFF, 0xFF, 0xFF}}},
        {{{0x00, 0x00, 0x00, 0x00}}}
    };
    #endif
    SFBDisplaySmp                               display;
    SFXWideString                               string;
    SFXRectangle                                remember;
    SFXRectangle                                rectangle;
    UInt32                                      flag;
    SFCError                                    error(SFERR_NO_ERROR);

    if (property != null) {
        _property = property;
        if ((display = SFBDisplay::GetInstance()) != null) {
            display->GetClipRect(&remember);
            display->SetClipRect(SFXRectangle::EmptyInstance());
            if ((_textctl = SFBTextCtl::NewInstance(GetSFBTextCtlClassID(), &error)) != null) {
                if ((_menuctl = SFBMenuCtl::NewInstance(GetSFBMenuCtlClassID(), &error)) != null) {
                    if ((error = string.Set(ITEM_NAME)) == SFERR_NO_ERROR) {
                        if (_menuctl->AddItem(LABEL_OK, &string, reinterpret_cast<UInt32>(_menuctl.Get()))) {
                            _textctl->SetSoftKeyMenu(_menuctl);
                            #if defined TARGET_ENVIRONMENT_SIMULATOR || defined TARGET_LANGUAGE_ENGLISH
                            flag = TP_FRAME | TP_MULTILINE | TP_FIXSETRECT;
                            #else
                            flag = TP_NODRAW | TP_FRAME | TP_NOUPDATE | TP_FIXSETRECT;
                            #endif
                            if (_property->GetPasswordMode()) {
                                flag |= TP_PASSWORD;
                            }
                            _textctl->SetProperties(flag);
                            rectangle.Set(SFXGrid::ZeroInstance(), SFXDevice().GetScreenSize());
                            rectangle.SubBottom(_menuctl->GetRect().GetHeight());
                            _textctl->SetRect(rectangle);
                            _textctl->SetMaxSize(_property->GetMaximumLength());
                            _textctl->SetInputMode(_property->GetInputMode());
                            if (_textctl->SetText(_property->GetText())) {
                                if ((error = RegisterBypass(XALLBACK_INTERNAL(OnBypass))) == SFERR_NO_ERROR) {
                                    _spp = spp;
                                    _reference = reference;
                                }
                            }
                            else {
                                error = SFERR_FAILED;
                            }
                        }
                        else {
                            error = SFERR_FAILED;
                        }
                    }
                }
            }
            if (error != SFERR_NO_ERROR) {
                Close();
            }
            display->SetClipRect(remember);
            if (error == SFERR_NO_ERROR) {
                #if defined TARGET_ENVIRONMENT_SIMULATOR || defined TARGET_LANGUAGE_ENGLISH
                display->SetColor(CLR_USER_TEXT, color[1]);
                display->SetColor(CLR_USER_BACKGROUND, color[0]);
                display->SetColor(CLR_USER_LINE, color[1]);
                #endif
                _textctl->SetActive(true);
                _textctl->SetCursorPos(TC_CURSORSTART);
            }
        }
        else {
            error = SFERR_FAILED;
        }
    }
    else {
        error = SFERR_INVALID_PARAM;
    }
    return error;
}// SFXEditor::Open //

/*public */Void SFXEditor::Close(Void)
{
    if (_textctl != null) {
        _textctl->SetSoftKeyMenu(SFBMenuCtlSmp::EmptyInstance());
        _textctl->SetActive(false);
    }
    UnregisterBypass(XALLBACK_INTERNAL(OnBypass));
    _textctl.Release();
    _menuctl.Release();
    _property = null;
    return;
}// SFXEditor::Close //

/*private */XALLBACK_IMPLEMENT_SFCAPPLICATION(SFXEditor, OnBypass, event)
{
    SFXWideString  string;
    SFCError       error;
    Bool           result(false);

    result = _textctl->HandleEvent(event);
    if (!result) {
        #if defined TARGET_ENVIRONMENT_SIMULATOR
        result = _menuctl->HandleEvent(event);
        #endif
    }
    switch (event.GetType()) {
        case SFEVT_APP_RESUME:
            result = true;
            break;
        case SFEVT_APP_SUSPEND:
            result = true;
            break;
        case SFEVT_KEY:
        case SFEVT_KEY_PRESS:
        case SFEVT_KEY_RELEASE:
        #if TARGET_VERSION_LT(3, 0, 0)
        case SFEVT_KEY_HELD:
        #endif
            result = true;
            break;
        case SFEVT_COMMAND:
            if (!result) {
                switch (event.GetP16()) {
                    case LABEL_OK:
                        if ((error = string.Set(_textctl->GetTextPtr())) == SFERR_NO_ERROR) {
                            if ((error = _property->SetText(string.Substring(0, _property->GetMaximumLength()))) == SFERR_NO_ERROR) {
                                _property->SetInputMode(_textctl->GetInputMode());
                            }
                        }
                        Close();
                        if (_spp != null) {
                            (*_spp)(error, _reference);
                        }
                        if ((application = SFCApplication::GetInstance()) != null) {
                            application->RenderDeviceScreen();
                        }
                        break;
                    default:
                        break;
                }
                result = true;
            }
            break;
        default:
            break;
    }
    return result;
}// XALLBACK_IMPLEMENT_SFCAPPLICATION(SFXEditor, OnBypass) //

Reference

SFCApplication::RenderDeviceScreen

Redraw the device screen.

[ public ]
Bool RenderDeviceScreen(Void);

Description

This function redraws the device screen by calling the SFCApplication::HandleRender function internally.

Internal Implementation

Internal implementation of the this function is as follows:

/*public */Bool SFCApplication::RenderDeviceScreen(Void)
{
    return HandleRender(SFXEvent(0, 0, 0));
    return;
}// SFCApplication::RenderDeviceScreen //

Reference

SFCApplication::HandleRender

SFCApplication::Terminate

Terminate this application.

[ public, static ]
SFCError Terminate(
    Bool idle = false   // whether or not to terminate all BREW applets (this argument is effect only on a handset device)
);

Return value

If succeeds: SFERR_NO_ERROR
if there is no PL_SYSTEM priviledge when true is specified in the idle argument: EPRIVLEVEL
Otherwise: SFERR_FAILED

Description

This function terminates the BREW applet that is currently active by calling the BREW API ISHELL_CloseApplet function internally.

The SFEVT_APP_STOP event will be dispatched to the BREW applet to be terminated and the memory allocated to the BREW applet will be released from the heap.

If the idle argument is set to "true", all BREW applets will be terminated and the screen to wait for a phone call will appear. To do this, the PL_SYSTEM priviledge is needed.

If the idle argument is set to "false", only the currently active BREW applet will be terminated and the screen to select a BREW applet will appear.

For more details, see the description of BREW API ISHELL_CloseApplet in the BREW API reference.

Finalization of the SFYApplication class

	Finalization of the SFYApplication class
When the Terminate() function of the `SFYApplication` class is called, the `SFCApplication::Terminate` function will be executed. At this time, the SFEVT_APP_STOP event will be dispatched to the BREW applet to be terminated, the finalization of the application class will be performed and its destructor, the `SFYApplication::~SFYApplication` function, will be called. In the `SFYApplication::~SFYApplication` function, the finalizations of all responders in the responder tree including the root will be performed. And the finalization of the renderer and the distributer which the application class contains internally. Concretely, in the `SFYApplication::~SFYApplication` function, the `SFXResponderPointer::Release` function of the root will be called first of all to release its smart pointer. This processing will make the reference count of the root "0", and the `SFYResponder::Terminate` function of the root will be called automatically to perform its finalization. Next, all responders in the responder tree will be disassembled into independent responders, whose reference counts will become "0". As a result, the `SFYResponder::Terminate` function for each responder will be called to perform its finalization too. At the end, the `SFYRenderer::Terminate` function and the `SFYDistributer::Terminate` function will be called in this order to perform the finalizations of the renderer and the distributer too. Reference: `SFYApplication` \| Responder \| Root \| Responder Tree \| Distributer \| Renderer \| `SFYApplication::~SFYApplication` \| `SFXResponderPointer::Release` \| `SFYResponder::Terminate` \| `SFYRenderer::Terminate` \| `SFYDistributer::Terminate`

When the Terminate() function of the SFYApplication class is called, the SFCApplication::Terminate function will be executed.

At this time, the SFEVT_APP_STOP event will be dispatched to the BREW applet to be terminated, the finalization of the application class will be performed and its destructor, the SFYApplication::~SFYApplication function, will be called.

In the SFYApplication::~SFYApplication function, the finalizations of all responders in the responder tree including the root will be performed. And the finalization of the renderer and the distributer which the application class contains internally.

Concretely, in the SFYApplication::~SFYApplication function, the SFXResponderPointer::Release function of the root will be called first of all to release its smart pointer.

This processing will make the reference count of the root "0", and the SFYResponder::Terminate function of the root will be called automatically to perform its finalization. Next, all responders in the responder tree will be disassembled into independent responders, whose reference counts will become "0". As a result, the SFYResponder::Terminate function for each responder will be called to perform its finalization too.

At the end, the SFYRenderer::Terminate function and the SFYDistributer::Terminate function will be called in this order to perform the finalizations of the renderer and the distributer too.

Reference

SFCApplication::UnregisterBypass

Unregister the highest priority event handler.

[ public ]
Void UnregisterBypass(
    CallbackSPP spp     // highest priority event handler
    VoidPtr reference   // user data
);

Description

SFCApplication::UnregisterBypass is the function to unregister a highest priority event handler from the instance of an application class inheriting from SFCApplication.

Only one highest priority event handler can be registered into one instance of an application class inheriting from SFCApplication.

	Highest Priority Event Handler
	For more details, see the description of the `SFCApplication::RegisterBypass` function.

Example

The below is the usage example in the implementation of the SFXEditor::Close function.

/*public */Void SFXEditor::Close(Void)
{
    if (_textctl.control != null) {
        if (_textctl.control->IsActive()) {
            _textctl.control->SetActive(false);
        }
    }
    if (_menuctl.control != null) {
        if (_menuctl.control->IsActive()) {
            _menuctl.control->SetActive(false);
        }
    }
    if (_application != null) {
        _application->UnregisterBypass(XALLBACK_INTERNAL(OnBypass));
    }
    _textctl.control.Release();
    _menuctl.control.Release();
    _application = null;
    return;
}// SFXEditor::Close //

/*private */XALLBACK_IMPLEMENT_SFCAPPLICATION(SFXEditor, OnBypass, event)
{
    SFXWideString  string;
    SFCError       error;
    Bool           result(false);

    ...

    // same with OnBypass function of usage example in the implementation of SFCApplication::RegisterBypass function

    ....

}// XALLBACK_IMPLEMENT_SFCAPPLICATION(SFXEditor, OnBypass) //

Reference