/*

 * Copyright (c) 2002 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: 

 * Support for Avkon Popped-up lists

 *

 *

 */

 #if !defined(__AKNPOPUP_H__)

 #define __AKNPOPUP_H__

 #include <coecntrl.h>

 #include <eikcmobs.h>

 #include <eiklbx.h>

 #include <aknpopuplayout.h>

 #include <aknintermediate.h>

 #include <aknpopupfader.h>

 class CAknPopupHeadingPane;

 class CEikButtonGroupContainer;

 class CEikListBox;

 class CAknSearchField;

 class CAknPopupListExtension;

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

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

  *

  * @c CAknPopupList is not a dialog!

  *

  * There are two standard usages of @c CAknPopupList:

  *

  * @code 

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

  *  CleanupStack::PushL(plist);

  *  ...

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

  *  // No leaving functions allowed between ExecuteLD and

  *  // CleanupStack::Pop().

  *  CleanupStack::Pop(); // plist

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

  * @endcode

  *

  * And then another way:

  * @code

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

  *  ...

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

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

  *  iPlist = NULL;

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

  *  // note, destructor deletes the iPlist instance.

  * @endcode

  * 

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

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

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

  */

 class CAknPopupList : public CEikBorderedControl,

                       public MEikCommandObserver,

                       public MEikListBoxObserver,

                       public MCoeControlObserver,

                       public MAknIntermediateState,

                       public MAknFadedComponent

     {

 public:	// enums 

     DECLARE_TYPE_ID(0x20018439)

 public:

     /**

      * Two-phased constructor.

      *

      * Creates the pop-up list.

      *

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

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

      * @param aType The layout used.

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

      */

     IMPORT_C static CAknPopupList* NewL( 

        CEikListBox* aListBox, 

        TInt aCbaResource,

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

     /**

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

      * accepted or cancelled the pop-up.

      *

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

      *            the popup was cancelled.

      */

 	IMPORT_C TBool ExecuteLD();

     /**

      * Sets the title for the selection list.

      *

      * @param aTitle Title to be displayed.

      */

     IMPORT_C void SetTitleL(const TDesC& aTitle);

     /**

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

      * @c EFalse.

      */

 	IMPORT_C void CancelPopup();

 public: // Access methods

     /**

      * Gets a button group container.

      *

      * @return The button group.

      */

 	IMPORT_C CEikButtonGroupContainer* ButtonGroupContainer();

     /**

      * Gets the popup header.

      *

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

      */

 	IMPORT_C CAknPopupHeadingPane* Heading();

     /**

      * Gets the popup header.

      *

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

      */

 	IMPORT_C CAknPopupHeadingPane* Heading() const;

     /**

      * Gets the list box.

      *

      * @return The list box.

      */

 	IMPORT_C CEikListBox* ListBox();

     /**

      * Sets the maximum height for the popup frame.

      *

      * @param aItems The maximum height.

      */

 	IMPORT_C void SetMaximumHeight(TInt aItems);

     /**

      * Enables the findbox of the popup list.

      *

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

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

      */

     IMPORT_C TBool EnableFind(TBool aEnable=ETrue);

     /**

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

      *

      * @since 5.0

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

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

      */

     IMPORT_C TBool EnableAdaptiveFind(TBool aEnable=ETrue);

     /**

      * Gets the search field control.

      *

      * @return Search field control.

      */

     IMPORT_C CAknSearchField* FindBox() const;

 public:

     /**

      * From @c CCoeControl.

      * 

      * Handles pointer events of popups.

      *

      * @param aPointerEvent Pointer event to be handled.

      */

     IMPORT_C void HandlePointerEventL(const TPointerEvent& aPointerEvent);

 protected:

     /**

      * From @c MEikCommandObserver.

      *

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

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

      *

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

      */

     IMPORT_C void ProcessCommandL(TInt aCommandId);

     /**

      * From @c MEikListBoxObserver.

      *

      * Processes key events from the listbox. Responds to 

      * @c EEventEnterKeyPressed to accept the pop-up.

      *

      * @param aListBox Listbox being observed.

      * @param aEventType Event being observed.

      */

     IMPORT_C void HandleListBoxEventL(CEikListBox* aListBox, 

                                       TListBoxEvent aEventType);

     /**

      * From @c MCoeControlObserver.

      *

      * Handles an event from an observed control.

      *

      * @param aControl Control being observed.

      * @param aEventType Event observed.

      */

     IMPORT_C void HandleControlEventL(CCoeControl* aControl,

                                       TCoeEvent aEventType);

 protected:

     /**

      * C++ default constructor.

      */

     IMPORT_C CAknPopupList();

     /**

      * Destructor.

      */

     IMPORT_C ~CAknPopupList();

     /**

      * Handles 2nd phase construction.

      * 

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

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

      * @param aType The layout used.

      */

     IMPORT_C void ConstructL(CEikListBox* aListBox, 

                              TInt aCbaResource,

                              AknPopupLayouts::TAknPopupLayouts aType );

     /**

      * Called when the user accepts or cancels the listbox.

      *

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

      *                   has cancelled the listbox.

      */

     IMPORT_C virtual void AttemptExitL(TBool aAccept);

     /**

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

      * position, shadow for the window.

      *

      * @param aType A choice of layout.  

      */

     IMPORT_C virtual void SetupWindowLayout(

                                      AknPopupLayouts::TAknPopupLayouts aType);

     /** 

      * Returns the listbox being used.

      *

      * @return Listbox contained in the pop-up.

      */

     IMPORT_C CEikListBox* ListBox() const;

     /**

      * Gets the layout definitions for the popup list.

      *

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

      *         windows.

      */

     IMPORT_C const TAknPopupWindowLayoutDef& Layout() const;

     /**

      * Gets the layout definitions for the popup list.

      *

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

      *         windows.

      */

     IMPORT_C TAknPopupWindowLayoutDef& Layout();

 protected:

     /**

      * From @c MopSupplyObject.

      *

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

      *

      * @param aId Encapsulated object type ID.

      * @return Encapsulates the pointer to the object provided.

      *         Note that the encapsulated pointer may be NULL.

      */

     IMPORT_C TTypeUid::Ptr MopSupplyObject(TTypeUid aId);

 protected:

     /**

      * From @c CCoeControl.

      *

      * Handles a change to the control's resources.

      *

      * @param aType A message UID value.

      */

     IMPORT_C void HandleResourceChange(TInt aType);

 protected:

 	IMPORT_C void FadeBehindPopup(TBool aFade);

 private:

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

 	// used in virtual table of any derived class.

 	IMPORT_C TSize MinimumSize();

 	IMPORT_C CCoeControl* ComponentControl(TInt aIndex) const;

 	IMPORT_C TInt CountComponentControls() const;

 	IMPORT_C void Draw(const TRect& aRect) const;

 	IMPORT_C TKeyResponse OfferKeyEventL(const TKeyEvent& aKeyEvent,

 	                                     TEventCode aType);

 	IMPORT_C void FocusChanged(TDrawNow aDrawNow);

 	IMPORT_C void CloseState();

 	// From MAknFadedComponent

 	IMPORT_C virtual TInt CountFadedComponents();

 	IMPORT_C virtual CCoeControl* FadedComponent(TInt aIndex);

 private:

     /**

     * From CAknControl

     */

     IMPORT_C void* ExtensionInterface( TUid aInterface );

 private:

 	void RemoveFindFiltering();

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

 	CEikListBox*				iListBox;

     /**

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

      * arrays.

      */

     CEikButtonGroupContainer* iPopoutCba;

     /** 

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

      * pop-up menu.

      */

     CAknPopupHeadingPane* iTitle;

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

     TBool* iReturn;

     /**  */

     TBool iMarkable;

     /**  */

     TInt iCurrentResource;

     /** Popup layout type. */

 	AknPopupLayouts::TAknPopupLayouts iWindowType;

     /**

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

      */

     TAknPopupWindowLayoutDef iLayout;

     /**  */

     TBool iAppBroughtForwards;

     /**  */

     TAknPopupFader iPopupFader;

     /**  */

     CIdle *iIdle;

     /**  */

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

 private:

     CAknPopupListExtension* iPopupListExtension;    // owned

 	};

 #endif