CAknPopupList Class Reference

class CAknPopupList : public CEikBorderedControl

Used to popup a list or grid. Takes an existing listbox control and puts it into a popup frame together with an optional title.

CAknPopupList is not a dialog!

There are two standard usages of CAknPopupList:

  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 { ... }

And then another way:

  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.

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 CleanupStack::Pop() before calling ExecuteLD().

Inherits from

CAknPopupList
- CEikBorderedControl
  - CAknControl
    - CCoeControl
      - CBase

Public Member Functions
IMPORT_C CEikButtonGroupContainer *	ButtonGroupContainer()
IMPORT_C void	CancelPopup()
IMPORT_C TBool	EnableAdaptiveFind(TBool)
IMPORT_C TBool	EnableFind(TBool)
IMPORT_C TBool	ExecuteLD()
IMPORT_C CAknSearchField *	FindBox()
IMPORT_C void	HandlePointerEventL(const TPointerEvent &)
IMPORT_C CAknPopupHeadingPane *	Heading()
IMPORT_C CAknPopupHeadingPane *	Heading()
IMPORT_C CEikListBox *	ListBox()
IMPORT_C CAknPopupList *	NewL(CEikListBox *, TInt, AknPopupLayouts::TAknPopupLayouts)
IMPORT_C void	SetMaximumHeight(TInt)
IMPORT_C void	SetTitleL(const TDesC &)

Protected Member Functions
	CAknPopupList()
	~CAknPopupList()
IMPORT_C void	AttemptExitL(TBool)
IMPORT_C void	ConstructL(CEikListBox *, TInt, AknPopupLayouts::TAknPopupLayouts)
IMPORT_C void	FadeBehindPopup(TBool)
IMPORT_C void	HandleControlEventL(CCoeControl *, TCoeEvent)
IMPORT_C void	HandleListBoxEventL(CEikListBox *, TListBoxEvent)
IMPORT_C void	HandleResourceChange(TInt)
IMPORT_C const TAknPopupWindowLayoutDef &	Layout()
IMPORT_C TAknPopupWindowLayoutDef &	Layout()
IMPORT_C CEikListBox *	ListBox()
IMPORT_C TTypeUid::Ptr	MopSupplyObject(TTypeUid)
IMPORT_C void	ProcessCommandL(TInt)
IMPORT_C void	SetupWindowLayout(AknPopupLayouts::TAknPopupLayouts)

Private Member Functions
IMPORT_C void	CloseState()
IMPORT_C CCoeControl *	ComponentControl(TInt)
IMPORT_C TInt	CountComponentControls()
IMPORT_C TInt	CountFadedComponents()
IMPORT_C void	Draw(const TRect &)
IMPORT_C void *	ExtensionInterface(TUid)
IMPORT_C CCoeControl *	FadedComponent(TInt)
IMPORT_C void	FocusChanged(TDrawNow)
IMPORT_C TSize	MinimumSize()
IMPORT_C TKeyResponse	OfferKeyEventL(const TKeyEvent &, TEventCode)
void	RemoveFindFiltering()

