|
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 class</title><p> <xref href="GUID-2CAC79B0-8BD3-3961-A162-75B004AEE5FC.dita"><apiname>MCoeForegroundObserver</apiname></xref> has |
|
19 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; |
|
20 virtual void HandleLosingForeground()=0;</codeblock> <p>The purpose of this |
|
21 class is to enable notification of when the application (in whose thread the |
|
22 client of this class is running) goes into the foreground or background. FEPs |
|
23 that have a window owning control should include the following code at the |
|
24 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 |
|
25 code switches the FEP to the window group that has gained focus. Doing this |
|
26 also enables FEPs to work with applications that have more than one window |
|
27 group. The <codeph>HandleGainingForeground()</codeph> and <codeph>HandleLosingForeground()</codeph> virtual |
|
28 functions might also be of use to a FEP if, for example, it is required to |
|
29 be invisible when the application underneath it is in the background. </p></section> |
|
30 <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 |
|
31 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; |
|
32 virtual void HandleDestructionOfFocusedItem()=0;</codeblock> <p>The purpose |
|
33 of this class is to enable notification of when controls under the FEP gain |
|
34 or lose focus. This notification is useful to FEPs that need to know about |
|
35 the input capabilities of their target control. See the next section for information |
|
36 on input capabilities. </p></section> |
|
37 <section id="GUID-5B6859ED-764F-4635-8457-91DDC29FBA7E"><title>Using the TCoeInputCapabilities class</title><p>The public |
|
38 parts of <codeph>TCoeInputCapabilities</codeph> (which is defined in <filepath>epoc32\include\COEINPUT.H</filepath>) |
|
39 are as follows: </p> <codeblock id="GUID-CF002ADB-2946-5D3A-9749-796D88D3C718" xml:space="preserve">class TCoeInputCapabilities |
|
40 { |
|
41 public: |
|
42 enum |
|
43 { |
|
44 ENone=0, |
|
45 EWesternNumericIntegerPositive=0x00000001, |
|
46 EWesternNumericIntegerNegative=0x00000002, |
|
47 EWesternNumericReal=0x00000004, |
|
48 EWesternAlphabetic=0x00000008, |
|
49 EJapaneseHiragana=0x00000010, |
|
50 EJapaneseKatakanaHalfWidth=0x00000020, |
|
51 EJapaneseKatakanaFullWidth=0x00000040, |
|
52 EDialableCharacters=0x00000080, |
|
53 ESecretText=0x00000100, |
|
54 EAllText=0x01000000, |
|
55 ENavigation=0x02000000 |
|
56 }; |
|
57 class MCoeFepSpecificExtensions; // to be defined by concrete FEPs, declared here |
|
58 public: |
|
59 IMPORT_C TCoeInputCapabilities(TUint aCapabilities); |
|
60 IMPORT_C TCoeInputCapabilities(TUint aCapabilities, MCoeFepAwareTextEditor* aFepAwareTextEditor, MCoeCaptionRetrieverForFep* aCaptionRetrieverForFep); |
|
61 IMPORT_C TCoeInputCapabilities(TUint aCapabilities, MCoeFepAwareTextEditor* aFepAwareTextEditor, MCoeCaptionRetrieverForFep* aCaptionRetrieverForFep, TUid aFepUid, MCoeFepSpecificExtensions* aFepSpecificExtensions); |
|
62 IMPORT_C TCoeInputCapabilities(const TCoeInputCapabilities& aAnother); |
|
63 IMPORT_C TCoeInputCapabilities& operator=(const TCoeInputCapabilities& aAnother); |
|
64 IMPORT_C TBool operator==(const TCoeInputCapabilities& aAnother) const; |
|
65 IMPORT_C TBool operator!=(const TCoeInputCapabilities& aAnother) const; |
|
66 IMPORT_C void MergeWith(const TCoeInputCapabilities& aAnother); |
|
67 IMPORT_C void SetCapabilities(TUint aCapabilities); |
|
68 IMPORT_C TUint Capabilities() const; |
|
69 IMPORT_C TBool IsNone() const; |
|
70 IMPORT_C TBool SupportsWesternNumericIntegerPositive() const; |
|
71 IMPORT_C TBool SupportsWesternNumericIntegerNegative() const; |
|
72 IMPORT_C TBool SupportsWesternNumericReal() const; |
|
73 IMPORT_C TBool SupportsWesternAlphabetic() const; |
|
74 IMPORT_C TBool SupportsJapaneseHiragana() const; |
|
75 IMPORT_C TBool SupportsJapaneseKatakanaHalfWidth() const; |
|
76 IMPORT_C TBool SupportsJapaneseKatakanaFullWidth() const; |
|
77 IMPORT_C TBool SupportsDialableCharacters() const; |
|
78 IMPORT_C TBool SupportsSecretText() const; |
|
79 IMPORT_C TBool SupportsAllText() const; |
|
80 IMPORT_C TBool SupportsNavigation() const; |
|
81 IMPORT_C MCoeFepAwareTextEditor* FepAwareTextEditor() const; |
|
82 IMPORT_C MCoeCaptionRetrieverForFep* CaptionRetrieverForFep() const; |
|
83 IMPORT_C MCoeFepSpecificExtensions* FepSpecificExtensions(TUid aFepUid) const; |
|
84 IMPORT_C MObjectProvider* ObjectProvider() const; |
|
85 IMPORT_C void SetObjectProvider(MObjectProvider* aObjectProvider); |
|
86 };</codeblock> <p>The following code initializes <codeph>inputCapabilities</codeph> to |
|
87 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 |
|
88 virtual functions. </p> <p>By calling <xref href="GUID-BB7D0D56-1713-3DC0-BDA0-3CA1F0462BE2.dita"><apiname>TCoeInputCapabilities</apiname></xref>'s |
|
89 inquiry functions, the FEP can vary its behaviour according to the input capabilities |
|
90 of the target control. The <codeph>Supports</codeph> <i>Xxxxx</i> <codeph>()</codeph> member |
|
91 functions indicate what sort of key events should be sent by the FEP to the |
|
92 target control. It is important for the FEP to behave appropriately for the |
|
93 capabilities of the target control(s). For example, a FEP should not allow |
|
94 the user to compose a large amount of text, only to pass it on to a control |
|
95 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, |
|
96 a NULL return value indicates that the interface is not supported by any of |
|
97 the currently focused controls. </p> <p> <xref href="GUID-A5D563D6-A99A-31DF-B844-5F94EF5FFE87.dita"><apiname>MCoeFepAwareTextEditor</apiname></xref> (which |
|
98 is defined in <filepath>epoc32\include\FEPBASE.H</filepath>) is an important |
|
99 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 |
|
100 interaction with text editor controls</xref> below. </p> <p> <xref href="GUID-68C16461-68A4-37D2-888E-DD4A6917442A.dita"><apiname>MCoeCaptionRetrieverForFep</apiname></xref>, |
|
101 which is also defined in <filepath>epoc32\include\FEPBASE.H</filepath>, has |
|
102 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. |
|
103 An example of a caption is the non-editable prompt displayed alongside each |
|
104 item in a dialog. </p> <p> <xref href="GUID-03D3A775-F899-30F1-8A4F-25D60439C11E.dita"><apiname>MCoeFepSpecificExtensions</apiname></xref> is |
|
105 declared in <filepath>epoc32\include\COEINPUT.H</filepath> within the scope |
|
106 of the <xref href="GUID-BB7D0D56-1713-3DC0-BDA0-3CA1F0462BE2.dita"><apiname>TCoeInputCapabilities</apiname></xref> class, although it is not |
|
107 defined by any component in Symbian OS. It is to be defined by concrete FEPs |
|
108 rather than by the FEP architecture. The intention of this is to allow applications |
|
109 to communicate specialized input capabilities with a particular FEP that they |
|
110 know about. The concrete FEP would define the class in a public header file |
|
111 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 |
|
112 which takes a <xref href="GUID-03D3A775-F899-30F1-8A4F-25D60439C11E.dita"><apiname>MCoeFepSpecificExtensions</apiname></xref> pointer, and also |
|
113 the inquiry function returning a <xref href="GUID-03D3A775-F899-30F1-8A4F-25D60439C11E.dita"><apiname>MCoeFepSpecificExtensions</apiname></xref> pointer |
|
114 both require the UID of the FEP defining this class to be passed. This is |
|
115 to ensure that the FEP and the application are both assuming the same definition |
|
116 of the <xref href="GUID-03D3A775-F899-30F1-8A4F-25D60439C11E.dita"><apiname>MCoeFepSpecificExtensions</apiname></xref> class. </p></section> |
|
117 </conbody></concept> |