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