Inherited Functions
	CAknControl::CAknControl()
	CAknControl::~CAknControl()
	CBase::CBase()
	CBase::Delete(CBase *)
	CBase::Extension_(TUint,TAny &,TAny )
	CBase::operator new(TUint)
	CBase::operator new(TUint,TAny *)
	CBase::operator new(TUint,TLeave)
	CBase::operator new(TUint,TLeave,TUint)
	CBase::operator new(TUint,TUint)
	CBase::~CBase()
	CCoeControl::AccumulatedZoom()const
	CCoeControl::ActivateGc()const
	CCoeControl::ActivateL()
	CCoeControl::BackedUpWindow()const
	CCoeControl::Background()const
	CCoeControl::CCoeControl()
	CCoeControl::CCoeControl(CCoeEnv *)
	CCoeControl::CCoeControl(const CCoeControl &)
	CCoeControl::CapturesPointer()const
	CCoeControl::ClaimPointerGrab(TBool)
	CCoeControl::ClaimPointerGrab(TInt,TBool)
	CCoeControl::CloseWindow()
	CCoeControl::ComponentArrayExists()const
	CCoeControl::Components()
	CCoeControl::Components()const
	CCoeControl::ConstructFromResourceL(TResourceReader &)
	CCoeControl::ControlContext()const
	CCoeControl::ControlEnv()const
	CCoeControl::CopyControlContextFrom(const CCoeControl *)
	CCoeControl::CreateBackedUpWindowL(RWindowTreeNode &)
	CCoeControl::CreateBackedUpWindowL(RWindowTreeNode &,TDisplayMode)
	CCoeControl::CreateWindowL()
	CCoeControl::CreateWindowL(RWindowGroup *)
	CCoeControl::CreateWindowL(RWindowTreeNode &)
	CCoeControl::CreateWindowL(const CCoeControl *)
	CCoeControl::CustomGc()const
	CCoeControl::DeactivateGc()const
	CCoeControl::DrawBackground(const TRect &)const
	CCoeControl::DrawDeferred()const
	CCoeControl::DrawForeground(const TRect &)const
	CCoeControl::DrawNow()const
	CCoeControl::DrawNow(const TRect &)const
	CCoeControl::DrawableWindow()const
	CCoeControl::EnableDragEvents()
	CCoeControl::EnableReportControlStateChange(TBool)
	CCoeControl::EnableWindowTransparency()
	CCoeControl::FindBackground()const
	CCoeControl::FindFontProvider()const
	CCoeControl::GetColor(TInt,TRgb &)const
	CCoeControl::GetGc()const
	CCoeControl::GetHelpContext(TCoeHelpContext &)const
	CCoeControl::GrabbingComponent()const
	CCoeControl::GrabbingComponent(TInt)const
	CCoeControl::HandleComponentControlsResourceChange(TInt)
	CCoeControl::HandleControlArrayEventL(CCoeControlArray::TEvent,const CCoeControlArray ,CCoeControl ,TInt)
	CCoeControl::HandlePointerBufferReadyL()
	CCoeControl::HandleRedrawEvent(const TRect &)const
	CCoeControl::HitTest()const
	CCoeControl::IgnoreEventsUntilNextPointerUp()
	CCoeControl::Index(const CCoeControl *)const
	CCoeControl::InitComponentArrayL()
	CCoeControl::InputCapabilities()const
	CCoeControl::IsActivated()const
	CCoeControl::IsBackedUp()const
	CCoeControl::IsBeingDestroyed()const
	CCoeControl::IsBlank()const
	CCoeControl::IsDimmed()const
	CCoeControl::IsFocused()const
	CCoeControl::IsNonFocusing()const
	CCoeControl::IsReadyToDraw()const
	CCoeControl::IsVisible()const
	CCoeControl::LayoutManager()const
	CCoeControl::MakeVisible(TBool)
	CCoeControl::MaximumWidth()const
	CCoeControl::NotifyFontChange(const CCoeFontProvider *)
	CCoeControl::Observer()const
	CCoeControl::OverrideColorL(TInt,TRgb)
	CCoeControl::OwnsWindow()const
	CCoeControl::Parent()
	CCoeControl::Parent()const
	CCoeControl::Position()const
	CCoeControl::PositionChanged()
	CCoeControl::PositionRelativeToScreen()const
	CCoeControl::PrepareForFocusGainL()
	CCoeControl::PrepareForFocusLossL()
	CCoeControl::ProcessPointerBufferReadyL()
	CCoeControl::ProcessPointerEventL(const TPointerEvent &)
	CCoeControl::Rect()const
	CCoeControl::RecursivelyMergeInputCapabilities(TCoeInputCapabilities &)const
	CCoeControl::RecursivelyMergedInputCapabilities()const
	CCoeControl::RefetchPixelMappingL()
	CCoeControl::RemoveFromParent()
	CCoeControl::ReportEventL(MCoeControlObserver::TCoeEvent)
	CCoeControl::RequestRelayout(const CCoeControl *)
	CCoeControl::ResetGc()const
	CCoeControl::ScreenFont(const TCoeFont &)const
	CCoeControl::SetAllowStrayPointers()
	CCoeControl::SetBackground(const MCoeControlBackground *)
	CCoeControl::SetBlank()
	CCoeControl::SetCanDrawOutsideRect()
	CCoeControl::SetComponentsToInheritVisibility(TBool)
	CCoeControl::SetContainerWindowL(RBackedUpWindow &)
	CCoeControl::SetContainerWindowL(RWindow &)
	CCoeControl::SetContainerWindowL(const CCoeControl &)
	CCoeControl::SetControlContext(MCoeControlContext *)
	CCoeControl::SetCornerAndSize(TGulAlignment,const TSize &)
	CCoeControl::SetCustomGc(CWindowGc *)
	CCoeControl::SetDimmed(TBool)
	CCoeControl::SetExtent(const TPoint &,const TSize &)
	CCoeControl::SetExtentToWholeScreen()
	CCoeControl::SetFocus(TBool,TDrawNow)
	CCoeControl::SetFocusing(TBool)
	CCoeControl::SetFontProviderL(const CCoeFontProvider &)
	CCoeControl::SetGc(CWindowGc *)const
	CCoeControl::SetGloballyCapturing(TBool)
	CCoeControl::SetHitTest(const MCoeControlHitTest *)
	CCoeControl::SetLayoutManagerL(MCoeLayoutManager *)
	CCoeControl::SetMaximumWidth(TInt)
	CCoeControl::SetMopParent(MObjectProvider *)
	CCoeControl::SetNeighbor(CCoeControl *)
	CCoeControl::SetNonFocusing()
	CCoeControl::SetObserver(MCoeControlObserver *)
	CCoeControl::SetParent(CCoeControl *)
	CCoeControl::SetPointerCapture(TBool)
	CCoeControl::SetPosition(const TPoint &)
	CCoeControl::SetRect(const TRect &)
	CCoeControl::SetSize(const TSize &)
	CCoeControl::SetSizeWithoutNotification(const TSize &)
	CCoeControl::SetTextBaselineSpacing(TInt)
	CCoeControl::SetUniqueHandle(TInt)
	CCoeControl::SetZoomFactorL(TInt,TZoomType)
	CCoeControl::Size()const
	CCoeControl::SizeChanged()
	CCoeControl::SystemGc()const
	CCoeControl::TextBaselineOffset(const TSize &)const
	CCoeControl::TextDrawer(TInt)const
	CCoeControl::UniqueHandle()const
	CCoeControl::Window()const
	CCoeControl::WriteInternalStateNowL(RWriteStream &)const
	CCoeControl::ZoomWithType()const
	CCoeControl::operator=(const CCoeControl &)
	CCoeControl::~CCoeControl()
	CEikBorderedControl::Border()const
	CEikBorderedControl::CEikBorderedControl()
	CEikBorderedControl::CEikBorderedControl(const TGulBorder &)
	CEikBorderedControl::GetColorUseListL(CArrayFix< TCoeColorUse > &)const
	CEikBorderedControl::HasBorder()const
	CEikBorderedControl::SetAdjacent(TInt)
	CEikBorderedControl::SetBorder(TGulBorder::TBorderType)
	CEikBorderedControl::SetBorder(TInt)
	CEikBorderedControl::WriteInternalStateL(RWriteStream &)const

