1.1 --- a/epoc32/include/mw/eiklbv.h Tue Nov 24 13:55:44 2009 +0000
1.2 +++ b/epoc32/include/mw/eiklbv.h Tue Mar 16 16:12:26 2010 +0000
1.3 @@ -1,1 +1,1135 @@
1.4 -eiklbv.h
1.5 +/*
1.6 +* Copyright (c) 1997-2009 Nokia Corporation and/or its subsidiary(-ies).
1.7 +* All rights reserved.
1.8 +* This component and the accompanying materials are made available
1.9 +* 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
1.10 +* which accompanies this distribution, and is available
1.11 +* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
1.12 +*
1.13 +* Initial Contributors:
1.14 +* Nokia Corporation - initial contribution.
1.15 +*
1.16 +* Contributors:
1.17 +*
1.18 +* Description:
1.19 +*
1.20 +*/
1.21 +
1.22 +
1.23 +
1.24 +#if !defined(__EIKLBV_H__)
1.25 +#define __EIKLBV_H__
1.26 +
1.27 +#if !defined(__E32BASE_H__)
1.28 +#include <e32base.h>
1.29 +#endif
1.30 +
1.31 +#if !defined(__GDI_H__)
1.32 +#include <gdi.h>
1.33 +#endif
1.34 +
1.35 +class CListItemDrawer;
1.36 +class MListBoxModel;
1.37 +class CWindowGc;
1.38 +class RWindowGroup;
1.39 +class CWsScreenDevice;
1.40 +class CWindowGc;
1.41 +class RWindow;
1.42 +class CListBoxViewExtension;
1.43 +class CEikListBox;
1.44 +
1.45 +//
1.46 +// class MListVisibiltyObserver
1.47 +//
1.48 +
1.49 +class MListVisibilityObserver
1.50 + {
1.51 +public:
1.52 + virtual TBool IsVisible() const = 0;
1.53 + };
1.54 +
1.55 +/**
1.56 + * List box view.
1.57 + *
1.58 + * A list box view displays the list items which are currently visible in
1.59 + * a list box. List box views draw each of the items for display using
1.60 + * methods defined in their associated list box drawer.
1.61 + *
1.62 + * Together with its list item drawer, a @c CListBoxView encapsulates the
1.63 + * on-screen appearance of data in a list box.
1.64 + *
1.65 + * List box views also encapsulate item selection, the current item, and the
1.66 + * fundamentals of how the selection and the current item are updated according
1.67 + * to user input. Input events themselves are handled by @c CEikListBox,
1.68 + * which calls member functions of @c CListBoxView appropriately.
1.69 + *
1.70 + * This class is sufficient for plain list box views, and may be derived from
1.71 + * in order to provide more complex list views. @c TechView supplies and uses
1.72 + * the classes @c CHierarchicalListBoxView and @c CSnakingListBoxView, which
1.73 + * provide two kinds of indented list views.
1.74 + */
1.75 +class CListBoxView : public CBase
1.76 + {
1.77 +public:
1.78 +
1.79 + /**
1.80 + * Cursor movement flags. These describe the cursor movements recognised by
1.81 + * @c MoveCursorL().
1.82 + */
1.83 + enum TCursorMovement
1.84 + {
1.85 + /** Cursors movement to next item. */
1.86 + ECursorNextItem,
1.87 +
1.88 + /** Cursors movement to previous item. */
1.89 + ECursorPreviousItem,
1.90 +
1.91 + /** Cursors movement to next column. */
1.92 + ECursorNextColumn,
1.93 +
1.94 + /** Cursors movement to previous column. */
1.95 + ECursorPreviousColumn,
1.96 +
1.97 + /** Cursors movement to previous page. */
1.98 + ECursorPreviousPage,
1.99 +
1.100 + /** Cursors movement to next page. */
1.101 + ECursorNextPage,
1.102 +
1.103 + /** Cursors movement to the first item. */
1.104 + ECursorFirstItem,
1.105 +
1.106 + /** Cursors movement to the last item. */
1.107 + ECursorLastItem,
1.108 +
1.109 + /** Cursors movement to the next screen. */
1.110 + ECursorNextScreen,
1.111 +
1.112 + /** Cursors movement to the previous screen. */
1.113 + ECursorPrevScreen
1.114 + };
1.115 +
1.116 + /**
1.117 + * List box view flags.
1.118 + *
1.119 + * These flags may be combined with a logical OR to get a combination of
1.120 + * effects.
1.121 + */
1.122 + enum TFlags
1.123 + {
1.124 + /** A selection anchor exists. */
1.125 + EAnchorExists = 0x0001,
1.126 +
1.127 + /** The view is emphasised. */
1.128 + EEmphasized = 0x0002,
1.129 +
1.130 + /** The view is dimmed. */
1.131 + EDimmed = 0x0004,
1.132 +
1.133 + /** List box view has a cursor for incremental matching. */
1.134 + EHasMatcherCursor = 0x0008,
1.135 +
1.136 + /** Redraw is disabled. */
1.137 + EDisableRedraw = 0x0010,
1.138 +
1.139 + /** If set, selected items are painted. */
1.140 + EPaintedSelection = 0x0020,
1.141 +
1.142 + /** Item marking enabled. */
1.143 + EMarkSelection = 0x0040,
1.144 +
1.145 + /** Item unmarking enabled. */
1.146 + EUnmarkSelection = 0x0080,
1.147 +
1.148 + /** Item count changes enabled. */
1.149 + EItemCountModified = 0x0100,
1.150 +
1.151 + /** Vertical offset has changed. */
1.152 + EOffsetChanged = 0x0200,
1.153 + };
1.154 +
1.155 + /**
1.156 + * Modes for modifying the selection.
1.157 + *
1.158 + * Changing the current item of a list box view may also affect which items
1.159 + * are selected. The selection mode of such an action describes how (or if)
1.160 + * the selection is altered by the action.
1.161 + *
1.162 + * Each function of @c CListBoxView which affects the current item is
1.163 + * passed an appropriate selection mode by the calling input handler method
1.164 + * of @c CEikListBox. The mode is varied according to the keyboard
1.165 + * modifiers held down by the user, or whether a pointer action was a tap
1.166 + * or a sweep.
1.167 + *
1.168 + * Note that the behaviour of list box views may vary with the target
1.169 + * phone due to the wide range of possible input devices.
1.170 + * The following description assumes a phone with a pointer and a keyboard.
1.171 + */
1.172 + enum TSelectionMode
1.173 + {
1.174 + /**
1.175 + * The selection is not changed by actions while this is in effect,
1.176 + * holding CTRL while pressing cursor up or down for example.
1.177 + */
1.178 + ENoSelection,
1.179 +
1.180 + /**
1.181 + * Only a single item in the list is allowed to be selected by an
1.182 + * action; when selecting individual items with the pointer, or
1.183 + * moving using the cursor keys without any modifiers for example.
1.184 + */
1.185 + ESingleSelection,
1.186 +
1.187 + /**
1.188 + * A single continuous run of items can be added to the selection array
1.189 + * by an action, when keyboard-selecting with the shift key held down,
1.190 + * or when sweeping a selection with the pointer for example.
1.191 + */
1.192 + EContiguousSelection,
1.193 +
1.194 + /**
1.195 + * Any single item in the list may be added to the selection by an
1.196 + * action, when selecting or drag-selecting with the pointer when the
1.197 + * @c CTRL key is held down for example.
1.198 + */
1.199 + EDisjointSelection,
1.200 +
1.201 + /**
1.202 + * Any single item in the list may be removed from the selection by an
1.203 + * action, when unselecting for example.
1.204 + */
1.205 + EDisjointMarkSelection,
1.206 +
1.207 + /**
1.208 + * Multiple items can be added to the selection array by an action,
1.209 + * when selecting with the edit key for example.
1.210 + */
1.211 + EPenMultiselection,
1.212 +
1.213 + /**
1.214 + * Mark mode is changed to @c EUnmarkSelection if item is marked or
1.215 + * @c EMarkSelection if item is not marked by an action, when selecting
1.216 + * or unselecting item for example.
1.217 + */
1.218 + EChangeMarkMode
1.219 + };
1.220 +
1.221 + /** The items which are selected within a list box list. */
1.222 + typedef CArrayFix<TInt> CSelectionIndexArray;
1.223 +
1.224 +public:
1.225 +
1.226 + /**
1.227 + * Destructor.
1.228 + */
1.229 + IMPORT_C ~CListBoxView();
1.230 +
1.231 + /**
1.232 + * C++ default constructor.
1.233 + *
1.234 + * Allocates an area of memory for a @c CListBoxView, and begins its
1.235 + * initialisation.
1.236 + */
1.237 + IMPORT_C CListBoxView();
1.238 +
1.239 + /**
1.240 + * By default Symbian 2nd phase constructor is private.
1.241 + *
1.242 + * This function completes the initialisation of a default-constructed list
1.243 + * box view. The item drawer’s graphics context is created on @c aScreen,
1.244 + * and the list item drawer’s graphics context is set to this. See
1.245 + * @c CListItemDrawer::SetGc().
1.246 + *
1.247 + * @param aListBoxModel The list box model to use.
1.248 + * @param aItemDrawer A default-constructed item drawer.
1.249 + * @param aScreen Screen on which to display.
1.250 + * @param aGroupWin This list box view’s window group.
1.251 + * @param aWsWindow Window for this view.
1.252 + * @param aDisplayArea The viewing rectangle this list box view is to use.
1.253 + * @param aItemHeight Height of a single list item.
1.254 + */
1.255 + IMPORT_C virtual void ConstructL(MListBoxModel* aListBoxModel,
1.256 + CListItemDrawer* aItemDrawer,
1.257 + CWsScreenDevice* aScreen,
1.258 + RWindowGroup* aGroupWin,
1.259 + RWindow* aWsWindow,
1.260 + const TRect& aDisplayArea,
1.261 + TInt aItemHeight);
1.262 +
1.263 + // functions for accessing the view rect (the area of the host window in
1.264 + // which the items are drawn)
1.265 + /**
1.266 + * Gets the list box’s view rectangle.
1.267 + *
1.268 + * @return This list box’s view rectangle.
1.269 + */
1.270 + IMPORT_C TRect ViewRect() const;
1.271 +
1.272 + /**
1.273 + * Sets the area within the list window in which the view can draw itself.
1.274 + *
1.275 + * @param aRect New view rectangle.
1.276 + */
1.277 + IMPORT_C void SetViewRect(const TRect& aRect);
1.278 +
1.279 + // misc. access functions for the main attributes
1.280 + /**
1.281 + * Gets the current item’s index.
1.282 + *
1.283 + * @return Index number of the current item.
1.284 + */
1.285 + IMPORT_C virtual TInt CurrentItemIndex() const;
1.286 +
1.287 + /**
1.288 + * Set the index of the current item. This function changes the current
1.289 + * item, but does not redraw the list view or update the selection.
1.290 + *
1.291 + * @param aItemIndex Which item to make current.
1.292 + * @panic EEikPanicListBoxInvalidCurrentItemIndexSpecified Panics if the
1.293 + * given index is not valid.
1.294 + */
1.295 + IMPORT_C void SetCurrentItemIndex(TInt aItemIndex);
1.296 +
1.297 + /**
1.298 + * Gets the index of the item at the top of the view.
1.299 + *
1.300 + * @return The item currently displayed at the top of this list box view.
1.301 + */
1.302 + IMPORT_C TInt TopItemIndex() const;
1.303 +
1.304 + /**
1.305 + * Sets the item at the top of the view by its index in the list of all
1.306 + * items. This function also invokes @c CalcBottomItemIndex().
1.307 + *
1.308 + * @param aItemIndex Index of the item to start the view at.
1.309 + * @panic EEikPanicListBoxInvalidTopItemIndexSpecified Panics if the given
1.310 + * index is not valid.
1.311 + */
1.312 + IMPORT_C virtual void SetTopItemIndex(TInt aItemIndex);
1.313 +
1.314 + /**
1.315 + * Gets the index of the item at the bottom of this view.
1.316 + *
1.317 + * @return Index of the item at the bottom of this view.
1.318 + */
1.319 + IMPORT_C TInt BottomItemIndex() const;
1.320 +
1.321 + /**
1.322 + * Recalculates the index of the bottom item in the list by using the top
1.323 + * item index and the size of the display.
1.324 + *
1.325 + * This function is called by the owning list box control when either the
1.326 + * size of the list box or the number of items in its model changes.
1.327 + */
1.328 + IMPORT_C virtual void CalcBottomItemIndex();
1.329 +
1.330 + /**
1.331 + * Sets the item height.
1.332 + *
1.333 + * @param aItemHeight New item height.
1.334 + */
1.335 + IMPORT_C virtual void SetItemHeight(TInt aItemHeight);
1.336 +
1.337 + // functions that support incremental matching
1.338 + /**
1.339 + * Sets the match cursor’s colour.
1.340 + *
1.341 + * @deprecated
1.342 + * @param aColor Colour in which to display the incremental match cursor.
1.343 + */
1.344 + IMPORT_C void SetMatcherCursorColor(TRgb aColor);
1.345 +
1.346 + /**
1.347 + * Sets the match cursor's position.
1.348 + *
1.349 + * @deprecated
1.350 + * @param aPosWithinCurrentItem Character position for the match cursor
1.351 + * within the current item’s string.
1.352 + */
1.353 + IMPORT_C void SetMatcherCursorPos(TInt aPosWithinCurrentItem);
1.354 +
1.355 + /**
1.356 + * Gets the match cursor’s position.
1.357 + *
1.358 + * @deprecated
1.359 + * @return Character position of the match cursor within the current
1.360 + * item’s string.
1.361 + */
1.362 + IMPORT_C TInt MatcherCursorPos() const;
1.363 +
1.364 + /**
1.365 + * Draws the match cursor in its current screen position if the matcher
1.366 + * cursor flag has been set.
1.367 + *
1.368 + * This is deprecated and broken and should not be used.
1.369 + *
1.370 + * @deprecated
1.371 + */
1.372 + IMPORT_C virtual void DrawMatcherCursor();
1.373 +
1.374 + /**
1.375 + * Hides the matcher cursor.
1.376 + *
1.377 + * @deprecated
1.378 + */
1.379 + IMPORT_C void HideMatcherCursor();
1.380 +
1.381 + /**
1.382 + * Sets whether the matcher cursor flag to specify whether the match
1.383 + * cursor is drawn.
1.384 + *
1.385 + * @deprecated
1.386 + * @param aMatcherCursor If @c ETrue, the view will draw match cursor.
1.387 + */
1.388 + IMPORT_C void SetMatcherCursor(TBool aMatcherCursor);
1.389 +
1.390 + /**
1.391 + * Sets whether or not items are drawn as emphasised.
1.392 + *
1.393 + * The function sets or resets the emphasised flag.
1.394 + *
1.395 + * @param aEmphasized If @c ETrue, this view will draw items emphasised.
1.396 + * If @c EFalse will not draw items emphasised.
1.397 + */
1.398 + IMPORT_C void SetEmphasized(TBool aEmphasized);
1.399 +
1.400 + /**
1.401 + * Sets whether items will be drawn dimmed.
1.402 + *
1.403 + * The function sets or resets the dim flag.
1.404 + *
1.405 + * @param aDimmed If @c ETrue, this view will draw items dimmed.
1.406 + * If @c EFalse this view will not draw items dimmed.
1.407 + */
1.408 + IMPORT_C void SetDimmed(TBool aDimmed);
1.409 +
1.410 + /**
1.411 + * Disables or enables redraws.
1.412 + *
1.413 + * If this flag is set to @c ETrue, all member functions which draw items
1.414 + * will return immediately without drawing anything. Functions which update
1.415 + * the internal state of the list box will still work, but nothing will be
1.416 + * drawn or updated on the screen.
1.417 + *
1.418 + * @param aDisableRedraw Disables redraw if @c ETrue.
1.419 + */
1.420 + IMPORT_C void SetDisableRedraw(TBool aDisableRedraw);
1.421 +
1.422 + /**
1.423 + * Tests whether redraw is disabled.
1.424 + *
1.425 + * @return ETrue if redraw is disabled.
1.426 + */
1.427 + IMPORT_C TBool RedrawDisabled() const;
1.428 +
1.429 + /**
1.430 + * Sets the painted selection flag.
1.431 + *
1.432 + * @deprecated
1.433 + * @param aPaintedSelection If @c ETrue the painted selection flag is set
1.434 + * on. If @c EFalse the selection flag is set off. If NULL the
1.435 + * painted selection flag is cleared.
1.436 + */
1.437 + IMPORT_C void SetPaintedSelection( TBool aPaintedSelection );
1.438 +
1.439 + // functions that support selection
1.440 + /**
1.441 + * Gets a pointer to the selection list of this view.
1.442 + *
1.443 + * @return Pointer to an array describing the items
1.444 + * in the list which are currently selected. The object pointed
1.445 + * at is owned by the @c CListBoxView.
1.446 + */
1.447 + IMPORT_C const CSelectionIndexArray* SelectionIndexes() const;
1.448 +
1.449 + /**
1.450 + * Gets a copy of the array of currently selected items.
1.451 + *
1.452 + * @param[in,out] aSelectionArray An instantiated @c CSelectionIndexArray.
1.453 + * On return, contains a copy of selection indexes.
1.454 + * @panic EEikPanicListBoxInvalidSelIndexArraySpecified Panics if the given
1.455 + * selection index array is not valid.
1.456 + * @panic EEikPanicListBoxNoSelIndexArray Panics if selection indexes have
1.457 + * not been defined for this class.
1.458 + */
1.459 + IMPORT_C void GetSelectionIndexesL(
1.460 + CSelectionIndexArray* aSelectionArray) const;
1.461 +
1.462 + /**
1.463 + * Sets the currently selected items of this view from a selection index
1.464 + * array.
1.465 + *
1.466 + * @param aSelectionIndexes Items to select.
1.467 + * @panic EEikPanicListBoxInvalidSelIndexArraySpecified Panics if the given
1.468 + * selection index array is not valid.
1.469 + */
1.470 + IMPORT_C void SetSelectionIndexesL(const CSelectionIndexArray*
1.471 + aSelectionIndexes);
1.472 +
1.473 + /**
1.474 + * Resets the selection state so that there is nothing selected.
1.475 + *
1.476 + * @panic EEikPanicListBoxNoSelIndexArray Panics if selection indexes have
1.477 + * not been defined for this class.
1.478 + */
1.479 + IMPORT_C void ClearSelection();
1.480 +
1.481 + // select/highlight items without moving the cursor
1.482 + /**
1.483 + * Updates item selection.
1.484 + *
1.485 + * @param aSelectionMode The selection mode.
1.486 + */
1.487 + IMPORT_C virtual void UpdateSelectionL(TSelectionMode aSelectionMode);
1.488 +
1.489 + /**
1.490 + * Toggles the selection of an item.
1.491 + *
1.492 + * @param aItemIndex Item to toggle.
1.493 + * @panic EEikPanicListBoxNoSelIndexArray Panics if selection indexes have
1.494 + * not been defined for this class.
1.495 + */
1.496 + IMPORT_C void ToggleItemL(TInt aItemIndex);
1.497 +
1.498 + /**
1.499 + * Selects an item by index.
1.500 + *
1.501 + * This function leaves if memory could not be allocated for an extra item
1.502 + * in the array of selected items.
1.503 + *
1.504 + * @param aItemIndex Item to select.
1.505 + * @panic EEikPanicListBoxNoSelIndexArray Panics if selection indexes have
1.506 + * not been defined for this class.
1.507 + */
1.508 + IMPORT_C void SelectItemL(TInt aItemIndex);
1.509 +
1.510 + /**
1.511 + * Deselects an item by index.
1.512 + *
1.513 + * @param aItemIndex Item to deselect.
1.514 + * @panic EEikPanicListBoxNoSelIndexArray Panics if selection indexes have
1.515 + * not been defined for this class.
1.516 + */
1.517 + IMPORT_C void DeselectItem(TInt aItemIndex);
1.518 +
1.519 + /**
1.520 + * Sets the anchor to the specified item.
1.521 + *
1.522 + * @param aItemIndex The index of the item at which the anchor is set.
1.523 + */
1.524 + IMPORT_C void SetAnchor(TInt aItemIndex);
1.525 +
1.526 + /**
1.527 + * Resets the anchor index, the active end and the @c EAnchorExists flag.
1.528 + */
1.529 + IMPORT_C void ClearSelectionAnchorAndActiveIndex();
1.530 +
1.531 + // functions that support scrolling
1.532 + /**
1.533 + * Scrolls vertically to make a particular item visible.
1.534 + *
1.535 + * @param aItemIndex The item to make visible.
1.536 + * @return @c ETrue if any scrolling was done, @c EFalse if no
1.537 + * scrolling was necessary.
1.538 + */
1.539 + IMPORT_C virtual TBool ScrollToMakeItemVisible(TInt aItemIndex);
1.540 +
1.541 + /**
1.542 + * Sets the index of the item to be the top item.
1.543 + *
1.544 + * @param aNewTopItemIndex The item to scroll to.
1.545 + */
1.546 + IMPORT_C virtual void VScrollTo(TInt aNewTopItemIndex);
1.547 +
1.548 + /**
1.549 + * Sets the index of the item to be the top item.
1.550 + *
1.551 + * This two argument version returns the area which needs redrawing via
1.552 + * @c aMinRedrawRect&. This function does not perform the redraw.
1.553 + *
1.554 + * @param aNewTopItemIndex The distance by which to scroll.
1.555 + * @param aMinRedrawRect On return, the minimum rectangle to redraw.
1.556 + */
1.557 + IMPORT_C virtual void VScrollTo(TInt aNewTopItemIndex,
1.558 + TRect& aMinRedrawRect);
1.559 +
1.560 + /**
1.561 + * Scrolls horizontally by the specified number of pixels.
1.562 + *
1.563 + * @param aHScrollAmount The distance to scroll by in pixels. A negative
1.564 + * value scrolls to the left, a positive value scrolls to the right.
1.565 + */
1.566 + IMPORT_C virtual void HScroll(TInt aHScrollAmount);
1.567 +
1.568 + /**
1.569 + * Gets the offset of the visible portion of the data from the left margin
1.570 + * in pixels.
1.571 + *
1.572 + * @return The horizontal scroll offset in pixels.
1.573 + */
1.574 + IMPORT_C TInt HScrollOffset() const;
1.575 +
1.576 + /**
1.577 + * Sets the horizontal scroll offset in pixels.
1.578 + *
1.579 + * @param aHorizontalOffset New value for the horizontal scroll offset, in
1.580 + * pixels.
1.581 + */
1.582 + IMPORT_C void SetHScrollOffset(TInt aHorizontalOffset);
1.583 +
1.584 + /**
1.585 + * Gets the width of the widest item in the list in pixels.
1.586 + *
1.587 + * @return Data width in pixels.
1.588 + */
1.589 + IMPORT_C TInt DataWidth() const;
1.590 +
1.591 + /**
1.592 + * Recalculates the data width of this list box view from the item width
1.593 + * of its list item drawer. This method is called directly by
1.594 + * @c CEikListBox when the list box’s size changes or when data is added.
1.595 + */
1.596 + IMPORT_C virtual void CalcDataWidth();
1.597 +
1.598 + /**
1.599 + * Gets the visible width of the specified rectangle in pixels. This
1.600 + * function is called by @c CListBoxView itself on its own viewing
1.601 + * rectangle.
1.602 + *
1.603 + * @param aRect The rectangle to get the visible width for.
1.604 + * @return Visible width of @c aRect.
1.605 + */
1.606 + IMPORT_C virtual TInt VisibleWidth(const TRect& aRect) const;
1.607 +
1.608 + /**
1.609 + * Calculates which item should be selected in order to make a
1.610 + * particular item visible. Calling
1.611 + * @c VScrollTo(CalcNewTopItemIndexSoItemIsVisible(idx)), for example,
1.612 + * would make the item whose index is @c idx visible.
1.613 + *
1.614 + * @param aItemIndex The index of the new top item.
1.615 + * @return The item to be selected.
1.616 + */
1.617 + IMPORT_C virtual TInt CalcNewTopItemIndexSoItemIsVisible(
1.618 + TInt aItemIndex) const;
1.619 +
1.620 + // functions that support drawing
1.621 + /**
1.622 + * Draws every visible item into the specified rectangle.
1.623 + *
1.624 + * As implemented in @c CListBoxView, this function's argument is ignored
1.625 + * and the internal viewing rectangle is used. See @c SetViewRect().
1.626 + *
1.627 + * @param aClipRect The rectangle to draw into, this is ignored. Default
1.628 + * value is NULL.
1.629 + * @panic EEikPanicListBoxNoModel Panics if the list box model for this
1.630 + * class has not been defined.
1.631 + */
1.632 + IMPORT_C virtual void Draw(const TRect* aClipRect = NULL) const;
1.633 +
1.634 + /**
1.635 + * Draws the specified item via @c CListBoxDrawer::DrawItem() if it is
1.636 + * visible.
1.637 + *
1.638 + * @param aItemIndex Index number of the item to draw.
1.639 + */
1.640 + IMPORT_C virtual void DrawItem(TInt aItemIndex) const;
1.641 +
1.642 + /**
1.643 + * Sets list box backroung text. This text is visible if the list box
1.644 + * has no items.
1.645 + *
1.646 + * @param aText The text for the empty list box background.
1.647 + */
1.648 + IMPORT_C void SetListEmptyTextL(const TDesC& aText);
1.649 +
1.650 + /**
1.651 + * Gets an empty list box text.
1.652 + *
1.653 + * @return Pointer the empty list box text.
1.654 + */
1.655 + inline const TDesC* EmptyListText() const;
1.656 +
1.657 + /**
1.658 + * Tests whether an item is selected.
1.659 + *
1.660 + * @param aItemIndex Index of item to test.
1.661 + * @return @c ETrue if the item is selected.
1.662 + */
1.663 + IMPORT_C TBool ItemIsSelected(TInt aItemIndex) const;
1.664 +
1.665 + /**
1.666 + * Tests whether an item is visible.
1.667 + *
1.668 + * @param aItemIndex Index of item to be tested.
1.669 + * @return @c ETrue if the item is visible.
1.670 + */
1.671 + IMPORT_C TBool ItemIsVisible(TInt aItemIndex) const;
1.672 +
1.673 + /**
1.674 + * Gets the on-screen position of an item.
1.675 + *
1.676 + * @param aItemIndex Index of an item.
1.677 + * @return Position of the item.
1.678 + */
1.679 + IMPORT_C virtual TPoint ItemPos(TInt aItemIndex) const;
1.680 +
1.681 + /**
1.682 + * Gets the on-screen size of an item.
1.683 + *
1.684 + * As implemented in @c CListBoxView, all items report the same size.
1.685 + * The size returned may be larger than the width of the list box view, but
1.686 + * will not be smaller.
1.687 + *
1.688 + * @param aItemIndex Index of an item. Default value is 0.
1.689 + * @return Size of the item.
1.690 + */
1.691 + IMPORT_C virtual TSize ItemSize(TInt aItemIndex=0) const;
1.692 +
1.693 + /**
1.694 + * Sets the colour in which to display text.
1.695 + *
1.696 + * @param aColor Colour in which to display text.
1.697 + */
1.698 + IMPORT_C void SetTextColor(TRgb aColor);
1.699 +
1.700 + /**
1.701 + * Sets the background colour.
1.702 + *
1.703 + * @param aColor The background colour.
1.704 + */
1.705 + IMPORT_C void SetBackColor(TRgb aColor);
1.706 +
1.707 + /**
1.708 + * Gets the colour in which text is to be displayed.
1.709 + *
1.710 + * @return Current text colour.
1.711 + */
1.712 + IMPORT_C TRgb TextColor() const;
1.713 +
1.714 + /**
1.715 + * Gets the background colour for this view.
1.716 + *
1.717 + * @return The background colour.
1.718 + */
1.719 + IMPORT_C TRgb BackColor() const;
1.720 +
1.721 + /**
1.722 + * Moves the current item cursor in the specified direction. This function
1.723 + * is called by @c CEikListBox in response to user input.
1.724 + *
1.725 + * @param aCursorMovement The cursor movement to apply.
1.726 + * @param aSelectionMode The selection mode of the calling list box.
1.727 + */
1.728 + IMPORT_C virtual void MoveCursorL(TCursorMovement aCursorMovement,
1.729 + TSelectionMode aSelectionMode);
1.730 +
1.731 + /**
1.732 + * Moves to the specified item, sets it as the current item and scrolls the
1.733 + * display to make the item visible.
1.734 + *
1.735 + * @param aTargetItemIndex The index of the item to which to move.
1.736 + * @param aSelectionMode The selection mode.
1.737 + */
1.738 + IMPORT_C virtual void VerticalMoveToItemL(TInt aTargetItemIndex,
1.739 + TSelectionMode aSelectionMode);
1.740 +
1.741 + /**
1.742 + * Converts a pixel position into an item index.
1.743 + *
1.744 + * The function returns @c ETrue and sets @c aItemIndex to the index of the
1.745 + * item whose bounding box contains @c aPosition. Returns @c EFalse if no
1.746 + * such item exists.
1.747 + *
1.748 + * @param aPosition A position relative to the origin of the list box
1.749 + * control.
1.750 + * @param aItemIndex Is set to the item at that position.
1.751 + * @return @c ETrue if there was an item at @c aPosition.
1.752 + */
1.753 + IMPORT_C virtual TBool XYPosToItemIndex(TPoint aPosition,
1.754 + TInt& aItemIndex) const;
1.755 +
1.756 + /**
1.757 + * Gets the number of items that will fit into a given rectangle.
1.758 + *
1.759 + * @param aRect The rectangle.
1.760 + * @return The number of items that will fit into the given rectangle.
1.761 + */
1.762 + IMPORT_C virtual TInt NumberOfItemsThatFitInRect(const TRect& aRect) const;
1.763 +
1.764 + /**
1.765 + * Sets the visibility observer.
1.766 + *
1.767 + * @param aObserver New visibility observer for this control.
1.768 + */
1.769 + void SetVisibilityObserver(MListVisibilityObserver* aObserver);
1.770 +
1.771 + /**
1.772 + * Tests if this view is visible.
1.773 + *
1.774 + * @return @c ETrue if this view is visible. @c EFalse if this view
1.775 + * is not visible or does not exist.
1.776 + */
1.777 + IMPORT_C TBool IsVisible() const;
1.778 +
1.779 + /**
1.780 + * Gets the object used by this list box view to draw its items.
1.781 + *
1.782 + * @return Pointer to the list box item drawer.
1.783 + */
1.784 + inline CListItemDrawer* ItemDrawer() const;
1.785 +
1.786 + /**
1.787 + * Not implemented.
1.788 + *
1.789 + * @param aClientRect Not used.
1.790 + */
1.791 + IMPORT_C virtual void DrawEmptyList(const TRect &aClientRect) const;
1.792 +
1.793 + // disables vertical line drawing, useful only for certain
1.794 + //custom list boxes
1.795 + /**
1.796 + * Disables vertical line drawing.
1.797 + *
1.798 + * @param aDisable @c ETrue if disabled.
1.799 + */
1.800 + void DisableVerticalLineDrawing( TBool aDisable );
1.801 +
1.802 + /**
1.803 + * Deselects range between given indexes.
1.804 + *
1.805 + * @deprecated
1.806 + * @param aItemIndex1 First index of selectable range.
1.807 + * @param aItemIndex2 Second index of selectable range.
1.808 + */
1.809 + IMPORT_C void DeselectRangeL(TInt aItemIndex1, TInt aItemIndex2);
1.810 +
1.811 + /**
1.812 + * Sets the offset for view.
1.813 + *
1.814 + * @internal
1.815 + * @param aOffset Offset in pixels.
1.816 + */
1.817 + IMPORT_C void SetItemOffsetInPixels(TInt aOffset);
1.818 +
1.819 + /**
1.820 + * Gets view offset.
1.821 + *
1.822 + * @internal
1.823 + * @return View's offset.
1.824 + */
1.825 + IMPORT_C TInt ItemOffsetInPixels() const;
1.826 +
1.827 + /**
1.828 + * Sets scrolling state.
1.829 + *
1.830 + * @internal
1.831 + */
1.832 + void SetScrolling( TBool aIsScrolling );
1.833 +
1.834 + /**
1.835 + * Returns item's height. All items have the same height.
1.836 + *
1.837 + * @internal
1.838 + * @return Item height.
1.839 + */
1.840 + TInt ItemHeight() const { return iItemHeight; }
1.841 +
1.842 + /**
1.843 + * Tests whether an item is partially visible.
1.844 + * Note that this returns @c EFalse also when item is fully visible,
1.845 + * i.e. the whole item area is inside the list view rectangle.
1.846 + *
1.847 + * @param aItemIndex Index of item to be tested.
1.848 + *
1.849 + * @return @c ETrue if the item is partially visible,
1.850 + * @c EFalse if it's not visible or fully visible.
1.851 + */
1.852 + IMPORT_C TBool ItemIsPartiallyVisible( TInt aItemIndex ) const;
1.853 +
1.854 +protected:
1.855 +
1.856 + // functions for accessing the flags
1.857 + /**
1.858 + * Gets this view’s flags.
1.859 + *
1.860 + * These flags are defined by the nested enum @c TFlags (below).
1.861 + *
1.862 + * @return List box's flags.
1.863 + */
1.864 + inline TInt Flags() const;
1.865 +
1.866 + /**
1.867 + * Sets this view’s flags according to a bitmask.
1.868 + *
1.869 + * These flags are defined by the nested enum @c TFlags (below).
1.870 + *
1.871 + * @param aMask Sets new flags for the list box.
1.872 + */
1.873 + inline void SetFlags(TInt aMask);
1.874 +
1.875 + /**
1.876 + * Clears this view’s flags according to a bitmask.
1.877 + *
1.878 + * These flags are defined by the nested enum @c TFlags (below).
1.879 + *
1.880 + * @param aMask Flags to be removed.
1.881 + */
1.882 + inline void ClearFlags(TInt aMask);
1.883 +
1.884 + /**
1.885 + * List box base class.
1.886 + * To access @c SetFlags()/ClearFlags().
1.887 + */
1.888 + friend class CEikListBox;
1.889 +
1.890 + // misc. functions
1.891 + /**
1.892 + * Selects items between given indexes.
1.893 + *
1.894 + * @deprecated
1.895 + * @param aItemIndex1 First index of selectable range.
1.896 + * @param aItemIndex2 Second index of selectable range.
1.897 + */
1.898 + IMPORT_C void SelectRangeL(TInt aItemIndex1, TInt aItemIndex2);
1.899 +
1.900 +private:
1.901 + /**
1.902 + * Set item index directly.
1.903 + * For CEikListBox.
1.904 + * @param aItemIndex New item index.
1.905 + */
1.906 + void SetItemIndex( TInt aItemIndex );
1.907 +
1.908 + /**
1.909 + * Tests whether an item is visible. This method get bottom item index
1.910 + * from parameter
1.911 + *
1.912 + * @param aItemIndex Index of item to be tested.
1.913 + * @param aBottomItemIndex Index of item in the bottom of view.
1.914 + * @return @c ETrue if the item is visible.
1.915 + */
1.916 + TBool ItemIsVisible(TInt aItemIndex, TInt aBottomItemIndex) const;
1.917 +
1.918 + /**
1.919 + * Selects an item by index.
1.920 + *
1.921 + * This function leaves if memory could not be allocated for an extra item
1.922 + * in the array of selected items.
1.923 + *
1.924 + * @param aItemIndex Item to select.
1.925 + * @param aBottomItemIndex Index of item in the bottom of view.
1.926 + * @panic EEikPanicListBoxNoSelIndexArray Panics if selection indexes have
1.927 + * not been defined for this class.
1.928 + */
1.929 + void SelectItemL(TInt aItemIndex, TInt aBottomItemIndex);
1.930 +
1.931 + /**
1.932 + * Deselects an item by index.
1.933 + *
1.934 + * @param aItemIndex Item to deselect.
1.935 + * @param aBottomItemIndex Index of item in the bottom of view.
1.936 + * @panic EEikPanicListBoxNoSelIndexArray Panics if selection indexes have
1.937 + * not been defined for this class.
1.938 + */
1.939 + void DeselectItem(TInt aItemIndex, TInt aBottomItemIndex);
1.940 +
1.941 + /**
1.942 + * Draws the specified item via @c CListBoxDrawer::DrawItem() if it is
1.943 + * visible.
1.944 + *
1.945 + * @param aItemIndex Index number of the item to draw.
1.946 + * @param aBottomItemIndex Index of item in the bottom of view.
1.947 + */
1.948 + void DrawItem(TInt aItemIndex, TInt aBottomItemIndex) const;
1.949 +
1.950 + /**
1.951 + * Updates item selection.
1.952 + *
1.953 + * @param aSelectionMode The selection mode.
1.954 + * @param aBottomItemIndex Index of item in the bottom of view.
1.955 + */
1.956 + void UpdateSelectionL(TSelectionMode aSelectionMode, TInt aBottomItemIndex);
1.957 +
1.958 +protected:
1.959 +
1.960 + /**
1.961 + * The flags for this list box. These flags are defined by the nested enum
1.962 + * @c TFlags (below).
1.963 + */
1.964 + TInt iFlags;
1.965 +
1.966 + /**
1.967 + * This view’s item drawer.
1.968 + * Not owned.
1.969 + */
1.970 + CListItemDrawer* iItemDrawer;
1.971 +
1.972 + /**
1.973 + * This view’s model.
1.974 + * Not owned.
1.975 + */
1.976 + MListBoxModel* iModel;
1.977 +
1.978 + /**
1.979 + * Width (in pixels) of the longest item in the model.
1.980 + */
1.981 + TInt iDataWidth;
1.982 +
1.983 + /**
1.984 + * Index of the item at the top of the view. This is not necessarily the
1.985 + * item at the start of the list.
1.986 + */
1.987 + TInt iTopItemIndex;
1.988 +
1.989 + /**
1.990 + * Index of the item at the bottom of the view. This is not necessarily the
1.991 + * item at the end of the list.
1.992 + */
1.993 + TInt iBottomItemIndex;
1.994 +
1.995 + /**
1.996 + * Pixel offset of the visible portion of the data from the left margin.
1.997 + */
1.998 + TInt iHScrollOffset;
1.999 +
1.1000 + /**
1.1001 + * Index of the current item.
1.1002 + */
1.1003 + TInt iCurrentItemIndex;
1.1004 +
1.1005 + /**
1.1006 + * Height of each item in the list in pixels.
1.1007 + */
1.1008 + TInt iItemHeight;
1.1009 +
1.1010 + /**
1.1011 + * This list box view’s window.
1.1012 + */
1.1013 + RWindow* iWin;
1.1014 +
1.1015 + /**
1.1016 + * The window group of this view.
1.1017 + */
1.1018 + RWindowGroup* iGroupWin;
1.1019 +
1.1020 + /**
1.1021 + * Graphics context for the control.
1.1022 + */
1.1023 + CWindowGc* iGc;
1.1024 +
1.1025 + /**
1.1026 + * Graphics context for the control.
1.1027 + */
1.1028 + TRect iViewRect;
1.1029 +
1.1030 + /**
1.1031 + * The empty list text.
1.1032 + */
1.1033 + HBufC *iListEmptyText;
1.1034 +
1.1035 + /**
1.1036 + * Indicates whether vertical line drawing is disabled.
1.1037 + */
1.1038 + TBool iDisableVerticalLineDrawing /*TInt iSpare*/;
1.1039 +
1.1040 +private:
1.1041 + TInt iMatcherCursorPos;
1.1042 + TRgb iMatcherCursorColor;
1.1043 + TRgb iBackColor;
1.1044 + TRgb iTextColor;
1.1045 + TInt iAnchorIndex;
1.1046 + TInt iActiveEndIndex;
1.1047 + CSelectionIndexArray* iSelectionIndexes;
1.1048 + MListVisibilityObserver* iVisibilityObserver;
1.1049 +protected:
1.1050 + /**
1.1051 + * Current vertical offset of the view in pixels.
1.1052 + */
1.1053 + TInt iVerticalOffset;
1.1054 +
1.1055 + CListBoxViewExtension* iExtension;
1.1056 + TInt iSpare[4];
1.1057 + };
1.1058 +
1.1059 +NONSHARABLE_CLASS( CListBoxViewExtension ) : public CBase
1.1060 + {
1.1061 + public:
1.1062 + static CListBoxViewExtension* NewL();
1.1063 +
1.1064 + ~CListBoxViewExtension();
1.1065 +
1.1066 + private:
1.1067 + void ConstructL();
1.1068 +
1.1069 + public:
1.1070 + CEikListBox* iListBox;
1.1071 + TBool iScrolling;
1.1072 + TBool iScrollingDisabled;
1.1073 + };
1.1074 +
1.1075 +
1.1076 +/**
1.1077 + * Return text currently in the empty list text
1.1078 + */
1.1079 +inline const TDesC* CListBoxView::EmptyListText() const
1.1080 + { return(iListEmptyText); }
1.1081 +
1.1082 +
1.1083 +class CSnakingListBoxView : public CListBoxView
1.1084 + {
1.1085 +public:
1.1086 + IMPORT_C ~CSnakingListBoxView();
1.1087 + IMPORT_C CSnakingListBoxView();
1.1088 + inline TInt ColumnWidth() const;
1.1089 + IMPORT_C void SetColumnWidth(TInt aColumnWidth);
1.1090 + IMPORT_C virtual void MoveCursorL(TCursorMovement aCursorMovement, TSelectionMode aSelectionMode);
1.1091 + IMPORT_C virtual void SetTopItemIndex(TInt aItemIndex);
1.1092 + IMPORT_C virtual void SetItemHeight(TInt aItemHeight);
1.1093 + IMPORT_C virtual TBool XYPosToItemIndex(TPoint aPosition, TInt& aItemIndex) const;
1.1094 + IMPORT_C virtual TInt NumberOfItemsThatFitInRect(const TRect& aRect) const;
1.1095 + IMPORT_C virtual void HScroll(TInt aHScrollAmount);
1.1096 + IMPORT_C virtual void CalcDataWidth();
1.1097 + IMPORT_C virtual void CalcBottomItemIndex();
1.1098 + IMPORT_C virtual void Draw(const TRect* aClipRect = NULL) const;
1.1099 + IMPORT_C virtual TInt VisibleWidth(const TRect& aRect) const;
1.1100 + IMPORT_C virtual TBool ScrollToMakeItemVisible(TInt aItemIndex);
1.1101 + IMPORT_C virtual TInt CalculateHScrollOffsetSoItemIsVisible(TInt aItemIndex);
1.1102 + IMPORT_C virtual TInt CalcNewTopItemIndexSoItemIsVisible(TInt aItemIndex) const;
1.1103 + IMPORT_C virtual TPoint ItemPos(TInt aItemIndex) const;
1.1104 + IMPORT_C virtual TSize ItemSize(TInt aItemIndex=0) const;
1.1105 + IMPORT_C void CalcRowAndColIndexesFromItemIndex(TInt aItemIndex, TInt& aRowIndex, TInt& aColIndex) const;
1.1106 + IMPORT_C void CalcItemIndexFromRowAndColIndexes(TInt& aItemIndex, TInt aRowIndex, TInt aColIndex) const;
1.1107 + IMPORT_C virtual TInt NumberOfItemsPerColumn() const;
1.1108 +protected:
1.1109 + IMPORT_C virtual void DrawItemRange(TInt aStartItemIndex, TInt aEndItemIndex) const;
1.1110 + IMPORT_C void DrawColumnRange(TInt aStartColIndex, TInt aEndColIndex) const;
1.1111 + IMPORT_C void MoveToPreviousColumnL(TSelectionMode aSelectionMode);
1.1112 + IMPORT_C void MoveToNextColumnL(TSelectionMode aSelectionMode);
1.1113 + IMPORT_C void ClearUnusedItemSpace(TInt aStartItemIndex, TInt aEndItemIndex) const;
1.1114 + IMPORT_C void UpdateHScrollOffsetBasedOnTopItemIndex();
1.1115 +private: // overridden from CListBoxView
1.1116 + IMPORT_C virtual TAny* Reserved_1();
1.1117 +protected:
1.1118 + TInt iColumnWidth;
1.1119 + };
1.1120 +
1.1121 +
1.1122 +
1.1123 +inline TInt CListBoxView::Flags() const
1.1124 + { return iFlags; }
1.1125 +
1.1126 +inline void CListBoxView::SetFlags(TInt aMask)
1.1127 + { iFlags|=aMask; }
1.1128 +
1.1129 +inline void CListBoxView::ClearFlags(TInt aMask)
1.1130 + { iFlags&=(~aMask); }
1.1131 +
1.1132 +inline CListItemDrawer* CListBoxView::ItemDrawer() const
1.1133 + { return iItemDrawer; }
1.1134 +
1.1135 +inline TInt CSnakingListBoxView::ColumnWidth() const
1.1136 + { return iColumnWidth; }
1.1137 +
1.1138 +
1.1139 +#endif // __EIKLBV_H__