|
1 /* |
|
2 * Copyright (c) 2002-2007 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: EIKON button group base class definitions. |
|
15 * |
|
16 */ |
|
17 |
|
18 |
|
19 #ifndef __EIKBTGRP_H__ |
|
20 #define __EIKBTGRP_H__ |
|
21 |
|
22 #include <e32std.h> |
|
23 |
|
24 class CCoeControl; |
|
25 class CEikCommandButton; |
|
26 class CFbsBitmap; |
|
27 class MEikCommandObserver; |
|
28 |
|
29 /** |
|
30 * Abstract base class for EIKON button group. |
|
31 * |
|
32 * @lib eikcoctl.lib |
|
33 * @since S60 0.9 |
|
34 * |
|
35 * @internal |
|
36 */ |
|
37 class MEikButtonGroup |
|
38 { |
|
39 public: |
|
40 /** |
|
41 * Deletes the object. |
|
42 */ |
|
43 void Release(); |
|
44 |
|
45 /** |
|
46 * Sets a command button's bitmap, text and command ID. |
|
47 * |
|
48 * @param aPosition The position within the button group of the button to change. |
|
49 * @param aCommandId Command ID the button will send. |
|
50 * @param aText The text for the button. |
|
51 * @param aBitmap The bitmap for the button. |
|
52 * @param aMask The mask bitmap for aBitmap. |
|
53 */ |
|
54 virtual void SetCommandL( |
|
55 TInt aPosition, |
|
56 TInt aCommandId, |
|
57 const TDesC* aText, |
|
58 const CFbsBitmap* aBitmap, |
|
59 const CFbsBitmap* aMask) = 0; |
|
60 |
|
61 /** |
|
62 * Sets a command button's bitmap, text label and command ID. |
|
63 * The bitmap, mask, text and command ID are all read from resource. |
|
64 * |
|
65 * @param aPosition The position within the button group of the button to change. |
|
66 * @param aResourceId Resource ID specifying the text, bitmaps and command ID. |
|
67 */ |
|
68 virtual void SetCommandL(TInt aPosition, |
|
69 TInt aResourceId) = 0; |
|
70 |
|
71 /** |
|
72 * Initialises the group of command buttons from a resource. |
|
73 * |
|
74 * @param aResourceId ID of the resource structure specifying the command buttons. |
|
75 */ |
|
76 virtual void SetCommandSetL(TInt aResourceId) = 0; |
|
77 |
|
78 /** |
|
79 * Adds a command button with a command ID and a label containing both a bitmap and text. |
|
80 * |
|
81 * @param aPosition The position in the button group for the new button. |
|
82 * @param aCommandId Command ID for the new button. |
|
83 * @param aText Text for the button. |
|
84 * @param aBitmap Bitmap for the button. |
|
85 * @param aMask Mask bitmap for aBitmap. |
|
86 */ |
|
87 virtual void AddCommandL( |
|
88 TInt aPosition, |
|
89 TInt aCommandId, |
|
90 const TDesC* aText, |
|
91 const CFbsBitmap* aBitmap, |
|
92 const CFbsBitmap* aMask) = 0; |
|
93 |
|
94 /** |
|
95 * Pushes a command button with text, bitmap, mask and a command ID onto a |
|
96 * position's button stack. |
|
97 * |
|
98 * @param aPosition The position in the button group at which to add the command button. |
|
99 * @param aCommandId Command ID the button will send. |
|
100 * @param aText Text for the button. |
|
101 * @param aBitmap Bitmap for the button. |
|
102 * @param aMask Mask bitmap for aBitmap. |
|
103 */ |
|
104 virtual void AddCommandToStackL( |
|
105 TInt aPosition, |
|
106 TInt aCommandId, |
|
107 const TDesC* aText, |
|
108 const CFbsBitmap* aBitmap, |
|
109 const CFbsBitmap* aMask) = 0; |
|
110 |
|
111 /** |
|
112 * Pushes a command button onto a position's button stack. |
|
113 * The text, bitmap, mask and command ID are all read from resource. |
|
114 * |
|
115 * @param aPosition The position in the button group at which to push the command button. |
|
116 * @param aResourceId ID of a resource specifying the text, bitmaps and command ID. |
|
117 */ |
|
118 virtual void AddCommandToStackL(TInt aPosition, |
|
119 TInt aResourceId) = 0; |
|
120 |
|
121 /** |
|
122 * As with SetCommandL() but for a set of buttons, also allows the previous |
|
123 * command button to be retrieved by calling RemoveCommand(). |
|
124 * |
|
125 * @param aResourceId Resource describing the set of command buttons. |
|
126 */ |
|
127 virtual void AddCommandSetToStackL(TInt aResourceId) = 0; |
|
128 |
|
129 /** |
|
130 * Sets the default command ID for buttons in this button group. |
|
131 * |
|
132 * @param aCommandId Command to issue if no other is specified. |
|
133 */ |
|
134 virtual void SetDefaultCommand(TInt aCommandId) = 0; |
|
135 |
|
136 /** |
|
137 * Calculates minimum size required to display the buttons defined in the |
|
138 * specified resource structure. |
|
139 * |
|
140 * @param aResourceId The ID of the resource structure describing the button group. |
|
141 * @return Minimum size required to display the button group defined in the specified |
|
142 * resource structure. |
|
143 */ |
|
144 virtual TSize CalcMinimumSizeL(TInt aResourceId) = 0; |
|
145 |
|
146 /** |
|
147 * Removes the command identified by aCommandId, in position aPosition in the |
|
148 * group, from the command stack. Automatically retrieves the previous command |
|
149 * details. Commands are added to the stack by calling AddCommandToStackL. |
|
150 * |
|
151 * @param aPosition The position in the button group from which to remove the |
|
152 * command button. |
|
153 * @param aCommandId Command ID. |
|
154 */ |
|
155 virtual void RemoveCommandFromStack(TInt aPosition, |
|
156 TInt aCommandId) = 0; |
|
157 |
|
158 /** |
|
159 * Returns the command position by command id. |
|
160 * |
|
161 * @param aCommandId The button's command id. |
|
162 * @return The command position in the button group. |
|
163 */ |
|
164 virtual TInt CommandPos(TInt aCommandId) const = 0; |
|
165 |
|
166 /** |
|
167 * Dims or undims a button without drawing it. |
|
168 * |
|
169 * @param aCommandId Command ID of the button to change. |
|
170 * @param aDimmed ETrue to dim the specified command. EFalse to undim the specified command. |
|
171 */ |
|
172 virtual void DimCommand(TInt aCommandId, |
|
173 TBool aDimmed) = 0; |
|
174 |
|
175 /** |
|
176 * Determines whether the button with the specified command ID is dimmed. |
|
177 * |
|
178 * @param aCommandId The command ID. |
|
179 * @return ETrue if the specified command is dimmed. EFalse if the specified command is |
|
180 * not dimmed. |
|
181 */ |
|
182 virtual TBool IsCommandDimmed(TInt aCommandId) const = 0; |
|
183 |
|
184 /** |
|
185 * Makes the button with the specified id either visible, or invisible. |
|
186 * |
|
187 * @param aCommandId Specifies the button to alter. |
|
188 |
|
189 * @param aVisible ETrue to make the specified button visible. EFalse to make the specified |
|
190 * button invisible. |
|
191 */ |
|
192 virtual void MakeCommandVisible(TInt aCommandId, |
|
193 TBool aVisible) = 0; |
|
194 |
|
195 /** |
|
196 * Tests whether the button with the specified command ID is visible. |
|
197 * |
|
198 * @param aCommandId Specifies the button. |
|
199 * @return ETrue if the specified button is visible. EFalse if the specified button is |
|
200 * not visible. |
|
201 */ |
|
202 virtual TBool IsCommandVisible(TInt aCommandId) const = 0; |
|
203 |
|
204 /** |
|
205 * Animates the button with the specified id. |
|
206 * |
|
207 * @param aCommandId The button to animate. |
|
208 */ |
|
209 IMPORT_C virtual void AnimateCommand(TInt aCommandId); |
|
210 |
|
211 /** |
|
212 * Returns the button group as a control. |
|
213 * |
|
214 * @return The button group as a control. |
|
215 */ |
|
216 virtual CCoeControl* AsControl() = 0; |
|
217 |
|
218 /** |
|
219 * Returns the button group as a control. |
|
220 * |
|
221 * @return The button group as a control. |
|
222 */ |
|
223 virtual const CCoeControl* AsControl() const = 0; |
|
224 |
|
225 /** |
|
226 * Sets the boundary rectangle for externally-positioned button groups. |
|
227 * For use by EExternal button groups only. |
|
228 * |
|
229 * @param aBoundingRect The boundary rectangle to use. The button group attaches itself |
|
230 * to the inside of this rectangle. |
|
231 */ |
|
232 virtual void SetBoundingRect(const TRect& aBoundingRect) = 0; |
|
233 |
|
234 /** |
|
235 * Subtracts the area occupied by the button group from the specified bounding rectangle. |
|
236 * This method should be used in preference to querying the container's area at all times. |
|
237 * For use by EExternal button groups only. |
|
238 * |
|
239 * @param aBoundingRect Rectangle to be modified. |
|
240 */ |
|
241 virtual void ReduceRect(TRect& aBoundingRect) const = 0; |
|
242 |
|
243 /** |
|
244 * Returns a group control (a button) as a control. |
|
245 * |
|
246 * @param aCommandId The button's command id. |
|
247 * @return The group control as a control. |
|
248 */ |
|
249 virtual CCoeControl* GroupControlById(TInt aCommandId) const = 0; |
|
250 |
|
251 /** |
|
252 * Returns a group control (a button) as a command button. |
|
253 * |
|
254 * @param aCommandId The button's command id. |
|
255 * @return The group control as a command button. |
|
256 */ |
|
257 virtual CEikCommandButton* GroupControlAsButton(TInt aCommandId) const = 0; |
|
258 |
|
259 /** |
|
260 * Returns the command id by position. |
|
261 * |
|
262 * @param aCommandPos The command's position. |
|
263 * @return The command id. |
|
264 */ |
|
265 virtual TInt CommandId(TInt aCommandPos) const = 0; |
|
266 |
|
267 /** |
|
268 * Gets the total number of buttons currently present in the group. |
|
269 * |
|
270 * @return The number of buttons. |
|
271 */ |
|
272 virtual TInt ButtonCount() const = 0; |
|
273 |
|
274 /** |
|
275 * Gets the button group flags. |
|
276 * |
|
277 * @return The button group flags. |
|
278 */ |
|
279 virtual TUint ButtonGroupFlags() const = 0; |
|
280 |
|
281 /** |
|
282 * Sets the middle softkey command observer. |
|
283 * |
|
284 * @param aCommandObserver The middle softkey command observer. |
|
285 */ |
|
286 virtual void SetMSKCommandObserver(MEikCommandObserver* aCommandObserver) = 0; |
|
287 |
|
288 /** |
|
289 * Dims (but doesn't draw) the button with position aPosition. |
|
290 * |
|
291 * @param aPosition The position for command to be dimmed. |
|
292 * @param aDimmed ETrue for dimming. |
|
293 */ |
|
294 virtual void DimCommandByPosition(TInt aPosition, |
|
295 TBool aDimmed) = 0; |
|
296 |
|
297 /** |
|
298 * Returns ETrue if the button with position aPosition is dimmed. |
|
299 * |
|
300 * @param aPosition The position for command to be checked. |
|
301 * @return The state of the button. |
|
302 */ |
|
303 virtual TBool IsCommandDimmedByPosition(TInt aPosition) const = 0; |
|
304 |
|
305 /** |
|
306 * Sets the the button with position aPosition to be visible if aVisible is ETrue. |
|
307 * |
|
308 * @param aPosition The position for command to be made visible. |
|
309 * @param aVisible EFalse for making button invisible. |
|
310 */ |
|
311 virtual void MakeCommandVisibleByPosition(TInt aPosition, |
|
312 TBool aVisible) = 0; |
|
313 |
|
314 /** |
|
315 * Returns ETrue if the button with position aPosition is visible. |
|
316 * |
|
317 * @param aPosition The position for command to be checked. |
|
318 * @return The state of the button. |
|
319 */ |
|
320 virtual TBool IsCommandVisibleByPosition(TInt aPosition) const = 0; |
|
321 |
|
322 /** |
|
323 * Animates the button with position aPosition. |
|
324 * |
|
325 * @param aPosition The position for command to be animated. |
|
326 */ |
|
327 virtual void AnimateCommandByPosition(TInt aPosition) = 0; |
|
328 |
|
329 private: |
|
330 IMPORT_C void Reserved_1(); |
|
331 }; |
|
332 |
|
333 |
|
334 /** |
|
335 * Extends needed functions for enhanced cba. |
|
336 * |
|
337 * @internal |
|
338 * @since S60 3.0 |
|
339 */ |
|
340 class MEikEnhancedButtonGroup : public MEikButtonGroup |
|
341 { |
|
342 public: |
|
343 /** |
|
344 * Used to offer list of commands for softkeys. |
|
345 * |
|
346 * @param aCommandList A list of command ids to be offered for softkeys. |
|
347 */ |
|
348 IMPORT_C virtual void OfferCommandListL(const RArray<TInt>& aCommandList) = 0; |
|
349 |
|
350 /** |
|
351 * Used to offer list of commands for softkeys. |
|
352 * |
|
353 * @param aResourceId Id for CBA resource that defines enhanced cba buttons. |
|
354 */ |
|
355 IMPORT_C virtual void OfferCommandListL(const TInt aResourceId) = 0; |
|
356 |
|
357 /** |
|
358 * Used to check if a certain command have been approved to the current command set. |
|
359 * |
|
360 * @param aCommandId The id for command which existence should be checked. |
|
361 * @return ETrue if command is in control group, otherwise EFalse. |
|
362 */ |
|
363 IMPORT_C virtual TBool IsCommandInGroup(const TInt aCommandId) const = 0; |
|
364 |
|
365 /** |
|
366 * Replace existing command with a new command. |
|
367 * |
|
368 * @param aCommandId Id for command that should be replaced. |
|
369 * @param aResourceId Resource id for new enhanced cba button. |
|
370 */ |
|
371 IMPORT_C virtual void ReplaceCommand(const TInt aCommandId, const TInt aResourceId) = 0; |
|
372 }; |
|
373 |
|
374 #endif // __EIKBTGRP_H__ |