Inherited Enumerations
	CCoeControl:TZoomType

Protected Attributes
TBool	iAppBroughtForwards
TInt	iCurrentResource
CIdle *	iIdle
TAknPopupWindowLayoutDef	iLayout
CEikListBox *	iListBox
TBool	iMarkable
CEikButtonGroupContainer *	iPopoutCba
TAknPopupFader	iPopupFader
TBool *	iReturn
CAknPopupHeadingPane *	iTitle
CActiveSchedulerWait	iWait
AknPopupLayouts::TAknPopupLayouts	iWindowType

Private Attributes
CAknPopupListExtension *	iPopupListExtension

Inherited Attributes
	CCoeControl::iCoeEnv
	CCoeControl::iContext
	CCoeControl::iPosition
	CCoeControl::iSize
	CEikBorderedControl::iBorder

Constructor & Destructor Documentation

CAknPopupList()

IMPORT_C

CAknPopupList

(

)

[protected]

C++ default constructor.

~CAknPopupList()

IMPORT_C

~CAknPopupList

(

)

[protected]

Destructor.

Member Functions Documentation

AttemptExitL(TBool)

IMPORT_C void

AttemptExitL

(

TBool

aAccept

)

[protected, virtual]

Called when the user accepts or cancels the listbox.

Parameters

TBool aAccept

ETrue if the user has accepted, EFalse if the user has cancelled the listbox.

ButtonGroupContainer()

IMPORT_C CEikButtonGroupContainer *

ButtonGroupContainer

(

)

Gets a button group container.

The button group.

CancelPopup()

IMPORT_C void

CancelPopup

(

)

Cancels the current popup. The popup ExecuteLD will return with EFalse.

CloseState()

IMPORT_C void

CloseState

(

)

[private]

ComponentControl(TInt)

IMPORT_C CCoeControl *

ComponentControl

(

TInt

aIndex

)

const [private, virtual]

Parameters

TInt aIndex

ConstructL(CEikListBox *, TInt, AknPopupLayouts::TAknPopupLayouts)

