<?xml version="1.0" encoding="utf-8"?>
<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->
<!-- This component and the accompanying materials are made available under the terms of the License 
"Eclipse Public License v1.0" which accompanies this distribution, 
and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->
<!-- Initial Contributors:
    Nokia Corporation - initial contribution.
Contributors: 
-->
<!DOCTYPE concept
  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept id="GUID-238D6070-96AC-5D8A-86EA-488C59DF2AE3" xml:lang="en"><title>Detecting
Changes in the Environment</title><prolog><metadata><keywords/></metadata></prolog><conbody>
<section id="GUID-829626B3-7A91-4A78-8608-9C9F35C96A5F"><title>Introduction</title> <p>There
are two classes defined in <filepath>epoc32\include\COEMAIN.H</filepath> that
enable FEPs to be notified about changes in their environment: <xref href="GUID-2CAC79B0-8BD3-3961-A162-75B004AEE5FC.dita"><apiname>MCoeForegroundObserver</apiname></xref> and <xref href="GUID-E591B7D7-ED56-3CEF-883F-7091D5833731.dita"><apiname>MCoeFocusObserver</apiname></xref>. <xref href="GUID-ADAA039A-7BF3-3B06-8486-2E3604C2633D.dita"><apiname>CCoeFep</apiname></xref> derives from both of these classes, but does not itself
implement any of their virtual functions. </p> </section>
<section id="GUID-357E255E-69AC-4A2C-B098-F1F0353A4F21"><title>Using the MCoeForegroundObserver
class</title><p> <xref href="GUID-2CAC79B0-8BD3-3961-A162-75B004AEE5FC.dita"><apiname>MCoeForegroundObserver</apiname></xref> has two (pure)
virtual functions whose signatures are as follows: </p> <codeblock id="GUID-123B7768-7C63-5398-9285-5F94436D8924" xml:space="preserve">virtual void HandleGainingForeground()=0;
virtual void HandleLosingForeground()=0;</codeblock> <p>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 <codeph>HandleGainingForeground()</codeph>: </p> <codeblock id="GUID-994FECF5-2EF2-5F29-A0CE-9C3225311812" xml:space="preserve">DrawableWindow()-&gt;MoveToGroup(iCoeEnv-&gt;WsSession().GetFocusWindowGroup());</codeblock> <p>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 <codeph>HandleGainingForeground()</codeph> and <codeph>HandleLosingForeground()</codeph> 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. </p></section>
<section id="GUID-C24BDB34-DBBE-4E7A-B07C-BC3E225683F3"><title>Using the MCoeFocusObserver
class</title><p> <xref href="GUID-E591B7D7-ED56-3CEF-883F-7091D5833731.dita"><apiname>MCoeFocusObserver</apiname></xref> has two (pure) virtual
functions whose signatures are as follows: </p> <codeblock id="GUID-36F6FD47-99F1-57B0-A3E9-4CB866272C09" xml:space="preserve">virtual void HandleChangeInFocus()=0;
virtual void HandleDestructionOfFocusedItem()=0;</codeblock> <p>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. </p></section>
<section id="GUID-5B6859ED-764F-4635-8457-91DDC29FBA7E"><title>Using the TCoeInputCapabilities
class</title><p>The public parts of <codeph>TCoeInputCapabilities</codeph> (which
is defined in <filepath>epoc32\include\COEINPUT.H</filepath>) are as follows: </p> <codeblock id="GUID-CF002ADB-2946-5D3A-9749-796D88D3C718" xml:space="preserve">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&amp; aAnother);
    IMPORT_C TCoeInputCapabilities&amp; operator=(const TCoeInputCapabilities&amp; aAnother);
    IMPORT_C TBool operator==(const TCoeInputCapabilities&amp; aAnother) const;
    IMPORT_C TBool operator!=(const TCoeInputCapabilities&amp; aAnother) const;
    IMPORT_C void MergeWith(const TCoeInputCapabilities&amp; 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);
    };</codeblock> <p>The following code initializes <codeph>inputCapabilities</codeph> to
