williamr@2: /* williamr@2: * Copyright (c) 2005 Nokia Corporation and/or its subsidiary(-ies). williamr@2: * All rights reserved. williamr@2: * This component and the accompanying materials are made available williamr@4: * under the terms of "Eclipse Public License v1.0" williamr@2: * which accompanies this distribution, and is available williamr@4: * at the URL "http://www.eclipse.org/legal/epl-v10.html". williamr@2: * williamr@2: * Initial Contributors: williamr@2: * Nokia Corporation - initial contribution. williamr@2: * williamr@2: * Contributors: williamr@2: * williamr@2: * Description: CAknChoiceList - Choice list for S60 williamr@2: * williamr@2: */ williamr@2: williamr@2: williamr@2: williamr@2: #ifndef AKNCHOICELIST_H williamr@2: #define AKNCHOICELIST_H williamr@2: williamr@2: // includes williamr@4: #include williamr@2: #include williamr@2: williamr@2: // forward declarations williamr@2: class CAknButton; williamr@2: class CEikLabel; williamr@2: class CAknChoiceListPopup; williamr@2: class CAknChoiceListPopupList; williamr@2: class CAknsFrameBackgroundControlContext; williamr@2: class CAknInfoPopupNoteController; williamr@2: williamr@2: // Class declaration williamr@2: williamr@2: /** williamr@2: * CAknChoiceList williamr@2: * Choice list is new component, which allows selection from vertical list of choices. williamr@2: * By default choice list shows currently selected item and a arrow for opening the williamr@2: * the choice list. Choice list can be used also without showing current selection. williamr@2: * @lib avkon.lib williamr@2: * @since S60 5.0 williamr@2: */ williamr@2: class CAknChoiceList : public CAknControl, public MCoeControlObserver williamr@2: { williamr@2: public: williamr@2: williamr@2: /* Flags for choice list types and positioning */ williamr@2: enum TAknChoiceListFlags williamr@2: { williamr@2: /* Using default choice list with popup list */ williamr@2: EAknChoiceListWithCurrentSelection = 0x01, williamr@2: /* Using user defined button to open choice list */ williamr@2: EAknChoiceListWithoutCurrentSelection = 0x02, williamr@2: /* Popup positioning flags */ williamr@2: EAknChoiceListPositionLeft = 0x04, williamr@2: EAknChoiceListPositionRight = 0x08, williamr@2: EAknChoiceListPositionBottom = 0x10 williamr@2: }; williamr@2: williamr@2: /* Tooltip positioning */ williamr@2: enum TTooltipPosition williamr@2: { williamr@2: EPositionTop = 1, /* Tooltip alignment vertically to top */ williamr@2: EPositionBottom, /* Tooltip alignment vertically to bottom */ williamr@2: EPositionLeft, /* Tooltip alignment horizontally to left */ williamr@2: EPositionRight /* Tooltip alignment horizontally to right */ williamr@2: }; williamr@2: public: williamr@2: williamr@2: /** williamr@2: * Two-phased constructor. williamr@2: * If the default flag is used then choice list shows an opening arrow and selected item on its williamr@2: * left side. If flag EAknChoiceListUsesButton is and user has defined own button then choice list williamr@2: * open with items in the given array. Selected item is not show when choice list is closed. williamr@2: * @param aParent the parent control for choice list williamr@2: * @param aItemArray Array of items to be shown in the choicelist. Transfers ownership. williamr@2: * @param aFlags Flags for choice list type and positioning williamr@2: * @param aButton user defined button for choicelist. Button replaces the typical choice list. williamr@2: * Transfers ownership. williamr@2: */ williamr@2: IMPORT_C static CAknChoiceList* NewL( CCoeControl* aParent, CDesCArray* aItemArray, TInt aFlags = EAknChoiceListWithCurrentSelection, CAknButton* aButton = NULL ); williamr@2: williamr@2: /** williamr@2: * Two-phased constructor. williamr@2: * If the default flag is used then choice list shows an opening arrow and selected item on its williamr@2: * left side. If flag EAknChoiceListUsesButton is and user has defined own button then choice list williamr@2: * open with items in the given array. Selected item is not show when choice list is closed. williamr@2: * @param aParent the parent control for choice list williamr@2: * @param aItemArray Array of items to be shown in the choicelist. Transfers ownership. williamr@2: * @param aFlags Flags for choice list type and positioning williamr@2: * @param aButton user defined button for choicelist. Button replaces the typical choice list. williamr@2: * Transfers ownership. williamr@2: */ williamr@2: IMPORT_C static CAknChoiceList* NewLC( CCoeControl* aParent, CDesCArray* aItemArray, TInt aFlags = EAknChoiceListWithCurrentSelection, CAknButton* aButton = NULL ); williamr@2: williamr@2: /** williamr@2: * Destructor williamr@2: */ williamr@2: ~CAknChoiceList(); williamr@2: williamr@2: /** williamr@2: * Open choice list. williamr@2: * Choicelist can be opened with this function. If the choicelist is already williamr@2: * open nothing will happen. williamr@2: * @return KErrNone if succeeded williamr@2: */ williamr@2: IMPORT_C TInt ShowChoiceListL(); williamr@2: williamr@2: /** williamr@2: * Set certain index of the choice list array to selected williamr@2: * @param aIndex Index of the array to be selected as default williamr@2: */ williamr@2: IMPORT_C void SetSelectedIndex( const TInt aIndex ); williamr@2: williamr@2: /** williamr@2: * Returns selected index from the choice list array williamr@2: * @return TInt selected index williamr@2: */ williamr@2: IMPORT_C TInt SelectedIndex() const; williamr@2: williamr@2: /** williamr@2: * Set certain array as the contents of the choice list. williamr@2: * It's recommended to use CDesCArrayFlat. The ownership of the array is transferred williamr@2: * to choice list. williamr@2: * @param aArray Array of text items to be inserted as the content for choice list williamr@2: */ williamr@2: IMPORT_C void SetItems( CDesCArray* aArray ); williamr@2: williamr@2: /** williamr@2: * Set certain array as the contents of the choice list. williamr@2: * It's recommended to use CDesCArrayFlat. williamr@2: * @param aResourceId Resource id for an array. williamr@2: */ williamr@2: IMPORT_C void SetItemsL( TInt aResourceId ); williamr@2: williamr@2: /** williamr@2: * Add a text as a new item in the end of the choice list array. williamr@2: * @param aDesC Pointer to a descriptor item that should be appended to the array. williamr@2: * Transfers ownership. williamr@2: * @return index in the choicelist array for newly added item. williamr@2: */ williamr@2: IMPORT_C TInt AddItemL( const TDesC* aDesC ); williamr@2: williamr@2: /** williamr@2: * Removes an item from the choice list array with the given index. williamr@2: * @param aIndex index for the item that should be removed from the choice list array williamr@2: */ williamr@2: IMPORT_C void RemoveItem( const TInt aIndex ); williamr@2: williamr@2: /** williamr@2: * Sets flags for choice list. williamr@2: * Choice lists position can be changed in runtime with right flags. williamr@2: * @param aFlags The flags to be set for choice list williamr@2: */ williamr@2: IMPORT_C void SetFlags( const TInt aFlags ); williamr@2: williamr@2: /** williamr@2: * Return choice list specific flags. williamr@2: * @return choice list flags williamr@2: */ williamr@2: IMPORT_C TInt Flags() const; williamr@2: williamr@2: /** williamr@2: * Set the button that launches choice list opening. williamr@2: * @param aButton The Button for opening choice list control williamr@2: */ williamr@2: IMPORT_C void SetButtonL( CAknButton* aButton ); williamr@2: williamr@2: /** williamr@2: * Hide choice list popup. Current selection is not selected. williamr@2: */ williamr@2: IMPORT_C void HideChoiceList(); williamr@2: williamr@2: /** williamr@2: * Set text for tooltip williamr@2: * @param aText The text shown as tooltip williamr@2: */ williamr@2: IMPORT_C void SetTooltipTextL( const TDesC& aText ); williamr@2: williamr@2: /** williamr@2: * Set the delays for tooltip williamr@2: * @param aBeforeTimeout The delay in milliseconds before tooltip williamr@2: * is shown. The default is 150 milliseconds williamr@2: * @param aInViewTiemout The interval in milliseconds how long the williamr@2: * tooltip is displayed. The default is 3000 milliseconds. williamr@2: */ williamr@2: IMPORT_C void SetTooltipTimeouts( const TInt aBeforeTimeout, williamr@2: const TInt aInViewTimeout ); williamr@2: /** williamr@2: * Set the postion of tooltip williamr@2: * @param aPosition The position expressed with TTooltipPosition williamr@2: * The default is EPositionTop williamr@2: */ williamr@2: IMPORT_C void SetTooltipPosition( const TTooltipPosition aPosition ); williamr@2: williamr@2: // From CCoeControl williamr@2: williamr@2: /** williamr@2: * From CCoeControl. Returns the control inside control with given index. williamr@2: * @param aIndex Index of a control be returned williamr@2: * @return A Pointer to control. williamr@2: */ williamr@2: IMPORT_C CCoeControl* ComponentControl( TInt aIndex ) const; williamr@2: williamr@2: /** williamr@2: * From CCoeControl. Returns number of controls inside the control. williamr@2: * @return Number of component controls. williamr@2: */ williamr@2: IMPORT_C TInt CountComponentControls() const; williamr@2: williamr@2: /** williamr@2: * From CCoeControl. Returns the Minimum size needed by the control. williamr@2: * @return TSize minimum size. williamr@2: */ williamr@2: IMPORT_C TSize MinimumSize(); williamr@2: williamr@2: /** williamr@2: * From CCoeControl. Handles a change to the control's resources. williamr@2: * @param aType A message UID value. williamr@2: */ williamr@2: IMPORT_C void HandleResourceChange( TInt aType ); williamr@2: williamr@2: /** williamr@2: * From CCoeControl. Handles key events. williamr@2: * @param aKeyEvent the key event williamr@2: * @param aType The type of key event williamr@2: * @return Indicates whether or not the keyevent was used by this control williamr@2: */ williamr@2: IMPORT_C TKeyResponse OfferKeyEventL( const TKeyEvent& aKeyEvent, TEventCode aType ); williamr@2: williamr@2: /** williamr@2: * From CCoeControl. Draws control to given area williamr@2: * @param aRect The rectangle that should be drawn by the control. williamr@2: */ williamr@2: IMPORT_C void Draw( const TRect& aRect ) const; williamr@2: williamr@2: williamr@2: /** williamr@2: * from CCoeControl williamr@2: * williamr@2: * Responds to changes in the position of a control. williamr@2: * williamr@2: */ williamr@2: IMPORT_C virtual void PositionChanged(); williamr@2: williamr@2: williamr@2: // From MCoeControlObserver williamr@2: williamr@2: /** williamr@2: * From MCoeControlObserver. Handles an event from an observed control. williamr@2: * If this component has observer, then a EEventStateChanged is sent to it williamr@2: * when a item is selected from choice list williamr@2: * @param aControl The control that sent the event. williamr@2: * @param aEventType The event type. williamr@2: */ williamr@2: IMPORT_C void HandleControlEventL( CCoeControl* aControl, TCoeEvent aEventType ); williamr@2: williamr@2: public: williamr@2: // new functions williamr@2: /** williamr@2: * Insert new item to a certain index. The rest of the array will be reindexed. williamr@2: * If given index is beyond current array then it's just appended to the end of the array. williamr@2: * @param aIndex The array index where new item is going to be inserted. williamr@2: * @param aText Items text williamr@2: * @return The index of newly inserted item. Index can be other than passed if given index williamr@2: * is out of array bounds williamr@2: */ williamr@2: IMPORT_C TInt InsertItemL( const TInt aIndex, const TDesC& aText ); williamr@2: williamr@2: protected: williamr@2: williamr@2: // from CCoeControl williamr@2: williamr@2: /** williamr@2: * From CCoeControl. Sets the size and position of the component. williamr@2: */ williamr@2: void SizeChanged(); williamr@2: williamr@2: /** williamr@2: * From CCoeControl. Handles pointer events williamr@2: * @param aPointerEvent the pointer event be be handled. williamr@2: */ williamr@2: void HandlePointerEventL( const TPointerEvent& aPointerEvent ); williamr@2: williamr@2: private: williamr@2: williamr@2: /** williamr@2: * C++ Default Constructor williamr@2: */ williamr@2: CAknChoiceList(); williamr@2: williamr@2: /** williamr@2: * 2nd phase constructor williamr@2: * @param aParent the parent control for choice list williamr@2: * @param aItemArray Array of items to be shown in the choicelist williamr@2: * @param aFlags Flags for choice list type and positioning williamr@2: * @param aButton user defined button for choicelist. Button replaces the typical choice list williamr@2: */ williamr@2: void ConstructL( CCoeControl* aParent, CDesCArray* aItemArray, TInt aFlags, CAknButton* aButton ); williamr@2: williamr@2: /** williamr@2: * Construct the typical choice list that open with arrow and show current selection williamr@2: * even in the closed state. williamr@2: */ williamr@2: void ConstructTypicalChoiceListL(); williamr@2: williamr@2: /** williamr@2: * Calculate positioning for the opened choice list popup by the given position flag. williamr@2: */ williamr@2: void SetPopupRect(); williamr@2: williamr@2: /** williamr@2: * Update labels text williamr@2: */ williamr@2: void UpdateLabelL(); williamr@2: williamr@2: /** williamr@2: * Show tooltip text williamr@2: */ williamr@2: void ShowTooltipL(); williamr@2: williamr@2: williamr@2: private: // data williamr@2: williamr@2: /** williamr@2: * Flags for choice list williamr@2: */ williamr@2: TInt iFlags; williamr@2: williamr@2: /** williamr@2: * Currently selected index of an item that is stored in choice list array. williamr@2: */ williamr@2: TInt iSelectedIndex; williamr@2: williamr@2: /** williamr@2: * Used to store if the choice list is closed mode or not. williamr@2: */ williamr@2: TBool iIsClosed; williamr@2: williamr@2: /** williamr@2: * Button for opening the choicelist. If choice lists type is williamr@2: * EAknChoiceListWithCurrentSelection this is the arrow button. williamr@2: * Otherwise this is user defined. williamr@2: * Own. williamr@2: */ williamr@2: CAknButton* iButton; williamr@2: williamr@2: /** williamr@2: * Label that shows the currently selected item if choice list type is williamr@2: * EAknChoiceListWithCurrentSelection. Otherwise this will not be used. williamr@2: * Own. williamr@2: */ williamr@2: CEikLabel* iLabel; williamr@2: williamr@2: /** williamr@2: * Array that stores all the items in the choice list. williamr@2: * Own. williamr@2: */ williamr@2: CDesCArray* iArray; williamr@2: williamr@2: /** williamr@2: * Pointer to current choice list popup window. Popup window is williamr@2: * used only internally and it cannot be accessed from outside. williamr@2: * Own. williamr@2: */ williamr@2: CAknChoiceListPopup* iPopup; williamr@2: williamr@2: /** williamr@2: * Component used to show tooltip williamr@2: * Own. williamr@2: */ williamr@2: CAknInfoPopupNoteController* iTooltip; williamr@2: williamr@2: /** williamr@2: * Stores the text for tooltip williamr@2: * Own. williamr@2: */ williamr@2: HBufC* iTooltipText; williamr@2: williamr@2: /** williamr@2: * Stores the delay in milliseconds when the tooltip is shown williamr@2: * Own. williamr@2: */ williamr@2: TInt iTooltipWaitInterval; williamr@2: williamr@2: /** williamr@2: * Stores the time interval in milliseconds how long the tooltip is shown williamr@2: * Own. williamr@2: */ williamr@2: TInt iTooltipInViewInterval; williamr@2: williamr@2: /** williamr@2: * Stores the tool tip positioning williamr@2: * Own. williamr@2: */ williamr@2: TTooltipPosition iTooltipPosition; williamr@2: williamr@2: williamr@2: }; williamr@2: williamr@2: #endif // AKNCHOICELIST_H williamr@2: williamr@2: // end of file