IMPORT_C void	ConstructL	(	CEikListBox *	aListBox,
			TInt	aCbaResource,
			AknPopupLayouts::TAknPopupLayouts	aType
		)	[protected]

Handles 2nd phase construction.

Parameters

CEikListBox * aListBox	Pre-existing listbox-derived class.
TInt aCbaResource	Softkey pane to display while pop-up is active.
AknPopupLayouts::TAknPopupLayouts aType	The layout used.

CountComponentControls()

IMPORT_C TInt

CountComponentControls

(

)

const [private, virtual]

CountFadedComponents()

IMPORT_C TInt

CountFadedComponents

(

)

[private, virtual]

Draw(const TRect &)

IMPORT_C void

Draw

(

const TRect &

aRect

)

const [private, virtual]

From CCoeControl. Draws the border around the control. This function also clears the central area if the IsBlank() method returns ETrue.

From CCoeControl

CCoeControl::IsBlank()

Border()

Parameters

const TRect & aRect

Not used.

EnableAdaptiveFind(TBool)

IMPORT_C TBool

EnableAdaptiveFind

(

TBool

aEnable = ETrue

)

Enables the findbox with adaptive search of the popup list.

5.0

ETrue if enabling/disabling was successfull.

Parameters

TBool aEnable = ETrue

Enables (default) or disables the adaptive findbox.

EnableFind(TBool)

IMPORT_C TBool

EnableFind

(

TBool

aEnable = ETrue

)

Enables the findbox of the popup list.

ETrue if enabling/disabling was successfull.

Parameters

TBool aEnable = ETrue

Enables (default) or disables the findbox.

ExecuteLD()

IMPORT_C TBool

ExecuteLD

(

)

Executes the pop-up selection list. Function returns when the user have accepted or cancelled the pop-up.

ETrue if the popup was accepted. EFalse if the popup was cancelled.

ExtensionInterface(TUid)

IMPORT_C void *

ExtensionInterface

(

TUid

aInterface

)

[private, virtual]

From CAknControl

Parameters

TUid aInterface

FadeBehindPopup(TBool)

IMPORT_C void

FadeBehindPopup

(

TBool

aFade

)

[protected]

Parameters

TBool aFade

FadedComponent(TInt)

IMPORT_C CCoeControl *

FadedComponent

(

TInt

aIndex

)

[private, virtual]

Parameters

TInt aIndex

FindBox()

IMPORT_C CAknSearchField *

FindBox

(

)

const

Gets the search field control.

Search field control.

FocusChanged(TDrawNow)

IMPORT_C void

FocusChanged

(

TDrawNow

aDrawNow

)

[private, virtual]

Parameters

TDrawNow aDrawNow

HandleControlEventL(CCoeControl *, TCoeEvent)

IMPORT_C void	HandleControlEventL	(	CCoeControl *	aControl,
			TCoeEvent	aEventType
		)	[protected]

From MCoeControlObserver.

Handles an event from an observed control.

Parameters

CCoeControl * aControl	Control being observed.
TCoeEvent aEventType	Event observed.

HandleListBoxEventL(CEikListBox *, TListBoxEvent)

IMPORT_C void	HandleListBoxEventL	(	CEikListBox *	aListBox,
			TListBoxEvent	aEventType
		)	[protected]

From MEikListBoxObserver.

Processes key events from the listbox. Responds to EEventEnterKeyPressed to accept the pop-up.

Parameters

CEikListBox * aListBox	Listbox being observed.
TListBoxEvent aEventType	Event being observed.

HandlePointerEventL(const TPointerEvent &)

IMPORT_C void

HandlePointerEventL

(

const TPointerEvent &

aPointerEvent

)

[virtual]

From CCoeControl.

Handles pointer events of popups.

Parameters

const TPointerEvent & aPointerEvent

Pointer event to be handled.

HandleResourceChange(TInt)

IMPORT_C void

HandleResourceChange

(

TInt

aType

)

[protected, virtual]

From CCoeControl.

Handles a change to the control's resources.

Parameters

TInt aType

A message UID value.

Heading()

IMPORT_C CAknPopupHeadingPane *

Heading

(

)

Gets the popup header.

Header properties of the pop-up menu.

Heading()

IMPORT_C CAknPopupHeadingPane *

Heading

(

)

const

Gets the popup header.

Header properties of the pop-up menu.

Layout()

IMPORT_C const TAknPopupWindowLayoutDef &

Layout

(

)

const [protected]

Gets the layout definitions for the popup list.

Collects all LAF specification lines that are needed for popup windows.

Layout()

