1 /*

     2 * Copyright (c) 2002 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 "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".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description: 

    15 * Support for Avkon Popped-up lists

    16 *

    17 *

    18 */

    19 

    20 

    21 #if !defined(__AKNPOPUP_H__)

    22 #define __AKNPOPUP_H__

    23 

    24 #include <coecntrl.h>

    25 #include <eikcmobs.h>

    26 #include <eiklbx.h>

    27 #include <aknpopuplayout.h>

    28 #include <aknintermediate.h>

    29 #include <AknPopupFader.h>

    30 

    31 class CAknPopupHeadingPane;

    32 class CEikButtonGroupContainer;

    33 class CEikListBox;

    34 class CAknSearchField;

    35 class CAknPopupListExtension;

    36 

    37 /** Used to popup a list or grid. Takes an existing listbox control and

    38  *  puts it into a popup frame together with an optional title.

    39  *

    40  * @c CAknPopupList is not a dialog!

    41  *

    42  * There are two standard usages of @c CAknPopupList:

    43  *

    44  * @code 

    45  *  CAknPopupList *plist = CAknPopupList::NewL(...);

    46  *  CleanupStack::PushL(plist);

    47  *  ...

    48  *  TInt popupOk = plist->ExecuteLD(...);

    49  *  // No leaving functions allowed between ExecuteLD and

    50  *  // CleanupStack::Pop().

    51  *  CleanupStack::Pop(); // plist

    52  *  if (popupOk) { ... } else { ... } 

    53  * @endcode

    54  *

    55  * And then another way:

    56  * @code

    57  *  iPList = CAknPopupList::NewL(...);

    58  *  ...

    59  *  TInt popupOk = iPlist->ExecuteLD(...);

    60  *  // No leaving functions allowed between ExecuteLD and iPlist=NULL;

    61  *  iPlist = NULL;

    62  *  if (popupOk) {... } else {... }

    63  *  // note, destructor deletes the iPlist instance.

    64  * @endcode

    65  * 

    66  * Both these work corretly and leave-safe way. Notice this usage is pretty

    67  * different of how dialogs work. With dialogs you _always_ want to do 

    68  * @c CleanupStack::Pop() before calling @c ExecuteLD().

    69  */

    70 class CAknPopupList : public CEikBorderedControl,

    71                       public MEikCommandObserver,

    72                       public MEikListBoxObserver,

    73                       public MCoeControlObserver,

    74                       public MAknIntermediateState,

    75                       public MAknFadedComponent

    76     {

    77 public:	// enums 

    78 

    79     DECLARE_TYPE_ID(0x20018439)

    80 

    81 public:

    82 

    83     /**

    84      * Two-phased constructor.

    85      *

    86      * Creates the pop-up list.

    87      *

    88      * @param aListBox Pre-existing listbox-derived class.

    89      * @param aCbaResource Softkey pane to display while pop-up is active.

    90      * @param aType The layout used.

    91      * @return A pointer to a pop-up list object.

    92      */

    93     IMPORT_C static CAknPopupList* NewL( 

    94        CEikListBox* aListBox, 

    95        TInt aCbaResource,

    96        AknPopupLayouts::TAknPopupLayouts aType = AknPopupLayouts::EMenuWindow);

    97 

    98     /**

    99      * Executes the pop-up selection list. Function returns when the user have

   100      * accepted or cancelled the pop-up.

   101      *

   102      * @return @c ETrue if the popup was accepted. @c EFalse if 

   103      *            the popup was cancelled.

   104      */

   105 	IMPORT_C TBool ExecuteLD();

   106 

   107     /**

   108      * Sets the title for the selection list.

   109      *

   110      * @param aTitle Title to be displayed.

   111      */

   112     IMPORT_C void SetTitleL(const TDesC& aTitle);

   113 

   114     /**

   115      * Cancels the current popup. The popup @c ExecuteLD will return with 

   116      * @c EFalse.

   117      */

   118 	IMPORT_C void CancelPopup();

   119 public: // Access methods

   120 

   121     /**

   122      * Gets a button group container.

   123      *

   124      * @return The button group.

   125      */

   126 	IMPORT_C CEikButtonGroupContainer* ButtonGroupContainer();

   127     /**

   128      * Gets the popup header.

   129      *

   130      * @return Header properties of the pop-up menu.

   131      */

   132 	IMPORT_C CAknPopupHeadingPane* Heading();

   133 

   134     /**

   135      * Gets the popup header.

   136      *

   137      * @return Header properties of the pop-up menu.

   138      */

   139 	IMPORT_C CAknPopupHeadingPane* Heading() const;

   140 

   141     /**

   142      * Gets the list box.

   143      *

   144      * @return The list box.

   145      */

   146 	IMPORT_C CEikListBox* ListBox();

   147 	

   148     /**

   149      * Sets the maximum height for the popup frame.

   150      *

   151      * @param aItems The maximum height.

   152      */

   153 	IMPORT_C void SetMaximumHeight(TInt aItems);

   154 

   155     /**

   156      * Enables the findbox of the popup list.

   157      *

   158      * @param aEnable Enables (default) or disables the findbox.

   159      * @return @c ETrue if enabling/disabling was successfull.

   160      */

   161     IMPORT_C TBool EnableFind(TBool aEnable=ETrue);

   162 

   163     /**

   164      * Enables the findbox with adaptive search of the popup list.

   165      *

   166      * @since 5.0

   167      * @param aEnable Enables (default) or disables the adaptive findbox.

   168      * @return @c ETrue if enabling/disabling was successfull.

   169      */

   170     IMPORT_C TBool EnableAdaptiveFind(TBool aEnable=ETrue);

   171 

   172     /**

   173      * Gets the search field control.

   174      *

   175      * @return Search field control.

   176      */

   177     IMPORT_C CAknSearchField* FindBox() const;

   178 public:

   179     /**

   180      * From @c CCoeControl.

   181      * 

   182      * Handles pointer events of popups.

   183      *

   184      * @param aPointerEvent Pointer event to be handled.

   185      */

   186     IMPORT_C void HandlePointerEventL(const TPointerEvent& aPointerEvent);

   187 protected:

   188     /**

   189      * From @c MEikCommandObserver.

   190      *

   191      * Processes events from the softkeys. Responds to @c EAknSoftkeyOk and 

   192      * @c EAknSoftkeyBack to accept or cancel the pop-up.

   193      *

   194      * @param aCommandId Event Id from the soft-key.

   195      */

   196     IMPORT_C void ProcessCommandL(TInt aCommandId);

   197 

   198     /**

   199      * From @c MEikListBoxObserver.

   200      *

   201      * Processes key events from the listbox. Responds to 

   202      * @c EEventEnterKeyPressed to accept the pop-up.

   203      *

   204      * @param aListBox Listbox being observed.

   205      * @param aEventType Event being observed.

   206      */

   207     IMPORT_C void HandleListBoxEventL(CEikListBox* aListBox, 

   208                                       TListBoxEvent aEventType);

   209     /**

   210      * From @c MCoeControlObserver.

   211      *

   212      * Handles an event from an observed control.

   213      *

   214      * @param aControl Control being observed.

   215      * @param aEventType Event observed.

   216      */

   217     IMPORT_C void HandleControlEventL(CCoeControl* aControl,

   218                                       TCoeEvent aEventType);

   219 protected:

   220 

   221     /**

   222      * C++ default constructor.

   223      */

   224     IMPORT_C CAknPopupList();

   225 

   226     /**

   227      * Destructor.

   228      */

   229     IMPORT_C ~CAknPopupList();

   230 

   231     /**

   232      * Handles 2nd phase construction.

   233      * 

   234      * @param aListBox Pre-existing listbox-derived class.

   235      * @param aCbaResource Softkey pane to display while pop-up is active.

   236      * @param aType The layout used.

   237      */

   238     IMPORT_C void ConstructL(CEikListBox* aListBox, 

   239                              TInt aCbaResource,

   240                              AknPopupLayouts::TAknPopupLayouts aType );

   241 

   242     /**

   243      * Called when the user accepts or cancels the listbox.

   244      *

   245      * @param aAccept @c ETrue if the user has accepted, @c EFalse if the user 

   246      *                   has cancelled the listbox.

   247      */

   248     IMPORT_C virtual void AttemptExitL(TBool aAccept);

   249 

   250     /**

   251      * Setup the whole window layout; window position, grid and heading 

   252      * position, shadow for the window.

   253      *

   254      * @param aType A choice of layout.  

   255      */

   256     IMPORT_C virtual void SetupWindowLayout(

   257                                      AknPopupLayouts::TAknPopupLayouts aType);

   258 

   259     /** 

   260      * Returns the listbox being used.

   261      *

   262      * @return Listbox contained in the pop-up.

   263      */

   264     IMPORT_C CEikListBox* ListBox() const;

   265 

   266     /**

   267      * Gets the layout definitions for the popup list.

   268      *

   269      * @return Collects all LAF specification lines that are needed for popup 

   270      *         windows.

   271      */

   272     IMPORT_C const TAknPopupWindowLayoutDef& Layout() const;

   273 

   274     /**

   275      * Gets the layout definitions for the popup list.

   276      *

   277      * @return Collects all LAF specification lines that are needed for popup 

   278      *         windows.

   279      */

   280     IMPORT_C TAknPopupWindowLayoutDef& Layout();

   281 

   282 protected:

   283 

   284     /**

   285      * From @c MopSupplyObject.

   286      *

   287      * Retrieves an object of the same type as that encapsulated in @c aId.

   288      *

   289      * @param aId Encapsulated object type ID.

   290      * @return Encapsulates the pointer to the object provided.

   291      *         Note that the encapsulated pointer may be NULL.

   292      */

   293     IMPORT_C TTypeUid::Ptr MopSupplyObject(TTypeUid aId);

   294 

   295 protected:

   296 

   297     /**

   298      * From @c CCoeControl.

   299      *

   300      * Handles a change to the control's resources.

   301      *

   302      * @param aType A message UID value.

   303      */

   304     IMPORT_C void HandleResourceChange(TInt aType);

   305 

   306 protected:

   307 	IMPORT_C void FadeBehindPopup(TBool aFade);

   308 

   309 

   310 

   311 private:

   312 	// the following needs to be imported, because they need to be

   313 	// used in virtual table of any derived class.

   314 	IMPORT_C TSize MinimumSize();

   315 	IMPORT_C CCoeControl* ComponentControl(TInt aIndex) const;

   316 	IMPORT_C TInt CountComponentControls() const;

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

   318 	IMPORT_C TKeyResponse OfferKeyEventL(const TKeyEvent& aKeyEvent,

   319 	                                     TEventCode aType);

   320 	IMPORT_C void FocusChanged(TDrawNow aDrawNow);

   321 

   322 	IMPORT_C void CloseState();

   323 	// From MAknFadedComponent

   324 	IMPORT_C virtual TInt CountFadedComponents();

   325 	IMPORT_C virtual CCoeControl* FadedComponent(TInt aIndex);

   326 

   327 private:

   328     /**

   329     * From CAknControl

   330     */

   331     IMPORT_C void* ExtensionInterface( TUid aInterface );

   332 

   333 private:

   334 	void RemoveFindFiltering();

   335 

   336 protected: // these are protected to allow overriding virtual functions.

   337 	CEikListBox*				iListBox;

   338     

   339     /**

   340      * A button group container - a wrapper around the different button 

   341      * arrays.

   342      */

   343     CEikButtonGroupContainer* iPopoutCba;

   344     

   345     /** 

   346      * Header control for queries. Defines properties of the header of the 

   347      * pop-up menu.

   348      */

   349     CAknPopupHeadingPane* iTitle;

   350     

   351     /** The address to hold the return value from the popup */

   352     TBool* iReturn;

   353     

   354     /**  */

   355     TBool iMarkable;

   356     

   357     /**  */

   358     TInt iCurrentResource;

   359     

   360     /** Popup layout type. */

   361 	AknPopupLayouts::TAknPopupLayouts iWindowType;

   362     

   363     /**

   364      * collects all LAF specification lines that are needed for popup window.

   365      */

   366     TAknPopupWindowLayoutDef iLayout;

   367 

   368 

   369     /**  */

   370     TBool iAppBroughtForwards;

   371     

   372     /**  */

   373     TAknPopupFader iPopupFader;

   374     

   375     /**  */

   376     CIdle *iIdle;

   377 

   378 

   379     /**  */

   380 	CActiveSchedulerWait iWait;		// owned, safe to use as direct member data.

   381 private:

   382     CAknPopupListExtension* iPopupListExtension;    // owned

   383 	};

   384 

   385 #endif

   386 

   387 

   388