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