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.