--- 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 <akncontrol.h>
+#include <coecobs.h>
+
+// 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