the merged input capabilities of all the currently focused controls: </p> <codeblock id="GUID-E82A2E62-B8BF-5D8C-B56C-B67CC4B34CCF" xml:space="preserve">TCoeInputCapabilities inputCapabilities(STATIC_CAST(CCoeAppUi*, iCoeEnv-&gt;AppUi())-&gt;InputCapabilities());</codeblock> <p>The best place for this code is inside the overrides of <xref href="GUID-E591B7D7-ED56-3CEF-883F-7091D5833731.dita"><apiname>MCoeFocusObserver</apiname></xref> ’s
virtual functions. </p> <p>By calling <xref href="GUID-BB7D0D56-1713-3DC0-BDA0-3CA1F0462BE2.dita"><apiname>TCoeInputCapabilities</apiname></xref>'s
inquiry functions, the FEP can vary its behaviour according to the input capabilities
of the target control. The <codeph>Supports</codeph> <i>Xxxxx</i> <codeph>()</codeph> 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 <codeph>FepAwareTextEditor()</codeph>, <codeph>CaptionRetrieverForFep()</codeph> and <codeph>FepSpecificExtensions()</codeph> member functions return pointers to objects of the interface classes <xref href="GUID-A5D563D6-A99A-31DF-B844-5F94EF5FFE87.dita"><apiname>MCoeFepAwareTextEditor</apiname></xref>, <xref href="GUID-68C16461-68A4-37D2-888E-DD4A6917442A.dita"><apiname>MCoeCaptionRetrieverForFep</apiname></xref> and <xref href="GUID-03D3A775-F899-30F1-8A4F-25D60439C11E.dita"><apiname>MCoeFepSpecificExtensions</apiname></xref> respectively. In each case,
a NULL return value indicates that the interface is not supported by any of
the currently focused controls. </p> <p> <xref href="GUID-A5D563D6-A99A-31DF-B844-5F94EF5FFE87.dita"><apiname>MCoeFepAwareTextEditor</apiname></xref> (which
is defined in <filepath>epoc32\include\FEPBASE.H</filepath>) is an important
and complex class, and is discussed in <xref href="GUID-38679CA2-0066-589C-988F-AC14B7E2F107.dita#GUID-38679CA2-0066-589C-988F-AC14B7E2F107/GUID-9C16757D-DC75-5223-A555-550B8D3C1DB4">Close
interaction with text editor controls</xref> below. </p> <p> <xref href="GUID-68C16461-68A4-37D2-888E-DD4A6917442A.dita"><apiname>MCoeCaptionRetrieverForFep</apiname></xref>,
which is also defined in <filepath>epoc32\include\FEPBASE.H</filepath>, has
a single member function whose signature is as follows: </p> <codeblock id="GUID-AD620A06-25B2-5E2D-B9F0-AB4D7686F96D" xml:space="preserve">virtual void GetCaptionForFep(TDes&amp; aCaption) const=0;</codeblock> <p>This sets <codeph>aCaption</codeph> to the caption of the target control.
An example of a caption is the non-editable prompt displayed alongside each
item in a dialog. </p> <p> <xref href="GUID-03D3A775-F899-30F1-8A4F-25D60439C11E.dita"><apiname>MCoeFepSpecificExtensions</apiname></xref> is
declared in <filepath>epoc32\include\COEINPUT.H</filepath> within the scope
of the <xref href="GUID-BB7D0D56-1713-3DC0-BDA0-3CA1F0462BE2.dita"><apiname>TCoeInputCapabilities</apiname></xref> 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 <xref href="GUID-BB7D0D56-1713-3DC0-BDA0-3CA1F0462BE2.dita"><apiname>TCoeInputCapabilities</apiname></xref> constructor which takes a <xref href="GUID-03D3A775-F899-30F1-8A4F-25D60439C11E.dita"><apiname>MCoeFepSpecificExtensions</apiname></xref> pointer,
and also the inquiry function returning a <xref href="GUID-03D3A775-F899-30F1-8A4F-25D60439C11E.dita"><apiname>MCoeFepSpecificExtensions</apiname></xref> 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 <xref href="GUID-03D3A775-F899-30F1-8A4F-25D60439C11E.dita"><apiname>MCoeFepSpecificExtensions</apiname></xref> class. </p></section>
</conbody></concept>