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-GENID-1-8-1-6-1-1-4-1-8-1-4-1-9-1" 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-GENID-1-8-1-6-1-1-4-1-8-1-4-1-9-1-2-1"><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-GENID-1-8-1-6-1-1-4-1-8-1-4-1-9-1-2-2"><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-GENID-1-8-1-6-1-1-4-1-8-1-4-1-9-1-2-2-3" 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-GENID-1-8-1-6-1-1-4-1-8-1-4-1-9-1-2-2-5" xml:space="preserve">DrawableWindow()->MoveToGroup(iCoeEnv->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-GENID-1-8-1-6-1-1-4-1-8-1-4-1-9-1-2-3"><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-GENID-1-8-1-6-1-1-4-1-8-1-4-1-9-1-2-3-3" 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-GENID-1-8-1-6-1-1-4-1-8-1-4-1-9-1-2-4"><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-GENID-1-8-1-6-1-1-4-1-8-1-4-1-9-1-2-4-3" 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& aAnother); |
|
65 IMPORT_C TCoeInputCapabilities& operator=(const TCoeInputCapabilities& aAnother); |
|
66 IMPORT_C TBool operator==(const TCoeInputCapabilities& aAnother) const; |
|
67 IMPORT_C TBool operator!=(const TCoeInputCapabilities& aAnother) const; |
|
68 IMPORT_C void MergeWith(const TCoeInputCapabilities& 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-GENID-1-8-1-6-1-1-4-1-8-1-4-1-9-1-2-4-5" 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 |
|
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-GENID-1-8-1-3-1-1-9-1-4-1-10-1.dita#GUID-38679CA2-0066-589C-988F-AC14B7E2F107-GENID-1-8-1-3-1-1-9-1-4-1-10-1/GUID-9C16757D-DC75-5223-A555-550B8D3C1DB4-GENID-1-8-1-3-1-1-9-1-4-1-10-1-2-1">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-GENID-1-8-1-6-1-1-4-1-8-1-4-1-9-1-2-4-10" xml:space="preserve">virtual void GetCaptionForFep(TDes& 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> |
|