Detecting Changes in the Environment

Introduction

There are two classes defined in epoc32\include\COEMAIN.H that enable FEPs to be notified about changes in their environment: MCoeForegroundObserver and MCoeFocusObserver. CCoeFep derives from both of these classes, but does not itself implement any of their virtual functions.

Using the MCoeForegroundObserver class

MCoeForegroundObserver has two (pure) virtual functions whose signatures are as follows:

virtual void HandleGainingForeground()=0;
virtual void HandleLosingForeground()=0;

The purpose of this class is to enable notification of when the application (in whose thread the client of this class is running) goes into the foreground or background. FEPs that have a window owning control should include the following code at the start of their implementation of HandleGainingForeground():

DrawableWindow()->MoveToGroup(iCoeEnv->WsSession().GetFocusWindowGroup());

This code switches the FEP to the window group that has gained focus. Doing this also enables FEPs to work with applications that have more than one window group. The HandleGainingForeground() and HandleLosingForeground() virtual functions might also be of use to a FEP if, for example, it is required to be invisible when the application underneath it is in the background.

Using the MCoeFocusObserver class

MCoeFocusObserver has two (pure) virtual functions whose signatures are as follows:

virtual void HandleChangeInFocus()=0;
virtual void HandleDestructionOfFocusedItem()=0;

The purpose of this class is to enable notification of when controls under the FEP gain or lose focus. This notification is useful to FEPs that need to know about the input capabilities of their target control. See the next section for information on input capabilities.

Using the TCoeInputCapabilities class

The public parts of TCoeInputCapabilities (which is defined in epoc32\include\COEINPUT.H) are as follows:

class TCoeInputCapabilities
    {
public:
    enum
        {
        ENone=0,
        EWesternNumericIntegerPositive=0x00000001,
        EWesternNumericIntegerNegative=0x00000002,
        EWesternNumericReal=0x00000004,
        EWesternAlphabetic=0x00000008,
        EJapaneseHiragana=0x00000010,
        EJapaneseKatakanaHalfWidth=0x00000020,
        EJapaneseKatakanaFullWidth=0x00000040,
        EDialableCharacters=0x00000080,
        ESecretText=0x00000100,
        EAllText=0x01000000,
        ENavigation=0x02000000
        };
    class MCoeFepSpecificExtensions; // to be defined by concrete FEPs, declared here
public:
    IMPORT_C TCoeInputCapabilities(TUint aCapabilities);
    IMPORT_C TCoeInputCapabilities(TUint aCapabilities, MCoeFepAwareTextEditor* aFepAwareTextEditor, MCoeCaptionRetrieverForFep* aCaptionRetrieverForFep);
    IMPORT_C TCoeInputCapabilities(TUint aCapabilities, MCoeFepAwareTextEditor* aFepAwareTextEditor,  MCoeCaptionRetrieverForFep* aCaptionRetrieverForFep,  TUid aFepUid, MCoeFepSpecificExtensions* aFepSpecificExtensions);
    IMPORT_C TCoeInputCapabilities(const TCoeInputCapabilities& aAnother);
    IMPORT_C TCoeInputCapabilities& operator=(const TCoeInputCapabilities& aAnother);
    IMPORT_C TBool operator==(const TCoeInputCapabilities& aAnother) const;
    IMPORT_C TBool operator!=(const TCoeInputCapabilities& aAnother) const;
    IMPORT_C void MergeWith(const TCoeInputCapabilities& aAnother);
    IMPORT_C void SetCapabilities(TUint aCapabilities);
    IMPORT_C TUint Capabilities() const;
    IMPORT_C TBool IsNone() const;
    IMPORT_C TBool SupportsWesternNumericIntegerPositive() const;
    IMPORT_C TBool SupportsWesternNumericIntegerNegative() const;
    IMPORT_C TBool SupportsWesternNumericReal() const;
    IMPORT_C TBool SupportsWesternAlphabetic() const;
    IMPORT_C TBool SupportsJapaneseHiragana() const;
    IMPORT_C TBool SupportsJapaneseKatakanaHalfWidth() const;
    IMPORT_C TBool SupportsJapaneseKatakanaFullWidth() const;
    IMPORT_C TBool SupportsDialableCharacters() const;
    IMPORT_C TBool SupportsSecretText() const;
    IMPORT_C TBool SupportsAllText() const;
    IMPORT_C TBool SupportsNavigation() const;
    IMPORT_C MCoeFepAwareTextEditor* FepAwareTextEditor() const;
    IMPORT_C MCoeCaptionRetrieverForFep* CaptionRetrieverForFep() const;
    IMPORT_C MCoeFepSpecificExtensions* FepSpecificExtensions(TUid aFepUid) const;
    IMPORT_C MObjectProvider* ObjectProvider() const;
    IMPORT_C void SetObjectProvider(MObjectProvider* aObjectProvider);
    };

The following code initializes inputCapabilities to the merged input capabilities of all the currently focused controls:

TCoeInputCapabilities inputCapabilities(STATIC_CAST(CCoeAppUi*, iCoeEnv->AppUi())->InputCapabilities());

The best place for this code is inside the overrides of MCoeFocusObserver ’s virtual functions.

By calling TCoeInputCapabilities's inquiry functions, the FEP can vary its behaviour according to the input capabilities of the target control. The Supports Xxxxx () member functions indicate what sort of key events should be sent by the FEP to the target control. It is important for the FEP to behave appropriately for the capabilities of the target control(s). For example, a FEP should not allow the user to compose a large amount of text, only to pass it on to a control that does not support it. The FepAwareTextEditor(), CaptionRetrieverForFep() and FepSpecificExtensions() member functions return pointers to objects of the interface classes MCoeFepAwareTextEditor, MCoeCaptionRetrieverForFep and MCoeFepSpecificExtensions respectively. In each case, a NULL return value indicates that the interface is not supported by any of the currently focused controls.

MCoeFepAwareTextEditor (which is defined in epoc32\include\FEPBASE.H) is an important and complex class, and is discussed in Close interaction with text editor controls below.

MCoeCaptionRetrieverForFep, which is also defined in epoc32\include\FEPBASE.H, has a single member function whose signature is as follows:

virtual void GetCaptionForFep(TDes& aCaption) const=0;

This sets aCaption to the caption of the target control. An example of a caption is the non-editable prompt displayed alongside each item in a dialog.

MCoeFepSpecificExtensions is declared in epoc32\include\COEINPUT.H within the scope of the TCoeInputCapabilities class, although it is not defined by any component in the Symbian platform. It is to be defined by concrete FEPs rather than by the FEP architecture. The intention of this is to allow applications to communicate specialized input capabilities with a particular FEP that they know about. The concrete FEP would define the class in a public header file which then can be used by the relevant applications. Note that the TCoeInputCapabilities constructor which takes a MCoeFepSpecificExtensions pointer, and also the inquiry function returning a MCoeFepSpecificExtensions pointer both require the UID of the FEP defining this class to be passed. This is to ensure that the FEP and the application are both assuming the same definition of the MCoeFepSpecificExtensions class.