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@4: * under the terms of "Eclipse Public License v1.0"
williamr@2: * which accompanies this distribution, and is available
williamr@4: * at the URL "http://www.eclipse.org/legal/epl-v10.html".
williamr@2: *
williamr@2: * Initial Contributors:
williamr@2: * Nokia Corporation - initial contribution.
williamr@2: *
williamr@2: * Contributors:
williamr@2: *
williamr@2: * Description:
williamr@2: *
williamr@2: */
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: #if !defined(__EIKLBV_H__)
williamr@2: #define __EIKLBV_H__
williamr@2: 
williamr@2: #if !defined(__E32BASE_H__)
williamr@2: #include <e32base.h>
williamr@2: #endif
williamr@2: 
williamr@2: #if !defined(__GDI_H__)
williamr@2: #include <gdi.h>
williamr@2: #endif
williamr@2: 
williamr@2: class CListItemDrawer;
williamr@2: class MListBoxModel;
williamr@2: class CWindowGc;
williamr@2: class RWindowGroup;
williamr@2: class CWsScreenDevice;
williamr@2: class CWindowGc;
williamr@2: class RWindow;
williamr@2: class CListBoxViewExtension;
williamr@2: class CEikListBox;
williamr@2: 
williamr@2: //
williamr@2: // class MListVisibiltyObserver
williamr@2: //
williamr@2: 
williamr@2: class MListVisibilityObserver 
williamr@2: 	{
williamr@2: public:
williamr@2: 	virtual TBool IsVisible() const = 0;
williamr@2: 	};
williamr@2: 
williamr@2: /**
williamr@2:  * List box view.
williamr@2:  *
williamr@2:  * A list box view displays the list items which are currently visible in 
williamr@2:  * a list box. List box views draw each of the items for display using 
williamr@2:  * methods defined in their associated list box drawer. 
williamr@2:  *
williamr@2:  * Together with its list item drawer, a @c CListBoxView encapsulates the 
williamr@2:  * on-screen appearance of data in a list box.
williamr@2:  *
williamr@2:  * List box views also encapsulate item selection, the current item, and the 
williamr@2:  * fundamentals of how the selection and the current item are updated according
williamr@2:  * to user input. Input events themselves are handled by @c CEikListBox, 
williamr@2:  * which calls member functions of @c CListBoxView appropriately.
williamr@2:  *
williamr@2:  * This class is sufficient for plain list box views, and may be derived from 
williamr@2:  * in order to provide more complex list views. @c TechView supplies and uses 
williamr@2:  * the classes @c CHierarchicalListBoxView and @c CSnakingListBoxView, which 
williamr@2:  * provide two kinds of indented list views.
williamr@2:  */
williamr@2: class CListBoxView : public CBase
williamr@2: 	{
williamr@2: public:
williamr@2: 
williamr@2:     /**
williamr@2:      * Cursor movement flags. These describe the cursor movements recognised by
williamr@2:      * @c MoveCursorL().
williamr@2:      */
williamr@2:     enum TCursorMovement 
williamr@2: 		{
williamr@2:         /** Cursors movement to next item. */
williamr@2:         ECursorNextItem,  	
williamr@2: 
williamr@2:         /** Cursors movement to previous item. */
williamr@2:         ECursorPreviousItem,
williamr@2: 
williamr@2:         /** Cursors movement to next column. */
williamr@2:         ECursorNextColumn,  
williamr@2: 
williamr@2:         /** Cursors movement to previous column. */
williamr@2:         ECursorPreviousColumn,  
williamr@2: 
williamr@2:         /** Cursors movement to previous page. */
williamr@2:         ECursorPreviousPage, 
williamr@2: 
williamr@2:         /** Cursors movement to next page. */
williamr@2:         ECursorNextPage,
williamr@2: 
williamr@2:         /** Cursors movement to the first item. */
williamr@2:         ECursorFirstItem,
williamr@2: 
williamr@2:         /** Cursors movement to the last item. */
williamr@2:         ECursorLastItem,
williamr@2: 
williamr@2:         /** Cursors movement to the next screen. */
williamr@2:         ECursorNextScreen,
williamr@2: 
williamr@2:         /** Cursors movement to the previous screen. */
williamr@2:         ECursorPrevScreen
williamr@2:         };  
williamr@2: 
williamr@2:     /**
williamr@2:      * List box view flags.
williamr@2:      *
williamr@2:      * These flags may be combined with a logical OR to get a combination of 
williamr@2:      * effects.
williamr@2:      */
williamr@2: 	enum TFlags
williamr@2: 		{
williamr@2:         /** A selection anchor exists. */
williamr@2: 		EAnchorExists   = 0x0001,
williamr@2: 
williamr@2:         /** The view is emphasised. */
williamr@2: 		EEmphasized     = 0x0002,
williamr@2: 
williamr@2:         /** The view is dimmed. */
williamr@2: 		EDimmed         = 0x0004,
williamr@2: 
williamr@2:         /** List box view has a cursor for incremental matching. */
williamr@2: 		EHasMatcherCursor = 0x0008,
williamr@2: 
williamr@2:         /** Redraw is disabled. */
williamr@2: 		EDisableRedraw  = 0x0010,
williamr@2: 
williamr@2:         /** If set, selected items are painted. */
williamr@2: 		EPaintedSelection = 0x0020,
williamr@2: 
williamr@2:         /** Item marking enabled. */
williamr@2: 		EMarkSelection  = 0x0040,
williamr@2: 
williamr@2:         /** Item unmarking enabled. */
williamr@2: 		EUnmarkSelection = 0x0080,
williamr@2: 
williamr@2:         /** Item count changes enabled. */
williamr@2: 		EItemCountModified = 0x0100,
williamr@2: 
williamr@2:         /** Vertical offset has changed. */
williamr@2: 		EOffsetChanged = 0x0200,
williamr@2: 		};
williamr@2: 		
williamr@2:     /**
williamr@2:      * Modes for modifying the selection.
williamr@2:      *
williamr@2:      * Changing the current item of a list box view may also affect which items
williamr@2:      * are selected. The selection mode of such an action describes how (or if)
williamr@2:      * the selection is altered by the action.
williamr@2:      *
williamr@2:      * Each function of @c CListBoxView which affects the current item is 
williamr@2:      * passed an appropriate selection mode by the calling input handler method
williamr@2:      * of @c CEikListBox. The mode is varied according to the keyboard 
williamr@2:      * modifiers held down by the user, or whether a pointer action was a tap 
williamr@2:      * or a sweep.
williamr@2:      *
williamr@2:      * Note that the behaviour of list box views may vary with the target 
williamr@2:      * phone due to the wide range of possible input devices. 
williamr@2:      * The following description assumes a phone with a pointer and a keyboard.
williamr@2:      */
williamr@2:     enum TSelectionMode 
williamr@2:         {
williamr@2:         /** 
williamr@2:          * The selection is not changed by actions while this is in effect, 
williamr@2:          * holding CTRL while pressing cursor up or down for example.
williamr@2:          */
williamr@2:         ENoSelection,
williamr@2:     
williamr@2:         /** 
williamr@2:          * Only a single item in the list is allowed to be selected by an 
williamr@2:          * action; when selecting individual items with the pointer, or 
williamr@2:          * moving using the cursor keys without any modifiers for example.
williamr@2:          */
williamr@2:         ESingleSelection,
williamr@2: 
williamr@2:         /** 
williamr@2:          * A single continuous run of items can be added to the selection array
williamr@2:          * by an action, when keyboard-selecting with the shift key held down, 
williamr@2:          * or when sweeping a selection with the pointer for example.
williamr@2:          */
williamr@2:         EContiguousSelection,
williamr@2: 
williamr@2:         /** 
williamr@2:          * Any single item in the list may be added to the selection by an 
williamr@2:          * action, when selecting or drag-selecting with the pointer when the
williamr@2:          * @c CTRL key is held down for example.
williamr@2:          */
williamr@2:         EDisjointSelection,
williamr@2: 
williamr@2:         /** 
williamr@2:          * Any single item in the list may be removed from the selection by an 
williamr@2:          * action, when unselecting for example.
williamr@2:          */
williamr@2:         EDisjointMarkSelection,
williamr@2: 
williamr@2:         /** 
williamr@2:          * Multiple items can be added to the selection array by an action, 
williamr@2:          * when selecting with the edit key for example.
williamr@2:          */
williamr@2:         EPenMultiselection,
williamr@2: 
williamr@2:         /** 
williamr@2:          * Mark mode is changed to @c EUnmarkSelection if item is marked or 
williamr@2:          * @c EMarkSelection if item is not marked by an action, when selecting
williamr@2:          * or unselecting item for example.
williamr@2:          */
williamr@2:         EChangeMarkMode
williamr@2:         };
williamr@2: 
williamr@2:     /** The items which are selected within a list box list. */
williamr@2: 	typedef CArrayFix<TInt> CSelectionIndexArray;
williamr@2: 
williamr@2: public:
williamr@2: 
williamr@2:     /**
williamr@2:      * Destructor.
williamr@2:      */
williamr@2: 	IMPORT_C ~CListBoxView();
williamr@2: 
williamr@2:     /**
williamr@2:      * C++ default constructor.
williamr@2:      *
williamr@2:      * Allocates an area of memory for a @c CListBoxView, and begins its 
williamr@2:      * initialisation.
williamr@2:      */
williamr@2:     IMPORT_C CListBoxView();
williamr@2: 
williamr@2:     /**
williamr@2:      * By default Symbian 2nd phase constructor is private. 
williamr@2:      *
williamr@2:      * This function completes the initialisation of a default-constructed list
williamr@2:      * box view. The item drawer’s graphics context is created on @c aScreen, 
williamr@2:      * and the list item drawer’s graphics context is set to this. See 
williamr@2:      * @c CListItemDrawer::SetGc().
williamr@2:      * 
williamr@2:      * @param aListBoxModel The list box model to use. 
williamr@2:      * @param aItemDrawer A default-constructed item drawer. 
williamr@2:      * @param aScreen Screen on which to display. 
williamr@2:      * @param aGroupWin This list box view’s window group. 
williamr@2:      * @param aWsWindow Window for this view. 
williamr@2:      * @param aDisplayArea The viewing rectangle this list box view is to use.
williamr@2:      * @param aItemHeight Height of a single list item. 
williamr@2:      */
williamr@2:     IMPORT_C virtual void ConstructL(MListBoxModel* aListBoxModel, 
williamr@2:                                      CListItemDrawer* aItemDrawer, 
williamr@2:                                      CWsScreenDevice* aScreen, 
williamr@2:                                      RWindowGroup* aGroupWin, 
williamr@2:                                      RWindow* aWsWindow, 
williamr@2:                                      const TRect& aDisplayArea, 
williamr@2:                                      TInt aItemHeight);
williamr@2: 
williamr@2:     // functions for accessing the view rect (the area of the host window in 
williamr@2:     // which the items are drawn)
williamr@2:     /**
williamr@2:      * Gets the list box’s view rectangle.
williamr@2:      *
williamr@2:      * @return This list box’s view rectangle.
williamr@2:      */
williamr@2:     IMPORT_C TRect ViewRect() const;
williamr@2: 
williamr@2:     /**
williamr@2:      * Sets the area within the list window in which the view can draw itself.
williamr@2:      * 
williamr@2:      * @param aRect New view rectangle.
williamr@2:      */
williamr@2: 	IMPORT_C void SetViewRect(const TRect& aRect);  
williamr@2: 
williamr@2: 	// misc. access functions for the main attributes 
williamr@2:     /**
williamr@2:      * Gets the current item’s index.
williamr@2:      *
williamr@2:      * @return Index number of the current item.
williamr@2:      */
williamr@2: 	IMPORT_C virtual TInt CurrentItemIndex() const;	
williamr@2: 
williamr@2:     /**
williamr@2:      * Set the index of the current item. This function changes the current 
williamr@2:      * item, but does not redraw the list view or update the selection.
williamr@2:      *
williamr@2:      * @param aItemIndex Which item to make current.
williamr@2:      * @panic EEikPanicListBoxInvalidCurrentItemIndexSpecified Panics if the 
williamr@2:      *        given index is not valid. 
williamr@2:      */
williamr@2: 	IMPORT_C void SetCurrentItemIndex(TInt aItemIndex); 
williamr@2: 
williamr@2:     /**
williamr@2:      * Gets the index of the item at the top of the view.
williamr@2:      *
williamr@2:      * @return The item currently displayed at the top of this list box view.
williamr@2:      */
williamr@2: 	IMPORT_C TInt TopItemIndex() const;		
williamr@2: 
williamr@2:     /**
williamr@2:      * Sets the item at the top of the view by its index in the list of all 
williamr@2:      * items. This function also invokes @c CalcBottomItemIndex().
williamr@2:      *
williamr@2:      * @param aItemIndex Index of the item to start the view at.
williamr@2:      * @panic EEikPanicListBoxInvalidTopItemIndexSpecified Panics if the given
williamr@2:      *        index is not valid. 
williamr@2:      */
williamr@2: 	IMPORT_C virtual void SetTopItemIndex(TInt aItemIndex);
williamr@2: 
williamr@2:     /**
williamr@2:      * Gets the index of the item at the bottom of this view.
williamr@2:      *
williamr@2:      * @return Index of the item at the bottom of this view.
williamr@2:      */
williamr@2: 	IMPORT_C TInt BottomItemIndex() const;
williamr@2: 
williamr@2:     /**
williamr@2:      * Recalculates the index of the bottom item in the list by using the top 
williamr@2:      * item index and the size of the display.
williamr@2:      *
williamr@2:      * This function is called by the owning list box control when either the 
williamr@2:      * size of the list box or the number of items in its model changes.
williamr@2:      */
williamr@2: 	IMPORT_C virtual void CalcBottomItemIndex();
williamr@2: 
williamr@2:     /**
williamr@2:      * Sets the item height.
williamr@2:      *
williamr@2:      * @param aItemHeight New item height.
williamr@2:      */
williamr@2: 	IMPORT_C virtual void SetItemHeight(TInt aItemHeight);
williamr@2: 
williamr@2: 	// functions that support incremental matching 
williamr@2:     /**
williamr@2:      * Sets the match cursor’s colour.
williamr@2:      *
williamr@2:      * @deprecated
williamr@2:      * @param aColor Colour in which to display the incremental match cursor.
williamr@2:      */
williamr@2: 	IMPORT_C void SetMatcherCursorColor(TRgb aColor);
williamr@2: 
williamr@2:     /**
williamr@2:      * Sets the match cursor's position.
williamr@2:      *
williamr@2:      * @deprecated
williamr@2:      * @param aPosWithinCurrentItem Character position for the match cursor 
williamr@2:      *        within the current item’s string.
williamr@2:      */
williamr@2: 	IMPORT_C void SetMatcherCursorPos(TInt aPosWithinCurrentItem);
williamr@2: 
williamr@2:     /**
williamr@2:      * Gets the match cursor’s position.
williamr@2:      *
williamr@2:      * @deprecated
williamr@2:      * @return Character position of the match cursor within the current
williamr@2:      *         item’s string.
williamr@2:      */
williamr@2: 	IMPORT_C TInt MatcherCursorPos() const;
williamr@2: 
williamr@2:     /**
williamr@2:      * Draws the match cursor in its current screen position if the matcher 
williamr@2:      * cursor flag has been set.
williamr@2:      * 
williamr@2:      * This is deprecated and broken and should not be used.
williamr@2:      *
williamr@2:      * @deprecated
williamr@2:      */
williamr@2: 	IMPORT_C virtual void DrawMatcherCursor();
williamr@2: 
williamr@2:     /**
williamr@2:      * Hides the matcher cursor.
williamr@2:      *
williamr@2:      * @deprecated
williamr@2:      */
williamr@2: 	IMPORT_C void HideMatcherCursor();
williamr@2: 
williamr@2:     /**
williamr@2:      * Sets whether the matcher cursor flag to specify whether the match 
williamr@2:      * cursor is drawn.
williamr@2:      *
williamr@2:      * @deprecated
williamr@2:      * @param aMatcherCursor If @c ETrue, the view will draw match cursor. 
williamr@2:      */
williamr@2: 	IMPORT_C void SetMatcherCursor(TBool aMatcherCursor);
williamr@2: 
williamr@2:     /**
williamr@2:      * Sets whether or not items are drawn as emphasised. 
williamr@2:      *
williamr@2:      * The function sets or resets the emphasised flag.
williamr@2:      *
williamr@2:      * @param aEmphasized If @c ETrue, this view will draw items emphasised. 
williamr@2:      *        If @c EFalse will not draw items emphasised.
williamr@2:      */
williamr@2: 	IMPORT_C void SetEmphasized(TBool aEmphasized);
williamr@2: 
williamr@2:     /**
williamr@2:      * Sets whether items will be drawn dimmed. 
williamr@2:      *
williamr@2:      * The function sets or resets the dim flag.
williamr@2:      *
williamr@2:      * @param aDimmed If @c ETrue, this view will draw items dimmed. 
williamr@2:      *        If @c EFalse this view will not draw items dimmed.
williamr@2:      */
williamr@2: 	IMPORT_C void SetDimmed(TBool aDimmed);
williamr@2: 
williamr@2:     /**
williamr@2:      * Disables or enables redraws.
williamr@2:      *
williamr@2:      * If this flag is set to @c ETrue, all member functions which draw items 
williamr@2:      * will return immediately without drawing anything. Functions which update
williamr@2:      * the internal state of the list box will still work, but nothing will be 
williamr@2:      * drawn or updated on the screen.
williamr@2:      *
williamr@2:      * @param aDisableRedraw Disables redraw if @c ETrue.
williamr@2:      */
williamr@2: 	IMPORT_C void SetDisableRedraw(TBool aDisableRedraw);
williamr@2: 
williamr@2:     /**
williamr@2:      * Tests whether redraw is disabled.
williamr@2:      *
williamr@2:      * @return ETrue if redraw is disabled.
williamr@2:      */
williamr@2: 	IMPORT_C TBool RedrawDisabled() const;
williamr@2: 
williamr@2:     /**
williamr@2:      * Sets the painted selection flag.
williamr@2:      *
williamr@2:      * @deprecated
williamr@2:      * @param aPaintedSelection If @c ETrue the painted selection flag is set 
williamr@2:      *        on. If @c EFalse the selection flag is set off. If NULL the 
williamr@2:      *        painted selection flag is cleared.
williamr@2:      */
williamr@2: 	IMPORT_C void SetPaintedSelection( TBool aPaintedSelection );
williamr@2: 
williamr@2: 	// functions that support selection
williamr@2:     /**
williamr@2:      * Gets a pointer to the selection list of this view.
williamr@2:      * 
williamr@2:      * @return Pointer to an array describing the items 
williamr@2:      *         in the list which are currently selected. The object pointed 
williamr@2:      *         at is owned by the @c CListBoxView.
williamr@2:      */
williamr@2:     IMPORT_C const CSelectionIndexArray* SelectionIndexes() const;
williamr@2: 
williamr@2:     /**
williamr@2:      * Gets a copy of the array of currently selected items. 
williamr@2:      * 
williamr@2:      * @param[in,out] aSelectionArray An instantiated @c CSelectionIndexArray.
williamr@2:      *                On return, contains a copy of selection indexes. 
williamr@2:      * @panic EEikPanicListBoxInvalidSelIndexArraySpecified Panics if the given
williamr@2:      *        selection index array is not valid.
williamr@2:      * @panic EEikPanicListBoxNoSelIndexArray Panics if selection indexes have 
williamr@2:      *        not been defined for this class. 
williamr@2:      */
williamr@2: 	IMPORT_C void GetSelectionIndexesL(
williamr@2:                                 CSelectionIndexArray* aSelectionArray) const;
williamr@2: 	
williamr@2:     /**
williamr@2:      * Sets the currently selected items of this view from a selection index 
williamr@2:      * array.
williamr@2:      * 
williamr@2:      * @param aSelectionIndexes Items to select.
williamr@2:      * @panic EEikPanicListBoxInvalidSelIndexArraySpecified Panics if the given
williamr@2:      *        selection index array is not valid.
williamr@2:      */
williamr@2:     IMPORT_C void SetSelectionIndexesL(const CSelectionIndexArray* 
williamr@2:                                        aSelectionIndexes);
williamr@2: 	
williamr@2:     /**
williamr@2:      * Resets the selection state so that there is nothing selected.
williamr@2:      *
williamr@2:      * @panic EEikPanicListBoxNoSelIndexArray Panics if selection indexes have 
williamr@2:      *        not been defined for this class. 
williamr@2:      */
williamr@2:     IMPORT_C void ClearSelection(); 		
williamr@2: 	
williamr@2:     // select/highlight items without moving the cursor
williamr@2:     /**
williamr@2:      * Updates item selection.
williamr@2:      *
williamr@2:      * @param aSelectionMode The selection mode. 
williamr@2:      */
williamr@2:     IMPORT_C virtual void UpdateSelectionL(TSelectionMode aSelectionMode);  
williamr@2:     	
williamr@2:     /**
williamr@2:      * Toggles the selection of an item.
williamr@2:      *
williamr@2:      * @param aItemIndex Item to toggle.
williamr@2:      * @panic EEikPanicListBoxNoSelIndexArray Panics if selection indexes have 
williamr@2:      *        not been defined for this class. 
williamr@2:      */
williamr@2:     IMPORT_C void ToggleItemL(TInt aItemIndex);
williamr@2: 	
williamr@2:     /**
williamr@2:      * Selects an item by index. 
williamr@2:      *
williamr@2:      * This function leaves if memory could not be allocated for an extra item
williamr@2:      * in the array of selected items.
williamr@2:      *
williamr@2:      * @param aItemIndex Item to select.
williamr@2:      * @panic EEikPanicListBoxNoSelIndexArray Panics if selection indexes have 
williamr@2:      *        not been defined for this class. 
williamr@2:      */
williamr@2:     IMPORT_C void SelectItemL(TInt aItemIndex);
williamr@2: 	
williamr@2:     /**
williamr@2:      * Deselects an item by index.
williamr@2:      *
williamr@2:      * @param aItemIndex Item to deselect.
williamr@2:      * @panic EEikPanicListBoxNoSelIndexArray Panics if selection indexes have 
williamr@2:      *        not been defined for this class. 
williamr@2:      */
williamr@2:     IMPORT_C void DeselectItem(TInt aItemIndex);
williamr@2: 	
williamr@2:     /**
williamr@2:      * Sets the anchor to the specified item.
williamr@2:      *
williamr@2:      * @param aItemIndex The index of the item at which the anchor is set.
williamr@2:      */
williamr@2:     IMPORT_C void SetAnchor(TInt aItemIndex);
williamr@2: 	
williamr@2:     /**
williamr@2:      * Resets the anchor index, the active end and the  @c EAnchorExists flag.
williamr@2:      */
williamr@2:     IMPORT_C void ClearSelectionAnchorAndActiveIndex();
williamr@2: 
williamr@2: 	// functions that support scrolling
williamr@2:     /**
williamr@2:      * Scrolls vertically to make a particular item visible. 
williamr@2:      * 
williamr@2:      * @param aItemIndex The item to make visible.
williamr@2:      * @return @c ETrue if any scrolling was done, @c EFalse if no 
williamr@2:      *         scrolling was necessary.
williamr@2:      */
williamr@2: 	IMPORT_C virtual TBool ScrollToMakeItemVisible(TInt aItemIndex);
williamr@2:     
williamr@2:     /**
williamr@2:      * Sets the index of the item to be the top item.
williamr@2:      *
williamr@2:      * @param aNewTopItemIndex The item to scroll to.
williamr@2:      */
williamr@2: 	IMPORT_C virtual void VScrollTo(TInt aNewTopItemIndex);
williamr@2: 
williamr@2:     /**
williamr@2:      * Sets the index of the item to be the top item.
williamr@2:      *
williamr@2:      * This two argument version returns the area which needs redrawing via 
williamr@2:      * @c aMinRedrawRect&. This function does not perform the redraw.
williamr@2:      *
williamr@2:      * @param aNewTopItemIndex The distance by which to scroll. 
williamr@2:      * @param aMinRedrawRect On return, the minimum rectangle to redraw.
williamr@2:      */
williamr@2:     IMPORT_C virtual void VScrollTo(TInt aNewTopItemIndex, 
williamr@2:                                     TRect& aMinRedrawRect);
williamr@2: 	
williamr@2:     /**
williamr@2:      * Scrolls horizontally by the specified number of pixels.
williamr@2:      *
williamr@2:      * @param aHScrollAmount The distance to scroll by in pixels. A negative 
williamr@2:      *        value scrolls to the left, a positive value scrolls to the right.
williamr@2:      */
williamr@2:     IMPORT_C virtual void HScroll(TInt aHScrollAmount);
williamr@2: 	
williamr@2:     /**
williamr@2:      * Gets the offset of the visible portion of the data from the left margin
williamr@2:      * in pixels.
williamr@2:      *
williamr@2:      * @return The horizontal scroll offset in pixels.
williamr@2:      */
williamr@2:     IMPORT_C TInt HScrollOffset() const;
williamr@2: 
williamr@2:     /**
williamr@2:      * Sets the horizontal scroll offset in pixels.
williamr@2:      *
williamr@2:      * @param aHorizontalOffset New value for the horizontal scroll offset, in 
williamr@2:      *        pixels.
williamr@2:      */
williamr@2: 	IMPORT_C void SetHScrollOffset(TInt aHorizontalOffset);
williamr@2: 
williamr@2:     /**
williamr@2:      * Gets the width of the widest item in the list in pixels.
williamr@2:      *
williamr@2:      * @return Data width in pixels.
williamr@2:      */
williamr@2: 	IMPORT_C TInt DataWidth() const;
williamr@2: 
williamr@2:     /**
williamr@2:      * Recalculates the data width of this list box view from the item width 
williamr@2:      * of its list item drawer. This method is called directly by 
williamr@2:      * @c CEikListBox when the list box’s size changes or when data is added.
williamr@2:      */
williamr@2: 	IMPORT_C virtual void CalcDataWidth();
williamr@2: 
williamr@2:     /**
williamr@2:      * Gets the visible width of the specified rectangle in pixels. This 
williamr@2:      * function is called by @c CListBoxView itself on its own viewing 
williamr@2:      * rectangle.
williamr@2:      *
williamr@2:      * @param aRect The rectangle to get the visible width for.
williamr@2:      * @return Visible width of @c aRect.
williamr@2:      */
williamr@2: 	IMPORT_C virtual TInt VisibleWidth(const TRect& aRect) const;
williamr@2: 
williamr@2:     /**
williamr@2:      * Calculates which item should be selected in order to make a 
williamr@2:      * particular item visible. Calling 
williamr@2:      * @c VScrollTo(CalcNewTopItemIndexSoItemIsVisible(idx)), for example, 
williamr@2:      * would make the item whose index is @c idx visible.
williamr@2:      *
williamr@2:      * @param aItemIndex The index of the new top item.
williamr@2:      * @return The item to be selected. 
williamr@2:      */
williamr@2:     IMPORT_C virtual TInt CalcNewTopItemIndexSoItemIsVisible(
williamr@2:                                                         TInt aItemIndex) const;
williamr@2: 
williamr@2: 	// functions that support drawing
williamr@2:     /**
williamr@2:      * Draws every visible item into the specified rectangle. 
williamr@2:      *
williamr@2:      * As implemented in @c CListBoxView, this function's argument is ignored 
williamr@2:      * and the internal viewing rectangle is used. See @c SetViewRect().
williamr@2:      *
williamr@2:      * @param aClipRect The rectangle to draw into, this is ignored. Default 
williamr@2:      *        value is NULL.
williamr@2:      * @panic EEikPanicListBoxNoModel Panics if the list box model for this 
williamr@2:      *        class has not been defined. 
williamr@2:      */
williamr@2: 	IMPORT_C virtual void Draw(const TRect* aClipRect = NULL) const;
williamr@2: 
williamr@2:     /**
williamr@2:      * Draws the specified item via @c CListBoxDrawer::DrawItem() if it is 
williamr@2:      * visible.
williamr@2:      *
williamr@2:      * @param aItemIndex Index number of the item to draw.
williamr@2:      */
williamr@2: 	IMPORT_C virtual void DrawItem(TInt aItemIndex) const;
williamr@2: 
williamr@2:     /**
williamr@2:      * Sets list box backroung text. This text is visible if the list box 
williamr@2:      * has no items.
williamr@2:      *
williamr@2:      * @param aText The text for the empty list box background.
williamr@2:      */
williamr@2: 	IMPORT_C void SetListEmptyTextL(const TDesC& aText);
williamr@2: 
williamr@2:     /**
williamr@2:      * Gets an empty list box text. 
williamr@2:      * 
williamr@2:      * @return Pointer the empty list box text. 
williamr@2:      */
williamr@2: 	inline const TDesC* EmptyListText() const;
williamr@2: 
williamr@2:     /**
williamr@2:      * Tests whether an item is selected.
williamr@2:      *
williamr@2:      * @param aItemIndex Index of item to test.
williamr@2:      * @return @c ETrue if the item is selected.
williamr@2:      */    
williamr@2:     IMPORT_C TBool ItemIsSelected(TInt aItemIndex) const; 
williamr@2: 
williamr@2:     /**
williamr@2:      * Tests whether an item is visible.
williamr@2:      *
williamr@2:      * @param aItemIndex Index of item to be tested.
williamr@2:      * @return @c ETrue if the item is visible.
williamr@2:      */
williamr@2: 	IMPORT_C TBool ItemIsVisible(TInt aItemIndex) const;
williamr@2: 
williamr@2:     /**
williamr@2:      * Gets the on-screen position of an item.
williamr@2:      * 
williamr@2:      * @param aItemIndex Index of an item.
williamr@2:      * @return Position of the item.
williamr@2:      */
williamr@2: 	IMPORT_C virtual TPoint ItemPos(TInt aItemIndex) const;
williamr@2: 
williamr@2:     /**
williamr@2:      * Gets the on-screen size of an item. 
williamr@2:      * 
williamr@2:      * As implemented in @c CListBoxView, all items report the same size. 
williamr@2:      * The size returned may be larger than the width of the list box view, but
williamr@2:      * will not be smaller.
williamr@2:      *
williamr@2:      * @param aItemIndex Index of an item. Default value is 0.
williamr@2:      * @return Size of the item.
williamr@2:      */
williamr@2: 	IMPORT_C virtual TSize ItemSize(TInt aItemIndex=0) const;
williamr@2: 
williamr@2:     /**
williamr@2:      * Sets the colour in which to display text.
williamr@2:      *
williamr@2:      * @param aColor Colour in which to display text.
williamr@2:      */
williamr@2: 	IMPORT_C void SetTextColor(TRgb aColor);
williamr@2: 
williamr@2:     /**
williamr@2:      * Sets the background colour.
williamr@2:      *
williamr@2:      * @param aColor The background colour.
williamr@2:      */
williamr@2: 	IMPORT_C void SetBackColor(TRgb aColor);
williamr@2: 	
williamr@2:     /**
williamr@2:      * Gets the colour in which text is to be displayed.
williamr@2:      *
williamr@2:      * @return Current text colour.
williamr@2:      */
williamr@2:     IMPORT_C TRgb TextColor() const;
williamr@2: 
williamr@2:     /**
williamr@2:      * Gets the background colour for this view.
williamr@2:      * 
williamr@2:      * @return The background colour.
williamr@2:      */
williamr@2: 	IMPORT_C TRgb BackColor() const;
williamr@2: 
williamr@2:     /**
williamr@2:      * Moves the current item cursor in the specified direction. This function 
williamr@2:      * is called by @c CEikListBox in response to user input.
williamr@2:      *
williamr@2:      * @param aCursorMovement The cursor movement to apply. 
williamr@2:      * @param aSelectionMode The selection mode of the calling list box.
williamr@2:      */
williamr@2: 	IMPORT_C virtual void MoveCursorL(TCursorMovement aCursorMovement, 
williamr@2:                                       TSelectionMode aSelectionMode);
williamr@2: 	
williamr@2:     /**
williamr@2:      * Moves to the specified item, sets it as the current item and scrolls the
williamr@2:      * display to make the item visible.
williamr@2:      *
williamr@2:      * @param aTargetItemIndex The index of the item to which to move.
williamr@2:      * @param aSelectionMode The selection mode. 
williamr@2:      */
williamr@2:     IMPORT_C virtual void VerticalMoveToItemL(TInt aTargetItemIndex, 
williamr@2:                                               TSelectionMode aSelectionMode);
williamr@2: 	
williamr@2:     /**
williamr@2:      * Converts a pixel position into an item index.
williamr@2:      *
williamr@2:      * The function returns @c ETrue and sets @c aItemIndex to the index of the
williamr@2:      * item whose bounding box contains @c aPosition. Returns @c EFalse if no 
williamr@2:      * such item exists.
williamr@2:      *
williamr@2:      * @param aPosition A position relative to the origin of the list box 
williamr@2:      *                  control.
williamr@2:      * @param aItemIndex Is set to the item at that position. 
williamr@2:      * @return @c ETrue if there was an item at @c aPosition.
williamr@2:      */
williamr@2:     IMPORT_C virtual TBool XYPosToItemIndex(TPoint aPosition, 
williamr@2:                                             TInt& aItemIndex) const;   
williamr@2:     
williamr@2:     /**
williamr@2:      * Gets the number of items that will fit into a given rectangle.
williamr@2:      *
williamr@2:      * @param aRect The rectangle.
williamr@2:      * @return The number of items that will fit into the given rectangle.
williamr@2:      */
williamr@2:     IMPORT_C virtual TInt NumberOfItemsThatFitInRect(const TRect& aRect) const;
williamr@2: 
williamr@2:     /**
williamr@2:      * Sets the visibility observer.
williamr@2:      *
williamr@2:      * @param aObserver New visibility observer for this control.
williamr@2:      */
williamr@2:     void SetVisibilityObserver(MListVisibilityObserver* aObserver);
williamr@2: 
williamr@2:     /**
williamr@2:      * Tests if this view is visible.
williamr@2:      *
williamr@2:      * @return @c ETrue if this view is visible. @c EFalse if this view 
williamr@2:      *         is not visible or does not exist.
williamr@2:      */
williamr@2: 	IMPORT_C TBool IsVisible() const;
williamr@2: 
williamr@2:     /**
williamr@2:      * Gets the object used by this list box view to draw its items.
williamr@2:      *
williamr@2:      * @return Pointer to the list box item drawer. 
williamr@2:      */
williamr@2: 	inline CListItemDrawer* ItemDrawer() const;
williamr@2: 
williamr@2:     /**
williamr@2:      * Not implemented.
williamr@2:      * 
williamr@2:      * @param aClientRect Not used.
williamr@2:      */
williamr@2: 	IMPORT_C virtual void DrawEmptyList(const TRect &aClientRect) const;
williamr@2: 
williamr@2:     // disables vertical line drawing, useful only for certain 
williamr@2:     //custom list boxes
williamr@2:     /**
williamr@2:      * Disables vertical line drawing.
williamr@2:      *
williamr@2:      * @param aDisable @c ETrue if disabled.
williamr@2:      */
williamr@2:     void DisableVerticalLineDrawing( TBool aDisable );
williamr@2: 
williamr@2:     /** 
williamr@2:     * Deselects range between given indexes.
williamr@2:     *
williamr@2:     * @deprecated
williamr@2:     * @param aItemIndex1 First index of selectable range.
williamr@2:     * @param aItemIndex2 Second index of selectable range.
williamr@2:     */
williamr@2:     IMPORT_C void DeselectRangeL(TInt aItemIndex1, TInt aItemIndex2);
williamr@2: 
williamr@2:     /**
williamr@2:      * Sets the offset for view.
williamr@2:      *
williamr@2:      * @internal
williamr@2:      * @param aOffset Offset in pixels.
williamr@2:      */
williamr@2:     IMPORT_C void SetItemOffsetInPixels(TInt aOffset);
williamr@2:     
williamr@2:     /**
williamr@2:      * Gets view offset.
williamr@2:      *
williamr@2:      * @internal
williamr@2:      * @return View's offset.
williamr@2:      */
williamr@2:     IMPORT_C TInt ItemOffsetInPixels() const;
williamr@2:     
williamr@2:     /**
williamr@2:      * Sets scrolling state.
williamr@2: 	 *
williamr@2: 	 * @internal
williamr@2:      */
williamr@2:     void SetScrolling( TBool aIsScrolling );
williamr@2: 	 
williamr@2: 	/**
williamr@2: 	 * Returns item's height. All items have the same height.
williamr@2: 	 *
williamr@2: 	 * @internal
williamr@2: 	 * @return Item height.
williamr@2: 	 */ 
williamr@2:     TInt ItemHeight() const { return iItemHeight; }
williamr@2:     
williamr@2:     /**
williamr@2:      * Tests whether an item is partially visible.
williamr@2:      * Note that this returns @c EFalse also when item is fully visible,
williamr@2:      * i.e. the whole item area is inside the list view rectangle.
williamr@2:      *
williamr@2:      * @param  aItemIndex  Index of item to be tested.
williamr@2:      *
williamr@2:      * @return @c ETrue if the item is partially visible,
williamr@2:      *         @c EFalse if it's not visible or fully visible.
williamr@2:      */
williamr@2:     IMPORT_C TBool ItemIsPartiallyVisible( TInt aItemIndex ) const;
williamr@2: 
williamr@2: protected:
williamr@2: 
williamr@2: 	// functions for accessing the flags
williamr@2:     /**
williamr@2:      * Gets this view’s flags.
williamr@2:      *
williamr@2:      * These flags are defined by the nested enum @c TFlags (below).
williamr@2:      *
williamr@2:      * @return List box's flags. 
williamr@2:      */
williamr@2: 	inline TInt Flags() const;
williamr@2: 
williamr@2:     /**
williamr@2:      * Sets this view’s flags according to a bitmask.
williamr@2:      *
williamr@2:      * These flags are defined by the nested enum @c TFlags (below).
williamr@2:      *
williamr@2:      * @param aMask Sets new flags for the list box.
williamr@2:      */
williamr@2: 	inline void SetFlags(TInt aMask);
williamr@2: 
williamr@2:     /**
williamr@2:      * Clears this view’s flags according to a bitmask.
williamr@2:      *
williamr@2:      * These flags are defined by the nested enum @c TFlags (below).
williamr@2:      *
williamr@2:      * @param aMask Flags to be removed. 
williamr@2:      */
williamr@2: 	inline void ClearFlags(TInt aMask);
williamr@2: 
williamr@2:     /**
williamr@2:      * List box base class.
williamr@2:      * To access @c SetFlags()/ClearFlags().
williamr@2:      */
williamr@2:     friend class CEikListBox; 
williamr@2: 
williamr@2: 	// misc. functions
williamr@2:     /**
williamr@2:      * Selects items between given indexes.
williamr@2:      * 
williamr@2:      * @deprecated
williamr@2:      * @param aItemIndex1 First index of selectable range.
williamr@2:      * @param aItemIndex2 Second index of selectable range.
williamr@2:      */
williamr@2: 	IMPORT_C void SelectRangeL(TInt aItemIndex1, TInt aItemIndex2);
williamr@2: 
williamr@2: private:
williamr@2:     /**
williamr@2:      * Set item index directly. 
williamr@2:      * For CEikListBox.
williamr@2:      * @param aItemIndex New item index.
williamr@2:      */
williamr@2:     void SetItemIndex( TInt aItemIndex );
williamr@2:  
williamr@2: protected:
williamr@2: 
williamr@2:     /**
williamr@2:      * The flags for this list box. These flags are defined by the nested enum
williamr@2:      * @c TFlags (below).
williamr@2:      */
williamr@2: 	TInt iFlags;   	
williamr@2: 
williamr@2:     /**
williamr@2:      * This view’s item drawer.
williamr@2:      * Not owned.
williamr@2:      */
williamr@2: 	CListItemDrawer* iItemDrawer;
williamr@2: 
williamr@2:     /**
williamr@2:      * This view’s model.
williamr@2:      * Not owned.
williamr@2:      */
williamr@2: 	MListBoxModel* iModel;
williamr@2: 
williamr@2:     /**
williamr@2:      * Width (in pixels) of the longest item in the model.
williamr@2:      */
williamr@2: 	TInt iDataWidth;			
williamr@2:     
williamr@2:     /**
williamr@2:      * Index of the item at the top of the view. This is not necessarily the 
williamr@2:      * item at the start of the list.
williamr@2:      */
williamr@2:     TInt iTopItemIndex;
williamr@2: 	
williamr@2:     /**
williamr@2:      * Index of the item at the bottom of the view. This is not necessarily the
williamr@2:      * item at the end of the list.
williamr@2:      */
williamr@2:     TInt iBottomItemIndex;
williamr@2: 	
williamr@2:     /**
williamr@2:      * Pixel offset of the visible portion of the data from the left margin.
williamr@2:      */
williamr@2:     TInt iHScrollOffset; 
williamr@2: 	
williamr@2:     /**
williamr@2:      * Index of the current item.
williamr@2:      */
williamr@2:     TInt iCurrentItemIndex;
williamr@2: 	
williamr@2:     /**
williamr@2:      * Height of each item in the list in pixels.
williamr@2:      */
williamr@2:     TInt iItemHeight;
williamr@2: 	
williamr@2:     /**
williamr@2:      * This list box view’s window.
williamr@2:      */
williamr@2:     RWindow* iWin;
williamr@2: 	
williamr@2:     /**
williamr@2:      * The window group of this view.
williamr@2:      */
williamr@2:     RWindowGroup* iGroupWin;
williamr@2: 	
williamr@2:     /**
williamr@2:      * Graphics context for the control.
williamr@2:      */
williamr@2:     CWindowGc* iGc;
williamr@2: 	
williamr@2:     /**
williamr@2:      * Graphics context for the control.
williamr@2:      */
williamr@2:     TRect iViewRect;
williamr@2: 
williamr@2:     /**
williamr@2:      * The empty list text.
williamr@2:      */
williamr@2: 	HBufC *iListEmptyText;
williamr@2:     
williamr@2:     /**
williamr@2:      * Indicates whether vertical line drawing is disabled.
williamr@2:      */
williamr@2:     TBool iDisableVerticalLineDrawing /*TInt iSpare*/;
williamr@2: 
williamr@2: private:
williamr@2: 	TInt iMatcherCursorPos;
williamr@2: 	TRgb iMatcherCursorColor; 
williamr@2: 	TRgb iBackColor;
williamr@2: 	TRgb iTextColor;
williamr@2: 	TInt iAnchorIndex;  
williamr@2: 	TInt iActiveEndIndex;
williamr@2: 	CSelectionIndexArray* iSelectionIndexes;
williamr@2: 	MListVisibilityObserver* iVisibilityObserver;
williamr@2: protected:
williamr@2:     /**
williamr@2:      * Current vertical offset of the view in pixels.
williamr@2:      */
williamr@2:     TInt iVerticalOffset;
williamr@2: 
williamr@2: 	CListBoxViewExtension* iExtension;
williamr@2:     TInt iSpare[4];
williamr@2: 	};
williamr@2: 
williamr@2: NONSHARABLE_CLASS( CListBoxViewExtension ) : public CBase
williamr@2:     {
williamr@2:     public:
williamr@2:         static CListBoxViewExtension* NewL();
williamr@2:         
williamr@2:         ~CListBoxViewExtension();
williamr@2:         
williamr@2:     private:
williamr@2:         void ConstructL();
williamr@2:         
williamr@2:     public:
williamr@2: 	CEikListBox* iListBox;
williamr@2: 	TBool iScrolling;
williamr@2: 	TBool iScrollingDisabled;
williamr@2:     };
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2:  * Return text currently in the empty list text
williamr@2:  */
williamr@2: inline const TDesC* CListBoxView::EmptyListText() const
williamr@2: 	{ return(iListEmptyText); }
williamr@2: 
williamr@2: 
williamr@2: class CSnakingListBoxView : public CListBoxView
williamr@2: 	{
williamr@2: public:
williamr@2: 	IMPORT_C ~CSnakingListBoxView();
williamr@2: 	IMPORT_C CSnakingListBoxView();
williamr@2: 	inline TInt ColumnWidth() const;
williamr@2: 	IMPORT_C void SetColumnWidth(TInt aColumnWidth);
williamr@2: 	IMPORT_C virtual void MoveCursorL(TCursorMovement aCursorMovement, TSelectionMode aSelectionMode);
williamr@2: 	IMPORT_C virtual void SetTopItemIndex(TInt aItemIndex);
williamr@2: 	IMPORT_C virtual void SetItemHeight(TInt aItemHeight);
williamr@2: 	IMPORT_C virtual TBool XYPosToItemIndex(TPoint aPosition, TInt& aItemIndex) const;
williamr@2: 	IMPORT_C virtual TInt NumberOfItemsThatFitInRect(const TRect& aRect) const;
williamr@2: 	IMPORT_C virtual void HScroll(TInt aHScrollAmount);
williamr@2: 	IMPORT_C virtual void CalcDataWidth();
williamr@2: 	IMPORT_C virtual void CalcBottomItemIndex();
williamr@2: 	IMPORT_C virtual void Draw(const TRect* aClipRect = NULL) const;
williamr@2: 	IMPORT_C virtual TInt VisibleWidth(const TRect& aRect) const;
williamr@2: 	IMPORT_C virtual TBool ScrollToMakeItemVisible(TInt aItemIndex);
williamr@2: 	IMPORT_C virtual TInt CalculateHScrollOffsetSoItemIsVisible(TInt aItemIndex);
williamr@2: 	IMPORT_C virtual TInt CalcNewTopItemIndexSoItemIsVisible(TInt aItemIndex) const;
williamr@2: 	IMPORT_C virtual TPoint ItemPos(TInt aItemIndex) const;
williamr@2: 	IMPORT_C virtual TSize ItemSize(TInt aItemIndex=0) const;
williamr@2: 	IMPORT_C void CalcRowAndColIndexesFromItemIndex(TInt aItemIndex, TInt& aRowIndex, TInt& aColIndex) const;
williamr@2: 	IMPORT_C void CalcItemIndexFromRowAndColIndexes(TInt& aItemIndex, TInt aRowIndex, TInt aColIndex) const;
williamr@2: 	IMPORT_C virtual TInt NumberOfItemsPerColumn() const;
williamr@2: protected:
williamr@2: 	IMPORT_C virtual void DrawItemRange(TInt aStartItemIndex, TInt aEndItemIndex) const;
williamr@2: 	IMPORT_C void DrawColumnRange(TInt aStartColIndex, TInt aEndColIndex) const;
williamr@2: 	IMPORT_C void MoveToPreviousColumnL(TSelectionMode aSelectionMode);
williamr@2: 	IMPORT_C void MoveToNextColumnL(TSelectionMode aSelectionMode);
williamr@2: 	IMPORT_C void ClearUnusedItemSpace(TInt aStartItemIndex, TInt aEndItemIndex) const;
williamr@2: 	IMPORT_C void UpdateHScrollOffsetBasedOnTopItemIndex();
williamr@2: private: // overridden from CListBoxView
williamr@2: 	IMPORT_C virtual TAny* Reserved_1();
williamr@2: protected:
williamr@2: 	TInt iColumnWidth;
williamr@2: 	};
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: inline TInt CListBoxView::Flags() const
williamr@2: 	{ return iFlags; }
williamr@2: 
williamr@2: inline void CListBoxView::SetFlags(TInt aMask)
williamr@2: 	{ iFlags|=aMask; }
williamr@2:  
williamr@2: inline void CListBoxView::ClearFlags(TInt aMask)
williamr@2: 	{ iFlags&=(~aMask); }
williamr@2: 
williamr@2: inline CListItemDrawer* CListBoxView::ItemDrawer() const
williamr@2: 	{ return iItemDrawer; }
williamr@2: 
williamr@2: inline TInt CSnakingListBoxView::ColumnWidth() const
williamr@2: 	{ return iColumnWidth; }
williamr@2: 
williamr@2: 
williamr@2: #endif  // __EIKLBV_H__