![[Index]](../../../../_stock/btn_index_wt.gif){kind=small}
![[Spacer]](../../../../_stock/btn_spacer.gif){kind=small}
![[Previous]](../../../../_stock/btn_prev_wt.gif){kind=small}
![[Next]](../../../../_stock/btn_next_wt.gif){kind=small}
|
|
| ||
|
|
|||
Location:
QikListBox.h
Link against: qiklbx.lib
class CQikListBox : public CCoeControl, public MEikScrollBarObserver, public MQikCommandListOwner, public MQikCommandHandler;
Primary API for access to the graphical listbox control.
All data is transparently stored in a model, hiding the complexity for simple usage of the listbox. More advanced users with great amounts of data will have to create their own model since the basic standard model is optimized for small amounts of data. A custom model must inherit from MQikListBoxModel .
The listbox uses two standard views to draw the listbox content in a row listbox or grid listbox, it is designed to allow custom implementations of any type of view as well. Runtime view switching is supported but the listbox can only have one view at the time, the application needs to implement it's own list of views if needed.
Each data entry is presented as an item in the view, each item can have two different layouts attached, that draws the item differently depending on if it is highlighted or not. I.e. fisheye. In the common case all items will use the same layouts but it is possible to set different layouts for each item as well.
An ornament can be used for adding additional graphical effects for each layout.
The user of a listbox might want to have a different string for the select command, such as view, choose, or edit. The correct way of changing the text is to change it in your view by inheriting DynInitOrDeleteCommandL. Switch on the Id() and change the text using an appropriate resource string (for i18n / l10n reasons).
Example:
CQikCommand* CYourView::DynInitOrDeleteCommandL(CQikCommand* aCommand, const CCoeControl& aControlAddingCommands)
{
switch(aCommand->Id())
{
case EQikListBoxCmdSelect:
{
aCommand->SetTextL(iYourResource); // Add with resource to support i18n / l10n
break;
}
default:
break;
}
return aCommand;
}
Using listboxes in building blocks.
It's possible to use a listbox inside a building block, but it is not supported in UIQ 3.0. If you plan on doing it anyway, be aware of the following problems:
Both the building blocks and the listbox wants key up and key down events. The listbox will not work when there is no touch screen unless extra care is taken when designing the solution. A custom building block might be needed.
MQikCommandHandler - Interface for classes responsible of executing commandsMQikCommandListOwner - Interface for classes adding commandsMEikScrollBarObserver - This mixin is implemented by classes wishing to receive notification about scroll events from a scroll barMObjectProvider - An interface that allows an object to be part of a network of object providersCBase - Base class for all classes to be instantiated on the heapCCoeControl - Control base class from which all other controls are derivedCQikListBox - Primary API for access to the graphical listbox controlDefined in CQikListBox:
ActivateL(), AddLayoutL(), AddLayoutL(), AddLayoutL(), CQikListBox(), ClearMatchBufferL(), ClearSelectionL(), ComponentControl(), ConstructFromResourceL(), ConstructFromResourceL(), ConstructL(), ConstructL(), CountComponentControls(), CurrentIncrementalMatchBuffer(), CurrentItemIndex(), DefaultLayoutId(), EHighlightedItem, FocusChanged(), GetColorUseListL(), GetHelpContext(), GetIncrementalMatching(), GetLayout(), GetTextDrawer(), HScrollBarVisibility(), HandleAttemptDimmedSelectionL(), HandleCommandL(), HandleControlArrayEventL(), HandlePointerBufferReadyL(), HandlePointerEventL(), HandleResourceChange(), HasBorder(), HasHighlight(), HasMultipleSelect(), InputCapabilities(), IsItemSelected(), IsItemVisible(), ItemCount(), ItemIdL(), LayoutCount(), LayoutUpdatedL(), LoopingEnabled(), MakeVisible(), MapCommandHandler(), Margins(), MinimumSize(), Mirroring(), Model(), MopSupplyObject(), OfferKeyEventL(), PositionChanged(), PrepareForFocusGainL(), PrepareForFocusLossL(), RemoveAllItemsL(), RemoveItemL(), RemoveLayout(), ReplaceLayoutL(), ReportListBoxEventL(), RequestRelayout(), ResetL(), SelectionIndexes(), SetAdjacent(), SetContainerWindowL(), SetCurrentAndTopItemIndexL(), SetCurrentItemIndexL(), SetDefaultLayoutIdL(), SetDimmed(), SetHighlightEnabledL(), SetIncrementalMatching(), SetItemIdL(), SetItemSelectedL(), SetLayoutManagerL(), SetListBoxObserver(), SetLoopingEnabled(), SetMargins(), SetMirroring(), SetModelL(), SetMultipleSelectL(), SetNeighbor(), SetParent(), SetScrollBarVisibility(), SetSelectionIndexesL(), SetTextBaselineSpacing(), SetViewL(), SetViewL(), SortL(), TListBoxTextDrawerKeys, TextBaselineOffset(), TopItemIndex(), VScrollBarVisibility(), View(), View(), ~CQikListBox()
Inherited from CBase:
Delete(),
Extension_(),
operator new()
Inherited from CCoeControl:
AccumulatedZoom(),
ActivateGc(),
BackedUpWindow(),
Background(),
CapturesPointer(),
ClaimPointerGrab(),
CloseWindow(),
Components(),
ControlContext(),
ControlEnv(),
CopyControlContextFrom(),
CreateBackedUpWindowL(),
CreateWindowL(),
DeactivateGc(),
DrawBackground(),
DrawDeferred(),
DrawForeground(),
DrawNow(),
DrawableWindow(),
EAbsoluteZoom,
ERelativeZoom,
EnableDragEvents(),
FindBackground(),
FindFontProvider(),
GetColor(),
GetGc(),
GrabbingComponent(),
HandleComponentControlsResourceChange(),
HandleRedrawEvent(),
HitTest(),
IgnoreEventsUntilNextPointerUp(),
Index(),
InitComponentArrayL(),
IsActivated(),
IsBackedUp(),
IsBeingDestroyed(),
IsBlank(),
IsDimmed(),
IsFocused(),
IsNonFocusing(),
IsReadyToDraw(),
IsVisible(),
LayoutManager(),
MaximumWidth(),
Observer(),
OverrideColorL(),
OwnsWindow(),
Parent(),
Position(),
PositionRelativeToScreen(),
Rect(),
RecursivelyMergedInputCapabilities(),
ReportEventL(),
Reserved_CCoeControl_10(),
Reserved_CCoeControl_11(),
Reserved_CCoeControl_12(),
Reserved_CCoeControl_13(),
ResetGc(),
ScreenFont(),
SetAllowStrayPointers(),
SetBackground(),
SetBlank(),
SetCanDrawOutsideRect(),
SetComponentsToInheritVisibility(),
SetControlContext(),
SetCornerAndSize(),
SetExtent(),
SetExtentToWholeScreen(),
SetFocus(),
SetFocusing(),
SetFontProviderL(),
SetGc(),
SetGloballyCapturing(),
SetHitTest(),
SetMaximumWidth(),
SetMopParent(),
SetNonFocusing(),
SetObserver(),
SetPointerCapture(),
SetPosition(),
SetRect(),
SetSize(),
SetSizeWithoutNotification(),
SetUniqueHandle(),
SetZoomFactorL(),
Size(),
SizeChanged(),
SystemGc(),
TZoomType,
TextDrawer(),
UniqueHandle(),
Window(),
WriteInternalStateL(),
ZoomWithType(),
iCoeEnv,
iContext,
iPosition,
iSize
Inherited from MEikScrollBarObserver:
HandleScrollEventL()
Inherited from MObjectProvider:
MopGetObject(),
MopGetObjectNoChaining()
IMPORT_C void ConstructL();
Constructs a ListBox with the default model and column ListBox view. Default values for all other settings are used.
IMPORT_C void ConstructL(MQikListBoxModel *aModel, CQikListBoxViewBase *aView);
Constructs a ListBox with the specified model and view. The view and model supplied is taken ownership of by the class.
The model and view needs to be fully constructed before calling this method.
! Need to give this the right behavior, as we turn on pointer grab from the window which owns us.
|
|
virtual IMPORT_C void ConstructFromResourceL(TResourceReader &aReader);
Constructs a ListBox from a resource.
|
IMPORT_C void ConstructFromResourceL(TResourceReader &aReader, MQikListBoxModel *aModel, CQikListBoxViewBase *aView);
Constructs a ListBox from a resource.
The view and model is taken ownership of.
! Need to give this the right behavior, as we turn on pointer grab from the window which owns us.
|
|
virtual IMPORT_C TKeyResponse OfferKeyEventL(const TKeyEvent &aKeyEvent, TEventCode aType);
The key event will be offered to the view if the control is focus able.
|
|
virtual IMPORT_C void HandlePointerEventL(const TPointerEvent &aPointerEvent);
Handles pointer events that occur in the control.
|
virtual IMPORT_C void SetDimmed(TBool aDimmed);
This function sets a flag within the control which indicates whether or not the control is dimmed (greyed out). This is typically used to show that the control is temporarily unavailable. Note that this method unlike CCoeControl::SetDimmed() initiates a redraw by calling DrawDeferred().
When the ListBox is dimmed it will not handle any commands through CQikListBox::HandleCommandL, instead a MCoeControlObserver::EEventInteractionRefused event will be reported.
|
virtual IMPORT_C void PrepareForFocusLossL();
Prepares the control for loss of focus by removing the commands.
This function is called immediately before focus is removed from a control.
virtual IMPORT_C void PrepareForFocusGainL();
Prepares the control for gaining focus by adding the commands.
This function is called immediately before a control is focused.
virtual IMPORT_C void GetColorUseListL(CArrayFix< TCoeColorUse > &aColorUseList) const;
|
virtual IMPORT_C void HandleResourceChange(TInt aType);
Handles a change to the control's resources.
|
virtual IMPORT_C TCoeInputCapabilities InputCapabilities() const;
Gets the control's input capabilities.
|
virtual IMPORT_C TSize MinimumSize();
Returns minimum size of the listbox.
|
virtual IMPORT_C CCoeControl *ComponentControl(TInt aIndex) const;
|
|
IMPORT_C void SetModelL(MQikListBoxModel *aNewModel);
Sets a new model on the listbox. The old model will get a ReleaseModel() call. Takes ownership in the sense that the model will get a ReleaseModel() call if it is replaced again or the listbox is deleted.
|
|
IMPORT_C TInt AddLayoutL(CQikListBoxLayoutPair *aLayoutPair);
Adds a new layout pair to the ListBox. Takes ownership of the layout pair.
|
|
|
IMPORT_C TInt AddLayoutL(TQikListBoxStandardLayout aNormalLayout);
Adds layout pair to the ListBox in which the normal layout is the layout corresponding to aNormalLayout and the highlight layout is NULL.
|
|
IMPORT_C TInt AddLayoutL(TQikListBoxStandardLayout aNormalLayout, TQikListBoxStandardLayout aHighlightLayout);
Adds layout pair to the ListBox where the normal layout is the standard layout corresponding to aNormalLayout and the highlight layout is the standard layout corresponding to aHighlightLayout.
|
|
IMPORT_C void ReplaceLayoutL(CQikListBoxLayoutPair *aLayoutPair, TInt aIndex);
Replaces an existing layout pair in the ListBox. Deletes the old layout pair. Ownership of aLayoutPair is taken in the beginning of this function, hence aLayoutPair should not be owned by the calling object or be pushed to cleanup stack before call.
|
|
IMPORT_C CQikListBoxLayoutPair *RemoveLayout(TInt aIndex);
Removes an existing layout pair in the ListBox. Transfers ownership of the return pair to the caller. There should be at least one layout left, i.e the last layout should not be removed. A ListBox without at least one layout is in an uncertain state.
|
|
|
IMPORT_C TInt LayoutCount() const;
Counts the number of layout pairs currently owned by this ListBox.
|
IMPORT_C void SetDefaultLayoutIdL(TInt aLayoutId);
Sets the default layout and updates the listbox.
It is up to the caller to make sure the layout set has been previously added.
|
IMPORT_C TInt DefaultLayoutId() const;
Gets the default layout.
|
IMPORT_C void LayoutUpdatedL();
Updates the view after layout has been changed. Should be called if the layout has been manually edited.
IMPORT_C void RemoveItemL(TInt aItemIndex);
Removes an item from the ListBox and deletes the item data.
Note that this method includes calls to MQikListBoxModel::ModelBeginUpdateLC and MQikListBoxModel::ModelEndUpdateL .
|
|
IMPORT_C void RemoveAllItemsL();
Removes all items from the ListBox and deletes the item's data.
Calls the models RemoveAllDataL.
|
![[Top]](../../../../_stock/arrow_up_2.gif){kind=icon}
MQikListBoxModel::RemoveAllDataLIMPORT_C TInt ItemCount() const;
Get the number of data items.
|
|
IMPORT_C CQikListBoxViewBase *SetViewL(CQikListBoxViewBase *aView);
Switches to another view. The ListBox takes ownership of the new view and the application is given back the ownership of the old view. The application is also responsible for constructing the new view as well as activating it before this function is called.
The standard behavior is that current item remains when switching views. To set the current item to 0 for example during the view switch, simply call SetCurrentItemIndexL(0,EFalse,ENoDrawNow) before the SetViewL function is called.
|
|
|
IMPORT_C CQikListBoxViewBase *SetViewL(CQikListBoxViewBase *aView, RPointerArray< CQikListBoxLayoutPair > *aLayoutPairArray, RArray< TInt > *aIndexArray);
Switches to another view. The ListBox takes ownership of the new view and the application is given back the ownership of the old view. The application is also responsible for constructing the new view as well as activating it before this function is called.
The standard behavior is that current item remains when switching views. To set the current item to 0 for example during the view switch, simply call SetCurrentItemIndexL(0,EFalse,ENoDrawNow) before the SetViewL function is called.
An array of layoutpairs and layoutid's should be passed as this method also changes layouts. If only the view should be switched and not the layouts, CQikListBox::SetViewL(CQikListBoxViewBase* aView) should be used instead.
Ownership of aView is taken at the end of the function, while ownership of aLayoutPairArray and aIndexArray is taken in the beginning. This means that if the function leaves aLayoutPairArray and aIndexArray is destroyed while the caller still has ownership of aView. In case of a leave the ListBox will keep it's old layout pairs and view.
|
|
|
IMPORT_C CQikListBoxLayoutPair *GetLayout(TInt aIndex) const;
Returns a pointer to the layout pair at the specified index.
|
|
|
IMPORT_C MQikListBoxModel &Model() const;
Returns the ListBox data model.
|
|
IMPORT_C const CQikListBoxViewBase *View() const;
Returns the ListBox view.
|
IMPORT_C CQikListBoxViewBase *View();
Returns the ListBox view.
|
IMPORT_C TInt CurrentItemIndex() const;
Returns the index of the item currently highlighted.
|
IMPORT_C TInt TopItemIndex() const;
Returns the index of the top most item shown in a page.
|
IMPORT_C void SetCurrentItemIndexL(TInt aItemIndex, TBool aMoveToCurrent, TDrawNow aDrawNow);
Set current item index and optionally updates the view.
|
IMPORT_C void SetCurrentAndTopItemIndexL(TInt aItemIndex, TInt aTopItemIndex, TDrawNow aDrawNow);
Set current item index and top index and optionally updates the view.
|
IMPORT_C TBool IsItemVisible(TInt aItemIndex) const;
Returns whether the specified item is currently visible in the ListBox.
|
|
IMPORT_C const RArray< TInt > &SelectionIndexes() const;
Returns the ListBox item indexes for all items currently selected.
|
IMPORT_C void SetSelectionIndexesL(const RArray< TInt > &aArrayOfSelectionIndexes);
Sets the ListBox selection index list.
|
IMPORT_C TBool IsItemSelected(TInt aItemIndex) const;
Returns the current selection state of an item.
|
|
IMPORT_C void SetItemSelectedL(TInt aItemIndex, TBool aSelected, TBool aReportSelectionChanged);
Sets the selection state of the specified item. If the selection state is set to ETrue , the item will be selected and EFalse consequently deselects it.
|
IMPORT_C void ResetL();
Reset the state of the ListBox. Removes all multiple selections and clears match buffer.
IMPORT_C CEikScrollBarFrame::TScrollBarVisibility VScrollBarVisibility() const;
Returns the current settings vertical scrollbar.
|
IMPORT_C CEikScrollBarFrame::TScrollBarVisibility HScrollBarVisibility() const;
Returns the current settings vertical scrollbar.
|
IMPORT_C void SetScrollBarVisibility(CEikScrollBarFrame::TScrollBarVisibility aVScrollBarVisibility, CEikScrollBarFrame::TScrollBarVisibility aHScrollBarVisibility);
Settings for using vertical or horizontal scrollbar.
The auto setting only shows the scrollbar if necessary.
The ListBox View to use should state in its documentation which scrollbars it supports. Setting visibility setting on an unsupported scrollbar yields no effect.
|
IMPORT_C void SetListBoxObserver(MQikListBoxObserver *aObserver);
Sets the ListBox observer, only a single observer is supported. When a observer is registered it will recieve MQikListBoxObserver events. If no ListBox observer is registered the ListBox will report MCoeControlObserver::EEventStateChanged when an item is tapped (what would have been reported as MQikListBoxObserver::EEventItemTapped) or confirmed (what would have been reported as MQikListBoxObserver::EEventItemConfirmed).
|
IMPORT_C void SortL(TLinearOrder< MQikListBoxData > aOrder);
Sorts the items in the ListBox.
Note that this method includes calls to MQikListBoxModel::ModelBeginUpdateLC and MQikListBoxModel::ModelEndUpdateL .
The application must provide the comparison function.
|
IMPORT_C TBool HasMultipleSelect() const;
Checks if multiple select is enabled or not.
|
IMPORT_C TBool HasHighlight() const;
Checks if highlight is enabled or not.
|
IMPORT_C void SetMultipleSelectL(TBool aMultiple);
Turns multiple select on and off.
|
IMPORT_C void SetHighlightEnabledL(TBool aHighlight);
Turns highlighting on and off. Not to be confused with highlighting an individual item.
|
IMPORT_C TMargins8 Margins() const;
Returns the margins between the ListBox´ inner edge and the view's outer edge.
|
IMPORT_C void SetMargins(const TMargins8 &aMargins);
Sets the margins between the ListBox´ inner edge and the view's outer edge.
|
IMPORT_C TBool LoopingEnabled() const;
Returns the setting for looping in the ListBox.
|
IMPORT_C void SetLoopingEnabled(TQikListBoxProperty aLooping);
Sets looping in the Lis