|
1 /* |
|
2 * Copyright (c) 1997-1999 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: |
|
15 * |
|
16 */ |
|
17 |
|
18 |
|
19 #if !defined(__EIKMENUP_H__) |
|
20 #define __EIKMENUP_H__ |
|
21 |
|
22 #if !defined(__EIKBCTRL_H__) |
|
23 #include <eikbctrl.h> |
|
24 #endif |
|
25 |
|
26 #if !defined(__EIKDEF_H__) |
|
27 #include <eikdef.h> |
|
28 #endif |
|
29 |
|
30 #if !defined(__EIKSBOBS_H__) |
|
31 #include <eiksbobs.h> // for TEikScrollEvent |
|
32 #endif |
|
33 |
|
34 #include <bidi.h> |
|
35 |
|
36 // FORWARD DECLARATIONS |
|
37 class MEikMenuObserver; |
|
38 class CEikHotKeyTable; |
|
39 class CEikMenuPaneTitle; |
|
40 class CEikButtonBase; |
|
41 class CEikScrollBarFrame; |
|
42 class CEikScrollBar; |
|
43 class TEikScrollBarModel; |
|
44 class CGulIcon; |
|
45 class CEikMenuPaneExtension ; |
|
46 class CEikCba; |
|
47 class CAknItemActionMenuData; |
|
48 |
|
49 // CONSTANTS |
|
50 const TInt KScaleableTextSeparator = 0x0001; |
|
51 |
|
52 /** |
|
53 * A helper class for extending CEikMenuPaneItem without breaking binary |
|
54 * compability. |
|
55 */ |
|
56 class CExtendedItemData : public CBase |
|
57 { |
|
58 |
|
59 public: |
|
60 |
|
61 /** |
|
62 * Destructor. |
|
63 */ |
|
64 ~CExtendedItemData(); |
|
65 |
|
66 public: |
|
67 |
|
68 /** Two packaked bitmaps: bitmap icon and mask for it. */ |
|
69 CGulIcon* iIcon; |
|
70 |
|
71 /** Scalable text buffer. */ |
|
72 HBufC* iScaleableText; |
|
73 }; |
|
74 |
|
75 |
|
76 /** |
|
77 * The @c CEikMenuPaneItem class encapsulates the data needed to define a menu |
|
78 * pane item and provides some of the functionality required to display the |
|
79 * item. |
|
80 * |
|
81 * @since ER5U |
|
82 */ |
|
83 class CEikMenuPaneItem : public CBase |
|
84 { |
|
85 |
|
86 public: |
|
87 |
|
88 /** Struct to menu pane item. */ |
|
89 struct SData |
|
90 { |
|
91 |
|
92 /** Nominal text length.*/ |
|
93 enum { ENominalTextLength=40 }; |
|
94 |
|
95 /** |
|
96 * ID of the command to issue when the menu item using this @c SData is |
|
97 * selected. |
|
98 */ |
|
99 TInt iCommandId; |
|
100 |
|
101 /** Resource ID of a menu pane to cascade from this item. */ |
|
102 TInt iCascadeId; |
|
103 |
|
104 /** |
|
105 * Flags used internally by @c CEikMenuPane and accessible through |
|
106 * functions such as @c CEikMenuPane::SetItemDimmed(). |
|
107 */ |
|
108 TInt iFlags; |
|
109 |
|
110 /** The text buffer displayed in the main area of the menu item. */ |
|
111 TBuf<ENominalTextLength> iText; // less than this actually stored |
|
112 |
|
113 /** |
|
114 * Additional descriptive text about the item. This is used by @c |
|
115 * CEikMenuPane to display hotkey names. |
|
116 */ |
|
117 TBuf<1> iExtraText; |
|
118 }; |
|
119 |
|
120 public: |
|
121 |
|
122 /** |
|
123 * C++ default constructor. |
|
124 */ |
|
125 IMPORT_C CEikMenuPaneItem(); |
|
126 |
|
127 /** |
|
128 * Destructor. |
|
129 */ |
|
130 IMPORT_C ~CEikMenuPaneItem(); |
|
131 |
|
132 /** |
|
133 * Sets a menu item icon. This replaces any icon already set for the menu |
|
134 * item. |
|
135 * |
|
136 * @param aIcon Menu item icon consisting of a picture bitmap and a mask |
|
137 * bitmap. |
|
138 */ |
|
139 IMPORT_C void SetIcon(CGulIcon* aIcon); |
|
140 |
|
141 /** |
|
142 * Draws the menu item icon. |
|
143 * |
|
144 * @param aGc Graphics context to which the icon is drawn. |
|
145 * @param aRect Rectangle in which the icon is drawn. |
|
146 * @param aDimmed If @c ETrue the icon is drawn dimmed. |
|
147 * @param aBitmapSpaceRequired Length of one side of the square required to |
|
148 * contain the bitmap. |
|
149 */ |
|
150 IMPORT_C void DrawItemIcon(CWindowGc& aGc, |
|
151 TRect aRect, |
|
152 TBool aDimmed, |
|
153 TInt aBitmapSpaceRequired) const; |
|
154 |
|
155 /** |
|
156 * Construct an icon from bitmaps. |
|
157 * |
|
158 * Constructs a new icon for the menu item, taking ownership of the picture |
|
159 * bitmap aBitmap and the mask bitmap aMask unless the bitmaps are |
|
160 * externally owned. |
|
161 * |
|
162 * @param aBitmap Picture bitmap. |
|
163 * @param aMask Mask bitmap. |
|
164 */ |
|
165 IMPORT_C void CreateIconL(CFbsBitmap* aBitmap, |
|
166 CFbsBitmap* aMask); |
|
167 |
|
168 /** |
|
169 * Gets a pointer to the menu item's icon picture bitmap. This does not |
|
170 * imply transfer of ownership. |
|
171 * |
|
172 * @return Picture bitmap. |
|
173 */ |
|
174 IMPORT_C CFbsBitmap* IconBitmap() const; |
|
175 |
|
176 /** |
|
177 * Gets a pointer to the menu item's icon mask bitmap. This does not imply |
|
178 * transfer of ownership. |
|
179 * |
|
180 * @return Mask bitmap. |
|
181 */ |
|
182 IMPORT_C CFbsBitmap* IconMask() const; |
|
183 |
|
184 /** |
|
185 * Sets icon bitmap ownership. |
|
186 * Sets the menu item's icon bitmaps as externally owned if @c |
|
187 * aOwnedExternally is @c ETrue. |
|
188 * |
|
189 * @param aOwnedExternally If @c ETrue bitmaps are set as externally owned. |
|
190 * @c If EFalse bitmaps are set as not being externally owned. |
|
191 */ |
|
192 IMPORT_C void SetBitmapsOwnedExternally(TBool aOwnedExternally); |
|
193 |
|
194 /** |
|
195 * Sets the picture bitmap. Transfers ownership unless the bitmaps are |
|
196 * already owned externally. |
|
197 * |
|
198 * @param aBitmap Picture bitmap. |
|
199 */ |
|
200 IMPORT_C void SetIconBitmapL(CFbsBitmap* aBitmap); |
|
201 |
|
202 /** |
|
203 * Sets the mask bitmap. Transfers ownership unless the bitmaps are already |
|
204 * owned externally. |
|
205 * |
|
206 * @param aMask Mask bitmap. |
|
207 */ |
|
208 IMPORT_C void SetIconMaskL(CFbsBitmap* aMask); |
|
209 |
|
210 /** |
|
211 * Returns scaleable text. If there isn't scaleable text available then |
|
212 * this method returns @c iData.iText. |
|
213 * |
|
214 * @return Pointer to TPtrC object that contains scaleable text. |
|
215 */ |
|
216 IMPORT_C TPtrC ScaleableText() const; |
|
217 |
|
218 /** |
|
219 * Sets scaleable text. @c iData.iText is set to first text version. |
|
220 * |
|
221 * @param aText Scalable text. |
|
222 */ |
|
223 IMPORT_C void SetScaleableTextL(const TDesC& aText); |
|
224 |
|
225 private: |
|
226 inline void CreateExtendedDataBlock(); |
|
227 inline TBool IsScaleableText(const TDesC& aText) const; |
|
228 TPtrC GetNominalText(const TDesC& aText); |
|
229 |
|
230 public: |
|
231 |
|
232 /** The y position of the menu pane item. */ |
|
233 TInt iPos; |
|
234 |
|
235 /** The menu pane item's hotkey text. */ |
|
236 TInt iHotKeyCode; |
|
237 |
|
238 /** Information from an SData struct. */ |
|
239 SData iData; |
|
240 |
|
241 private: |
|
242 CExtendedItemData* iExtendedData; |
|
243 }; |
|
244 |
|
245 |
|
246 inline void CEikMenuPaneItem::CreateExtendedDataBlock() |
|
247 { |
|
248 if (!iExtendedData) |
|
249 { |
|
250 TRAPD(err, ( iExtendedData = new (ELeave) CExtendedItemData() ) ); |
|
251 } |
|
252 } |
|
253 |
|
254 |
|
255 inline TBool CEikMenuPaneItem::IsScaleableText(const TDesC& aText) const |
|
256 { |
|
257 return aText.Locate( TChar( KScaleableTextSeparator ) ) != KErrNotFound; |
|
258 } |
|
259 |
|
260 |
|
261 /** |
|
262 * Menu panes are opened by activating the menu title |
|
263 * @c (CEikMenuPaneTitle / MENU_TITLE) which is displayed in the menu bar @c |
|
264 * (CEikMenuBar / MENU_BAR). They can also be cascaded from a menu item @c |
|
265 * (CEikMenuPaneItem / MENU_ITEM) or launched by a menu button @c |
|
266 * (CEikMenuButton). |
|
267 * |
|
268 * Menu panes may be defined using a @c MENU_PANE resource. |
|
269 */ |
|
270 class CEikMenuPane : public CEikBorderedControl |
|
271 { |
|
272 private: |
|
273 enum {ENothingSelected=-1}; |
|
274 class CMenuScroller; |
|
275 friend class CMenuScroller; |
|
276 friend class CEikMenuPaneExtension; |
|
277 public: |
|
278 |
|
279 /** The text to be displayed for a hotkey. */ |
|
280 typedef TBuf<20> THotKeyDisplayText; |
|
281 |
|
282 public: |
|
283 |
|
284 /** |
|
285 * This class provides a constructor to create an array of menu pane items |
|
286 * and a destructor to destroy an array of menu pane items. |
|
287 */ |
|
288 class CItemArray:public CArrayPtrFlat<CEikMenuPaneItem> |
|
289 { |
|
290 |
|
291 public: |
|
292 |
|
293 /** |
|
294 * C++ default constructor that creates a flat array of menu pane |
|
295 * items. |
|
296 */ |
|
297 IMPORT_C CItemArray(); |
|
298 |
|
299 /** |
|
300 * Destructor. |
|
301 */ |
|
302 IMPORT_C ~CItemArray(); |
|
303 |
|
304 /** |
|
305 * Appends @c CEikMenuPaneItem class object to array. |
|
306 * |
|
307 * @param aMenuItem The menu item to add. |
|
308 */ |
|
309 IMPORT_C void AddItemL(CEikMenuPaneItem* aMenuItem); |
|
310 }; |
|
311 |
|
312 public: |
|
313 |
|
314 /** |
|
315 * Destructor. |
|
316 */ |
|
317 IMPORT_C ~CEikMenuPane(); |
|
318 |
|
319 /** |
|
320 * C++ default constructor. Constructs a menu pane object with the |
|
321 * specified observer. |
|
322 * |
|
323 * @param aMenuObserver Menu observer. |
|
324 */ |
|
325 IMPORT_C CEikMenuPane(MEikMenuObserver* aMenuObserver); |
|
326 |
|
327 /** |
|
328 * Handles 2nd base construction. Completes construction of a menu pane object. |
|
329 * |
|
330 * @param aOwner Menu pane owner ( for cascade menu ). |
|
331 * @param aEditMenuObserver Observer for the edit menu. In default this is |
|
332 * @c NULL. |
|
333 */ |
|
334 IMPORT_C void ConstructL(CEikMenuPane* aOwner, |
|
335 MEikMenuObserver* aEditMenuObserver = NULL); |
|
336 |
|
337 /** |
|
338 * Destroys the menu pane's item array. |
|
339 */ |
|
340 IMPORT_C void Reset(); |
|
341 |
|
342 public: // framework |
|
343 |
|
344 /** |
|
345 * From @c CcoeControl. |
|
346 * |
|
347 * Handles key events offered to the menu by the control environment and |
|
348 * provides an appropriate implementation of @c |
|
349 * CCoeControl::OfferKeyEventL(). |
|
350 * |
|
351 * @param aKeyEvent The key event. |
|
352 * @param aType The type of key event: @c EEventKey, @c EEventKeyUp or @c |
|
353 * EEventKeyDown. |
|
354 */ |
|
355 IMPORT_C TKeyResponse OfferKeyEventL(const TKeyEvent& aKeyEvent, |
|
356 TEventCode aType); |
|
357 |
|
358 /** |
|
359 * From @c CcoeControl. |
|
360 * |
|
361 * Handles a pointer event on the menu. |
|
362 * |
|
363 * @param aPointerEvent The pointer event to handle. |
|
364 */ |
|
365 IMPORT_C void HandlePointerEventL(const TPointerEvent& aPointerEvent); |
|
366 |
|
367 /** |
|
368 * From @c CcoeControl. |
|
369 * |
|
370 * Gets the list of logical colours employed in the drawing of the control, |
|
371 * paired with an explanation of how they are used. Appends the list into |
|
372 * @c aColorUseList. |
|
373 * |
|
374 * @since 005u |
|
375 * @param aColorUseList The list of colours paired with explanations. |
|
376 */ |
|
377 IMPORT_C virtual void GetColorUseListL( |
|
378 CArrayFix<TCoeColorUse>& aColorUseList) const; |
|
379 |
|
380 /** |
|
381 * From @c CcoeControl. |
|
382 * |
|
383 * Handles a change to the menu's resources which are shared across the |
|
384 * environment. For example, colours or fonts. |
|
385 * |
|
386 * @since 005u |
|
387 * @param aType The type of resource that has changed. |
|
388 */ |
|
389 IMPORT_C virtual void HandleResourceChange(TInt aType); // not available before Release 005u |
|
390 |
|
391 private: // from base class |
|
392 |
|
393 /** |
|
394 * Not implemented. |
|
395 * |
|
396 * @param Not used. |
|
397 * @return NULL |
|
398 */ |
|
399 IMPORT_C void* ExtensionInterface( TUid aInterface ); |
|
400 |
|
401 public: // from MCoeInputObserver |
|
402 |
|
403 /** |
|
404 * From @c CCoeControl. |
|
405 * |
|
406 * Gets the list box’s input capabilities as set through the list box flags. |
|
407 * |
|
408 * @return List box input capabilities. |
|
409 */ |
|
410 IMPORT_C TCoeInputCapabilities InputCapabilities() const; |
|
411 |
|
412 protected: // from base class |
|
413 |
|
414 /** |
|
415 * From @c CCoeControl |
|
416 * |
|
417 * Draw a control called by window server. |
|
418 * |
|
419 * All controls, except blank controls, should implement this function. The |
|
420 * default implementation draws a blank control. This function is used for |
|
421 * window server-initiated redrawing of controls, and for some |
|
422 * application-initiated drawing. It should be implemented by each control, |
|
423 * but is only called from within @c CCoeControl's member functions, and |
|
424 * not from the derived class. For this reason it is a private member |
|
425 * function of @c CCoeControl. |
|
426 * |
|
427 * The rectangle aRect indicates the region of the control that needs to be |
|
428 * redrawn. The implementation of @c Draw() must always draw to every pixel |
|
429 * within this rectangle. |
|
430 * |
|
431 * @param aRect The region of the control to be redrawn. |
|
432 * Co-ordinates are relative to the control's origin (top left |
|
433 * corner). Optional, not used currently. |
|
434 */ |
|
435 IMPORT_C void Draw(const TRect& aRect) const; |
|
436 |
|
437 /** |
|
438 * From @c CCoeControl. |
|
439 * |
|
440 * Takes any action required when the menu pane gains or loses focus, |
|
441 * to change its appearance for example. |
|
442 * |
|
443 * @param aDrawNow If @c EDrawNow the menu pane is redrawn. If @c |
|
444 * ENoDrawNow the menu pane is not redrawn. |
|
445 */ |
|
446 IMPORT_C void FocusChanged(TDrawNow aDrawNow); |
|
447 |
|
448 /** |
|
449 * From @c CCoeControl. |
|
450 * |
|
451 * Constructs the menu pane using the specified resource reader. |
|
452 * Fills the menu item array with the list of menu items provided by the |
|
453 * resource file. |
|
454 * |
|
455 * @param aReader The resource reader to use. |
|
456 * @leave KErrNoMemory Memory allocation failure earlier construction. |
|
457 */ |
|
458 IMPORT_C void ConstructFromResourceL(TResourceReader& aReader); |
|
459 |
|
460 public: // new functions |
|
461 |
|
462 /** |
|
463 * Adds a menu item dynamically by creating a new menu item, setting its |
|
464 * data to @c aMenuItem and appending it to the pane's menu item array. |
|
465 * Updates the menu's scroll bar to take account of the new item. |
|
466 * |
|
467 * @param aMenuItem The menu item to add. |
|
468 * NOTICE that @c SData is a structure so all fields in it should be |
|
469 * set to avoid any unexpected behaviour. |
|
470 */ |
|
471 IMPORT_C void AddMenuItemL(const CEikMenuPaneItem::SData& aMenuItem); |
|
472 |
|
473 /** |
|
474 * Adds a menu item dynamically by creating a new menu item, setting its |
|
475 * data to @c aMenuItem and inserting it into the pane's menu item array. |
|
476 * Updates the menu's scroll bar to take account of the new item. |
|
477 * |
|
478 * @param aMenuItem The menu item to add. NOTICE that @c SData is a |
|
479 * structure so all fields in it should be set to avoid any |
|
480 * unexpected behaviour. |
|
481 * @param aPreviousId The id of the item after which the new item should be |
|
482 * added. |
|
483 */ |
|
484 IMPORT_C void AddMenuItemL(const CEikMenuPaneItem::SData& aMenuItem, |
|
485 TInt aPreviousId); |
|
486 |
|
487 /** |
|
488 * Adds menu items dynamically by creating new menu items from resource |
|
489 * and inserts them into the pane's menu item array. |
|
490 * |
|
491 * @param aResourceId The ID of the resource for the menu item. |
|
492 * @param aPreviousId The ID of the previous menu item, after which this |
|
493 * newly created item should be added. |
|
494 * @param aAddSeperator Shouldn't be used as separator is not not supported |
|
495 * anymore. |
|
496 */ |
|
497 IMPORT_C void AddMenuItemsL(TInt aResourceId, |
|
498 TInt aPreviousId = 0, |
|
499 TBool aAddSeperator = EFalse); |
|
500 |
|
501 /** |
|
502 * Deletes the specified item in the menu pane. |
|
503 * |
|
504 * @param aCommandId The ID for the item to be deleted. |
|
505 */ |
|
506 IMPORT_C void DeleteMenuItem(TInt aCommandId); |
|
507 |
|
508 /** |
|
509 * Deletes the items between specified items. |
|
510 * |
|
511 * @param aStartIndex The index of the item after which items should be |
|
512 * deleted. |
|
513 * @param aEndIndex The index of the item up to which items should be |
|
514 * deleted. |
|
515 */ |
|
516 IMPORT_C void DeleteBetweenMenuItems(TInt aStartIndex, |
|
517 TInt aEndIndex); |
|
518 |
|
519 /** |
|
520 * Gets a reference to the data in the specified menu item. |
|
521 * |
|
522 * @param aCommandId The command ID of the menu item for which data is |
|
523 * obtained. |
|
524 * @return Reference to struct that contains command id. |
|
525 */ |
|
526 IMPORT_C CEikMenuPaneItem::SData& ItemData(TInt aCommandId); |
|
527 |
|
528 /** |
|
529 * Gets a pointer to the specified menu item. Also gets the position of the |
|
530 * item within the menu pane. Panics if there are no menu items in the menu |
|
531 * pane. Panics if the menu pane id does not identify any menu pane item in |
|
532 * the array. |
|
533 * |
|
534 * @param aCommandId The ID of the menu item for which a pointer is |
|
535 * returned. |
|
536 * @param aPos On return, the position of the menu item with an ID of |
|
537 * aCommandId. |
|
538 * @return A pointer to the menu item. |
|
539 * @panic EEikPanicNoSuchMenuItem Panics if there are no menu items in the |
|
540 * menu pane or if the menu pane id does not |
|
541 * identify any menu pane item in the array. |
|
542 */ |
|
543 IMPORT_C CEikMenuPaneItem* ItemAndPos(TInt aCommandId,TInt& aPos); |
|
544 |
|
545 /** |
|
546 * Displays the menu pane with the corner identified by @c aTargetType in |
|
547 * the position specified by @c aTargetPos. This function uses @c |
|
548 * aMinTitleWidth to calculate the area required to display the menu pane, |
|
549 * taking into account whether the menu is a cascading menu or popup menu. |
|
550 * |
|
551 * @param aHotKeyTable Optional hotkey table. |
|
552 * @param aTargetPos Position of the corner of the menu pane identified by |
|
553 * @c aTargetType. |
|
554 * @param aMenuPaneTitle The menu pane's title. |
|
555 * @param aMinWidth Minimum width of the menu's title. |
|
556 * @param aTargetType The corner of the menu pane to which @c aTargetPos |
|
557 * relates. The default is the top left corner. Possible: @c |
|
558 * EPopupTargetTopLeft, @c EPopupTargetTopRight, |
|
559 * @cEPopupTargetBottomLeft, @c EPopupTargetBottomRight. |
|
560 */ |
|
561 IMPORT_C void StartDisplayingMenuPane( |
|
562 const CEikHotKeyTable* aHotKeyTable, |
|
563 const TPoint& aTargetPos, |
|
564 const CEikMenuPaneTitle* aMenuPaneTitle, |
|
565 TInt aMinWidth, |
|
566 TPopupTargetPosType aTargetType = EPopupTargetTopLeft); |
|
567 |
|
568 /** |
|
569 * Sets the text in a menu item. |
|
570 * |
|
571 * @param aCommandId The command (as defined in an .hrh file) associated |
|
572 * with this menu item. This identifies the menu item whose text is |
|
573 * to be set. |
|
574 * @param aDes New item text. |
|
575 */ |
|
576 IMPORT_C void SetItemTextL(TInt aCommandId, |
|
577 const TDesC& aDes); |
|
578 |
|
579 /** |
|
580 * Sets the text in a menu item from resource. |
|
581 * |
|
582 * @param aCommandId The command (as defined in an .hrh file) associated |
|
583 * with this menu item. This identifies the menu item whose text is |
|
584 * to be set. |
|
585 * @param aRid The resource ID of the menu item text. |
|
586 */ |
|
587 IMPORT_C void SetItemTextL(TInt aCommandId, |
|
588 TInt aRid); |
|
589 |
|
590 /** |
|
591 * Dims (greys out) or undims a menu item. Dimming indicates that user |
|
592 * input is not accepted. |
|
593 * |
|
594 * @param aCommandId The command (as defined in an .hrh file) associated |
|
595 * with this menu item. This identifies the menu item whose text is |
|
596 * to be dimmed or un-dimmed. |
|
597 * @param aDimmed @c ETrue to dim this menu item. @c EFalse to un-dim this |
|
598 * menu item. |
|
599 */ |
|
600 IMPORT_C void SetItemDimmed(TInt aCommandId, |
|
601 TBool aDimmed); |
|
602 |
|
603 /** |
|
604 * Sets the item to be indicated or not. It should be used to change the |
|
605 * state of radio buttons or check box items. It has real effect only |
|
606 * starting from S60 v3.0. |
|
607 * |
|
608 * @param aCommandId The command (as defined in an .hrh file) associated |
|
609 * with this menu item. This identifies the menu item for which the |
|
610 * state is set or unset. |
|
611 * @param aButtonState should be @c EEikMenuItemSymbolOn or @c |
|
612 * EEikMenuItemSymbolIndeterminate |
|
613 */ |
|
614 IMPORT_C void SetItemButtonState(TInt aCommandId, |
|
615 TInt aButtonState); |
|
616 |
|
617 /** |
|
618 * Sets the selected menu item. |
|
619 * |
|
620 * @param aSelectedItem The index of the item to get selected |
|
621 */ |
|
622 IMPORT_C void SetSelectedItem(TInt aSelectedItem); |
|
623 |
|
624 /** |
|
625 * Gets the position of the selected menu item. |
|
626 * |
|
627 * @return The position of the selected menu item. |
|
628 */ |
|
629 IMPORT_C TInt SelectedItem() const; |
|
630 |
|
631 /** |
|
632 * Closes and destroys any current cascade menu and takes focus back. Does |
|
633 * nothing if no cascade menu exists. |
|
634 */ |
|
635 IMPORT_C void CloseCascadeMenu(); |
|
636 |
|
637 /** |
|
638 * Sets the array containing the list of menu items for the current menu |
|
639 * pane. |
|
640 * |
|
641 * @param aItemArray The menu item array for the menu pane. |
|
642 */ |
|
643 IMPORT_C void SetItemArray(CItemArray* aItemArray); |
|
644 |
|
645 /** |
|
646 * Set menu item array ownership. |
|
647 * |
|
648 * @param aOwnedExternally If @c ETrue the menu pane's menu item array is |
|
649 * set as externally owned. If @c EFalse the menu pane's menu item |
|
650 * array is set as not externally owned. |
|
651 */ |
|
652 IMPORT_C void SetItemArrayOwnedExternally(TBool aOwnedExternally); |
|
653 |
|
654 /** |
|
655 * Sets the specified button to launch the menu pane. Doesn't have any |
|
656 * effect in current implementation. |
|
657 * |
|
658 * @param aButton The button to set as launching the menu. |
|
659 */ |
|
660 IMPORT_C void SetLaunchingButton(CEikButtonBase* aButton); |
|
661 |
|
662 /** |
|
663 * Moves the menu pane highlight to a newly selected menu item identified |
|
664 * by @c aNewSelectedItem. Scrolls the menu to show the new selected item |
|
665 * if necessary and redraws only the newly selected item and the currently |
|
666 * selected item if possible. |
|
667 * |
|
668 * @param aNewSelectedItem The newly selected menu item index. |
|
669 */ |
|
670 IMPORT_C void MoveHighlightTo(TInt aNewSelectedItem); |
|
671 |
|
672 /** |
|
673 * Gets the number of menu items within the menu pane. |
|
674 * |
|
675 * @return Number of menu items within menu pane. |
|
676 */ |
|
677 IMPORT_C TInt NumberOfItemsInPane() const; |
|
678 |
|
679 /** |
|
680 * Closes the menu pane. |
|
681 */ |
|
682 IMPORT_C void Close(); |
|
683 |
|
684 /** |
|
685 * From @ CCoeControl |
|
686 * |
|
687 * Handles key events offered to the menu by the control environment. |
|
688 * |
|
689 * @since Platform 004. |
|
690 * @param aKeyEvent The key event. |
|
691 * @param aType The type of key event: @c EEventKey, @c EEventKeyUp or @c |
|
692 * EEventKeyDown. |
|
693 * @param aConsumeAllKeys If @c ETrue this function returns @c |
|
694 * EKeyWasConsumed regardless of whether it was used. If @c EFalse |
|
695 * the key event is consumed if possible and either @c |
|
696 * EKeyWasConsumed or @c EKeyWasNotConsumed is returned as |
|
697 * appropriate. |
|
698 */ |
|
699 IMPORT_C TKeyResponse OfferKeyEventL(const TKeyEvent& aKeyEvent, |
|
700 TEventCode aType, |
|
701 TBool aConsumeAllKeys); // not available before Platform 004 |
|
702 |
|
703 /** |
|
704 * Sets whether the scroll bar occupies the left side of the menu pane. |
|
705 * |
|
706 * @param aOnLeft If @c ETrue the scroll bar will occupy the left side of |
|
707 * the menu pane. |
|
708 */ |
|
709 IMPORT_C void SetScrollBarOnLeft(TBool aOnLeft); |
|
710 |
|
711 /** |
|
712 * Sets whether the menu pane uses an arrow head scroll bar. |
|
713 * |
|
714 * @param aArrowHead If @c ETrue the menu pane uses an arrow head scroll |
|
715 * bar. |
|
716 */ |
|
717 IMPORT_C void SetArrowHeadScrollBar(TBool aArrowHead); |
|
718 |
|
719 // new for AVKON |
|
720 |
|
721 /** |
|
722 * Moves highlight to the next item or to the first one if last item is |
|
723 * selected. |
|
724 */ |
|
725 IMPORT_C void NavigateToNextItem(); |
|
726 |
|
727 /** |
|
728 * Inserts the menu item to the specified position. |
|
729 * |
|
730 * @param aMenuItem The menu item to add. NOTICE @c SData is the structure |
|
731 * and all fileds should be initialized. |
|
732 * @param aPosition The position of newly created item in the array. |
|
733 */ |
|
734 IMPORT_C void InsertMenuItemL(const CEikMenuPaneItem::SData& aMenuItem, |
|
735 TInt aPosition); |
|
736 |
|
737 /** |
|
738 * Checks whether menu pane contains the menu item and returns position of |
|
739 * it if the item is found. |
|
740 * |
|
741 * @param[in] aCommandId The command ID of the item to be searched for. |
|
742 * @param[out] aPosition On return contains position of the item. |
|
743 * @return @c ETrue if item was found. Otherwise @c EFalse. |
|
744 */ |
|
745 IMPORT_C TBool MenuItemExists(TInt aCommandId, |
|
746 TInt& aPosition); |
|
747 |
|
748 /** |
|
749 * Checks whether the menu pane is a cascade menu or a main menu. |
|
750 * |
|
751 * @return @c ETrue if the menu pane is cascade menu and @c EFalse if the |
|
752 * menu pane is the main menu. |
|
753 */ |
|
754 IMPORT_C TBool IsCascadeMenuPane() const; |
|
755 |
|
756 /** |
|
757 * Enables or disables text scrolling functionality. It is disabled by |
|
758 * default. |
|
759 * |
|
760 * @param aEnable @c ETrue to enable text scrolling functionality. |
|
761 */ |
|
762 IMPORT_C void EnableMarqueeL(const TBool aEnable); |
|
763 |
|
764 /** |
|
765 * Report that selection was done for the currently highlighted item. |
|
766 */ |
|
767 void ActivateCurrentItemL(); |
|
768 |
|
769 /** |
|
770 * Closes cascade menu if there is one and it is active. |
|
771 */ |
|
772 TBool CancelActiveMenuPane(); |
|
773 |
|
774 /** |
|
775 * Deletes dimmed items from the menu item array. |
|
776 */ |
|
777 void FilterDimmedItems(); |
|
778 |
|
779 /** |
|
780 * Gets the menu pane for the cascade menu. |
|
781 * |
|
782 * @return The menu pane for the cascade menu. |
|
783 */ |
|
784 IMPORT_C CEikMenuPane* CascadeMenuPane(); |
|
785 |
|
786 /** |
|
787 * Gets a reference to the data in the specified menu item. |
|
788 * |
|
789 * @since S60 3.1 |
|
790 * @param aItemIndex The index of the item in the items array. |
|
791 * @return The menu item's data. |
|
792 * @leave KErrArgument Wrong @aItemIndex. |
|
793 */ |
|
794 IMPORT_C CEikMenuPaneItem::SData& ItemDataByIndexL(TInt aItemIndex); |
|
795 |
|
796 /** |
|
797 * Creates and enables a special characters row to be used in the edit |
|
798 * menu. |
|
799 * |
|
800 * @since S60 3.1 |
|
801 * @param aSpecialChars Buffer that holds the selected characters after |
|
802 * user has selected them. |
|
803 */ |
|
804 IMPORT_C void ConstructMenuSctRowL( TDes& aSpecialChars ); |
|
805 |
|
806 /** |
|
807 * Returns the command id of the specified menu item. The function panics |
|
808 * if aIndex doesn't exist or is out of range. |
|
809 * @param aIndex The index of the menu item for which the command ID is returned. |
|
810 * @since 3.1 |
|
811 */ |
|
812 IMPORT_C TInt MenuItemCommandId( TInt aIndex ) const; |
|
813 |
|
814 /** |
|
815 * Creates and enables a special characters row to be used in the edit menu. |
|
816 * The special character row is constructed from the given special character table. |
|
817 * |
|
818 * @param aSpecialChars Buffer that holds the selected characters after |
|
819 * user has selected them. |
|
820 * @param aResourceId The special character table resource id to define the |
|
821 * characters in the row. |
|
822 * |
|
823 * @since S60 3.1 |
|
824 */ |
|
825 IMPORT_C void ConstructMenuSctRowL( TDes& aSpecialChars, TInt aResourceId ); |
|
826 |
|
827 /** |
|
828 * Creates and enables a special characters row to be used in the edit menu. |
|
829 * The special character row is constructed from the given special character dialog. |
|
830 * |
|
831 * @param aSpecialChars Buffer that holds the selected characters after |
|
832 * user has selected them. |
|
833 * @param aResourceId The special character dialog resource id that contains a special character table |
|
834 * |
|
835 * @since S60 3.2 |
|
836 */ |
|
837 IMPORT_C void ConstructMenuSctRowFromDialogL( TDes& aSpecialChars, TInt aResourceId ); |
|
838 |
|
839 /** |
|
840 * Creates and enables a special characters row to be used in the edit menu. |
|
841 * The special character row is constructed from the given special character dialog. |
|
842 * |
|
843 * @param aCharCase the charcase used by menu sct |
|
844 * @param aSpecialChars Buffer that holds the selected characters after |
|
845 * user has selected them. |
|
846 * @param aResourceId The special character dialog resource id that contains a special character table |
|
847 * |
|
848 * @since S60 3.2 |
|
849 */ |
|
850 IMPORT_C void ConstructMenuSctRowFromDialogL( TInt aCharCase, TDes& aSpecialChars, TInt aResourceId ); |
|
851 |
|
852 /** |
|
853 * Sets menu item as item specific command. |
|
854 * |
|
855 * @param aCommandId The command associated with this menu item. |
|
856 * @param aItemSpecific ETrue to define the menu item item specific, |
|
857 * EFalse otherwise. |
|
858 */ |
|
859 IMPORT_C void SetItemSpecific( TInt aCommandId, TBool aItemSpecific ); |
|
860 |
|
861 /** |
|
862 * Sets the embedded cba to options menu |
|
863 * |
|
864 * @param aCba Cba to embed to menu |
|
865 * |
|
866 * @since S60 v5.2 |
|
867 */ |
|
868 void SetEmbeddedCba( CEikCba* aCba ); |
|
869 |
|
870 /** |
|
871 * Closes and destroys any current cascade menu and takes focus back. Does |
|
872 * nothing if no cascade menu exists. |
|
873 * |
|
874 * @param aMainMenuClosing ETrue if main menu is also to be closed. |
|
875 */ |
|
876 void CloseCascadeMenu( TBool aMainMenuClosing ); |
|
877 |
|
878 /** |
|
879 * Symbian two-phased constructor for menu panes that are created for |
|
880 * item specific menus. |
|
881 * |
|
882 * @internal |
|
883 * @since S60 v5.2 |
|
884 * @return Created menu pane. Ownership transfers to caller. |
|
885 */ |
|
886 static CEikMenuPane* NewItemCommandMenuL( MEikMenuObserver* aObserver ); |
|
887 |
|
888 /** |
|
889 * Sets item specific commands dimmed. |
|
890 * |
|
891 * @internal |
|
892 * @since S60 v5.2 |
|
893 */ |
|
894 void SetItemCommandsDimmed(); |
|
895 |
|
896 /** |
|
897 * Adds menu items to this menu and item action menu data. |
|
898 * |
|
899 * @internal |
|
900 * @since S60 v5.2 |
|
901 * @param aMenuData Item action menu data. |
|
902 */ |
|
903 void AddMenuItemsToItemActionMenuL( |
|
904 CAknItemActionMenuData& aMenuData ); |
|
905 |
|
906 /** |
|
907 * Adds cascade menu items to item action menu data. |
|
908 * |
|
909 * @internal |
|
910 * @since S60 v5.2 |
|
911 * @param aCascadeId Cascade menu id. |
|
912 * @param aItemSpecific If ETrue, adds only item specific items. |
|
913 * @param aMenuData Item action menu data. |
|
914 */ |
|
915 void AddCascadeMenuItemsToActionMenuL( |
|
916 TInt aCascadeId, |
|
917 TBool aItemSpecific, |
|
918 CAknItemActionMenuData& aMenuData ); |
|
919 |
|
920 /** |
|
921 * Enables the default highlight in menu |
|
922 */ |
|
923 void SetDefaultHighlight(); |
|
924 |
|
925 private: |
|
926 enum { EInvalidCurrentSize=0x01, EBackgroundFaded=0x02 }; |
|
927 |
|
928 private: // new functions |
|
929 TRect CalculateSizeAndPosition() ; |
|
930 enum THighlightType {ENoHighlight,EDrawHighlight,ERemoveHighlight}; |
|
931 void DrawItem( TInt aItem, THighlightType aHighlight ) const; |
|
932 void DrawItem(CWindowGc& aGc,TInt aItem, THighlightType aHighlight) const; |
|
933 void ReportSelectionMadeL( TBool aAbortTransition = ETrue ); |
|
934 void ReportCanceled(); |
|
935 void LaunchCascadeMenuL(TInt aCascadeMenuId); |
|
936 void DoLaunchCascadeMenuL(TInt aCascadeMenuId); |
|
937 void TryLaunchCascadeMenuL(const CEikMenuPaneItem& aItem); |
|
938 void PrepareGcForDrawingItems(CGraphicsContext& aGc) const; |
|
939 TBool ItemArrayOwnedExternally() const; |
|
940 TBool IsHotKeyL(const TInt modifiers,const TInt aCode); |
|
941 TBool MoveToItemL(TInt aCode, TInt aModifiers); |
|
942 void HandleScrollEventL(CEikScrollBar* aScrollBar,TEikScrollEvent aEventType); |
|
943 void CreateScrollBarFrame(); |
|
944 void UpdateScrollBar(); |
|
945 void DoUpdateScrollBarL(); |
|
946 void UpdateScrollBarThumbs(); |
|
947 static TInt UpdateScrollBarCallBackL(TAny* aObj); |
|
948 TRect ViewRect() const; |
|
949 TInt TotalItemHeight() const; |
|
950 void ScrollToMakeItemVisible(TInt aItemIndex); |
|
951 void Scroll(TInt aAmount); |
|
952 TBool CheckCreateScroller(); |
|
953 void CheckCreateScrollerL(); |
|
954 void ResetItemArray(); |
|
955 void CreateItemArrayL(); |
|
956 void CreateIconFromResourceL(TResourceReader& aReader, CEikMenuPaneItem& aItem) const; |
|
957 |
|
958 // Skin support for menu |
|
959 void UpdateBackgroundContext(const TRect& aWindowRect); |
|
960 |
|
961 // Support method for highlight animation |
|
962 void RepaintHighlight() const; |
|
963 |
|
964 private: // from CCoeControl |
|
965 IMPORT_C void Reserved_1(); |
|
966 IMPORT_C void Reserved_2(); |
|
967 |
|
968 private : // new functions |
|
969 void LoadCascadeBitmapL() ; |
|
970 |
|
971 // Support for check mark, from v3.0 |
|
972 void LoadCheckMarkBitmapL(); |
|
973 TBool MenuHasCheckBoxOn() const; |
|
974 // Support for radio button, from v3.0 |
|
975 void LoadRadioButtonBitmapL(); |
|
976 TBool IsItemMemberOfRadioButtonGroup(TInt aItem) const ; |
|
977 // for drawing,from v3.0 |
|
978 TBool MenuHasIcon() const; |
|
979 |
|
980 TRect CalculateSizeAndPositionScalable( const TRect& aWindowRect, TInt aNumItemsInPane ) ; |
|
981 TRect HighlightRect() const; |
|
982 void PrepareHighlightFrame() const; |
|
983 void SetCascadedIconSize() const; |
|
984 |
|
985 // fixes marquee flickering |
|
986 friend class CAknMarqueeControl; |
|
987 |
|
988 CEikMenuPaneExtension* Extension() const; |
|
989 |
|
990 /** |
|
991 * Creates menu pane's extension object if it doesn't exist yet. |
|
992 */ |
|
993 void CheckCreateExtensionL(); |
|
994 |
|
995 protected: // from CoeControl |
|
996 |
|
997 /** |
|
998 * From @c CCoeControl. |
|
999 * |
|
1000 * Retrieves an object of the same type as that encapsulated in aId. Other |
|
1001 * than in the case where @c NULL is returned, the object returned must be |
|
1002 * of the same object type - that is, the @c ETypeId member of the object |
|
1003 * pointed to by the pointer returned by this function must be equal to the |
|
1004 * @c iUid member of @c aId. |
|
1005 * |
|
1006 * @since SDK 7.0s |
|
1007 * @param aId An encapsulated object type ID. |
|
1008 * @return Encapsulates the pointer to the object provided. Note that the |
|
1009 * encapsulated pointer may be @c NULL. |
|
1010 */ |
|
1011 IMPORT_C TTypeUid::Ptr MopSupplyObject(TTypeUid aId); |
|
1012 |
|
1013 public: // From CoeControl. |
|
1014 |
|
1015 /** |
|
1016 * From @c CoeControl. |
|
1017 * |
|
1018 * Gets the number of controls contained in a compound control. This |
|
1019 * function should be implemented by all compound controls. |
|
1020 * |
|
1021 * Note: |
|
1022 * In SDK 6.1 this was changed from protected to public. |
|
1023 * |
|
1024 * @return The number of component controls contained by this control. |
|
1025 */ |
|
1026 IMPORT_C TInt CountComponentControls() const; |
|
1027 |
|
1028 /** |
|
1029 * From @c CoeControl. |
|
1030 * |
|
1031 * Gets the specified component of a compound control. This function should? |
|
1032 * be implemented by all compound controls. |
|
1033 * |
|
1034 * Note: |
|
1035 * Within a compound control, each component control is identified by an |
|
1036 * index, where the index depends on the order the controls were added: the |
|
1037 * first is given an index of 0, the next an index of 1, and so on. |
|
1038 * |
|
1039 * @param[in, out] aIndex The index of the control to get. |
|
1040 * @return The component control with an index of @c aIndex. |
|
1041 */ |
|
1042 IMPORT_C CCoeControl* ComponentControl(TInt aIndex) const; |
|
1043 |
|
1044 protected: // new functions |
|
1045 |
|
1046 /** |
|
1047 * Gets the maximum number of items which can be seen simultaneously. |
|
1048 * |
|
1049 * @return The maximum number of items which can be seen simultaneously. |
|
1050 */ |
|
1051 TInt NumberOfItemsThatFitInView() const; |
|
1052 |
|
1053 private: // data |
|
1054 friend class CEikMenuButton; |
|
1055 MEikMenuObserver* iMenuObserver; |
|
1056 MEikMenuObserver* iEditMenuObserver; |
|
1057 CEikMenuPane* iCascadeMenuPane; |
|
1058 const CEikMenuPaneTitle* iMenuPaneTitle; |
|
1059 const CEikHotKeyTable* iHotKeyTable; |
|
1060 CEikMenuPane* iOwner; |
|
1061 CItemArray* iItemArray; |
|
1062 TBool iArrayOwnedExternally; |
|
1063 TBool iAllowPointerUpEvents; |
|
1064 TInt iNumberOfDragEvents; |
|
1065 TInt iSelectedItem; |
|
1066 TInt iItemHeight; |
|
1067 TInt iBaseLine; |
|
1068 TInt iHotkeyColWidth; |
|
1069 TInt iFlags; |
|
1070 CEikScrollBarFrame* iSBFrame; |
|
1071 CMenuScroller* iScroller; |
|
1072 CEikButtonBase* iLaunchingButton; // for popouts only |
|
1073 TInt iSubPopupWidth; // 0..2 |
|
1074 TInt iSpare; |
|
1075 CEikMenuPaneExtension* iExtension ; |
|
1076 |
|
1077 }; |
|
1078 |
|
1079 #endif |
|
1080 |