2 * Copyright (c) 2002-2008 Nokia Corporation and/or its subsidiary(-ies).
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".
9 * Initial Contributors:
10 * Nokia Corporation - initial contribution.
14 * Description: Tab control for the status pane's navigation pane.
23 #include <AknControl.h>
26 #include <AknNaviDecoratorObserver.h>
27 #include "aknconsts.h"
33 // FORWARD DECLARATIONS
38 class CAknTabGroupExtension;
39 class MAknTabObserver;
40 class MAknNaviDecoratorObserver;
41 class TAknWindowLineLayout;
42 class CAknTabExtension;
45 * Tab item control used inside a tab group.
50 NONSHARABLE_CLASS( CAknTab ) : public CAknControl
52 friend class CAknTabGroup;
57 * Indicates a tab title's type
61 /** Tab title is empty.*/
63 /** Tab title has only text. */
65 /** Tab title has only icon */
67 /** Tab title has both text and icon. */
79 * Two-phased constructor.
81 * @param aParent Reference to parent control.
82 * @param aReader Reference to resource reader.
84 * @return A pointer to constructed @c CAknTab object.
86 static CAknTab* NewL( const CCoeControl& aParent,
87 TResourceReader& aReader );
90 * Two-phased constructor.
92 * @param aParent Reference to parent control.
93 * @param aReader Reference to resource reader.
95 * @return A pointer to constructed @c CAknTab object.
97 static CAknTab* NewLC( const CCoeControl& aParent,
98 TResourceReader& aReader );
101 * Two-phased constructor.
104 * @param aParent Reference to parent control.
105 * @param aTabText Reference to title text.
107 * @return A pointer to constructed @c CAknTab object.
109 static CAknTab* NewL( TInt aId,
110 const CCoeControl& aParent,
111 const TDesC& aTabText );
114 * Two-phased constructor.
117 * @param aParent Reference to parent control.
118 * @param aTabText Reference to title text.
120 * @return A pointer to constructed @c CAknTab object.
122 static CAknTab* NewLC( TInt aId,
123 const CCoeControl& aParent,
124 const TDesC& aTabText );
127 * Two-phased constructor.
130 * @param aParent Reference to parent control.
131 * @param aTabText Reference to title text.
132 * @param aTabBitmap Bitmap for the tab. Ownership of the bitmap is taken.
133 * @param aMask Bitmap's mask. Ownership of the mask is taken.
135 * @return A pointer to constructed @c CAknTab object.
137 static CAknTab* NewL( TInt aId,
138 const CCoeControl& aParent,
139 const TDesC& aTabText,
140 const CFbsBitmap* aTabBitmap,
141 const CFbsBitmap* aMask = NULL );
144 * Two-phased constructor.
147 * @param aParent Reference to parent control.
148 * @param aTabText Reference to title text.
149 * @param aTabBitmap Bitmap for the tab. Ownership of the bitmap is taken.
150 * @param aMask Bitmap's mask. Ownership of the mask is taken.
152 * @return A pointer to constructed @c CAknTab object.
154 static CAknTab* NewLC( TInt aId,
155 const CCoeControl& aParent,
156 const TDesC& aTabText,
157 const CFbsBitmap* aTabBitmap,
158 const CFbsBitmap* aMask = NULL );
161 * Two-phased constructor.
164 * @param aParent Reference to parent control.
165 * @param aTabBitmap Bitmap for the tab. Ownership of the bitmap is taken.
166 * @param aMask Bitmap's mask. Ownership of the mask is taken.
168 * @return A pointer to constructed @c CAknTab object.
170 static CAknTab* NewL( TInt aId,
171 const CCoeControl& aParent,
172 const CFbsBitmap* aTabBitmap,
173 const CFbsBitmap* aMask = NULL );
176 * Two-phased constructor.
179 * @param aParent Reference to parent control.
180 * @param aTabBitmap Bitmap for the tab. Ownership of the bitmap is taken.
181 * @param aMask Bitmap's mask. Ownership of the mask is taken.
183 * @return A pointer to constructed @c CAknTab object.
185 static CAknTab* NewLC( TInt aId,
186 const CCoeControl& aParent,
187 const CFbsBitmap* aTabBitmap,
188 const CFbsBitmap* aMask = NULL );
191 * Replace the tab title.
193 * @param aTabText New title text.
195 void ReplaceTextL( const TDesC& aTabText );
198 * Activate or deactive this tab.
200 * @param aActive @c ETrue for activation, @c EFalse for deactivation.
201 * @param aDrawNow Indicates whether control need to be redrawn.
203 void SetActive( TBool aActive, TDrawNow aDrawNow );
206 * Determines whether this tab is active.
208 * @return @c ETrue if a tab is active, @c EFalse if not.
210 TBool Active() const;
220 * Gets this tab's type.
222 * @return Tab's type.
224 enum TAknTabDataType TabType() const;
228 * Sets the total amount of tabs in the tabgroup where this tab belongs to.
230 void SetTotalAmountOfTabs( TInt aAmount );
233 * Sets the narrow tab layout.
234 * @internal Used by the UI framework.
235 * Applications can set the narrow layout using @c CAknNaviDecorator class.
237 void SetNarrowTabLayout( TBool aNarrow );
240 * Sets the flag indicating whether or not this tab contains
241 * a multi-colored title icon.
243 * The multi-color mode should be used with color icons,
244 * otherwise the tab icon is drawn using a color
245 * defined in the current skin.
247 * @param aMultiColor @c ETrue to set the multi-color mode on,
248 * @c EFalse to turn it off.
250 void SetMultiColorMode( TBool aMultiColor );
253 * Checks whether or not this tab is drawn using multi-color mode or not.
255 * @return @c ETrue if this tab contains a multi-color icon,
256 * @c EFalse otherwise.
258 TBool MultiColorMode() const;
261 * Sets the long tab layout.
262 * @internal Used by the UI framework.
264 void SetLongTabLayout( TBool aLongTab );
266 public: // From base class @c CCoeControl.
269 * Gets the minimum size of the tab.
271 * @return Minimum size of the tab.
273 virtual TSize MinimumSize();
276 * Sets the tab dimmed.
278 * @param aDimmed @c ETrue to dim the control,
279 * @c EFalse to set the control as not dimmed.
281 virtual void SetDimmed( TBool aDimmed );
284 * Gets the list of logical colors employed
285 * in the drawing of the control, paired with an explanation of how
286 * they are used. Appends the list into @c aColorUseList.
288 * @param[in,out] aColorUseList The color list.
290 virtual void GetColorUseListL(
291 CArrayFix<TCoeColorUse>& aColorUseList ) const;
293 protected: // From base class @c CCoeControl.
296 * Responds to size changes events to sets the size and
297 * position of the contents of this control.
299 virtual void SizeChanged();
302 * Gets the number of controls contained in a compound control.
304 * @return The number of component controls contained by this control.
306 virtual TInt CountComponentControls() const;
309 * Gets the specified component of a compound control.
311 * @param aIndex The index of the control to get.
313 * @return The component control with an index of @c aIndex.
316 virtual CCoeControl* ComponentControl( TInt aIndex ) const;
319 * Handles pointer events.
320 * This function is called by framework whenever a pointer event
321 * occurs in the control.
323 * @param aPointerEvent The pointer event.
325 virtual void HandlePointerEventL( const TPointerEvent& aPointerEvent );
327 private: // From base class @c CAknControl.
329 IMPORT_C void* ExtensionInterface( TUid aInterface );
331 private: // From base class @c CCoeControl.
333 virtual void Draw( const TRect& aRect ) const;
339 void ConstructFromResourceL( TResourceReader& aReader );
341 void ConstructL( const TDesC& aTabText );
343 void ConstructL( const CFbsBitmap* aTabBitmap,
344 const CFbsBitmap* aMask = NULL );
346 void LoadColorBitmapL();
349 * Handles a change to the control's resources.
351 * @param aType The event type.
353 void HandleResourceChange( TInt aType );
355 void SizeChangedInNormalLayout();
356 void SizeChangedInFlatLayout();
357 void SizeChangedInNarrowLayout();
365 const CFbsBitmap* iBitmap;
366 const CFbsBitmap* iBitmapMask;
367 TAknLayoutRect iBitmapRect;
369 CAknTabExtension* iExtension;
371 typedef CArrayPtrFlat<CFbsBitmap> CAknTabColorBitmapArray;
372 CAknTabColorBitmapArray* iColorBitmaps;
377 * Tab group functionality for navigation pane.
382 class CAknTabGroup : public CAknControl,
383 public MCoeControlObserver,
384 public MCoeControlContext,
385 public MAknNaviDecoratorObserver
391 IMPORT_C ~CAknTabGroup();
394 * Creates new tab group.
396 * @param aParent Parent control.
398 IMPORT_C static CAknTabGroup* NewL( const CCoeControl& aParent );
401 * Creates new tab group and pushes it to the clean up stack.
403 * @param aParent Parent control.
405 IMPORT_C static CAknTabGroup* NewLC( const CCoeControl& aParent );
410 * Add a tab to the tab group from resources.
412 * @param aReader Resource reader.
414 * @return ID of the added tab.
416 IMPORT_C TInt AddTabL( TResourceReader& aReader );
419 * Add a tab to the tab group.
421 * @param aTabId ID of the tab to be added.
422 * @param aTabText Text for the tab.
424 IMPORT_C void AddTabL( TInt aTabId, const TDesC& aText );
427 * Add a tab to the tab group.
429 * @param aTabId ID of the tab.
430 * @param aTabText Text for the tab.
431 * @param aTabBitmap Bitmap for the tab. Ownership of the bitmap is taken.
432 * @param aMask Bitmap's mask. Ownership of the mask is taken.
434 IMPORT_C void AddTabL( TInt aTabId,
436 const CFbsBitmap* aTabBitmap,
437 const CFbsBitmap* aMask = NULL );
440 * Add a tab to the tab group.
442 * @param aTabId ID of the tab.
443 * @param aTabBitmap Bitmap for the tab. Ownership of the bitmap is taken.
444 * @param aMask Bitmap's mask. Ownership of the mask is taken.
446 IMPORT_C void AddTabL( TInt aTabId,
447 const CFbsBitmap* aTabBitmap,
448 const CFbsBitmap* aMask = NULL );
450 * Replaces a tab with a new one from resources.
451 * Tab with same ID is replaced.
453 * @param aReader Resource reader.
455 IMPORT_C void ReplaceTabL( TResourceReader& aReader );
458 * Replaces a tab with a new one.
460 * @param aTabId ID of the tab to be replaced.
461 * @param aTabText Text for the new tab.
463 IMPORT_C void ReplaceTabL( TInt aTabId, const TDesC& aText );
466 * Replaces a tab with a new one.
468 * @param aTabId ID of the tab to be replaced.
469 * @param aTabText Text for the new tab.
470 * @param aTabBitmap Bitmap for the tab. Ownership of the bitmap is taken.
471 * @param aMask Bitmap's mask. Ownership of the mask is taken.
473 IMPORT_C void ReplaceTabL( TInt aTabId,
475 const CFbsBitmap* aTabBitmap,
476 const CFbsBitmap* aMask = NULL );
479 * Replaces a tab with a new one.
481 * @param aTabId ID of the tab to be replaced.
482 * @param aTabBitmap Bitmap for the tab. Ownership of the bitmap is taken.
483 * @param aMask Bitmap's mask. Ownership of the mask is taken.
485 IMPORT_C void ReplaceTabL( TInt aTabId,
486 const CFbsBitmap* aTabBitmap,
487 const CFbsBitmap* aMask = NULL );
490 * Replaces a tab text with a new one.
492 * @param aTabId ID of the tab containing the text to be replaced.
493 * @param aTabText New tab text.
495 IMPORT_C void ReplaceTabTextL( TInt aTabId, const TDesC& aTabText );
498 * Delete a tab from the tab group.
500 * @param aTabId ID of the tab to be deleted.
502 IMPORT_C void DeleteTabL( TInt aTabId );
505 * Activate (highlight) a tab.
507 * @param aTabId ID of the tab to be highlighted.
509 IMPORT_C void SetActiveTabById( TInt aTabId );
512 * Activate (highlight) a tab.
514 * @param aTabIndex Index of the tab to be highlighted.
516 IMPORT_C void SetActiveTabByIndex( TInt aTabIndex );
519 * Returns the ID of the currently active (highlighted) tab.
521 * @return ID of the highlighted tab.
523 IMPORT_C TInt ActiveTabId() const;
526 * Returns the index of the currently active (highlighted) tab.
528 * @return Index of the highlighted tab.
530 IMPORT_C TInt ActiveTabIndex() const;
533 * Set width of each tab.
534 * This width determines what tab layout is used.
535 * To get a specific tab layout, use the following constants:
536 * - KTabWidthWithOneTab One tab layout
537 * - KTabWidthWithTwoTabs Two tabs layout
538 * - KTabWidthWithThreeTabs Three tabs layout
539 * - KTabWidthWithFourTabs Four tabs layout
540 * - KTabWidthWithTwoLongTabs Two long tabs layout
541 * - KTabWidthWithThreeLongTabs Three long tabs layout
543 * @param aWidth Width of each tab, @see aknconsts.h.
545 IMPORT_C void SetTabFixedWidthL( TInt aWidth );
548 * Sets a tab dimmed/not dimmed.
550 * @param aTabId ID of the tab.
551 * @param aDimmed @c ETrue to set the tab dimmed,
552 * @c EFalse otherwise.
554 IMPORT_C void DimTab( TInt aTabId, TBool aDimmed );
557 * Used to check whether or not a tab is dimmed.
559 * @param aTabId ID of the tab.
561 * @return @c ETrue if the tab is dimmed, @c EFalse otherwise.
563 IMPORT_C virtual TBool IsTabDimmed( TInt aTabId ) const;
566 * Returns the index of a tab.
568 * @param aTabId ID of a tab.
570 * @return Index of the tab.
572 IMPORT_C virtual TInt TabIndexFromId( TInt aTabId ) const;
575 * Returns the ID of a tab.
577 * @param aTabIndex Index of a tab.
579 * @return ID of the tab.
581 IMPORT_C virtual TInt TabIdFromIndex( TInt aTabIndex ) const;
584 * Number of tabs in the tab group.
586 * @return Number of tabs in the tab group.
588 IMPORT_C virtual TInt TabCount() const;
591 * Sets the tab observer for this tab group.
593 * @param aObserver Tab observer to set.
595 IMPORT_C void SetObserver( MAknTabObserver* aObserver );
597 public: // From base class @c CCoeControl.
600 * Return minimum size of the control.
602 * @return Minimum size of the control.
604 IMPORT_C virtual TSize MinimumSize();
607 * Handles key events.
609 * @param aKeyEvent The key event.
610 * @param aType The type of the event.
612 * @return Indicates whether or not the key event was used by this control.
614 IMPORT_C virtual TKeyResponse OfferKeyEventL( const TKeyEvent& aKeyEvent,
618 * Gets the list of logical colors employed in the drawing of the control,
619 * paired with an explanation of how they are used.
620 * Appends the list into @c aColorUseList.
622 * @param[in,out] aColorUseList The color list.
624 IMPORT_C virtual void GetColorUseListL(
625 CArrayFix<TCoeColorUse>& aColorUseList ) const;
628 * Handles a change to the control's resources.
630 * @param aType The type of resource change.
632 void HandleResourceChange( TInt aType );
635 * Handles pointer events in tabs.
637 * @param aPointerEvent Pointer event to be handled.
639 IMPORT_C void HandlePointerEventL( const TPointerEvent& aPointerEvent );
641 public: // From base class @c MCoeControlObserver.
644 * Handles an event from an observed control.
646 * @param aControl Control that caused the event.
647 * @param aEventType Type of the event.
649 IMPORT_C virtual void HandleControlEventL( CCoeControl* aControl,
650 TCoeEvent aEventType );
652 public: // From base class @c MCoeControlContext.
655 * Allows to modify graphics context before Draw.
657 * @param aGc Graphics context to be modified.
659 IMPORT_C virtual void PrepareContext( CWindowGc& aGc ) const;
661 public: // From base class @c MAknNaviDecoratorObserver.
664 * Handles events from navi decorator parent control.
666 * @param aEventID ID of event to be handled.
668 IMPORT_C virtual void HandleNaviDecoratorEventL( TInt aEventID );
670 protected: // From base class @c CCoeControl.
673 * Handles the size change events.
675 IMPORT_C virtual void SizeChanged();
678 * Returns number of controls inside this control.
680 * @return Number of component controls.
682 IMPORT_C virtual TInt CountComponentControls() const;
685 * Returns a component control determined by control index.
687 * @param aIndex Index of a control to be returned.
689 * @return Pointer to the control.
691 IMPORT_C virtual CCoeControl* ComponentControl( TInt aIndex ) const;
694 * This is called when the focus is changed.
696 * @param aDrawNow Whether or not to draw the control.
698 IMPORT_C virtual void FocusChanged( TDrawNow aDrawNow );
701 * Reverse the order of tabs in tab array.
703 void ReverseTabOrderL();
710 IMPORT_C virtual void Reserved1();
715 IMPORT_C virtual void Reserved2();
720 IMPORT_C virtual void Reserved3();
724 IMPORT_C CAknTabGroup();
727 * Tab groups can be mirrored depending on current locale. To client
728 * application everything always seems like tabs are not mirrored but
729 * the internal order of tabs in tab group may or may not be mirrored.
730 * If mirroring is off then this function just returns given
731 * parameter as it is. If mirroring is on then this function returns
732 * unmirrored index if given index was mirrord and vice versa. Two
733 * nested calls to this function cancels its effect
734 * (ConvertTabIndex(ConvertTabIndex(aIndex)) == aIndex).
736 * @param aIndex Index to be converted.
737 * @return Converted index.
739 TInt ConvertTabIndex(TInt aIndex) const;
741 private: // From base class @c CCoeControl.
743 IMPORT_C virtual void Draw( const TRect& aRect ) const;
745 private: // From base class @c CAknControl.
747 IMPORT_C void* ExtensionInterface( TUid aInterface );
749 public: // New methods
752 * Sets the multi-color drawing mode of a tab.
753 * This should be called after adding a tab to the tab group
754 * if the icon in the tab should be drawn as multi-colored.
755 * The tab icon will be drawn using a color specified in the
756 * active skin if multi-color mode is not defined.
758 * This function should be called right after a tab containing
759 * a multi-color icon is added to the tab group.
761 * @param aTabId ID of the tab.
762 * @param aMultiColor @c ETrue to set the multi-color mode on,
763 * @c EFalse to turn it off.
765 IMPORT_C void SetTabMultiColorMode( TInt aTabId, TBool aMultiColor );
767 /** Directions in which the tab group focus can be moved. */
776 void CommonAddTabL(CAknTab* aTab);
777 void CommonReplaceTabL(CAknTab* aTab);
778 void HandleTabStateChanged(CCoeControl* aControl);
779 TInt Index(TInt aTabId) const;
780 TBool CycleFocus(TDirection aDirection,TDrawNow aDrawNow);
781 TInt LeftMostTabIndex() const;
782 TInt RightMostTabIndex() const;
783 void DrawLowerBorder(TDrawNow aDrawNow) const;
784 void DoDrawLowerBorder() const;
785 void ReportNavigationEvent();
786 void LoadTabBitmapsL(TInt aNumberOfTabsShown, TBool aLongTabs);
787 TBool TabsVisibleInCurrentLayout() const;
788 void CurrentLayout( TAknWindowLineLayout& aLayout ) const;
789 void InitTabGroupGraphicsL();
791 void InitTabAnimationEventTimer();
792 void CancelTabAnimationEventTimer();
793 static TInt TabAnimationEvent(TAny * aPtr);
794 void DoTabAnimationEvent();
796 TBool NarrowTabLayoutNext();
797 TBool NarrowTabLayout();
802 * Sets the navigation decorator layout so that it corresponds
803 * the current tab group layout.
805 * @param aNarrow @c ETrue if narrow tab group layout is used,
806 * @c EFalse if normal layout is used.
808 void SetDecoratorLayout( TBool aNarrow );
812 void SizeChangedInNormalLayout();
813 void SizeChangedInFlatLayout();
814 void SizeChangedInNarrowLayout();
815 void InitTabAnimationL();
819 * Gets the rectangle for the tab group.
820 * If the tab arrows are not shown, then the tab group gets a wider
823 * @param aArrowsUsed @c ETrue if tab arrows are shown,
824 * @c EFalse otherwise.
826 static TRect ParentRect( TBool aArrowsUsed );
829 * @internal Used by the UI framework.
831 * Starts the animation shown when tab focus is cycled.
832 * Note that this starts the animation only when required, i.e.
833 * when layout that needs cycle animation is used and when the first
834 * shown tab in the tab group changes.
836 * @param aDirection Direction which the focus in cycled to.
837 * @param aNewTab Index of the tab that receives the focus.
839 void StartCycleAnimationL( TDirection aDirection, TInt aNewTab );
842 * Called on the dynamic layout switch event, switches the current tab
843 * layout to a corresponding one that is usable in the new layout.
845 void SwitchTabLayoutL();
850 * @internal Used by the UI framework.
851 * Applications can set the narrow layout using @c CAknNaviDecorator class.
853 void SetNarrowTabLayoutL( TBool aNarrow, TBool aUseAnimation = EFalse );
856 * @internal Used by the UI framework.
858 * Sets the tab arrows' visibility.
860 * @param aVisible @c ETrue to set the arrows visible,
861 * @c EFalse to hide them.
863 void SetNaviArrowsVisible( TBool aVisible );
866 CArrayPtr<CAknTab>* iTabArray;
872 TInt iNumberOfTabsShown;
875 CFbsBitmap* iTabBitmaps[KTabNumberOfTabBitmaps];
876 CFbsBitmap* iTabMaskBitmaps[KTabNumberOfTabBitmaps];
878 TInt iBitmapNames[KTabNumberOfTabBitmaps];
879 TInt iBitmapMaskNames[KTabNumberOfTabBitmaps];
880 CAknTabGroupExtension* iExtension;
882 MAknTabObserver* iTabObserver;
886 #endif // AKNTABGRP_H