williamr@2: /*
williamr@2: * Copyright (c) 2002 Nokia Corporation and/or its subsidiary(-ies).
williamr@2: * All rights reserved.
williamr@2: * This component and the accompanying materials are made available
williamr@4: * under the terms of "Eclipse Public License v1.0"
williamr@2: * which accompanies this distribution, and is available
williamr@4: * at the URL "http://www.eclipse.org/legal/epl-v10.html".
williamr@2: *
williamr@2: * Initial Contributors:
williamr@2: * Nokia Corporation - initial contribution.
williamr@2: *
williamr@2: * Contributors:
williamr@2: *
williamr@2: * Description: 
williamr@2: * Support for Avkon Popped-up lists
williamr@2: *
williamr@2: *
williamr@2: */
williamr@2: 
williamr@2: 
williamr@2: #if !defined(__AKNPOPUP_H__)
williamr@2: #define __AKNPOPUP_H__
williamr@2: 
williamr@2: #include <coecntrl.h>
williamr@2: #include <eikcmobs.h>
williamr@2: #include <eiklbx.h>
williamr@2: #include <aknpopuplayout.h>
williamr@2: #include <aknintermediate.h>
williamr@4: #include <AknPopupFader.h>
williamr@2: 
williamr@2: class CAknPopupHeadingPane;
williamr@2: class CEikButtonGroupContainer;
williamr@2: class CEikListBox;
williamr@2: class CAknSearchField;
williamr@2: class CAknPopupListExtension;
williamr@2: 
williamr@2: /** Used to popup a list or grid. Takes an existing listbox control and
williamr@2:  *  puts it into a popup frame together with an optional title.
williamr@2:  *
williamr@2:  * @c CAknPopupList is not a dialog!
williamr@2:  *
williamr@2:  * There are two standard usages of @c CAknPopupList:
williamr@2:  *
williamr@2:  * @code 
williamr@2:  *  CAknPopupList *plist = CAknPopupList::NewL(...);
williamr@2:  *  CleanupStack::PushL(plist);
williamr@2:  *  ...
williamr@2:  *  TInt popupOk = plist->ExecuteLD(...);
williamr@2:  *  // No leaving functions allowed between ExecuteLD and
williamr@2:  *  // CleanupStack::Pop().
williamr@2:  *  CleanupStack::Pop(); // plist
williamr@2:  *  if (popupOk) { ... } else { ... } 
williamr@2:  * @endcode
williamr@2:  *
williamr@2:  * And then another way:
williamr@2:  * @code
williamr@2:  *  iPList = CAknPopupList::NewL(...);
williamr@2:  *  ...
williamr@2:  *  TInt popupOk = iPlist->ExecuteLD(...);
williamr@2:  *  // No leaving functions allowed between ExecuteLD and iPlist=NULL;
williamr@2:  *  iPlist = NULL;
williamr@2:  *  if (popupOk) {... } else {... }
williamr@2:  *  // note, destructor deletes the iPlist instance.
williamr@2:  * @endcode
williamr@2:  * 
williamr@2:  * Both these work corretly and leave-safe way. Notice this usage is pretty
williamr@2:  * different of how dialogs work. With dialogs you _always_ want to do 
williamr@2:  * @c CleanupStack::Pop() before calling @c ExecuteLD().
williamr@2:  */
williamr@2: class CAknPopupList : public CEikBorderedControl,
williamr@2:                       public MEikCommandObserver,
williamr@2:                       public MEikListBoxObserver,
williamr@2:                       public MCoeControlObserver,
williamr@2:                       public MAknIntermediateState,
williamr@2:                       public MAknFadedComponent
williamr@2:     {
williamr@2: public:	// enums 
williamr@2: 
williamr@2:     DECLARE_TYPE_ID(0x20018439)
williamr@2: 
williamr@2: public:
williamr@2: 
williamr@2:     /**
williamr@2:      * Two-phased constructor.
williamr@2:      *
williamr@2:      * Creates the pop-up list.
williamr@2:      *
williamr@2:      * @param aListBox Pre-existing listbox-derived class.
williamr@2:      * @param aCbaResource Softkey pane to display while pop-up is active.
williamr@2:      * @param aType The layout used.
williamr@2:      * @return A pointer to a pop-up list object.
williamr@2:      */
williamr@2:     IMPORT_C static CAknPopupList* NewL( 
williamr@2:        CEikListBox* aListBox, 
williamr@2:        TInt aCbaResource,
williamr@2:        AknPopupLayouts::TAknPopupLayouts aType = AknPopupLayouts::EMenuWindow);
williamr@2: 
williamr@2:     /**
williamr@2:      * Executes the pop-up selection list. Function returns when the user have
williamr@2:      * accepted or cancelled the pop-up.
williamr@2:      *
williamr@2:      * @return @c ETrue if the popup was accepted. @c EFalse if 
williamr@2:      *            the popup was cancelled.
williamr@2:      */
williamr@2: 	IMPORT_C TBool ExecuteLD();
williamr@2: 
williamr@2:     /**
williamr@2:      * Sets the title for the selection list.
williamr@2:      *
williamr@2:      * @param aTitle Title to be displayed.
williamr@2:      */
williamr@2:     IMPORT_C void SetTitleL(const TDesC& aTitle);
williamr@2: 
williamr@2:     /**
williamr@2:      * Cancels the current popup. The popup @c ExecuteLD will return with 
williamr@2:      * @c EFalse.
williamr@2:      */
williamr@2: 	IMPORT_C void CancelPopup();
williamr@2: public: // Access methods
williamr@2: 
williamr@2:     /**
williamr@2:      * Gets a button group container.
williamr@2:      *
williamr@2:      * @return The button group.
williamr@2:      */
williamr@2: 	IMPORT_C CEikButtonGroupContainer* ButtonGroupContainer();
williamr@2:     /**
williamr@2:      * Gets the popup header.
williamr@2:      *
williamr@2:      * @return Header properties of the pop-up menu.
williamr@2:      */
williamr@2: 	IMPORT_C CAknPopupHeadingPane* Heading();
williamr@2: 
williamr@2:     /**
williamr@2:      * Gets the popup header.
williamr@2:      *
williamr@2:      * @return Header properties of the pop-up menu.
williamr@2:      */
williamr@2: 	IMPORT_C CAknPopupHeadingPane* Heading() const;
williamr@2: 
williamr@2:     /**
williamr@2:      * Gets the list box.
williamr@2:      *
williamr@2:      * @return The list box.
williamr@2:      */
williamr@2: 	IMPORT_C CEikListBox* ListBox();
williamr@2: 	
williamr@2:     /**
williamr@2:      * Sets the maximum height for the popup frame.
williamr@2:      *
williamr@2:      * @param aItems The maximum height.
williamr@2:      */
williamr@2: 	IMPORT_C void SetMaximumHeight(TInt aItems);
williamr@2: 
williamr@2:     /**
williamr@2:      * Enables the findbox of the popup list.
williamr@2:      *
williamr@2:      * @param aEnable Enables (default) or disables the findbox.
williamr@2:      * @return @c ETrue if enabling/disabling was successfull.
williamr@2:      */
williamr@2:     IMPORT_C TBool EnableFind(TBool aEnable=ETrue);
williamr@2: 
williamr@2:     /**
williamr@2:      * Enables the findbox with adaptive search of the popup list.
williamr@2:      *
williamr@2:      * @since 5.0
williamr@2:      * @param aEnable Enables (default) or disables the adaptive findbox.
williamr@2:      * @return @c ETrue if enabling/disabling was successfull.
williamr@2:      */
williamr@2:     IMPORT_C TBool EnableAdaptiveFind(TBool aEnable=ETrue);
williamr@2: 
williamr@2:     /**
williamr@2:      * Gets the search field control.
williamr@2:      *
williamr@2:      * @return Search field control.
williamr@2:      */
williamr@2:     IMPORT_C CAknSearchField* FindBox() const;
williamr@2: public:
williamr@2:     /**
williamr@2:      * From @c CCoeControl.
williamr@2:      * 
williamr@2:      * Handles pointer events of popups.
williamr@2:      *
williamr@2:      * @param aPointerEvent Pointer event to be handled.
williamr@2:      */
williamr@2:     IMPORT_C void HandlePointerEventL(const TPointerEvent& aPointerEvent);
williamr@2: protected:
williamr@2:     /**
williamr@2:      * From @c MEikCommandObserver.
williamr@2:      *
williamr@2:      * Processes events from the softkeys. Responds to @c EAknSoftkeyOk and 
williamr@2:      * @c EAknSoftkeyBack to accept or cancel the pop-up.
williamr@2:      *
williamr@2:      * @param aCommandId Event Id from the soft-key.
williamr@2:      */
williamr@2:     IMPORT_C void ProcessCommandL(TInt aCommandId);
williamr@2: 
williamr@2:     /**
williamr@2:      * From @c MEikListBoxObserver.
williamr@2:      *
williamr@2:      * Processes key events from the listbox. Responds to 
williamr@2:      * @c EEventEnterKeyPressed to accept the pop-up.
williamr@2:      *
williamr@2:      * @param aListBox Listbox being observed.
williamr@2:      * @param aEventType Event being observed.
williamr@2:      */
williamr@2:     IMPORT_C void HandleListBoxEventL(CEikListBox* aListBox, 
williamr@2:                                       TListBoxEvent aEventType);
williamr@2:     /**
williamr@2:      * From @c MCoeControlObserver.
williamr@2:      *
williamr@2:      * Handles an event from an observed control.
williamr@2:      *
williamr@2:      * @param aControl Control being observed.
williamr@2:      * @param aEventType Event observed.
williamr@2:      */
williamr@2:     IMPORT_C void HandleControlEventL(CCoeControl* aControl,
williamr@2:                                       TCoeEvent aEventType);
williamr@2: protected:
williamr@2: 
williamr@2:     /**
williamr@2:      * C++ default constructor.
williamr@2:      */
williamr@2:     IMPORT_C CAknPopupList();
williamr@2: 
williamr@2:     /**
williamr@2:      * Destructor.
williamr@2:      */
williamr@2:     IMPORT_C ~CAknPopupList();
williamr@2: 
williamr@2:     /**
williamr@2:      * Handles 2nd phase construction.
williamr@2:      * 
williamr@2:      * @param aListBox Pre-existing listbox-derived class.
williamr@2:      * @param aCbaResource Softkey pane to display while pop-up is active.
williamr@2:      * @param aType The layout used.
williamr@2:      */
williamr@2:     IMPORT_C void ConstructL(CEikListBox* aListBox, 
williamr@2:                              TInt aCbaResource,
williamr@2:                              AknPopupLayouts::TAknPopupLayouts aType );
williamr@2: 
williamr@2:     /**
williamr@2:      * Called when the user accepts or cancels the listbox.
williamr@2:      *
williamr@2:      * @param aAccept @c ETrue if the user has accepted, @c EFalse if the user 
williamr@2:      *                   has cancelled the listbox.
williamr@2:      */
williamr@2:     IMPORT_C virtual void AttemptExitL(TBool aAccept);
williamr@2: 
williamr@2:     /**
williamr@2:      * Setup the whole window layout; window position, grid and heading 
williamr@2:      * position, shadow for the window.
williamr@2:      *
williamr@2:      * @param aType A choice of layout.  
williamr@2:      */
williamr@2:     IMPORT_C virtual void SetupWindowLayout(
williamr@2:                                      AknPopupLayouts::TAknPopupLayouts aType);
williamr@2: 
williamr@2:     /** 
williamr@2:      * Returns the listbox being used.
williamr@2:      *
williamr@2:      * @return Listbox contained in the pop-up.
williamr@2:      */
williamr@2:     IMPORT_C CEikListBox* ListBox() const;
williamr@2: 
williamr@2:     /**
williamr@2:      * Gets the layout definitions for the popup list.
williamr@2:      *
williamr@2:      * @return Collects all LAF specification lines that are needed for popup 
williamr@2:      *         windows.
williamr@2:      */
williamr@2:     IMPORT_C const TAknPopupWindowLayoutDef& Layout() const;
williamr@2: 
williamr@2:     /**
williamr@2:      * Gets the layout definitions for the popup list.
williamr@2:      *
williamr@2:      * @return Collects all LAF specification lines that are needed for popup 
williamr@2:      *         windows.
williamr@2:      */
williamr@2:     IMPORT_C TAknPopupWindowLayoutDef& Layout();
williamr@2: 
williamr@2: protected:
williamr@2: 
williamr@2:     /**
williamr@2:      * From @c MopSupplyObject.
williamr@2:      *
williamr@2:      * Retrieves an object of the same type as that encapsulated in @c aId.
williamr@2:      *
williamr@2:      * @param aId Encapsulated object type ID.
williamr@2:      * @return Encapsulates the pointer to the object provided.
williamr@2:      *         Note that the encapsulated pointer may be NULL.
williamr@2:      */
williamr@2:     IMPORT_C TTypeUid::Ptr MopSupplyObject(TTypeUid aId);
williamr@2: 
williamr@2: protected:
williamr@2: 
williamr@2:     /**
williamr@2:      * From @c CCoeControl.
williamr@2:      *
williamr@2:      * Handles a change to the control's resources.
williamr@2:      *
williamr@2:      * @param aType A message UID value.
williamr@2:      */
williamr@2:     IMPORT_C void HandleResourceChange(TInt aType);
williamr@2: 
williamr@2: protected:
williamr@2: 	IMPORT_C void FadeBehindPopup(TBool aFade);
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: private:
williamr@2: 	// the following needs to be imported, because they need to be
williamr@2: 	// used in virtual table of any derived class.
williamr@2: 	IMPORT_C TSize MinimumSize();
williamr@2: 	IMPORT_C CCoeControl* ComponentControl(TInt aIndex) const;
williamr@2: 	IMPORT_C TInt CountComponentControls() const;
williamr@2: 	IMPORT_C void Draw(const TRect& aRect) const;
williamr@2: 	IMPORT_C TKeyResponse OfferKeyEventL(const TKeyEvent& aKeyEvent,
williamr@2: 	                                     TEventCode aType);
williamr@2: 	IMPORT_C void FocusChanged(TDrawNow aDrawNow);
williamr@2: 
williamr@2: 	IMPORT_C void CloseState();
williamr@2: 	// From MAknFadedComponent
williamr@2: 	IMPORT_C virtual TInt CountFadedComponents();
williamr@2: 	IMPORT_C virtual CCoeControl* FadedComponent(TInt aIndex);
williamr@2: 
williamr@2: private:
williamr@2:     /**
williamr@2:     * From CAknControl
williamr@2:     */
williamr@2:     IMPORT_C void* ExtensionInterface( TUid aInterface );
williamr@2: 
williamr@2: private:
williamr@2: 	void RemoveFindFiltering();
williamr@2: 
williamr@2: protected: // these are protected to allow overriding virtual functions.
williamr@2: 	CEikListBox*				iListBox;
williamr@2:     
williamr@2:     /**
williamr@2:      * A button group container - a wrapper around the different button 
williamr@2:      * arrays.
williamr@2:      */
williamr@2:     CEikButtonGroupContainer* iPopoutCba;
williamr@2:     
williamr@2:     /** 
williamr@2:      * Header control for queries. Defines properties of the header of the 
williamr@2:      * pop-up menu.
williamr@2:      */
williamr@2:     CAknPopupHeadingPane* iTitle;
williamr@2:     
williamr@2:     /** The address to hold the return value from the popup */
williamr@2:     TBool* iReturn;
williamr@2:     
williamr@2:     /**  */
williamr@2:     TBool iMarkable;
williamr@2:     
williamr@2:     /**  */
williamr@2:     TInt iCurrentResource;
williamr@2:     
williamr@2:     /** Popup layout type. */
williamr@2: 	AknPopupLayouts::TAknPopupLayouts iWindowType;
williamr@2:     
williamr@2:     /**
williamr@2:      * collects all LAF specification lines that are needed for popup window.
williamr@2:      */
williamr@2:     TAknPopupWindowLayoutDef iLayout;
williamr@2: 
williamr@2: 
williamr@2:     /**  */
williamr@2:     TBool iAppBroughtForwards;
williamr@2:     
williamr@2:     /**  */
williamr@2:     TAknPopupFader iPopupFader;
williamr@2:     
williamr@2:     /**  */
williamr@2:     CIdle *iIdle;
williamr@2: 
williamr@2: 
williamr@2:     /**  */
williamr@2: 	CActiveSchedulerWait iWait;		// owned, safe to use as direct member data.
williamr@2: private:
williamr@2:     CAknPopupListExtension* iPopupListExtension;    // owned
williamr@2: 	};
williamr@2: 
williamr@2: #endif
williamr@2: 
williamr@2: 
williamr@2: