--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/SDK/Source/GUID-238D6070-96AC-5D8A-86EA-488C59DF2AE3.dita Fri Jun 11 12:39:03 2010 +0100
@@ -0,0 +1,119 @@
+<?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()->MoveToGroup(iCoeEnv->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->AppUi())->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& 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>
\ No newline at end of file