IMPORT_C TAknPopupWindowLayoutDef &

Layout

(

)

[protected]

Gets the layout definitions for the popup list.

Collects all LAF specification lines that are needed for popup windows.

ListBox()

IMPORT_C CEikListBox *

ListBox

(

)

Gets the list box.

The list box.

ListBox()

IMPORT_C CEikListBox *

ListBox

(

)

const [protected]

Returns the listbox being used.

Listbox contained in the pop-up.

MinimumSize()

IMPORT_C TSize

MinimumSize

(

)

[private, virtual]

MopSupplyObject(TTypeUid)

IMPORT_C TTypeUid::Ptr

MopSupplyObject

(

TTypeUid

aId

)

[protected]

From MopSupplyObject.

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

Encapsulates the pointer to the object provided. Note that the encapsulated pointer may be NULL.

Parameters

TTypeUid aId

Encapsulated object type ID.

NewL(CEikListBox *, TInt, AknPopupLayouts::TAknPopupLayouts)

IMPORT_C CAknPopupList *	NewL	(	CEikListBox *	aListBox,
			TInt	aCbaResource,
			AknPopupLayouts::TAknPopupLayouts	aType = AknPopupLayouts::EMenuWindow
		)	[static]

Two-phased constructor.

Creates the pop-up list.

A pointer to a pop-up list object.

Parameters

CEikListBox * aListBox	Pre-existing listbox-derived class.
TInt aCbaResource	Softkey pane to display while pop-up is active.
AknPopupLayouts::TAknPopupLayouts aType = AknPopupLayouts::EMenuWindow	The layout used.

OfferKeyEventL(const TKeyEvent &, TEventCode)

IMPORT_C TKeyResponse	OfferKeyEventL	(	const TKeyEvent &	aKeyEvent,
			TEventCode	aType
		)	[private, virtual]

Parameters

const TKeyEvent & aKeyEvent
TEventCode aType

ProcessCommandL(TInt)

IMPORT_C void

ProcessCommandL

(

TInt

aCommandId

)

[protected]

From MEikCommandObserver.

Processes events from the softkeys. Responds to EAknSoftkeyOk and EAknSoftkeyBack to accept or cancel the pop-up.

Parameters

TInt aCommandId

Event Id from the soft-key.

RemoveFindFiltering()

void

RemoveFindFiltering

(

)

[private]

SetMaximumHeight(TInt)

IMPORT_C void

SetMaximumHeight

(

TInt

aItems

)

Sets the maximum height for the popup frame.

Parameters

TInt aItems

The maximum height.

SetTitleL(const TDesC &)

IMPORT_C void

SetTitleL

(

const TDesC &

aTitle

)

Sets the title for the selection list.

Parameters

const TDesC & aTitle

Title to be displayed.

SetupWindowLayout(AknPopupLayouts::TAknPopupLayouts)

IMPORT_C void

SetupWindowLayout

(

AknPopupLayouts::TAknPopupLayouts

aType

)

[protected, virtual]

Setup the whole window layout; window position, grid and heading position, shadow for the window.

Parameters

AknPopupLayouts::TAknPopupLayouts aType

A choice of layout.

Member Data Documentation

TBool iAppBroughtForwards

TBool

iAppBroughtForwards

[protected]

TInt iCurrentResource

TInt

iCurrentResource

[protected]

CIdle * iIdle

CIdle *

iIdle

[protected]

TAknPopupWindowLayoutDef iLayout

TAknPopupWindowLayoutDef

iLayout

[protected]

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

CEikListBox * iListBox

CEikListBox *

iListBox

[protected]

TBool iMarkable

TBool

iMarkable

[protected]

CEikButtonGroupContainer * iPopoutCba

CEikButtonGroupContainer *

iPopoutCba

[protected]

A button group container - a wrapper around the different button arrays.

TAknPopupFader iPopupFader

TAknPopupFader

iPopupFader

[protected]

CAknPopupListExtension * iPopupListExtension

CAknPopupListExtension *

iPopupListExtension

[private]

TBool * iReturn

TBool *

iReturn

[protected]

The address to hold the return value from the popup

CAknPopupHeadingPane * iTitle

CAknPopupHeadingPane *

iTitle

[protected]

Header control for queries. Defines properties of the header of the pop-up menu.

CActiveSchedulerWait iWait

CActiveSchedulerWait

iWait

[protected]

AknPopupLayouts::TAknPopupLayouts iWindowType

AknPopupLayouts::TAknPopupLayouts

iWindowType

[protected]

Popup layout type.