Detecting +Changes in the Environment

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 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.