/*
* 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