|
1 /* |
|
2 * Copyright (c) 2007-2009 Nokia Corporation and/or its subsidiary(-ies). |
|
3 * All rights reserved. |
|
4 * This component and the accompanying materials are made available |
|
5 * under the terms of "Eclipse Public License v1.0" |
|
6 * which accompanies this distribution, and is available |
|
7 * at the URL "http://www.eclipse.org/legal/epl-v10.html". |
|
8 * |
|
9 * Initial Contributors: |
|
10 * Nokia Corporation - initial contribution. |
|
11 * |
|
12 * Contributors: |
|
13 * |
|
14 * Description: Interface class for AP2 |
|
15 * |
|
16 */ |
|
17 |
|
18 |
|
19 /** |
|
20 * @file ActivePalette2UI.h |
|
21 * Interface class for AP2 |
|
22 */ |
|
23 |
|
24 #ifndef _ACTIVE_PALETTE_2_UI_H |
|
25 #define _ACTIVE_PALETTE_2_UI_H |
|
26 |
|
27 |
|
28 #include <e32std.h> |
|
29 |
|
30 class CCoeControl; |
|
31 class CHuiControl; |
|
32 class CBitmapContext; |
|
33 class MActivePalette2Observer; |
|
34 class TActivePalette2NavigationKeys; |
|
35 class TActivePalette2ItemVisible; |
|
36 |
|
37 /** |
|
38 * The interface for the Active Palette. The ActivePalette2Factory is used to instantiate |
|
39 * objects that provide this interface. |
|
40 */ |
|
41 class MActivePalette2UI |
|
42 { |
|
43 public: |
|
44 /** |
|
45 * Installs an item to the AP. |
|
46 * @param aItemVisible The ID and visibility of the new item |
|
47 * @param aPluginUid The UID of the plugin to handle this item |
|
48 * @param aCustomDataDes Descriptor data to pass to the plugin |
|
49 * @return Standard error code |
|
50 */ |
|
51 virtual TInt InstallItemL(const TActivePalette2ItemVisible& aItemVisible, |
|
52 const TUid& aPluginUid, |
|
53 const TDesC8& aCustomDataDes) = 0; |
|
54 |
|
55 /** |
|
56 * Installs an item to the AP. |
|
57 * @param aItemVisible The ID and visibility of the new item |
|
58 * @param aPluginUid The UID of the plugin to handle this item |
|
59 * @param aCustomDataInt Integer data to pass to the plugin |
|
60 * @return Standard error code |
|
61 */ |
|
62 virtual TInt InstallItemL(const TActivePalette2ItemVisible& aItemVisible, |
|
63 const TUid& aPluginUid, |
|
64 TInt aCustomDataInt = 0) = 0; |
|
65 |
|
66 /** |
|
67 * Installs an item to the AP. |
|
68 * @param aItemVisible The ID and visibility of the new item |
|
69 * @param aPluginUid The UID of the plugin to handle this item |
|
70 * @param aCustomDataInt Integer data to pass to the plugin |
|
71 * @param aCustomDataDes Descriptor data to pass to the plugin |
|
72 * @return Standard error code |
|
73 */ |
|
74 virtual TInt InstallItemL(const TActivePalette2ItemVisible& aItemVisible, |
|
75 const TUid& aPluginUid, |
|
76 TInt aCustomDataInt, |
|
77 const TDesC8& aCustomDataDes) = 0; |
|
78 |
|
79 /** |
|
80 * Removes an item |
|
81 * @param aItemId The resource ID of the item to install |
|
82 * @return Standard error code |
|
83 */ |
|
84 virtual TInt RemoveItem(TInt aItemId) = 0; |
|
85 |
|
86 /** |
|
87 * Sets the visibility of an item |
|
88 * @param aItemId The item's ID |
|
89 * @param aIsVisible The visibility state |
|
90 * @return Standard error code |
|
91 */ |
|
92 virtual TInt SetItemVisibility(TInt aItemId, TBool aIsVisible) = 0; |
|
93 |
|
94 /** |
|
95 * Find out the visibility of a specified item |
|
96 * @param aItemId The item's ID |
|
97 * @param aIsVisible On return, indicates the visibility of the item |
|
98 * @return Standard error code |
|
99 */ |
|
100 virtual TInt GetItemVisibility(TInt aItemId, TBool& aIsVisible) const = 0; |
|
101 |
|
102 /** |
|
103 * Gets the list of currently installed items. |
|
104 * The list will include all items, both visible and invisible. |
|
105 * @see SetItemList() |
|
106 * |
|
107 * @param aItemVisibleList On return, will contain the item list. |
|
108 * @return Standard error code |
|
109 */ |
|
110 virtual TInt GetItemList(RArray<TActivePalette2ItemVisible>& aItemVisibleList) const = 0; |
|
111 |
|
112 /** |
|
113 * Sets the order and visibility of installed items. |
|
114 * aItemVisibleList may be incomplete (i.e. not all installed item IDs must be present). |
|
115 * In this case, the non-specified items will be shuffled down to the end of the AP, |
|
116 * whilst retaining their relative order. |
|
117 * If the item that was in focus before the call is still visible, it retains the focus, |
|
118 * else the first visible item gains focus. |
|
119 * |
|
120 * @see GetItemList() |
|
121 * |
|
122 * @param aItemVisibleList The list describing the order and visibility of the items |
|
123 * @return Standard error code |
|
124 */ |
|
125 virtual TInt SetItemList(const RArray<TActivePalette2ItemVisible>& aItemVisibleList) = 0; |
|
126 |
|
127 /** |
|
128 * Sends a message to the specified item's handling plugin |
|
129 * @param aItemId The item's ID |
|
130 * @param aMessageId Message ID |
|
131 * @param aDataDes Custom data passed as a descriptor |
|
132 * @return Error code |
|
133 */ |
|
134 virtual TInt SendMessage(TInt aItemId, TInt aMessageId, const TDesC8& aDataDes) = 0; |
|
135 |
|
136 /** |
|
137 * Sends a message to the specified item's handling plugin |
|
138 * @param aItemId The item's ID |
|
139 * @param aMessageId Message ID |
|
140 * @param aDataInt Custom data passed as an integer |
|
141 * @return Standard error code |
|
142 */ |
|
143 virtual TInt SendMessage(TInt aItemId, TInt aMessageId, TInt aDataInt) = 0; |
|
144 |
|
145 /** |
|
146 * Gets the currently focussed item |
|
147 * @param aItemId On return, will contain the ID of the item in focus |
|
148 * @return Standard error code |
|
149 */ |
|
150 virtual TInt GetCurrentItem(TInt& aItemId) const = 0; |
|
151 |
|
152 /** |
|
153 * Sets the currently focussed item |
|
154 * @param aItemId The ID of the item to focus |
|
155 * @return Standard error code |
|
156 */ |
|
157 virtual TInt SetCurrentItem(TInt aItemId) = 0; |
|
158 |
|
159 /** |
|
160 * Hides or shows the palette. |
|
161 * After calling this function, and until the transition (if any) is complete, the AP will |
|
162 * not accept any user input. |
|
163 * |
|
164 * @see SetPaletteVisibilityAnimationDuration() |
|
165 * @see GetPaletteVisibilityAnimationDuration() |
|
166 * |
|
167 * @param aVisible If ETrue, shows the AP, otherwise hides it |
|
168 * @param aAnimated Whether the transition should be animated. If not, the change is made as soon |
|
169 * as aDelayedStartMilliseconds has passed |
|
170 * @param aDelayedStartMilliseconds An optional pause before the transition begins. |
|
171 * @return Standard error code |
|
172 */ |
|
173 virtual TInt SetPaletteVisibility(TBool aVisible, TBool aAnimated, TInt aDelayedStartMilliseconds = 0) = 0; |
|
174 |
|
175 /** |
|
176 * Sets the duration of the SetPaletteVisibility animation. |
|
177 * |
|
178 * @see SetPaletteVisibility() |
|
179 * @see GetPaletteVisibilityAnimationDuration() |
|
180 * |
|
181 * @param aTimeInMilliseconds How long the animation should take, in milliseconds |
|
182 * @return Standard error code |
|
183 */ |
|
184 virtual TInt SetPaletteVisibilityAnimationDuration(TInt aTimeInMilliseconds) = 0; |
|
185 |
|
186 /** |
|
187 * Gets the duration of the SetPaletteVisibility animation. |
|
188 * |
|
189 * @see SetPaletteVisibility() |
|
190 * @see SetPaletteVisibilityAnimationDuration() |
|
191 * |
|
192 * @param aTimeInMilliseconds On return, will contain how long the animation will take, in milliseconds |
|
193 * @return Standard error code |
|
194 */ |
|
195 virtual TInt GetPaletteVisibilityAnimationDuration(TInt& aTimeInMilliseconds) const = 0; |
|
196 |
|
197 /** |
|
198 * Move the AP. |
|
199 * @param aTopLeft Point specifying where to move the AP to |
|
200 */ |
|
201 virtual void LocateTo(const TPoint& aTopLeft) = 0; |
|
202 |
|
203 /** |
|
204 * Returns the top left point of the AP |
|
205 * @return A TPoint indicating the top left point of the AP |
|
206 */ |
|
207 virtual TPoint Location() const = 0; |
|
208 |
|
209 /** |
|
210 * Returns the underlying CCoeControl, if any. |
|
211 * @return A valid CCoeControl pointer if the underlying implementation is a CCoeControl; NULL otherwise. |
|
212 */ |
|
213 virtual CCoeControl* CoeControl() = 0; |
|
214 |
|
215 /** |
|
216 * Returns the underlying CHuiControl, if any. |
|
217 * @return A valid CHuiControl pointer if the underlying implementation is a CHuiControl; NULL otherwise. |
|
218 */ |
|
219 virtual CHuiControl* HuiControl() = 0; |
|
220 |
|
221 /** |
|
222 * Sets the graphics context to draw to. |
|
223 * If called with aGc being non-NULL, the AP will be rendered to the supplied context |
|
224 * in future drawing operations. If called with NULL, the screen's GC will be used instead. |
|
225 * Calls to this will only have an effect if a CCoeControl-based AP has been created. |
|
226 * |
|
227 * @see RenderActivePalette() |
|
228 * |
|
229 * @param aGc The graphics context to draw to |
|
230 */ |
|
231 virtual void SetGc(CBitmapContext* aGc = NULL) = 0; |
|
232 |
|
233 /** |
|
234 * Forces the AP to draw itself to the supplied aRect. |
|
235 * Uses the context previously set by SetGc, if any; uses the screen's context otherwise. |
|
236 * Calls to this will only have an effect if a CCoeControl-based AP has been created. |
|
237 * |
|
238 * @see SetGc() |
|
239 * |
|
240 * @param aRect The rect to render to |
|
241 */ |
|
242 virtual void RenderActivePalette(const TRect& aRect) const = 0; |
|
243 |
|
244 /** |
|
245 * Sets the active palette observer used for callbacks. Calls to this function replace the previously |
|
246 * set observer. SetObserver(NULL) may be called to remove the previously set observer without specifying |
|
247 * a new observer |
|
248 * |
|
249 * @param aObserver The new observer to use |
|
250 */ |
|
251 virtual void SetObserver(MActivePalette2Observer* aObserver) = 0; |
|
252 |
|
253 /** |
|
254 * Gets a list of available external plugins. |
|
255 * |
|
256 * @param aPluginList On return, will contain a list a valid plugin UIDs |
|
257 * @return Standard error code |
|
258 */ |
|
259 virtual TInt GetAvailablePlugins(RArray<TUid>& aPluginList) const = 0; |
|
260 |
|
261 /** |
|
262 * Sets the keys the user will press to navigate the AP. This sets the scancodes responded to when |
|
263 * CCoeControl::OfferKeyEvent, CHuiControl::OfferEvent or similar are called. |
|
264 * |
|
265 * @param aNavigationKeys The new navigation keys |
|
266 */ |
|
267 virtual void SetNavigationKeys(const TActivePalette2NavigationKeys& aNavigationKeys) = 0; |
|
268 |
|
269 /** |
|
270 * Destructor. Will clean up all installed plugins. |
|
271 */ |
|
272 virtual ~MActivePalette2UI() {}; |
|
273 }; |
|
274 |
|
275 #endif // _ACTIVE_PALETTE_2_UI_H |