<?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& 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);

    };</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>