williamr@2: /* williamr@2: * Copyright (c) 1997-2009 Nokia Corporation and/or its subsidiary(-ies). williamr@2: * All rights reserved. williamr@2: * This component and the accompanying materials are made available williamr@2: * 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 williamr@2: * which accompanies this distribution, and is available williamr@2: * at the URL "http://www.symbianfoundation.org/legal/licencesv10.html". williamr@2: * williamr@2: * Initial Contributors: williamr@2: * Nokia Corporation - initial contribution. williamr@2: * williamr@2: * Contributors: williamr@2: * williamr@2: * Description: Base class for an on-screen list box control from williamr@2: * which one or more items can be selected. williamr@2: * williamr@2: */ williamr@2: williamr@2: #ifndef __EIKLBX_H__ williamr@2: #define __EIKLBX_H__ williamr@2: williamr@2: // INCLUDES williamr@2: #include williamr@2: #include williamr@2: #include williamr@2: #include williamr@2: #include williamr@2: #include williamr@2: #include williamr@2: #include williamr@2: #include williamr@2: #include williamr@2: williamr@2: // FORWARD DECLARATIONS williamr@2: enum TKeyCode; williamr@2: class RIncrMatcherBase; williamr@2: class CListItemDrawer; williamr@2: class CEikScrollBarFrame; williamr@2: class CEikButtonBase; williamr@2: class CMatchBuffer; williamr@2: class CListBoxExt; williamr@2: class CEikListBox; williamr@2: williamr@2: // CLASS DECLARATION williamr@2: williamr@2: /** williamr@2: * Item change observer will be notified when list box items have been added or williamr@2: * removed or the list box has been reset. Observers can be added and removed by williamr@2: * using @c CEikListBox methods @c AddItemChangeObserverL() and williamr@2: * @c RemoveItemChangeObserver(). williamr@2: * williamr@2: * @since 3.0 williamr@2: */ williamr@2: class MListBoxItemChangeObserver williamr@2: { williamr@2: public: williamr@2: /** williamr@2: * Notification and handling of a list box item change. williamr@2: * williamr@2: * @param aListBox The source list box of this message. williamr@2: */ williamr@2: virtual void ListBoxItemsChanged(CEikListBox* aListBox) = 0; williamr@2: }; williamr@2: williamr@2: williamr@2: /** williamr@2: * Item selection (marking) observer is used to let application control item marking williamr@2: * (in markable lists). Observers can be added and removed by using williamr@2: * @c CEikListBox methods @c AddSelectionObserverL() and williamr@2: * @c RemoveSelectionObserver(). williamr@2: * williamr@2: * @since 3.2 williamr@2: */ williamr@2: class MListBoxSelectionObserver williamr@2: { williamr@2: public: williamr@2: /** williamr@2: * Notification of entering and leaving marking mode. Marking mode williamr@2: * is enabled by long pressing shift, ctrl or hash keys (when hash key marking is enabled). williamr@2: * williamr@2: * @param aListBox The source list box of this message. williamr@2: * @param aSelectionModeEnabled ETrue, when entering selection (marking) mode. williamr@2: */ williamr@2: virtual void SelectionModeChanged(CEikListBox* aListBox, TBool aSelectionModeEnabled) = 0; williamr@2: }; williamr@2: williamr@2: williamr@2: // CLASS DECLARATION williamr@2: williamr@2: /** williamr@2: * Base class for an on-screen list box control from which one or more items williamr@2: * can be selected. williamr@2: * williamr@2: * @c CEikListBox implements the basics of a list box. It has a scroll bar williamr@2: * frame, an item drawer, and a model, and reports events to a list box williamr@2: * observer. williamr@2: * williamr@2: * List boxes display a number of items within a scrolling frame; the items williamr@2: * in a list box which are visible at one time are represented by a list williamr@2: * box view. williamr@2: * williamr@2: * Writing derived classes: williamr@2: * williamr@2: * This class may be derived from to provide specialisations of the basic williamr@2: * list box behaviour. It is usual when subclassing CEikListBox to also williamr@2: * provide specialisations of CListItemDrawer and CListBoxView for williamr@2: * representing the data of such a list box effectively williamr@2: */ williamr@2: class CEikListBox : public CEikBorderedControl, public MEikScrollBarObserver williamr@2: { williamr@2: williamr@2: public: williamr@2: williamr@2: friend class CListBoxExt; williamr@2: williamr@2: public: williamr@2: williamr@2: /** williamr@2: * Construction flags. williamr@2: */ williamr@2: enum TFlags williamr@2: { williamr@2: williamr@2: /** williamr@2: * Construction flag for a list box from which the user can williamr@2: * select multiple items. williamr@2: */ williamr@2: EMultipleSelection = SLafListBox::EMultipleSelection, williamr@2: williamr@2: /** williamr@2: * Construction flag for disabling extended selection. williamr@2: * If this is set the user cannot select multiple items by williamr@2: * using @c SHIFT button. williamr@2: */ williamr@2: ENoExtendedSelection = SLafListBox::ENoExtendedSelection, williamr@2: williamr@2: /** williamr@2: * Construction flag that sets the list box to match user’s keystrokes williamr@2: * incrementally. williamr@2: */ williamr@2: EIncrementalMatching = SLafListBox::EIncrementalMatching, williamr@2: williamr@2: /** williamr@2: * Construction flag for setting the list box as a pop-out list box. williamr@2: * Pop-out list boxes handle certain keystrokes and events differently. williamr@2: */ williamr@2: EPopout = SLafListBox::EPopout, williamr@2: williamr@2: /** williamr@2: * Construction flag that enables the indication of pointer press williamr@2: * inside the view of the list box. williamr@2: */ williamr@2: ELeftDownInViewRect = SLafListBox::ELeftDownInViewRect, williamr@2: williamr@2: /** williamr@2: * Construction flag for enabling @c CEiklist box item double click williamr@2: * indication. williamr@2: */ williamr@2: EItemDoubleClicked = SLafListBox::EItemDoubleClicked, williamr@2: williamr@2: /** williamr@2: * Construction flag for removing the ownership of the supplied list box williamr@2: * model from the @c CEikListBox so that the list box model will not be williamr@2: * deleted with the @c CEikListBoxes destruction. williamr@2: */ williamr@2: EKeepModel = SLafListBox::EKeepModel, williamr@2: williamr@2: /** williamr@2: * Construction flag for excluding the scroll bar. williamr@2: * If the flag is set the scroll bas is drawn ouside the window that williamr@2: * describes the scroll bars extent. williamr@2: */ williamr@2: EScrollBarSizeExcluded = SLafListBox::EScrollBarSizeExcluded, williamr@2: williamr@2: /** williamr@2: * Construction flag for enabling @c CEikListBox change indication. williamr@2: */ williamr@2: EStateChanged = SLafListBox::EStateChanged, williamr@2: williamr@2: /** williamr@2: * Construction flag that indicates that the list box should be created williamr@2: * to its own window. williamr@2: */ williamr@2: ECreateOwnWindow = SLafListBox::ECreateOwnWindow, williamr@2: williamr@2: /** williamr@2: * Construction flag for disabling key matching. williamr@2: */ williamr@2: ENoFirstLetterMatching = SLafListBox::ENoFirstLetterMatching, williamr@2: williamr@2: /** williamr@2: * Construction flag for enabling painting of selected items. williamr@2: */ williamr@2: EPaintedSelection = SLafListBox::EPaintedSelection , williamr@2: williamr@2: /** williamr@2: * Construction flag for enabling loop scrolling in which the list box williamr@2: * jumps from the last item to the first item. williamr@2: */ williamr@2: ELoopScrolling = 0x1000, williamr@2: williamr@2: /** williamr@2: * Construction flag for enabling @c Avkon multiselection list. williamr@2: */ williamr@2: EEnterMarks = 0x2000, // Avkon multiselection list williamr@2: williamr@2: /** williamr@2: * Construction flag for enabling Avkon markable list which enables the williamr@2: * marking of several items from the list. williamr@2: */ williamr@2: EShiftEnterMarks = 0x4000, // Avkon markable list williamr@2: williamr@2: /** williamr@2: * Construction flag that combines @c EPageAtOnceScrolling and williamr@2: * @c EDisableHighlight flags williamr@2: */ williamr@2: EViewerFlag = 0x8000, // combined the two flags to fit to WORD. williamr@2: williamr@2: /** williamr@2: * Construction flag for enabling scrolling at a page per time so that williamr@2: * the whole list box page is scrolled to the next. williamr@2: */ williamr@2: EPageAtOnceScrolling = 0x8000, // Avkon viewers williamr@2: williamr@2: /** williamr@2: * Construction flag for disabling the highlighting of the selected item. williamr@2: */ williamr@2: EDisableHighlight = 0x8000, // Avkon viewers williamr@2: williamr@2: /** williamr@2: * Construction flag for enabling S60 style selection of multiple items williamr@2: * from the list box. williamr@2: */ williamr@2: ES60StyleMultiselection = SLafListBox::ES60StyleMultiselection, williamr@2: williamr@2: /** williamr@2: * Construction flag for enabling S60 style markable items. williamr@2: */ williamr@2: ES60StyleMarkable = SLafListBox::ES60StyleMarkable williamr@2: }; williamr@2: enum {KEikMaxMatchingBufferLength = 2}; williamr@2: williamr@2: /** williamr@2: * Indicates who owns the scroll bar. williamr@2: */ williamr@2: enum TScrollBarOwnerShip williamr@2: { williamr@2: /** williamr@2: * Indicates that the scrollbar is not owned by an external class. williamr@2: */ williamr@2: ENotOwnedExternally=0x0000, williamr@2: /** williamr@2: * Indicates that the scrollbar is owned by an external class. williamr@2: */ williamr@2: EOwnedExternally =0x0001 williamr@2: }; williamr@2: williamr@2: protected: williamr@2: williamr@2: /** williamr@2: * Used for indicating the reason why the item lost focus. williamr@2: */ williamr@2: enum TReasonForFocusLost williamr@2: { williamr@2: /** williamr@2: * Focus has been lost from the list box to an external control. williamr@2: */ williamr@2: EFocusLostToExternalControl, williamr@2: /** williamr@2: * Focus has been moved from the list box to an internal editor. williamr@2: */ williamr@2: EFocusLostToInternalEditor williamr@2: }; williamr@2: williamr@2: public: williamr@2: /** williamr@2: * Destructor. williamr@2: */ williamr@2: IMPORT_C ~CEikListBox(); williamr@2: williamr@2: /** williamr@2: * C++ default constructor. williamr@2: */ williamr@2: IMPORT_C CEikListBox(); williamr@2: /** williamr@2: * Handles 2nd phase construction. williamr@2: * williamr@2: * Sets list box model and list item drawer. Request another @c ConstructL williamr@2: * to handle @c aParent and @c aFlags. williamr@2: * williamr@2: * @param aListBoxModel List box model that is to be used with the list box. williamr@2: * @param aListItemDrawer List item drawer that is to be used with the williamr@2: * list box. williamr@2: * @param aParent Host @c CoeControl for the list box. williamr@2: * @param aFlags Construction flags (@c TFlags) for the list box. williamr@2: */ williamr@2: IMPORT_C void ConstructL(MListBoxModel* aListBoxModel, williamr@2: CListItemDrawer* aListItemDrawer, williamr@2: const CCoeControl* aParent, williamr@2: TInt aFlags = 0); williamr@2: williamr@2: /** williamr@2: * Handles 2nd phase construction. williamr@2: * williamr@2: * williamr@2: * Sets the border that is to be drawn outside the list box. Request another williamr@2: * @c ConstructL to handle list box model, list item drawer, @c aParent williamr@2: * and @c aFlags. williamr@2: * williamr@2: * @param aListBoxModel List box model that is to be used with the list box. williamr@2: * @param aListItemDrawer List item drawer that is to be used with the williamr@2: * list box. williamr@2: * @param aParent Host @c CoeControl for the list box. williamr@2: * @param aBorder Border to be drawn outside the list box. williamr@2: * @param aFlags Construction flags (@c TFlags) for the list box. williamr@2: */ williamr@2: IMPORT_C void ConstructL(MListBoxModel* aListBoxModel, williamr@2: CListItemDrawer* aListItemDrawer, williamr@2: const CCoeControl* aParent, williamr@2: TGulBorder aBorder, williamr@2: TInt aFlags = 0); williamr@2: /** williamr@2: * Informs the @c CEikListbox of a key press. williamr@2: * williamr@2: * @param aKeyEvent Details of the key event that is being handled. williamr@2: * @param aType Defines what kind of key event is being handled e.g. williamr@2: * @c EEventKeyUp. williamr@2: * @return @c EKeyWasConsumed if the key was handled by the method. williamr@2: * @c EKeyWasNotConsumed if the key was not handled. williamr@2: */ williamr@2: IMPORT_C virtual TKeyResponse OfferKeyEventL(const TKeyEvent& aKeyEvent, williamr@2: TEventCode aType); williamr@2: williamr@2: /** williamr@2: * Handling of pointer event within the @c CEikListBox. williamr@2: * Used for e.g. selecting an item from the list box. williamr@2: * williamr@2: * @param aPointerEvent Details of the pointer event that is being handled. williamr@2: */ williamr@2: IMPORT_C virtual void HandlePointerEventL( williamr@2: const TPointerEvent& aPointerEvent); williamr@2: williamr@2: /** williamr@2: * Creates an own window for the list box or draws the list box to an old williamr@2: * window defined by the @c aContainer. williamr@2: * williamr@2: * @param aContainer Defines the container where the list box will be drawn. williamr@2: */ williamr@2: IMPORT_C virtual void SetContainerWindowL(const CCoeControl& aContainer); williamr@2: williamr@2: /** williamr@2: * Checks the minimum size needed for the list box. williamr@2: * williamr@2: * @return The two dimensional minimum size for the list box. williamr@2: */ williamr@2: IMPORT_C virtual TSize MinimumSize(); williamr@2: williamr@2: /** williamr@2: * This function sets a flag within the control which indicates williamr@2: * whether or not the control is dimmed (greyed out). williamr@2: * williamr@2: * @param aDimmed @c ETrue dimmed. @c EFalse not dimmed. williamr@2: */ williamr@2: IMPORT_C virtual void SetDimmed(TBool aDimmed); williamr@2: williamr@2: /** williamr@2: * Used for scrolling through the items in the list box. williamr@2: * williamr@2: * @param aScrollBar Scroll bar for the list box. williamr@2: * @param aEventType Type of the event that occured. williamr@2: */ williamr@2: IMPORT_C virtual void HandleScrollEventL(CEikScrollBar* aScrollBar, williamr@2: TEikScrollEvent aEventType); williamr@2: williamr@2: // model/view access functions williamr@2: /** williamr@2: * Gets the list box data model. williamr@2: * williamr@2: * @return Interface to the list box data model. williamr@2: */ williamr@2: IMPORT_C MListBoxModel* Model() const; williamr@2: williamr@2: /** williamr@2: * Gets the list box view. williamr@2: * williamr@2: * @return Interface to the list box view. williamr@2: */ williamr@2: IMPORT_C CListBoxView* View() const; williamr@2: williamr@2: // functions for accessing top/current/bottom item index williamr@2: /** williamr@2: * Gets the index number of the top item. williamr@2: * williamr@2: * @return Index number for the top item. williamr@2: */ williamr@2: IMPORT_C TInt TopItemIndex() const; williamr@2: williamr@2: /** williamr@2: * Sets the selected item to be the top item. williamr@2: * williamr@2: * @param aItemIndex Index for the item to be set as the top item. williamr@2: */ williamr@2: IMPORT_C virtual void SetTopItemIndex(TInt aItemIndex) const; williamr@2: williamr@2: /** williamr@2: * Gets for the bottom items index. williamr@2: * williamr@2: * @return Index for the bottom item. williamr@2: */ williamr@2: IMPORT_C TInt BottomItemIndex() const; williamr@2: williamr@2: /** williamr@2: * Gets the index number of the selected item. williamr@2: * williamr@2: * @return Index of the selected item. williamr@2: */ williamr@2: IMPORT_C TInt CurrentItemIndex() const; williamr@2: williamr@2: /** williamr@2: * Changes the current item index to the selected item index. Does not williamr@2: * redraw the list. If the item was not previously visible it is set to the williamr@2: * top item in the view. williamr@2: * williamr@2: * @param aItemIndex Defines the index of the selected item. williamr@2: */ williamr@2: IMPORT_C void SetCurrentItemIndex(TInt aItemIndex) const; williamr@2: williamr@2: /** williamr@2: * Changes the current item index to the selected item index and williamr@2: * redraws the view. williamr@2: * williamr@2: * @param aItemIndex Defines the index of the selected item. williamr@2: */ williamr@2: IMPORT_C void SetCurrentItemIndexAndDraw(TInt aItemIndex) const; williamr@2: williamr@2: // functions for dealing with the selection state williamr@2: /** williamr@2: * Gets for list boxes selection indexes. williamr@2: * williamr@2: * @return Pointer to the list boxes in array of selection indexes. williamr@2: */ williamr@2: IMPORT_C const CListBoxView::CSelectionIndexArray* SelectionIndexes() const; williamr@2: williamr@2: /** williamr@2: * Assigns a array of selection indexes for the list box. williamr@2: * williamr@2: * @param aArrayOfSelectionIndexes The index array that is to be assigned williamr@2: * to the list Box. williamr@2: */ williamr@2: IMPORT_C void SetSelectionIndexesL( williamr@2: CListBoxView::CSelectionIndexArray* aArrayOfSelectionIndexes); williamr@2: williamr@2: /** williamr@2: * Clears the selection from the view. williamr@2: */ williamr@2: IMPORT_C void ClearSelection(); williamr@2: williamr@2: // Functions for updating a list box's internal state after its model has williamr@2: // been updated, all of them will emit item change event to item change williamr@2: // observers. williamr@2: /** williamr@2: * Handles the addition of item to the list box. williamr@2: */ williamr@2: IMPORT_C void HandleItemAdditionL(); williamr@2: williamr@2: /** williamr@2: * Handles the removal of an item from the list box. williamr@2: */ williamr@2: IMPORT_C void HandleItemRemovalL(); williamr@2: williamr@2: /** williamr@2: * Handles the addition of new items to the list box and updates williamr@2: * selection indexes array. williamr@2: * williamr@2: * NOTE. This algorithm can not handle position of the list highlight williamr@2: * nor can it update the top item index correctly. williamr@2: * williamr@2: * @param aArrayOfNewIndexesAfterAddition Array of new indexes to be added. williamr@2: */ williamr@2: IMPORT_C void HandleItemAdditionL( williamr@2: CArrayFix &aArrayOfNewIndexesAfterAddition); williamr@2: williamr@2: /** williamr@2: * Handles the removal of items to the list box and updates williamr@2: * selection indexes array. williamr@2: * williamr@2: * NOTE. This algorithm cannot handle position of the list highlight williamr@2: * nor can it update the top item index correctly. williamr@2: * williamr@2: * @param aArrayOfOldIndexesBeforeRemoval Array of indexes to be removed. williamr@2: */ williamr@2: IMPORT_C void HandleItemRemovalL( williamr@2: CArrayFix &aArrayOfOldIndexesBeforeRemoval); williamr@2: williamr@2: /** williamr@2: * Deletes the item editor williamr@2: */ williamr@2: IMPORT_C void Reset(); williamr@2: williamr@2: /** williamr@2: * Adds an item change observer to the listbox. Duplicates are not checked williamr@2: * (i.e. adding the same observer multiple times is not prevented). williamr@2: * williamr@2: * @since 3.0 williamr@2: * @param aObserver Must be non-NULL. williamr@2: */ williamr@2: IMPORT_C void AddItemChangeObserverL( MListBoxItemChangeObserver* aObserver ); williamr@2: /** williamr@2: * Removes an item change observer from the listbox. williamr@2: * williamr@2: * @since 3.0 williamr@2: * @param aObserver The observer to be removed. williamr@2: * @return ETrue if removal ok, EFalse if observer was not removed (not williamr@2: * found from the list of observers). williamr@2: */ williamr@2: IMPORT_C TBool RemoveItemChangeObserver( MListBoxItemChangeObserver* aObserver ); williamr@2: williamr@2: // functions for accessing the item height williamr@2: /** williamr@2: * Sets the height of the item to the selected value. williamr@2: * williamr@2: * @param aHeight New height for the item. williamr@2: */ williamr@2: IMPORT_C virtual void SetItemHeightL(TInt aHeight); williamr@2: williamr@2: /** williamr@2: * Gets height of the item. williamr@2: * williamr@2: * @return Height of the item. williamr@2: */ williamr@2: IMPORT_C TInt ItemHeight() const; williamr@2: williamr@2: // functions for scrollbars williamr@2: /** williamr@2: * Creates a scrollbar frame. williamr@2: * williamr@2: * @param aPreAlloc Boolean defining if there should be initial williamr@2: * memory allocations. williamr@2: * @return The new scroll bar frame. williamr@2: */ williamr@2: IMPORT_C CEikScrollBarFrame* CreateScrollBarFrameL(TBool aPreAlloc=EFalse); williamr@2: williamr@2: /** williamr@2: * Sets the given scroll bar frame for the list box with the given williamr@2: * ownership leve. williamr@2: * williamr@2: * @param aScrollBarFrame The new frame that is going to be used. williamr@2: * @param aOwnerShip Ownership level of the scroll bar frame. williamr@2: */ williamr@2: IMPORT_C void SetScrollBarFrame(CEikScrollBarFrame* aScrollBarFrame, TScrollBarOwnerShip aOwnerShip); williamr@2: williamr@2: /** williamr@2: * Gets pointer for the scroll bar frame. williamr@2: * williamr@2: * @return Pointer to the scroll bar frame. williamr@2: */ williamr@2: IMPORT_C CEikScrollBarFrame* const ScrollBarFrame(); williamr@2: williamr@2: /** williamr@2: * Updates all scroll bars. williamr@2: */ williamr@2: IMPORT_C virtual void UpdateScrollBarsL(); williamr@2: williamr@2: // construction support functions williamr@2: /** williamr@2: * Gets the size of the rectangle required to display a pop out. williamr@2: * williamr@2: * @param aTargetItemIndex The item from which the popout originates. williamr@2: * @param aTargetYPos Vertical position of the item from which the popout williamr@2: * originates. williamr@2: * @param aListBoxRect The list box rectangle. williamr@2: * @param aMinHeightInNumOfItems The minimum number of items for the popout. williamr@2: */ williamr@2: IMPORT_C void CalculatePopoutRect( TInt aTargetItemIndex, williamr@2: TInt aTargetYPos, williamr@2: TRect& aListBoxRect, williamr@2: TInt aMinHeightInNumOfItems = 1 ); williamr@2: /** williamr@2: * Gets the size of the list box in pixels based on the height of williamr@2: * the list box in items and the length of the items in characters. williamr@2: * williamr@2: * Returns @c TSize element consisting of two elements, the height williamr@2: * and the width. Height is the number of items times the height williamr@2: * of the font in pixels. Width is the number of characters in a williamr@2: * single line times the width of the font in pixels. williamr@2: * williamr@2: * @param aWidthAsNumOfChars Width of list box in characters. williamr@2: * @param aHeightAsNumOfItems Height of list box in characters. williamr@2: * @return The size of the list box in pixels as TSize. williamr@2: */ williamr@2: IMPORT_C TSize CalcSizeInPixels(TInt aWidthAsNumOfChars, williamr@2: TInt aHeightAsNumOfItems) const; williamr@2: williamr@2: /** williamr@2: * Gets the width of the list box in pixels based on the width of the list williamr@2: * box in characters. williamr@2: * williamr@2: * Returns the number of characters times the width of a character williamr@2: * in pixels. williamr@2: * williamr@2: * @param aNumOfChars The number of characters. williamr@2: * @return The width of the list box in pixels. williamr@2: */ williamr@2: IMPORT_C TInt CalcWidthBasedOnNumOfChars(TInt aNumOfChars) const; williamr@2: williamr@2: /** williamr@2: * Gets the height of the list box in pixels based on the width of the williamr@2: * list box in characters. williamr@2: * williamr@2: * Returns the number of items times the height of the font in pixels. williamr@2: * williamr@2: * @param aNumOfItems The number of items. williamr@2: * @return The height of the list box in pixels. williamr@2: */ williamr@2: IMPORT_C TInt CalcHeightBasedOnNumOfItems(TInt aNumOfItems) const; williamr@2: williamr@2: /** williamr@2: * Gets the width of the list box in pixels based on the width of the williamr@2: * list box text in pixels. williamr@2: * williamr@2: * returns the width of the whole list box in pixels, which includes williamr@2: * the text width and the width of elements in the list box that have williamr@2: * an effect on the overall width. williamr@2: * williamr@2: * @param aTextWidthInPixels Width of list box text in pixels. williamr@2: * @return Required width of whole list box in pixels. williamr@2: */ williamr@2: IMPORT_C TInt CalcWidthBasedOnRequiredItemWidth( williamr@2: TInt aTextWidthInPixels) const; williamr@2: williamr@2: // drawing/scrolling functions williamr@2: /** williamr@2: * Draws a list box item, first scrolling the list to make it visible williamr@2: * if it is not already. williamr@2: * williamr@2: * @c DrawItem() panics if there is no list box view currently set. williamr@2: * @param aItemIndex Index of the item to reveal. williamr@2: */ williamr@2: IMPORT_C void DrawItem(TInt aItemIndex) const; williamr@2: williamr@2: /** williamr@2: * Makes an item visible in the list, scrolling it if necessary. williamr@2: * williamr@2: * @param aItemIndex Index of the item to reveal. williamr@2: */ williamr@2: IMPORT_C void ScrollToMakeItemVisible(TInt aItemIndex) const; williamr@2: williamr@2: /** williamr@2: * Redraws list item. williamr@2: * @param aItemIndex index of item to be redrawn. williamr@2: * @since 3.2 williamr@2: */ williamr@2: IMPORT_C void RedrawItem( TInt aItemIndex ); williamr@2: williamr@2: // observer support williamr@2: /** williamr@2: * Sets the observer for the list box. williamr@2: * williamr@2: * @param aObserver Wanted observer for the list box. williamr@2: */ williamr@2: IMPORT_C void SetListBoxObserver(MEikListBoxObserver* aObserver); williamr@2: williamr@2: williamr@2: /** williamr@2: * Gets the size of the vertical gap between items. This space is used williamr@2: * by the view to allow a box to be drawn around each item. williamr@2: * williamr@2: * @return Size of the vertical gap in pixels. williamr@2: */ williamr@2: IMPORT_C TInt VerticalInterItemGap() const; williamr@2: williamr@2: // popouts only williamr@2: /** williamr@2: * Provides a call back mechanism to the button which just launched a williamr@2: * popout menu. williamr@2: * williamr@2: * @param aButton The button which just launched a popout menu. williamr@2: */ williamr@2: IMPORT_C void SetLaunchingButton(CEikButtonBase* aButton); williamr@2: williamr@2: // Editing support williamr@2: /** williamr@2: * Selects an item editor for the list box. williamr@2: * williamr@2: * @param aEditor The editor that has been selected for usage. williamr@2: */ williamr@2: IMPORT_C void SetItemEditor(MEikListBoxEditor* aEditor); williamr@2: williamr@2: /** williamr@2: * Resets the list boxes item editor. williamr@2: */ williamr@2: IMPORT_C void ResetItemEditor(); williamr@2: /** williamr@2: * Gets item editor for the current class. williamr@2: * williamr@2: * @return The item editor used by the list box class. williamr@2: */ williamr@2: IMPORT_C MEikListBoxEditor* ItemEditor(); williamr@2: williamr@2: /** williamr@2: * Creates an item editor and starts editing the current item. williamr@2: * williamr@2: * The editor can edit the current item up to a maximum length of williamr@2: * @c aMaxLength characters. Also reports an @c EEventEditingStarted event williamr@2: * to any list box observer by default. williamr@2: * williamr@2: * The function only creates a new editor if one does not already exist. williamr@2: * williamr@2: * @param aMaxLength Maximum length of characters to edit. williamr@2: */ williamr@2: IMPORT_C virtual void EditItemL(TInt aMaxLength); williamr@2: williamr@2: /** williamr@2: * Stops editing and deletes the item editor. williamr@2: * williamr@2: * The function reports an @c EEventEditingStopped event to any list box williamr@2: * observer, and updates the list box model if @c aUpdateModel is @c ETrue. williamr@2: * williamr@2: * @param aUpdateModel If @c ETrue the list box model is updated. williamr@2: */ williamr@2: IMPORT_C void StopEditingL(TBool aUpdateModel); williamr@2: williamr@2: // functions needed for Avkon shortcuts, williamr@2: // passing information from one list to another williamr@2: williamr@2: /** williamr@2: * No Implementation. williamr@2: * williamr@2: * @return Always returns 0. williamr@2: */ williamr@2: IMPORT_C virtual TInt ShortcutValueForNextList(); williamr@2: williamr@2: /** williamr@2: * No Implementation. williamr@2: * williamr@2: * @param aValue Not Used. williamr@2: */ williamr@2: IMPORT_C virtual void SetShortcutValueFromPrevList(TInt aValue); williamr@2: williamr@2: // pop-up positioning support williamr@2: /** williamr@2: * Gets the position and the size of the list box. williamr@2: * williamr@2: * @return A rectangle with the correct position data as williamr@2: * well as size data for the list box. williamr@2: */ williamr@2: IMPORT_C TRect HighlightRect() const; williamr@2: williamr@2: /** williamr@2: * Checks whether background drawing is suppressed on item level i.e. each williamr@2: * list item doesn't draw its background. williamr@2: * williamr@2: * @since S60 5.0 williamr@2: * @return ETrue if background drawing is suppressed. williamr@2: */ williamr@2: IMPORT_C TBool BackgroundDrawingSuppressed() const; williamr@2: williamr@2: public: // from CCoeControl williamr@2: williamr@2: /** williamr@2: * From @c CCoeControl williamr@2: * williamr@2: * Gets the list of logical colours employed in the drawing of the control, williamr@2: * paired with an explanation of how they are used. Appends the list to williamr@2: * @c aColorUseList. williamr@2: * williamr@2: * @param aColorUseList List of logical colours. williamr@2: */ williamr@2: IMPORT_C virtual void GetColorUseListL( williamr@2: CArrayFix& aColorUseList) const; williamr@2: // not available before Release 005u williamr@2: williamr@2: /** williamr@2: * From @c CCoeControl williamr@2: * williamr@2: * Handles a change to the list box’s resources of type @c aType which are williamr@2: * shared across the environment, colours or fonts for example. williamr@2: * williamr@2: * @param aType The type of resources that have changed. williamr@2: */ williamr@2: IMPORT_C virtual void HandleResourceChange(TInt aType); williamr@2: // not available before Release 005u williamr@2: williamr@2: /** williamr@2: * From @c CCoeControl williamr@2: * williamr@2: * Sets the control as ready to be drawn. williamr@2: * williamr@2: * The application should call this function on all controls that are not williamr@2: * components in a compound control. williamr@2: * williamr@2: * The purpose of this function is that controls are not always ready to williamr@2: * be drawn as soon as they have been constructed. For example, it may williamr@2: * not be possible to set the control's extent during construction, but williamr@2: * its extent should always be set before it is drawn. Similarly, if a williamr@2: * control is to be made invisible, this should be done before it is williamr@2: * activated. williamr@2: * williamr@2: * The default implementation sets a flag in the control to indicate it is williamr@2: * ready to be drawn. If the control is a compound control, the default williamr@2: * implementation also calls @c ActivateL() for all the control's components. williamr@2: * To get the control's components it uses @c CountComponentControls() and williamr@2: * @c ComponentControl(), which should be implemented by the compound control. williamr@2: * williamr@2: * @c ActivateL() is typically called from the control's @c ConstructL() williamr@2: * function. williamr@2: * williamr@2: * Notes: williamr@2: * williamr@2: * This function can be overridden. This is useful for doing late williamr@2: * initialisation of the control, using information that was not available williamr@2: * at the time the control was created. For example, a text editor might williamr@2: * override @c ActivateL() and use it to enquire whether it is focused: if williamr@2: * it is, it makes the cursor and any highlighting visible. At the time when williamr@2: * the editor is created, it doesn't know whether or not it has keyboard williamr@2: * focus. williamr@2: * williamr@2: * If overriding @c ActivateL(), the implementation must include a base williamr@2: * call to @c CCoeControl's @c ActivateL(). williamr@2: */ williamr@2: IMPORT_C virtual void ActivateL(); williamr@2: williamr@2: /** williamr@2: * From @c CCoeControl. williamr@2: * williamr@2: * Gets the input capabilities of the control and all its components. williamr@2: * williamr@2: * @return The input capabilities of the control. williamr@2: */ williamr@2: IMPORT_C TCoeInputCapabilities InputCapabilities() const; 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: protected: williamr@2: // Shortcuts need access to Incremental matching williamr@2: // The shortcuts will be used inside OfferkeyEventL(). williamr@2: friend class AknListBoxShortCutsImplementation; williamr@2: // Avkon layout uses SetVerticalMargin, which is protected. williamr@2: friend class AknListBoxLayouts; williamr@2: williamr@2: /** williamr@2: * Responds to a change in focus. williamr@2: * williamr@2: * This is called whenever the control gains or loses focus, williamr@2: * as a result of a call to @c SetFocus(). A typical use of williamr@2: * @c FocusChanged() is to change the appearance of the control, williamr@2: * for example by drawing a focus rectangle around it. williamr@2: * williamr@2: * The default implementation is empty, and should be williamr@2: * overridden by the @c CCoeControl-derived class. williamr@2: * williamr@2: * @param aDrawNow Contains the value that was passed to it williamr@2: * by @c SetFocus(). williamr@2: */ williamr@2: IMPORT_C virtual void FocusChanged(TDrawNow aDrawNow); williamr@2: williamr@2: /** williamr@2: * Responds to changes to the size and position of the contents williamr@2: * of this control. williamr@2: * williamr@2: * For a simple control this might include text or graphics. williamr@2: * For a compound control it sets the size and position of the williamr@2: * components. It has an empty default implementation and should williamr@2: * be implemented by the CCoeControl-derived class. williamr@2: * williamr@2: * The function is called whenever @c SetExtent(), @c SetSize(), williamr@2: * @c SetRect(), @c SetCornerAndSize(), or @c SetExtentToWholeScreen() williamr@2: * are called on the control. Note that the window server does not williamr@2: * generate size-changed events: @c SizeChanged() gets called only as williamr@2: * a result of calling the functions listed above. Therefore, if a williamr@2: * resize of one control affects the size of other controls, it is williamr@2: * up to the application to ensure that it handles the re-sizing williamr@2: * of all affected controls. williamr@2: */ williamr@2: IMPORT_C virtual void SizeChanged(); williamr@2: williamr@2: /** williamr@2: * Handles the change in case that the size of the view rectangle williamr@2: * for the list box changes. williamr@2: */ williamr@2: IMPORT_C virtual void HandleViewRectSizeChangeL(); williamr@2: williamr@2: /** williamr@2: * Gets the number of controls contained in a compound control. williamr@2: * williamr@2: * There are two ways to implement a compound control. One way is to williamr@2: * override this function. The other way is to use the @c CCoeControlArray williamr@2: * functionality (see the @c InitComponentArrayL method). williamr@2: * williamr@2: * @return The number of component controls contained by this control. williamr@2: */ williamr@2: IMPORT_C virtual TInt CountComponentControls() const; williamr@2: williamr@2: /** williamr@2: * Gets an indexed component of a compound control. williamr@2: * williamr@2: * There are two ways to implement a compound control. One way is to williamr@2: * override this function. The other way is to use the @c CCoeControlArray williamr@2: * functionality (see the @c InitComponentArrayL method). williamr@2: * williamr@2: * Note: Within a compound control each component control is identified williamr@2: * by an index, where the index depends on the order the controls were williamr@2: * added: the first is given an index of 0, the next an index of 1, and williamr@2: * so on. williamr@2: * williamr@2: * @param aIndex The index of the control. williamr@2: * @return The component control with an index of aIndex. williamr@2: */ williamr@2: IMPORT_C virtual CCoeControl* ComponentControl(TInt aIndex) const; williamr@2: williamr@2: // functions that implement first letter and incremental matching williamr@2: /** williamr@2: * Creates a buffer for checking how well two strings match up. williamr@2: */ williamr@2: IMPORT_C void CreateMatchBufferL(); williamr@2: williamr@2: /** williamr@2: * Empties the match buffer . williamr@2: */ williamr@2: IMPORT_C void ClearMatchBuffer() const; williamr@2: williamr@2: /** williamr@2: * Checks matching for the given character. williamr@2: * williamr@2: * @param aCode Character code. williamr@2: */ williamr@2: IMPORT_C void MatchTypedCharL(TUint aCode); williamr@2: williamr@2: /** williamr@2: * Undoes changes from the match buffer that have been caused williamr@2: * by the last match with a character. williamr@2: */ williamr@2: IMPORT_C void UndoLastChar(); williamr@2: /** williamr@2: * Checks if the last character matched with the string. williamr@2: * williamr@2: * @return @c ETrue if a match was found from the buffer with the character. williamr@2: */ williamr@2: IMPORT_C TBool LastCharMatched() const; williamr@2: williamr@2: // functions needed for supporting scrollbars williamr@2: /** williamr@2: * Updates the position of this list box’s scroll bars’ thumbs to reflect williamr@2: * the horizontal and vertical position of the list view within the list. williamr@2: */ williamr@2: IMPORT_C virtual void UpdateScrollBarThumbs() const; williamr@2: williamr@2: /** williamr@2: * Get horizontal scroll granularity in pixels. williamr@2: * The granularity is the minimum size of a horizontal move of the client williamr@2: * area. williamr@2: * williamr@2: * @return Grain size for horizontal scrolling in pixels. williamr@2: */ williamr@2: IMPORT_C virtual TInt HorizScrollGranularityInPixels() const; williamr@2: williamr@2: /** williamr@2: * Gets the number of grains to move horizontally when a nudge button is williamr@2: * tapped. williamr@2: * For simple list boxes, this value is a fraction of the width of the williamr@2: * client area. williamr@2: * williamr@2: * @return Number of grains to move left or right on each nudge williamr@2: */ williamr@2: IMPORT_C virtual TInt HorizontalNudgeValue() const; williamr@2: williamr@2: /** williamr@2: * Called by various functions of this class to ensure that the top williamr@2: * item index is always a sane value. The implementation in @c CEikListBox williamr@2: * tries to ensure the minimum amount of white space at the bottom of williamr@2: * the list box. Note that this function does not affect the williamr@2: * current item index. williamr@2: */ williamr@2: IMPORT_C virtual void AdjustTopItemIndex() const; williamr@2: williamr@2: // navigation support functions williamr@2: /** williamr@2: * Simulates an arrow key event. williamr@2: * williamr@2: * If the list box flags include @c EMultipleSelection, this has the effect williamr@2: * of pressing @c SHIFT with the arrow key represented by @c aKeyCode. williamr@2: * Calls @c CEikListBox::OfferKeyEventL() with aKeyCode translated into a williamr@2: * key event. williamr@2: * williamr@2: * @param aKeyCode A key code. williamr@2: */ williamr@2: IMPORT_C void SimulateArrowKeyEventL(TKeyCode aKeyCode); williamr@2: williamr@2: /** williamr@2: * Handles a left arrow key event. williamr@2: * williamr@2: * The method used to handle the event depends on the selection mode, e.g. williamr@2: * whether the user has pressed the @c SHIFT or @c CONTROL key. williamr@2: * williamr@2: * @param aSelectionMode Not used williamr@2: */ williamr@2: IMPORT_C virtual void HandleLeftArrowKeyL(CListBoxView::TSelectionMode aSelectionMode); williamr@2: williamr@2: /** williamr@2: * Handles a right arrow key event. williamr@2: * williamr@2: * The method used to handle the event depends on the selection mode, williamr@2: * e.g. whether the user has pressed the @c SHIFT or @c CONTROL key. williamr@2: * williamr@2: * @param aSelectionMode Not used. williamr@2: */ williamr@2: IMPORT_C virtual void HandleRightArrowKeyL(CListBoxView::TSelectionMode aSelectionMode); williamr@2: williamr@2: // construction support functions williamr@2: /** williamr@2: * Restores the list box properties shared by all subclasses from a resource williamr@2: * reader. This function is not called within @c CEikListBox itself, but is williamr@2: * used by subclasses which support construction from resources. williamr@2: * williamr@2: * @param aReader A resource reader. williamr@2: */ williamr@2: IMPORT_C void RestoreCommonListBoxPropertiesL(TResourceReader& aReader); williamr@2: williamr@2: /** williamr@2: * Second-phase constructor. williamr@2: * williamr@2: * This protected form is overridden non-virtually by the second-phase williamr@2: * constructors of each subclass, and should be invoked by them using williamr@2: * @c CEikListBox::ConstructL(). williamr@2: * williamr@2: * @param aParent The parent control. May be NULL. williamr@2: * @param aFlags Construction flags. williamr@2: */ williamr@2: IMPORT_C virtual void ConstructL(const CCoeControl* aParent, TInt aFlags = 0); williamr@2: williamr@2: /** williamr@2: * Completes the list box view’s construction. williamr@2: * williamr@2: * This function is called by @c ConstructL() to complete construction williamr@2: * of the resource view, calling its @c ConstructL() with appropriate williamr@2: * arguments and assigning it to @c iView. Also prepares the view for use. williamr@2: */ williamr@2: IMPORT_C virtual void CreateViewL(); williamr@2: williamr@2: /** williamr@2: * Creates the list box view. williamr@2: * williamr@2: * The function is called by @c ConstructL() to create an instance of williamr@2: * the appropriate list box view class for this list box. The returned williamr@2: * instance is owned by this object, and does not have to have its williamr@2: * second-phase constructor run. This function is called by @c CreateViewL(). williamr@2: * williamr@2: * @return Pointer to a newly constructed list box view for this object. williamr@2: */ williamr@2: IMPORT_C virtual CListBoxView* MakeViewClassInstanceL(); williamr@2: williamr@2: /** williamr@2: * Sets the view rectangle from the client rectangle making sure a whole williamr@2: * number of items is displayed. williamr@2: * williamr@2: * @param aClientRect The client rectangle williamr@2: */ williamr@2: IMPORT_C void SetViewRectFromClientRect(const TRect& aClientRect); williamr@2: williamr@2: /** williamr@2: * Calculates the client area. williamr@2: * williamr@2: * This method is called by various functions of this class to williamr@2: * recalculate the extent of the client area from @c iViewRect. This williamr@2: * implementation takes into account any rounding of the viewing williamr@2: * rectangle made to fit a whole number of items. williamr@2: * williamr@2: * @param aClientRect On return contains a size for the client area williamr@2: * in pixels. williamr@2: */ williamr@2: IMPORT_C virtual void RestoreClientRectFromViewRect( TRect& aClientRect) const; williamr@2: williamr@2: /** williamr@2: * Rounds down the height of the rectangle (if necessary) so that williamr@2: * only a whole number of items can be displayed inside the list box. williamr@2: * williamr@2: * @param aRect The rectangle to be modified. williamr@2: * @return The number of pixels reduced. williamr@2: */ williamr@2: IMPORT_C virtual TInt AdjustRectHeightToWholeNumberOfItems( TRect& aRect) const; williamr@2: williamr@2: // accessor for Laf members williamr@2: /** williamr@2: * Gets list box margins. williamr@2: * williamr@2: * @return The list box margins in pixels. williamr@2: */ williamr@2: IMPORT_C TMargins8 ListBoxMargins() const; williamr@2: williamr@2: // various accessors for private data members williamr@2: /** williamr@2: * This function gets the horizontal margin. Use williamr@2: * @c CEikListBox::ListBoxMargins() instead, as this williamr@2: * provides a more accurate value due to the bit shifting involved. williamr@2: * williamr@2: * @deprecated Use @c CEikListBox::ListBoxMargins() williamr@2: * @return The horizontal margin in pixels. williamr@2: */ williamr@2: IMPORT_C TInt HorizontalMargin() const; williamr@2: williamr@2: /** williamr@2: * This function gets the vertical margin. This function williamr@2: * is deprecated, use @c CEikListBox::ListBoxMargins() instead, williamr@2: * this provides a more accurate value due to the bit williamr@2: * shifting involved. williamr@2: * williamr@2: * @deprecated Use @c CEikListBox::ListBoxMargins() williamr@2: * @return The vertical margin in pixels. williamr@2: */ williamr@2: IMPORT_C TInt VerticalMargin() const; williamr@2: williamr@2: /** williamr@2: * Sets the horizontal margin. williamr@2: * williamr@2: * @param aMargin The required horizontal margin. williamr@2: */ williamr@2: IMPORT_C void SetHorizontalMargin(TInt aMargin); williamr@2: williamr@2: /** williamr@2: * Sets the vertical margin. williamr@2: * williamr@2: * @param aMargin The required vertical margin. williamr@2: */ williamr@2: IMPORT_C void SetVerticalMargin(TInt aMargin); williamr@2: williamr@2: /** williamr@2: * Gets a pointer to the match buffer. Returns williamr@2: * NULL if the match buffer does not exist. williamr@2: * williamr@2: * @return Pointer to the match buffer. williamr@2: */ williamr@2: IMPORT_C RIncrMatcherBase* MatchBuffer() const; williamr@2: williamr@2: /** williamr@2: * Gets the view rectangle height adjustment. williamr@2: * williamr@2: * These are the adjustments that were made to the williamr@2: * view rectangle when the @c SetViewRectFromClientRect() williamr@2: * function was called. williamr@2: * williamr@2: * @return Height adjustment. williamr@2: */ williamr@2: IMPORT_C TInt ViewRectHeightAdjustment() const; williamr@2: williamr@2: /** williamr@2: * Gets the background colour. williamr@2: * williamr@2: * @return The background colour. williamr@2: */ williamr@2: IMPORT_C TRgb BackColor() const; williamr@2: williamr@2: /** williamr@2: * Sets the view rectangle height adjustment. williamr@2: * williamr@2: * @param aAdjustment New adjustment. williamr@2: */ williamr@2: IMPORT_C void SetViewRectHeightAdjustment(TInt aAdjustment); williamr@2: williamr@2: // misc functions williamr@2: williamr@2: /** williamr@2: * Reports a list box event to any observer of this list box. williamr@2: * This function returns immediately if no observer is set. williamr@2: * williamr@2: * @param aEvent The event to report. williamr@2: */ williamr@2: IMPORT_C virtual void ReportListBoxEventL( MEikListBoxObserver::TListBoxEvent aEvent ); williamr@2: williamr@2: /** williamr@2: * Redraws the specified area of this list box into the specified rectangle. williamr@2: * williamr@2: * @param aRect Rectangle to be redrawn. Specified relative to the williamr@2: * origin of this control. williamr@2: */ williamr@2: IMPORT_C virtual void Draw(const TRect& aRect) const; williamr@2: williamr@2: /** williamr@2: * Clears the list box margins. The list box is redrawn only if redraws williamr@2: * are enabled for the list box view. williamr@2: */ williamr@2: IMPORT_C void ClearMargins() const; williamr@2: williamr@2: /** williamr@2: * Sets an item as the current item, even if it is not currently williamr@2: * visible. Redraws the list box to reflect the change. This williamr@2: * should not be called from within another Draw function. williamr@2: * williamr@2: * @param aItemIndex The index of the list box item to update. williamr@2: */ williamr@2: IMPORT_C virtual void UpdateCurrentItem(TInt aItemIndex) const; williamr@2: williamr@2: /** williamr@2: * Handles drag events. williamr@2: * williamr@2: * This function is called by @c HandlePointerEventL() to handle pointer williamr@2: * drag events appropriately. williamr@2: * williamr@2: * @param aPointerPos The position of the @c TPointerEvent for which this williamr@2: * handler is invoked. williamr@2: */ williamr@2: IMPORT_C virtual void HandleDragEventL(TPoint aPointerPos); williamr@2: williamr@2: /** williamr@2: * Tests whether an item exists. williamr@2: * williamr@2: * @param aItemIndex Index to test. williamr@2: * @return @c ETrue if the specified item exists, EFalse otherwise. williamr@2: */ williamr@2: IMPORT_C TBool ItemExists(TInt aItemIndex) const; williamr@2: williamr@2: /** williamr@2: * Draws the matcher cursor in the correct location for the current match. williamr@2: * If there is no match buffer, this function returns immediately; williamr@2: * otherwise the cursor is drawn on the current item using williamr@2: * @c CListBoxView::DrawMatcherCursor() after scrolling to make the current williamr@2: * item visible. williamr@2: * williamr@2: * A list box control’s matcher cursor is an on-screen cursor which is williamr@2: * drawn to indicate to the user the location of the current text. Whether williamr@2: * the cursor is drawn is dependent on the williamr@2: * @c CListBoxView::TFlags::EHasMatcherCursor flag, which may be set on the williamr@2: * list box’s view. williamr@2: * williamr@2: * Note, that CListBoxView::DrawMatcherCursor() is not implemented in S60. williamr@2: */ williamr@2: IMPORT_C void DrawMatcherCursor() const; williamr@2: williamr@2: /** williamr@2: * Gets the vertical gap between elements in the list box. williamr@2: * williamr@2: * @return The vertical gap between elements in the list box. williamr@2: */ williamr@2: IMPORT_C static TInt InterItemGap(); williamr@2: williamr@2: /** williamr@2: * Updates the view colours in line with the colours in effect for the williamr@2: * Uikon environment. Has no effect if there is no view. williamr@2: */ williamr@2: IMPORT_C void UpdateViewColors(); williamr@2: williamr@2: /** williamr@2: * Updates the item drawer colours in line with the colours in effect williamr@2: * for the Uikon environment. Has no effect if there is no item drawer. williamr@2: */ williamr@2: IMPORT_C void UpdateItemDrawerColors(); williamr@2: williamr@2: /** williamr@2: * Notifies item change observers about item change. Subclasses must call williamr@2: * this method if they have implemented item handling functions (e.g. williamr@2: * @c HandleItemAdditionL or @c HandleItemRemovalL). williamr@2: * williamr@2: * @since S60 3.0 williamr@2: */ williamr@2: IMPORT_C void FireItemChange(); williamr@2: williamr@2: williamr@2: protected: // functions which deal with extension williamr@2: /** williamr@2: * Sets the reason for the list box’s loss of focus. williamr@2: * williamr@2: * This is required so the list box can determine whether williamr@2: * loss of focus is due to an external control or an internal component. williamr@2: * williamr@2: * @param aReasonForFocusLost The reason for the loss of focus. williamr@2: */ williamr@2: IMPORT_C void SetReasonForFocusLostL( TReasonForFocusLost aReasonForFocusLost ); williamr@2: williamr@2: /** williamr@2: * Gets the reason for the list box’s loss of focus. williamr@2: * williamr@2: * @return The reason for the loss of focus. williamr@2: */ williamr@2: IMPORT_C TReasonForFocusLost ReasonForFocusLostL(); williamr@2: williamr@2: /** williamr@2: * Tests whether the list box match buffer exists. williamr@2: * williamr@2: * @return @c ETrue if the list box match buffer exists. williamr@2: @c EFalse if the list box match buffer does not exist. williamr@2: */ williamr@2: IMPORT_C TBool IsMatchBuffer() const; williamr@2: williamr@2: /** williamr@2: * Checks for a list box extension. Attempts to create one if not present. williamr@2: * williamr@2: * This function leaves if an extension cannot be created. williamr@2: */ williamr@2: void CheckCreateExtensionL(); williamr@2: williamr@2: /** williamr@2: * Checks for a list box extension. Creates one if not present. williamr@2: * williamr@2: * @return @c ETrue if a list box extension already existed or williamr@2: * if there was no previous extension and a new extension williamr@2: * class was created successfully. williamr@2: * @c EFalse if there was no previous extension and a new one williamr@2: * could not be constructed. williamr@2: */ williamr@2: TBool CheckCreateExtension(); williamr@2: williamr@2: /** williamr@2: * Checks the list box match buffer exists. If a buffer does not williamr@2: * exist, one is created. williamr@2: */ williamr@2: void CheckCreateBufferL(); williamr@2: williamr@2: /** williamr@2: * Gets the list box match buffer. williamr@2: * williamr@2: * @return The list box match buffer. williamr@2: */ williamr@2: CMatchBuffer* Buffer() const; williamr@2: williamr@2: protected: williamr@2: /** williamr@2: * Creates a scroll bar frame layout according to @c aLayout. williamr@2: * williamr@2: * @param aLayout Defines the layout. williamr@2: */ williamr@2: IMPORT_C void CreateScrollBarFrameLayout(TEikScrollBarFrameLayout& aLayout) const; williamr@2: williamr@2: /** williamr@2: * If MiddleSoftKey is either Mark or Unmark, this method sets MSK williamr@2: * according to the current item selection state. williamr@2: */ williamr@2: void UpdateMarkUnmarkMSKL() const; williamr@2: williamr@2: public: williamr@2: /** williamr@2: * @return Event modifiers for the @c CEikListBox. williamr@2: */ williamr@2: IMPORT_C TInt EventModifiers(); williamr@2: williamr@2: /* williamr@2: * Returns ETrue if list has ES60StyleMultiselection flag. williamr@2: */ williamr@2: IMPORT_C TBool IsMultiselection(); williamr@2: williamr@2: /** williamr@2: * Creates a scrollbar for the listbox. The caller may choose if the scrollbar is requested williamr@2: * remotely via the mop chain from parent control williamr@2: * williamr@2: * @param aPreAlloc Is the scrollbar created immediately or when taking in to use williamr@2: * @param aRemote If True, the scrollbar is obtained via mop-chain from williamr@2: * parent control. If used, the listbox only sets the scrollbar williamr@2: * values. The scrollbar position and size must set in the parent williamr@2: * control's code. williamr@2: * williamr@2: * @return CEikScrollBarFrame* pointer to scrollbar frame object williamr@2: */ williamr@2: IMPORT_C CEikScrollBarFrame* CreateScrollBarFrameL(TBool aPreAlloc, TBool aRemote); williamr@2: williamr@2: /** williamr@2: * Creates a scrollbar for the listbox. The caller may choose if the scrollbar is requested williamr@2: * remotely via the mop chain from parent control williamr@2: * williamr@2: * @param aPreAlloc Is the scrollbar created immediately or when taking in to use williamr@2: * @param aRemote If True, the scrollbar is obtained via mop-chain from williamr@2: * parent control. If used, the listbox only sets the scrollbar williamr@2: * values. The scrollbar position and size must set in the parent williamr@2: * control's code. williamr@2: * @param aWindowOwning Does the created scrollbar create own window or williamr@2: * is it compound control. The listbox uses a window owning williamr@2: * scrollbar by default. williamr@2: * williamr@2: * @return CEikScrollBarFrame* pointer to scrollbar frame object williamr@2: */ williamr@2: IMPORT_C CEikScrollBarFrame* CreateScrollBarFrameL(TBool aPreAlloc, TBool aRemote, TBool aWindowOwning); williamr@2: williamr@2: /** williamr@2: * By default markable listbox has middle softkey observer, which handles williamr@2: * Mark / Unmark functionality. By this method, the caller may disable default williamr@2: * observer. williamr@2: * williamr@2: * @since S60 3.1 williamr@2: * williamr@2: * @param aEnable If EFalse, disables default middle softkey observer williamr@2: * for markable lists. ETrue enables observer again. williamr@2: */ williamr@2: IMPORT_C void EnableMSKObserver(TBool aEnable); williamr@2: williamr@2: /** williamr@2: * Called from MSK observer when shift+MSK have been pressed williamr@2: * williamr@2: * @Since S60 3.1 williamr@2: */ williamr@2: void DoShiftMSKMarkingL(); williamr@2: williamr@2: /** williamr@2: * This method is only called by CEikButtonGroupContainer when MSK observer williamr@2: * is enabled and CEikButtonGroupContainer is deleted. williamr@2: * williamr@2: * @Since S60 3.1 williamr@2: */ williamr@2: void InformMSKButtonGroupDeletion(); williamr@2: williamr@2: /** williamr@2: * Adds a selection (item marking) observer to the listbox. Duplicates are not checked williamr@2: * (i.e. adding the same observer multiple times is not prevented). williamr@2: * williamr@2: * @since 3.2 williamr@2: * @param aObserver Must be non-NULL. williamr@2: */ williamr@2: IMPORT_C void AddSelectionObserverL( MListBoxSelectionObserver* aObserver ); williamr@2: williamr@2: /** williamr@2: * Removes a selection (item marking) observer from the listbox. williamr@2: * williamr@2: * @since 3.2 williamr@2: * @param aObserver The observer to be removed. williamr@2: */ williamr@2: IMPORT_C void RemoveSelectionObserver( MListBoxSelectionObserver* aObserver ); williamr@2: williamr@2: /** williamr@2: * This switches listbox into selection mode. Basicly only changes MSK and williamr@2: * informs selection observers about the change. williamr@2: * williamr@2: * @since 3.2 williamr@2: * @param aEnable ETrue when entering into selection mode, EFalse when leaving williamr@2: */ williamr@2: void ChangeSelectionMode(TBool aEnable); williamr@2: williamr@2: /** williamr@2: * Sets the number of list items that form one grid line. williamr@2: * williamr@2: * @since S60 5.0 williamr@2: * @param aItems Number of items in one grid line. williamr@2: */ williamr@2: IMPORT_C void SetItemsInSingleLine(TInt aItems); williamr@2: williamr@2: /** williamr@2: * Removes pointer event filtering for list items. williamr@2: * williamr@2: * When there are two pointer up events on the same item at short interval, williamr@2: * listbox will only get the first one and drop the second one. This method forces listbox to handle all pointer up events. williamr@2: * williamr@2: * @since S60 5.0 williamr@2: * williamr@2: * @param aItemIndexes Array of item indexes to be added. williamr@2: **/ williamr@2: IMPORT_C void SetPointerEventFilterDisabledL( const CArrayFix& aItemIndexes ); williamr@2: williamr@2: /** williamr@2: * Scrolls the view by the given amount of pixels while keeping the williamr@2: * physics parameters up-to-date. williamr@2: * This should be called when scrolling the list box view except for williamr@2: * when it is done by list dragging (e.g. scrolling with scroll bar). williamr@2: * williamr@2: * @param aDeltaPixels Amount of pixels to scroll the view. williamr@2: * williamr@2: * @since 5.0 williamr@2: */ williamr@2: IMPORT_C void HandlePhysicsScrollEventL( TInt aDeltaPixels ); williamr@2: williamr@2: /** williamr@2: * Disables the kinetic scrolling functionality in the list. williamr@2: * By default the feature is enabled. williamr@2: * williamr@2: * @param aDisabled @c ETrue to disable kinetic scrolling, williamr@2: * @c EFalse otherwise. williamr@2: * williamr@2: * @since 5.0 williamr@2: */ williamr@2: IMPORT_C void DisableScrolling( TBool aDisabled ); williamr@2: williamr@2: /** williamr@2: * Checks if the kinetic scrolling is currently enabled in the list. williamr@2: * williamr@2: * @return @c ETrue if kinetic scrolling is enabled, @c EFalse otherwise. williamr@2: * williamr@2: * @since 5.0 williamr@2: */ williamr@2: IMPORT_C TBool ScrollingDisabled(); williamr@2: williamr@2: /** williamr@2: * Suspends transitions effects. williamr@2: * williamr@2: * @since S60 5.0 williamr@2: * williamr@2: * @param aSuspend ETrue to suspend effects, EFalse to re-enable them. williamr@2: */ williamr@2: IMPORT_C void SuspendEffects( TBool aSuspend ); williamr@2: williamr@2: private: williamr@2: IMPORT_C virtual void CEikListBox_Reserved(); // listbox use only williamr@2: void HorizontalScroll(TInt aScrollAmountInPixels); williamr@2: void DrawItemInView(TInt aItemIndex) const; williamr@2: void ClearMargins(CWindowGc& aGc) const; williamr@2: TKeyResponse DoOfferKeyEventL(const TKeyEvent& aKeyEvent,TEventCode aType); williamr@2: void UpdateScrollBarColors(CEikScrollBar* aScrollBar); williamr@2: void UpdateScrollBarsColors(); williamr@2: williamr@2: void HandleItemRemovalWithoutSelectionsL(); williamr@2: williamr@2: /** williamr@2: * Scrolls the view by the given amount of pixels. williamr@2: * williamr@2: * @param aOffset Amount of offset in pixels. williamr@2: * @param aDrawNow Whether or not the view is be drawn. williamr@2: * If @c EFalse then only the logical state is updated. williamr@2: * williamr@2: * @internal williamr@2: * @since 5.0 williamr@2: */ williamr@2: void ScrollView( const TInt aOffset, TBool aDrawNow ); williamr@2: williamr@2: /** williamr@2: * Handles pointer events if physics are enabled. williamr@2: * williamr@2: * @return @c ETrue if the event was consumed by kinetic scrolling. williamr@2: * williamr@2: * @internal williamr@2: * @since 5.0 williamr@2: */ williamr@2: TBool HandlePhysicsPointerEventL( const TPointerEvent& aPointerEvent ); williamr@2: williamr@2: /** williamr@2: * Selects an item and draws highlight to it. williamr@2: * williamr@2: * @param aItemIndex Index of the highlighted item. williamr@2: * williamr@2: * @internal williamr@2: * @since 5.0 williamr@2: */ williamr@2: void UpdateHighlightL( TInt aItemIndex ); williamr@2: williamr@2: protected: williamr@2: /** Flags for this list box */ williamr@2: TInt iListBoxFlags; williamr@2: williamr@2: /** This List box's view */ williamr@2: CListBoxView* iView; williamr@2: williamr@2: /** Item drawer for this list box */ williamr@2: CListItemDrawer* iItemDrawer; williamr@2: williamr@2: /** Data model for this list box */ williamr@2: MListBoxModel* iModel; williamr@2: williamr@2: /** Height of each item in the list */ williamr@2: TInt iItemHeight; williamr@2: williamr@2: /** The scroll bar used by this control */ williamr@2: CEikScrollBarFrame* iSBFrame; williamr@2: williamr@2: /** Identifies if the scroll bar is owned by this list */ williamr@2: TScrollBarOwnerShip iSBFrameOwned; williamr@2: williamr@2: /** The required height of this list box expressed in williamr@2: * terms of a number of items. williamr@2: */ williamr@2: TInt iRequiredHeightInNumOfItems; williamr@2: williamr@2: /** williamr@2: * Defines which button launched the popout. williamr@2: */ williamr@2: CEikButtonBase* iLaunchingButton; // only used by popouts williamr@2: williamr@2: /** The button which just launched a popout menu. */ williamr@2: MEikListBoxObserver* iListBoxObserver; williamr@2: williamr@2: private: williamr@2: williamr@2: TRgb iBackColor; williamr@2: // TInt iHorizontalMargin; williamr@2: // TInt iVerticalMargin; williamr@2: TMargins8 iMargins ; williamr@2: CListBoxExt* iListBoxExt; williamr@2: TInt iViewRectHeightAdjustment; williamr@2: MEikListBoxEditor* iItemEditor; williamr@2: TBool* iLbxDestroyed; williamr@2: TBool iLastCharMatched; williamr@2: TInt iSpare; williamr@2: }; williamr@2: williamr@2: williamr@2: williamr@2: /** williamr@2: * This is a list box that scrolls horizontally, displaying its items williamr@2: * in as many vertical columns as needed. Columns are arranged across williamr@2: * the control from left to right; within columns, items are arranged williamr@2: * from top to bottom. The flow of items or text ‘snakes’ across the williamr@2: * face of the control. williamr@2: * williamr@2: * This is a flexible control class that makes good use of short, wide williamr@2: * display areas; for instance, subclasses of @c CEikSnakingListBox could williamr@2: * be used for file lists or for a control panel. A standard user williamr@2: * subclass, @c CEikSnakingTextListBox, also exists. williamr@2: * williamr@2: * @since Symbian 5.0 williamr@2: */ williamr@2: class CEikSnakingListBox : public CEikListBox williamr@2: { williamr@2: public: williamr@2: /** williamr@2: * C++ standard constructor williamr@2: */ williamr@2: IMPORT_C CEikSnakingListBox(); williamr@2: williamr@2: /** williamr@2: * Destructor williamr@2: */ williamr@2: IMPORT_C ~CEikSnakingListBox(); williamr@2: williamr@2: /** williamr@2: * Creates an instance of the view class. williamr@2: * williamr@2: * This function is called during construction to create williamr@2: * (but not second-phase construct) an instance of the correct view williamr@2: * class for this list box control. In the case of the snaking list williamr@2: * box, a @c CSnakingListBoxView is returned. williamr@2: * williamr@2: * This function overrides @c CEikListBox::MakeViewClassInstanceL(). williamr@2: * williamr@2: * @return The view which will be used by the list box being created williamr@2: */ williamr@2: IMPORT_C virtual CListBoxView* MakeViewClassInstanceL(); williamr@2: williamr@2: /** williamr@2: * Sets the top item’s index. williamr@2: * williamr@2: * @param aItemIndex Index of the item to set as the top item. williamr@2: */ williamr@2: IMPORT_C virtual void SetTopItemIndex(TInt aItemIndex) const; williamr@2: williamr@2: /** williamr@2: * Gets the width of this list box’s columns. williamr@2: * williamr@2: * @return Width of each column. williamr@2: */ williamr@2: IMPORT_C TInt ColumnWidth() const; williamr@2: williamr@2: /** williamr@2: * Sets the width of all columns in the list box. williamr@2: * williamr@2: * @param aColumnWidth New column width. williamr@2: */ williamr@2: IMPORT_C void SetColumnWidth(TInt aColumnWidth); williamr@2: williamr@2: public: //from CCoeControl williamr@2: williamr@2: /** williamr@2: * From @c CCoeControl. williamr@2: * williamr@2: * Handles pointer events. williamr@2: * williamr@2: * @param aPointerEvent The pointer event. williamr@2: */ williamr@2: IMPORT_C void HandlePointerEventL(const TPointerEvent& aPointerEvent); williamr@2: williamr@2: protected: williamr@2: williamr@2: /** williamr@2: * Handles a change in size of the viewing rectangle. williamr@2: * williamr@2: * This function is called by framework functions to update the content, williamr@2: * view, and scroll bars of this list box after the viewing rectangle has williamr@2: * changed size. This implementation ensures that the current item is williamr@2: * visible after a resize. williamr@2: */ williamr@2: IMPORT_C virtual void HandleViewRectSizeChangeL(); williamr@2: williamr@2: /** williamr@2: * Handles a left arrow key event. williamr@2: * williamr@2: * Moves the cursor into the correct column and clears any matcher buffer williamr@2: * that may have been built up. williamr@2: * williamr@2: * @param aSelectionMode Not used. williamr@2: */ williamr@2: IMPORT_C virtual void HandleLeftArrowKeyL( williamr@2: CListBoxView::TSelectionMode aSelectionMode); williamr@2: williamr@2: /** williamr@2: * Handles a right arrow key event. williamr@2: * williamr@2: * Moves the cursor into the correct column and clears any matcher buffer williamr@2: * that may have been built up. williamr@2: * williamr@2: * @param aSelectionMode Not used. williamr@2: */ williamr@2: IMPORT_C virtual void HandleRightArrowKeyL( williamr@2: CListBoxView::TSelectionMode aSelectionMode); williamr@2: williamr@2: /** williamr@2: * Gets the number of grains to move horizontally when a nudge button williamr@2: * is tapped. williamr@2: * williamr@2: * For simple list boxes, this value is a fraction of the width of the williamr@2: * client area. williamr@2: * williamr@2: * @return Number of grains to move left or right on each nudge. williamr@2: */ williamr@2: IMPORT_C virtual TInt HorizontalNudgeValue() const; williamr@2: williamr@2: /** williamr@2: * Gets the granularity for horizontal scrolls. williamr@2: * williamr@2: * The granularity is the minimum size of a horizontal move of the williamr@2: * client area. williamr@2: * williamr@2: * @return Grain size for horizontal scrolling in pixels. williamr@2: */ williamr@2: IMPORT_C virtual TInt HorizScrollGranularityInPixels() const; williamr@2: williamr@2: /** williamr@2: * Called by various functions of this class to ensure that the top williamr@2: * item index is always a sane value. The implementation in @c CEikListBox williamr@2: * tries to ensure the minimum amount of white space at the bottom of williamr@2: * the list box. Note that this function does not affect the current williamr@2: * item index. williamr@2: */ williamr@2: IMPORT_C virtual void AdjustTopItemIndex() const; williamr@2: williamr@2: /** williamr@2: * Handles drag events. williamr@2: * williamr@2: * This function is called by @c HandlePointerEventL() to handle williamr@2: * pointer drag events appropriately. williamr@2: * williamr@2: * @param aPointerPos The position of the @c TPointerEvent for which this williamr@2: * handler is invoked. williamr@2: */ williamr@2: IMPORT_C virtual void HandleDragEventL(TPoint aPointerPos); williamr@2: williamr@2: /** williamr@2: * Calculates the client area. williamr@2: * williamr@2: * This method is called by various functions of this class to recalculate williamr@2: * the extent of the client area from @c iViewRect. This implementation williamr@2: * takes into account any rounding of the viewing rectangle made to fit a williamr@2: * whole number of items. williamr@2: * williamr@2: * @param aClientRect On return contains a size for the client area in williamr@2: * pixels. williamr@2: */ williamr@2: IMPORT_C virtual void RestoreClientRectFromViewRect( williamr@2: TRect& aClientRect) const; williamr@2: williamr@2: /** williamr@2: * Rounds down the height of the rectangle (if necessary) so that only a williamr@2: * whole number of items can be displayed inside the list box. williamr@2: * williamr@2: * @param aRect The rectangle to be modified. williamr@2: * @return The number of pixels reduced. williamr@2: */ williamr@2: IMPORT_C virtual TInt AdjustRectHeightToWholeNumberOfItems( williamr@2: TRect& aRect) const; williamr@2: williamr@2: /** williamr@2: * Move to next or previous item according to the given parameter. williamr@2: * williamr@2: * @param aPoint Position which defines the moving direction. williamr@2: */ williamr@2: IMPORT_C void MoveToNextOrPreviousItemL(TPoint aPoint); williamr@2: williamr@2: protected: //from CCoeControl williamr@2: williamr@2: /** williamr@2: * From @c CCoeControl williamr@2: * williamr@2: * Updates the viewing rectangle of this control appropriately. The function williamr@2: * updates the viewing rectangle, and invokes @c HandleViewRectSizeChangeL(). williamr@2: */ williamr@2: IMPORT_C virtual void SizeChanged(); williamr@2: williamr@2: /** williamr@2: * From @c CCoeControl williamr@2: * williamr@2: * Gets the list of logical colours employed in the drawing of the control, williamr@2: * paired with an explanation of how they are used. Appends the list to williamr@2: * @c aColorUseList. williamr@2: * williamr@2: * @param aColorUseList List of logical colours. williamr@2: */ williamr@2: IMPORT_C virtual void GetColorUseListL( williamr@2: CArrayFix& aColorUseList) const; williamr@2: // not available before Release 005u williamr@2: /** williamr@2: * From @c CCoeControl. williamr@2: * williamr@2: * Handles a change to the list box’s resources of type @c aType which are williamr@2: * shared across the environment, colours or fonts for example. williamr@2: * williamr@2: * @param aType The type of resources that have changed. williamr@2: */ williamr@2: IMPORT_C virtual void HandleResourceChange(TInt aType); williamr@2: // not available before Release 005u williamr@2: williamr@2: private: // from CCoeControl williamr@2: IMPORT_C void Reserved_1(); williamr@2: williamr@2: IMPORT_C void Reserved_2(); 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: IMPORT_C virtual void CEikListBox_Reserved(); // listbox use only williamr@2: }; williamr@2: williamr@2: #endif // __EIKLBX_H__