1 aknchoicelist.h

     1 /*

     2 * Copyright (c) 2005 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 the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  CAknChoiceList - Choice list for S60 

    15 *

    16 */

    17 

    18 

    19 

    20 #ifndef AKNCHOICELIST_H

    21 #define AKNCHOICELIST_H

    22 

    23 // includes 

    24 #include <akncontrol.h>

    25 #include <coecobs.h>

    26 

    27 // forward declarations  

    28 class CAknButton;

    29 class CEikLabel;

    30 class CAknChoiceListPopup;

    31 class CAknChoiceListPopupList;

    32 class CAknsFrameBackgroundControlContext;

    33 class CAknInfoPopupNoteController;

    34 

    35 // Class declaration

    36 

    37 /**

    38  *  CAknChoiceList

    39  *  Choice list is new component, which allows selection from vertical list of choices.

    40  *  By default choice list shows currently selected item and a arrow for opening the 

    41  *  the choice list. Choice list can be used also without showing current selection. 

    42  *  @lib avkon.lib

    43  *  @since S60 5.0

    44  */ 

    45 class CAknChoiceList : public CAknControl, public MCoeControlObserver

    46     {   

    47 public:

    48 

    49     /* Flags for choice list types and positioning */   

    50     enum TAknChoiceListFlags

    51         {

    52         /* Using default choice list with popup list */

    53         EAknChoiceListWithCurrentSelection = 0x01,

    54         /* Using user defined button to open choice list */

    55         EAknChoiceListWithoutCurrentSelection = 0x02,

    56         /* Popup positioning flags */

    57         EAknChoiceListPositionLeft = 0x04,   

    58         EAknChoiceListPositionRight = 0x08,   

    59         EAknChoiceListPositionBottom = 0x10  

    60         };    

    61      

    62      /* Tooltip positioning */

    63      enum TTooltipPosition

    64         {

    65         EPositionTop = 1, /* Tooltip alignment vertically to top */

    66         EPositionBottom, /* Tooltip alignment vertically to bottom */

    67         EPositionLeft, /* Tooltip alignment horizontally to left */

    68         EPositionRight /* Tooltip alignment horizontally to right */

    69         };

    70 public: 

    71 

    72     /**

    73      * Two-phased constructor.

    74      * If the default flag is used then choice list shows an opening arrow and selected item on its 

    75      * left side. If flag EAknChoiceListUsesButton is and user has defined own button then choice list

    76      * open with items in the given array. Selected item is not show when choice list is closed. 

    77      * @param aParent the parent control for choice list

    78      * @param aItemArray Array of items to be shown in the choicelist. Transfers ownership.

    79      * @param aFlags Flags for choice list type and positioning

    80      * @param aButton user defined button for choicelist. Button replaces the typical choice list. 

    81      * Transfers ownership.

    82      */

    83     IMPORT_C static CAknChoiceList* NewL( CCoeControl* aParent, CDesCArray* aItemArray, TInt aFlags = EAknChoiceListWithCurrentSelection, CAknButton* aButton = NULL );

    84 

    85     /**

    86      * Two-phased constructor.

    87      * If the default flag is used then choice list shows an opening arrow and selected item on its 

    88      * left side. If flag EAknChoiceListUsesButton is and user has defined own button then choice list

    89      * open with items in the given array. Selected item is not show when choice list is closed. 

    90      * @param aParent the parent control for choice list

    91      * @param aItemArray Array of items to be shown in the choicelist. Transfers ownership.

    92      * @param aFlags Flags for choice list type and positioning

    93      * @param aButton user defined button for choicelist. Button replaces the typical choice list. 

    94      * Transfers ownership.

    95      */

    96     IMPORT_C static CAknChoiceList* NewLC( CCoeControl* aParent, CDesCArray* aItemArray, TInt aFlags = EAknChoiceListWithCurrentSelection, CAknButton* aButton = NULL );

    97     

    98     /**

    99      * Destructor

   100      */

   101     ~CAknChoiceList();

   102     

   103     /**

   104      * Open choice list.

   105      * Choicelist can be opened with this function. If the choicelist is already

   106      * open nothing will happen.

   107      * @return KErrNone if succeeded

   108      */

   109     IMPORT_C TInt ShowChoiceListL();

   110     

   111     /**

   112      * Set certain index of the choice list array to selected

   113      * @param aIndex Index of the array to be selected as default

   114      */

   115     IMPORT_C void SetSelectedIndex( const TInt aIndex );

   116     

   117     /**

   118      * Returns selected index from the choice list array

   119      * @return TInt selected index

   120      */

   121     IMPORT_C TInt SelectedIndex() const;

   122     

   123     /**

   124      * Set certain array as the contents of the choice list. 

   125      * It's recommended to use CDesCArrayFlat. The ownership of the array is transferred

   126      * to choice list.

   127      * @param aArray Array of text items to be inserted as the content for choice list

   128      */

   129     IMPORT_C void SetItems( CDesCArray* aArray );

   130     

   131     /**

   132      * Set certain array as the contents of the choice list. 

   133      * It's recommended to use CDesCArrayFlat. 

   134      * @param aResourceId Resource id for an array. 

   135      */

   136     IMPORT_C void SetItemsL( TInt aResourceId );

   137     

   138     /**

   139      * Add a text as a new item in the end of the choice list array. 

   140      * @param aDesC Pointer to a descriptor item that should be appended to the array. 

   141      * Transfers ownership.

   142      * @return index in the choicelist array for newly added item. 

   143      */

   144     IMPORT_C TInt AddItemL( const TDesC* aDesC );

   145     

   146     /**

   147      * Removes an item from the choice list array with the given index. 

   148      * @param aIndex index for the item that should be removed from the choice list array

   149      */

   150     IMPORT_C void RemoveItem( const TInt aIndex );    

   151     

   152     /**

   153      * Sets flags for choice list.

   154      * Choice lists position can be changed in runtime with right flags. 

   155      * @param aFlags The flags to be set for choice list

   156      */        

   157     IMPORT_C void SetFlags( const TInt aFlags );

   158     

   159     /**

   160      * Return choice list specific flags.

   161      * @return choice list flags

   162      */

   163     IMPORT_C TInt Flags() const;

   164     

   165     /**

   166      * Set the button that launches choice list opening.

   167      * @param aButton The Button for opening choice list control 

   168      */

   169     IMPORT_C void SetButtonL( CAknButton* aButton );

   170     

   171     /**

   172      * Hide choice list popup. Current selection is not selected.

   173      */

   174     IMPORT_C void HideChoiceList();

   175 

   176     /**

   177      * Set text for tooltip

   178      * @param aText The text shown as tooltip

   179      */

   180     IMPORT_C void SetTooltipTextL( const TDesC& aText );

   181 

   182     /**

   183      * Set the delays for tooltip

   184      * @param aBeforeTimeout The delay in milliseconds before tooltip

   185      *        is shown. The default is 150 milliseconds

   186      * @param aInViewTiemout The interval in milliseconds how long the

   187      *        tooltip is displayed. The default is 3000 milliseconds.

   188      */

   189     IMPORT_C void SetTooltipTimeouts( const TInt aBeforeTimeout,

   190                                       const TInt aInViewTimeout );

   191     /**

   192      * Set the postion of tooltip

   193      * @param aPosition The position expressed with TTooltipPosition

   194      *        The default is EPositionTop

   195      */                                      

   196     IMPORT_C void SetTooltipPosition( const TTooltipPosition aPosition );

   197     

   198 // From CCoeControl

   199     

   200     /**

   201      * From CCoeControl. Returns the control inside control with given index.

   202      * @param aIndex Index of a control be returned

   203      * @return A Pointer to control.

   204      */

   205     IMPORT_C CCoeControl* ComponentControl( TInt aIndex ) const;

   206 

   207     /**

   208      * From CCoeControl. Returns number of controls inside the control.

   209      * @return Number of component controls.

   210      */

   211     IMPORT_C TInt CountComponentControls() const;

   212 

   213     /**

   214      * From CCoeControl. Returns the Minimum size needed by the control. 

   215      * @return TSize minimum size. 

   216      */

   217     IMPORT_C TSize MinimumSize();    

   218     

   219     /**

   220      * From CCoeControl. Handles a change to the control's resources.

   221      * @param aType A message UID value.   

   222      */

   223     IMPORT_C void HandleResourceChange( TInt aType );    

   224     

   225     /**

   226      * From CCoeControl. Handles key events.

   227      * @param aKeyEvent the key event    

   228      * @param aType The type of key event

   229      * @return Indicates whether or not the keyevent was used by this control   

   230      */

   231     IMPORT_C TKeyResponse OfferKeyEventL( const TKeyEvent& aKeyEvent, TEventCode aType );    

   232     

   233     /**

   234      * From CCoeControl. Draws control to given area

   235      * @param aRect The rectangle that should be drawn by the control. 

   236      */

   237     IMPORT_C void Draw( const TRect& aRect ) const;

   238     

   239 

   240     /**

   241     * from CCoeControl 

   242     *

   243     * Responds to changes in the position of a control.

   244     *

   245     */

   246     IMPORT_C virtual void PositionChanged();

   247 

   248 

   249 // From MCoeControlObserver

   250     

   251     /**

   252      * From MCoeControlObserver. Handles an event from an observed control.

   253      * If this component has observer, then a EEventStateChanged is sent to it

   254      * when a item is selected from choice list

   255      * @param aControl The control that sent the event.

   256      * @param aEventType The event type. 

   257      */

   258     IMPORT_C void HandleControlEventL( CCoeControl* aControl, TCoeEvent aEventType );

   259 

   260 public: 

   261     // new functions

   262     /**

   263     * Insert new item to a certain index. The rest of the array will be reindexed. 

   264     * If given index is beyond current array then it's just appended to the end of the array.

   265     * @param aIndex The array index where new item is going to be inserted.

   266     * @param aText Items text

   267     * @return The index of newly inserted item. Index can be other than passed if given index 

   268     * is out of array bounds

   269     */

   270     IMPORT_C TInt InsertItemL( const TInt aIndex, const TDesC& aText );

   271     

   272 protected: 

   273 

   274 // from CCoeControl         

   275     

   276     /**

   277      * From CCoeControl. Sets the size and position of the component. 

   278      */

   279     void SizeChanged();

   280     

   281     /**

   282      * From CCoeControl. Handles pointer events

   283      * @param aPointerEvent the pointer event be be handled.

   284      */

   285     void HandlePointerEventL( const TPointerEvent& aPointerEvent );    

   286 

   287 private:

   288 

   289     /**

   290      * C++ Default Constructor 

   291      */

   292     CAknChoiceList(); 

   293 

   294     /**

   295      * 2nd phase constructor

   296      * @param aParent the parent control for choice list

   297      * @param aItemArray Array of items to be shown in the choicelist

   298      * @param aFlags Flags for choice list type and positioning

   299      * @param aButton user defined button for choicelist. Button replaces the typical choice list

   300      */

   301     void ConstructL( CCoeControl* aParent, CDesCArray* aItemArray, TInt aFlags, CAknButton* aButton );    

   302     

   303     /**

   304      * Construct the typical choice list that open with arrow and show current selection 

   305      * even in the closed state.

   306      */

   307     void ConstructTypicalChoiceListL();

   308     

   309     /**

   310      * Calculate positioning for the opened choice list popup by the given position flag.

   311      */

   312     void SetPopupRect();

   313     

   314     /**

   315      * Update labels text 

   316      */

   317     void UpdateLabelL();

   318 

   319     /**

   320      * Show tooltip text

   321      */

   322     void ShowTooltipL();

   323 

   324     

   325 private: // data

   326 

   327     /**

   328      * Flags for choice list

   329      */

   330     TInt iFlags;

   331     

   332     /** 

   333      * Currently selected index of an item that is stored in choice list array.

   334      */

   335     TInt iSelectedIndex;

   336     

   337     /** 

   338      * Used to store if the choice list is closed mode or not. 

   339      */

   340     TBool iIsClosed;    

   341     

   342     /**

   343      * Button for opening the choicelist. If choice lists type is 

   344      * EAknChoiceListWithCurrentSelection this is the arrow button. 

   345      * Otherwise this is user defined.

   346      * Own.

   347      */

   348     CAknButton* iButton;

   349     

   350     /**

   351      * Label that shows the currently selected item if choice list type is 

   352      * EAknChoiceListWithCurrentSelection. Otherwise this will not be used. 

   353      * Own.

   354      */

   355     CEikLabel* iLabel;

   356 

   357     /**

   358      * Array that stores all the items in the choice list. 

   359      * Own.

   360      */

   361     CDesCArray* iArray;    

   362     

   363     /**

   364      * Pointer to current choice list popup window. Popup window is 

   365      * used only internally and it cannot be accessed from outside.

   366      * Own.

   367      */

   368     CAknChoiceListPopup* iPopup;

   369 

   370     /**

   371      * Component used to show tooltip

   372      * Own.

   373      */

   374     CAknInfoPopupNoteController* iTooltip;

   375 

   376     /**

   377      * Stores the text for tooltip

   378      * Own.

   379      */

   380     HBufC* iTooltipText;

   381 

   382     /**

   383      * Stores the delay in milliseconds when the tooltip is shown

   384      * Own.

   385      */

   386     TInt iTooltipWaitInterval;

   387 

   388     /**

   389      * Stores the time interval in milliseconds how long the tooltip is shown

   390      * Own.

   391      */

   392     TInt iTooltipInViewInterval;

   393 

   394     /**

   395      * Stores the tool tip positioning

   396      * Own.

   397      */

   398     TTooltipPosition iTooltipPosition;

   399 

   400     

   401     };    

   402 

   403 #endif // AKNCHOICELIST_H

   404 

   405 // end of file