Symbian3/SDK/Source/GUID-238D6070-96AC-5D8A-86EA-488C59DF2AE3.dita
changeset 8 ae94777fff8f
equal deleted inserted replaced
7:51a74ef9ed63 8:ae94777fff8f
       
     1 <?xml version="1.0" encoding="utf-8"?>
       
     2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->
       
     3 <!-- This component and the accompanying materials are made available under the terms of the License 
       
     4 "Eclipse Public License v1.0" which accompanies this distribution, 
       
     5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->
       
     6 <!-- Initial Contributors:
       
     7     Nokia Corporation - initial contribution.
       
     8 Contributors: 
       
     9 -->
       
    10 <!DOCTYPE concept
       
    11   PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
       
    12 <concept id="GUID-238D6070-96AC-5D8A-86EA-488C59DF2AE3" xml:lang="en"><title>Detecting
       
    13 Changes in the Environment</title><prolog><metadata><keywords/></metadata></prolog><conbody>
       
    14 <section id="GUID-829626B3-7A91-4A78-8608-9C9F35C96A5F"><title>Introduction</title> <p>There
       
    15 are two classes defined in <filepath>epoc32\include\COEMAIN.H</filepath> that
       
    16 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
       
    17 implement any of their virtual functions. </p> </section>
       
    18 <section id="GUID-357E255E-69AC-4A2C-B098-F1F0353A4F21"><title>Using the MCoeForegroundObserver
       
    19 class</title><p> <xref href="GUID-2CAC79B0-8BD3-3961-A162-75B004AEE5FC.dita"><apiname>MCoeForegroundObserver</apiname></xref> has two (pure)
       
    20 virtual functions whose signatures are as follows: </p> <codeblock id="GUID-123B7768-7C63-5398-9285-5F94436D8924" xml:space="preserve">virtual void HandleGainingForeground()=0;
       
    21 virtual void HandleLosingForeground()=0;</codeblock> <p>The purpose of this
       
    22 class is to enable notification of when the application (in whose thread the
       
    23 client of this class is running) goes into the foreground or background. FEPs
       
    24 that have a window owning control should include the following code at the
       
    25 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
       
    26 code switches the FEP to the window group that has gained focus. Doing this
       
    27 also enables FEPs to work with applications that have more than one window
       
    28 group. The <codeph>HandleGainingForeground()</codeph> and <codeph>HandleLosingForeground()</codeph> virtual
       
    29 functions might also be of use to a FEP if, for example, it is required to
       
    30 be invisible when the application underneath it is in the background. </p></section>
       
    31 <section id="GUID-C24BDB34-DBBE-4E7A-B07C-BC3E225683F3"><title>Using the MCoeFocusObserver
       
    32 class</title><p> <xref href="GUID-E591B7D7-ED56-3CEF-883F-7091D5833731.dita"><apiname>MCoeFocusObserver</apiname></xref> has two (pure) virtual
       
    33 functions whose signatures are as follows: </p> <codeblock id="GUID-36F6FD47-99F1-57B0-A3E9-4CB866272C09" xml:space="preserve">virtual void HandleChangeInFocus()=0;
       
    34 virtual void HandleDestructionOfFocusedItem()=0;</codeblock> <p>The purpose
       
    35 of this class is to enable notification of when controls under the FEP gain
       
    36 or lose focus. This notification is useful to FEPs that need to know about
       
    37 the input capabilities of their target control. See the next section for information
       
    38 on input capabilities. </p></section>
       
    39 <section id="GUID-5B6859ED-764F-4635-8457-91DDC29FBA7E"><title>Using the TCoeInputCapabilities
       
    40 class</title><p>The public parts of <codeph>TCoeInputCapabilities</codeph> (which
       
    41 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
       
    42     {
       
    43 public:
       
    44     enum
       
    45         {
       
    46         ENone=0,
       
    47         EWesternNumericIntegerPositive=0x00000001,
       
    48         EWesternNumericIntegerNegative=0x00000002,
       
    49         EWesternNumericReal=0x00000004,
       
    50         EWesternAlphabetic=0x00000008,
       
    51         EJapaneseHiragana=0x00000010,
       
    52         EJapaneseKatakanaHalfWidth=0x00000020,
       
    53         EJapaneseKatakanaFullWidth=0x00000040,
       
    54         EDialableCharacters=0x00000080,
       
    55         ESecretText=0x00000100,
       
    56         EAllText=0x01000000,
       
    57         ENavigation=0x02000000
       
    58         };
       
    59     class MCoeFepSpecificExtensions; // to be defined by concrete FEPs, declared here
       
    60 public:
       
    61     IMPORT_C TCoeInputCapabilities(TUint aCapabilities);
       
    62     IMPORT_C TCoeInputCapabilities(TUint aCapabilities, MCoeFepAwareTextEditor* aFepAwareTextEditor, MCoeCaptionRetrieverForFep* aCaptionRetrieverForFep);
       
    63     IMPORT_C TCoeInputCapabilities(TUint aCapabilities, MCoeFepAwareTextEditor* aFepAwareTextEditor,  MCoeCaptionRetrieverForFep* aCaptionRetrieverForFep,  TUid aFepUid, MCoeFepSpecificExtensions* aFepSpecificExtensions);
       
    64     IMPORT_C TCoeInputCapabilities(const TCoeInputCapabilities&amp; aAnother);
       
    65     IMPORT_C TCoeInputCapabilities&amp; operator=(const TCoeInputCapabilities&amp; aAnother);
       
    66     IMPORT_C TBool operator==(const TCoeInputCapabilities&amp; aAnother) const;
       
    67     IMPORT_C TBool operator!=(const TCoeInputCapabilities&amp; aAnother) const;
       
    68     IMPORT_C void MergeWith(const TCoeInputCapabilities&amp; aAnother);
       
    69     IMPORT_C void SetCapabilities(TUint aCapabilities);
       
    70     IMPORT_C TUint Capabilities() const;
       
    71     IMPORT_C TBool IsNone() const;
       
    72     IMPORT_C TBool SupportsWesternNumericIntegerPositive() const;
       
    73     IMPORT_C TBool SupportsWesternNumericIntegerNegative() const;
       
    74     IMPORT_C TBool SupportsWesternNumericReal() const;
       
    75     IMPORT_C TBool SupportsWesternAlphabetic() const;
       
    76     IMPORT_C TBool SupportsJapaneseHiragana() const;
       
    77     IMPORT_C TBool SupportsJapaneseKatakanaHalfWidth() const;
       
    78     IMPORT_C TBool SupportsJapaneseKatakanaFullWidth() const;
       
    79     IMPORT_C TBool SupportsDialableCharacters() const;
       
    80     IMPORT_C TBool SupportsSecretText() const;
       
    81     IMPORT_C TBool SupportsAllText() const;
       
    82     IMPORT_C TBool SupportsNavigation() const;
       
    83     IMPORT_C MCoeFepAwareTextEditor* FepAwareTextEditor() const;
       
    84     IMPORT_C MCoeCaptionRetrieverForFep* CaptionRetrieverForFep() const;
       
    85     IMPORT_C MCoeFepSpecificExtensions* FepSpecificExtensions(TUid aFepUid) const;
       
    86     IMPORT_C MObjectProvider* ObjectProvider() const;
       
    87     IMPORT_C void SetObjectProvider(MObjectProvider* aObjectProvider);
       
    88     };</codeblock> <p>The following code initializes <codeph>inputCapabilities</codeph> to
       
    89 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
       
    90 virtual functions. </p> <p>By calling <xref href="GUID-BB7D0D56-1713-3DC0-BDA0-3CA1F0462BE2.dita"><apiname>TCoeInputCapabilities</apiname></xref>'s
       
    91 inquiry functions, the FEP can vary its behaviour according to the input capabilities
       
    92 of the target control. The <codeph>Supports</codeph> <i>Xxxxx</i> <codeph>()</codeph> member
       
    93 functions indicate what sort of key events should be sent by the FEP to the
       
    94 target control. It is important for the FEP to behave appropriately for the
       
    95 capabilities of the target control(s). For example, a FEP should not allow
       
    96 the user to compose a large amount of text, only to pass it on to a control
       
    97 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,
       
    98 a NULL return value indicates that the interface is not supported by any of
       
    99 the currently focused controls. </p> <p> <xref href="GUID-A5D563D6-A99A-31DF-B844-5F94EF5FFE87.dita"><apiname>MCoeFepAwareTextEditor</apiname></xref> (which
       
   100 is defined in <filepath>epoc32\include\FEPBASE.H</filepath>) is an important
       
   101 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
       
   102 interaction with text editor controls</xref> below. </p> <p> <xref href="GUID-68C16461-68A4-37D2-888E-DD4A6917442A.dita"><apiname>MCoeCaptionRetrieverForFep</apiname></xref>,
       
   103 which is also defined in <filepath>epoc32\include\FEPBASE.H</filepath>, has
       
   104 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.
       
   105 An example of a caption is the non-editable prompt displayed alongside each
       
   106 item in a dialog. </p> <p> <xref href="GUID-03D3A775-F899-30F1-8A4F-25D60439C11E.dita"><apiname>MCoeFepSpecificExtensions</apiname></xref> is
       
   107 declared in <filepath>epoc32\include\COEINPUT.H</filepath> within the scope
       
   108 of the <xref href="GUID-BB7D0D56-1713-3DC0-BDA0-3CA1F0462BE2.dita"><apiname>TCoeInputCapabilities</apiname></xref> class, although it is not
       
   109 defined by any component in the Symbian platform. It is to be defined by concrete
       
   110 FEPs rather than by the FEP architecture. The intention of this is to allow
       
   111 applications to communicate specialized input capabilities with a particular
       
   112 FEP that they know about. The concrete FEP would define the class in a public
       
   113 header file which then can be used by the relevant applications. Note that
       
   114 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,
       
   115 and also the inquiry function returning a <xref href="GUID-03D3A775-F899-30F1-8A4F-25D60439C11E.dita"><apiname>MCoeFepSpecificExtensions</apiname></xref> pointer
       
   116 both require the UID of the FEP defining this class to be passed. This is
       
   117 to ensure that the FEP and the application are both assuming the same definition
       
   118 of the <xref href="GUID-03D3A775-F899-30F1-8A4F-25D60439C11E.dita"><apiname>MCoeFepSpecificExtensions</apiname></xref> class. </p></section>
       
   119 </conbody></concept>