SFXEditor

Concrete class to edit the native text input control of the standard BREW.

#include <SFXEditor.h.hpp>

class SFXEditor : public SFXBaseEditor;

SFMTYPEDEFCLASS(SFXEditor)

Inheritance diagram

Collaboration diagram

Description

SFXEditor is the concrete class to use the native BREW text input control (i.e., BREW API ITextCtl and BREW API IMenuCtl) with ease.

SFZSingleEditLabelControl, SFZSingleEditBoxControl, SFZMultipleEditLabelControl, or SFZMultipleEditBoxControl uses this class in SFYSingleEditWidget or SFYMultipleEditWidget which is its child resopnder.

In SophiaFramework UNIVERSE, processing of the text input control of the standard BREW is encapsulated into the SFXBaseEditor, SFXEditor, and SFXEditProperty classes. It is enough that the same one kind of code has only to be programmed regardless of BREW SDK version, simulator, and device.

Reference

Member

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

Public Functions
`Void`	Close( `Void` ) Close the text input control of the standard BREW.
`SFCError`	Open( `SFXEditPropertyPtr` property , `CallbackSPP` spp , `VoidPtr` reference ) Open the text input control of the standard BREW.
`AEECLSID`	GetSFBMenuCtlClassID( `Void` ) (inherits from SFXBaseEditor) Get the Class ID of the menu control of the text input control of the standard BREW.
`AEECLSID`	GetSFBTextCtlClassID( `Void` ) (inherits from SFXBaseEditor) Get the Class ID of the text input control of the standard BREW.
`Void`	SetSFBMenuCtlClassID( `AEECLSID` param ) (inherits from SFXBaseEditor) Set the Class ID of the menu control of the text input control of the standard BREW.
`Void`	SetSFBTextCtlClassID( `AEECLSID` param ) (inherits from SFXBaseEditor) Set the Class ID of the text input control of the standard BREW.

Protected Functions
static `SFCError`	RegisterBypass( `SFCApplication::CallbackSPP` spp , `VoidPtr` reference ) (inherits from SFXBaseEditor) Register the highest priority event handler.
static `Void`	UnregisterBypass( `SFCApplication::CallbackSPP` spp , `VoidPtr` reference ) (inherits from SFXBaseEditor) Unregister the highest priority event handler.

Types
CallbackSPP (inherits from SFXBaseEditor) Type of the callback function which will be called when the text input control(FEP) is finished.

SFXEditor::SFXEditor

Constructor of the SFXEditor class.

[ public, explicit ]
SFXEditor(Void);

Description

This constructor sets the pointer to the SFXEditProperty instance which this text input control editor contains internally to null.

Reference

SFXEditProperty

SFXEditor::~SFXEditor

Destructor of the SFXEditor class.

[ public ]
~SFXEditor(Void);

SFXEditor::Close

Close the text input control of the standard BREW.

[ public ]
Void Close(Void);

Description

This function deactives and releases the menu control and the text input control of the standard BREW set with the SFXBaseEditor::SetSFBMenuCtlClassID function and the SFXBaseEditor::SetSFBTextCtlClassID function. And it unregisters the highest priority event handler as the event handler for the text input control of the standard BREW.

	Note
	The `SFXEditor::Close` function will be automatically called in the `SFXEditor::~SFXEditor` function or when an error occurs in the `SFXEditor::Open` function.

Example

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

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

Internal Implemenation

The implementation of the SFXEditor::Close function is as follows.

/*public */SFXEditor::~SFXEditor(Void)
/*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 //

Reference

SFXBaseEditor::SetSFBMenuCtlClassID | SFXBaseEditor::SetSFBTextCtlClassID | SFXBaseEditor::UnregisterBypass | SFXEditor::Open | SFXEditor::~SFXEditor

SFXEditor::Open

Open the text input control of the standard BREW.

[ public, virtual ]
SFCError Open(
    SFXEditPropertyPtr property   // property for the text input control
    CallbackSPP spp               // callback function which will be called when the text input control(FEP) is finished
    VoidPtr reference             // user data which will be passed to the callback function
);

Description

This function creates the text input control of the standard BREW with the contents set by SFXBaseEditor::SetSFBMenuCtlClassID, SFXBaseEditor::SetSFBTextCtlClassID, SFXEditProperty::SetPasswordMode, SFXEditProperty::SetInputMode, SFXEditProperty::SetMaximumLength, SFXEditProperty::SetText functions. And it internally registers the highest priority event handler as an event handler for the text input control of the standard BREW. The callback function specified in the spp argument will be called when the native BREW text input control is finished.

Example

The below is the usage example in the implementation of the SFYSingleEditWidget::Edit function.

class SFYSingleEditWidget : public SFYWidget {
    private:

        ...

 SFXEditProperty  _property;

        ...

};

// function which transfers to the text input control
/*public */SFCError SFYSingleEditWidget::Edit(Void)
{
    SFCError  error(SFERR_NO_ERROR);

    // set the maximum length of the text for the  text input control
    if ((error = _property.SetMaximumLength(_maximum)) == SFERR_NO_ERROR) { 

        // set the initial text of the text input control
        if ((error = _property.SetText(_text)) == SFERR_NO_ERROR) { 

            // boot up the text input control(i.e., ITextCtl of the BREW)
            // OnEditor is the callback function that will be called immediately after the text input control finishes
            error = _editor.Open(XALLBACK_INTERNAL(OnEditor));
        }
    }

    return error;
}// SFYSingleEditWidget::Edit //

// callback function called when the text input control finishes
/*private */XALLBACK_IMPLEMENT_SFXEDITOR(SFYSingleEditWidget, OnEditor, context)
{
    SFCError         error;

    if ((error = context) == SFERR_NO_ERROR) {

        // set the text of the text input control to SFYSingleEditWidget instance
        if ((error = SetTextMaximumLength(_property.GetText(), _property.GetMaximumLength())) == SFERR_NO_ERROR) {

            // send the result event
            InvokeForward(SFXEvent(SFEVT_RESPONDER_RESULT, SFP16_RESULT_OK, 0), false);
        }
    }
    if (error != SFERR_NO_ERROR) {

        // send the result event
        InvokeForward(SFXEvent(SFEVT_RESPONDER_RESULT, SFP16_RESULT_ERROR, error), false);
    }
    return;
}// XALLBACK_IMPLEMENT_SFXEDITOR(SFYSingleEditWidget, OnEditor) //

Internal Implemenation

The implemenation of the SFXEditor::Open function is as follows.

/*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 //

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

    result = _textctl->HandleEvent(event);
    #if defined TARGET_ENVIRONMENT_SIMULATOR || defined TARGET_LANGUAGE_ENGLISH
    if (!result) {
        result = _menuctl->HandleEvent(event);
    }
    #endif
    switch (event.GetType()) {
        case SFEVT_APP_RESUME:
            #if defined TARGET_ENVIRONMENT_SIMULATOR || defined TARGET_LANGUAGE_ENGLISH
            if (_menuctl->IsActive()) {
                _menuctl->SetActive(false);
            }
            if (!_textctl->IsActive()) {
                _textctl->SetActive(true);
            }
            #endif
            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)) == 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