1.1 --- a/epoc32/include/mw/eiklbx.h Tue Nov 24 13:55:44 2009 +0000
1.2 +++ b/epoc32/include/mw/eiklbx.h Tue Mar 16 16:12:26 2010 +0000
1.3 @@ -1,1 +1,1809 @@
1.4 -eiklbx.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: Base class for an on-screen list box control from
1.19 +* which one or more items can be selected.
1.20 +*
1.21 +*/
1.22 +
1.23 +#ifndef __EIKLBX_H__
1.24 +#define __EIKLBX_H__
1.25 +
1.26 +// INCLUDES
1.27 +#include <gdi.h>
1.28 +#include <eikbctrl.h>
1.29 +#include <eiklbo.h>
1.30 +#include <eiksbfrm.h>
1.31 +#include <eiklbm.h>
1.32 +#include <eiklbv.h>
1.33 +#include <gulbordr.h>
1.34 +#include <eiklbed.h>
1.35 +#include <gulutil.h>
1.36 +#include <lafpublc.h>
1.37 +
1.38 +// FORWARD DECLARATIONS
1.39 +enum TKeyCode;
1.40 +class RIncrMatcherBase;
1.41 +class CListItemDrawer;
1.42 +class CEikScrollBarFrame;
1.43 +class CEikButtonBase;
1.44 +class CMatchBuffer;
1.45 +class CListBoxExt;
1.46 +class CEikListBox;
1.47 +
1.48 +// CLASS DECLARATION
1.49 +
1.50 +/**
1.51 +* Item change observer will be notified when list box items have been added or
1.52 +* removed or the list box has been reset. Observers can be added and removed by
1.53 +* using @c CEikListBox methods @c AddItemChangeObserverL() and
1.54 +* @c RemoveItemChangeObserver().
1.55 +*
1.56 +* @since 3.0
1.57 +*/
1.58 +class MListBoxItemChangeObserver
1.59 + {
1.60 + public:
1.61 + /**
1.62 + * Notification and handling of a list box item change.
1.63 + *
1.64 + * @param aListBox The source list box of this message.
1.65 + */
1.66 + virtual void ListBoxItemsChanged(CEikListBox* aListBox) = 0;
1.67 + };
1.68 +
1.69 +
1.70 +/**
1.71 +* Item selection (marking) observer is used to let application control item marking
1.72 +* (in markable lists). Observers can be added and removed by using
1.73 +* @c CEikListBox methods @c AddSelectionObserverL() and
1.74 +* @c RemoveSelectionObserver().
1.75 +*
1.76 +* @since 3.2
1.77 +*/
1.78 +class MListBoxSelectionObserver
1.79 + {
1.80 + public:
1.81 + /**
1.82 + * Notification of entering and leaving marking mode. Marking mode
1.83 + * is enabled by long pressing shift, ctrl or hash keys (when hash key marking is enabled).
1.84 + *
1.85 + * @param aListBox The source list box of this message.
1.86 + * @param aSelectionModeEnabled ETrue, when entering selection (marking) mode.
1.87 + */
1.88 + virtual void SelectionModeChanged(CEikListBox* aListBox, TBool aSelectionModeEnabled) = 0;
1.89 + };
1.90 +
1.91 +
1.92 +// CLASS DECLARATION
1.93 +
1.94 +/**
1.95 + * Base class for an on-screen list box control from which one or more items
1.96 + * can be selected.
1.97 + *
1.98 + * @c CEikListBox implements the basics of a list box. It has a scroll bar
1.99 + * frame, an item drawer, and a model, and reports events to a list box
1.100 + * observer.
1.101 + *
1.102 + * List boxes display a number of items within a scrolling frame; the items
1.103 + * in a list box which are visible at one time are represented by a list
1.104 + * box view.
1.105 + *
1.106 + * Writing derived classes:
1.107 + *
1.108 + * This class may be derived from to provide specialisations of the basic
1.109 + * list box behaviour. It is usual when subclassing CEikListBox to also
1.110 + * provide specialisations of CListItemDrawer and CListBoxView for
1.111 + * representing the data of such a list box effectively
1.112 + */
1.113 +class CEikListBox : public CEikBorderedControl, public MEikScrollBarObserver
1.114 + {
1.115 +
1.116 +public:
1.117 +
1.118 + friend class CListBoxExt;
1.119 +
1.120 +public:
1.121 +
1.122 + /**
1.123 + * Construction flags.
1.124 + */
1.125 + enum TFlags
1.126 + {
1.127 +
1.128 + /**
1.129 + * Construction flag for a list box from which the user can
1.130 + * select multiple items.
1.131 + */
1.132 + EMultipleSelection = SLafListBox::EMultipleSelection,
1.133 +
1.134 + /**
1.135 + * Construction flag for disabling extended selection.
1.136 + * If this is set the user cannot select multiple items by
1.137 + * using @c SHIFT button.
1.138 + */
1.139 + ENoExtendedSelection = SLafListBox::ENoExtendedSelection,
1.140 +
1.141 + /**
1.142 + * Construction flag that sets the list box to match user’s keystrokes
1.143 + * incrementally.
1.144 + */
1.145 + EIncrementalMatching = SLafListBox::EIncrementalMatching,
1.146 +
1.147 + /**
1.148 + * Construction flag for setting the list box as a pop-out list box.
1.149 + * Pop-out list boxes handle certain keystrokes and events differently.
1.150 + */
1.151 + EPopout = SLafListBox::EPopout,
1.152 +
1.153 + /**
1.154 + * Construction flag that enables the indication of pointer press
1.155 + * inside the view of the list box.
1.156 + */
1.157 + ELeftDownInViewRect = SLafListBox::ELeftDownInViewRect,
1.158 +
1.159 + /**
1.160 + * Construction flag for enabling @c CEiklist box item double click
1.161 + * indication.
1.162 + */
1.163 + EItemDoubleClicked = SLafListBox::EItemDoubleClicked,
1.164 +
1.165 + /**
1.166 + * Construction flag for removing the ownership of the supplied list box
1.167 + * model from the @c CEikListBox so that the list box model will not be
1.168 + * deleted with the @c CEikListBoxes destruction.
1.169 + */
1.170 + EKeepModel = SLafListBox::EKeepModel,
1.171 +
1.172 + /**
1.173 + * Construction flag for excluding the scroll bar.
1.174 + * If the flag is set the scroll bas is drawn ouside the window that
1.175 + * describes the scroll bars extent.
1.176 + */
1.177 + EScrollBarSizeExcluded = SLafListBox::EScrollBarSizeExcluded,
1.178 +
1.179 + /**
1.180 + * Construction flag for enabling @c CEikListBox change indication.
1.181 + */
1.182 + EStateChanged = SLafListBox::EStateChanged,
1.183 +
1.184 + /**
1.185 + * Construction flag that indicates that the list box should be created
1.186 + * to its own window.
1.187 + */
1.188 + ECreateOwnWindow = SLafListBox::ECreateOwnWindow,
1.189 +
1.190 + /**
1.191 + * Construction flag for disabling key matching.
1.192 + */
1.193 + ENoFirstLetterMatching = SLafListBox::ENoFirstLetterMatching,
1.194 +
1.195 + /**
1.196 + * Construction flag for enabling painting of selected items.
1.197 + */
1.198 + EPaintedSelection = SLafListBox::EPaintedSelection ,
1.199 +
1.200 + /**
1.201 + * Construction flag for enabling loop scrolling in which the list box
1.202 + * jumps from the last item to the first item.
1.203 + */
1.204 + ELoopScrolling = 0x1000,
1.205 +
1.206 + /**
1.207 + * Construction flag for enabling @c Avkon multiselection list.
1.208 + */
1.209 + EEnterMarks = 0x2000, // Avkon multiselection list
1.210 +
1.211 + /**
1.212 + * Construction flag for enabling Avkon markable list which enables the
1.213 + * marking of several items from the list.
1.214 + */
1.215 + EShiftEnterMarks = 0x4000, // Avkon markable list
1.216 +
1.217 + /**
1.218 + * Construction flag that combines @c EPageAtOnceScrolling and
1.219 + * @c EDisableHighlight flags
1.220 + */
1.221 + EViewerFlag = 0x8000, // combined the two flags to fit to WORD.
1.222 +
1.223 + /**
1.224 + * Construction flag for enabling scrolling at a page per time so that
1.225 + * the whole list box page is scrolled to the next.
1.226 + */
1.227 + EPageAtOnceScrolling = 0x8000, // Avkon viewers
1.228 +
1.229 + /**
1.230 + * Construction flag for disabling the highlighting of the selected item.
1.231 + */
1.232 + EDisableHighlight = 0x8000, // Avkon viewers
1.233 +
1.234 + /**
1.235 + * Construction flag for enabling S60 style selection of multiple items
1.236 + * from the list box.
1.237 + */
1.238 + ES60StyleMultiselection = SLafListBox::ES60StyleMultiselection,
1.239 +
1.240 + /**
1.241 + * Construction flag for enabling S60 style markable items.
1.242 + */
1.243 + ES60StyleMarkable = SLafListBox::ES60StyleMarkable
1.244 + };
1.245 + enum {KEikMaxMatchingBufferLength = 2};
1.246 +
1.247 + /**
1.248 + * Indicates who owns the scroll bar.
1.249 + */
1.250 + enum TScrollBarOwnerShip
1.251 + {
1.252 + /**
1.253 + * Indicates that the scrollbar is not owned by an external class.
1.254 + */
1.255 + ENotOwnedExternally=0x0000,
1.256 + /**
1.257 + * Indicates that the scrollbar is owned by an external class.
1.258 + */
1.259 + EOwnedExternally =0x0001
1.260 + };
1.261 +
1.262 +protected:
1.263 +
1.264 + /**
1.265 + * Used for indicating the reason why the item lost focus.
1.266 + */
1.267 + enum TReasonForFocusLost
1.268 + {
1.269 + /**
1.270 + * Focus has been lost from the list box to an external control.
1.271 + */
1.272 + EFocusLostToExternalControl,
1.273 + /**
1.274 + * Focus has been moved from the list box to an internal editor.
1.275 + */
1.276 + EFocusLostToInternalEditor
1.277 + };
1.278 +
1.279 +public:
1.280 + /**
1.281 + * Destructor.
1.282 + */
1.283 + IMPORT_C ~CEikListBox();
1.284 +
1.285 + /**
1.286 + * C++ default constructor.
1.287 + */
1.288 + IMPORT_C CEikListBox();
1.289 + /**
1.290 + * Handles 2nd phase construction.
1.291 + *
1.292 + * Sets list box model and list item drawer. Request another @c ConstructL
1.293 + * to handle @c aParent and @c aFlags.
1.294 + *
1.295 + * @param aListBoxModel List box model that is to be used with the list box.
1.296 + * @param aListItemDrawer List item drawer that is to be used with the
1.297 + * list box.
1.298 + * @param aParent Host @c CoeControl for the list box.
1.299 + * @param aFlags Construction flags (@c TFlags) for the list box.
1.300 + */
1.301 + IMPORT_C void ConstructL(MListBoxModel* aListBoxModel,
1.302 + CListItemDrawer* aListItemDrawer,
1.303 + const CCoeControl* aParent,
1.304 + TInt aFlags = 0);
1.305 +
1.306 + /**
1.307 + * Handles 2nd phase construction.
1.308 + *
1.309 + *
1.310 + * Sets the border that is to be drawn outside the list box. Request another
1.311 + * @c ConstructL to handle list box model, list item drawer, @c aParent
1.312 + * and @c aFlags.
1.313 + *
1.314 + * @param aListBoxModel List box model that is to be used with the list box.
1.315 + * @param aListItemDrawer List item drawer that is to be used with the
1.316 + * list box.
1.317 + * @param aParent Host @c CoeControl for the list box.
1.318 + * @param aBorder Border to be drawn outside the list box.
1.319 + * @param aFlags Construction flags (@c TFlags) for the list box.
1.320 + */
1.321 + IMPORT_C void ConstructL(MListBoxModel* aListBoxModel,
1.322 + CListItemDrawer* aListItemDrawer,
1.323 + const CCoeControl* aParent,
1.324 + TGulBorder aBorder,
1.325 + TInt aFlags = 0);
1.326 + /**
1.327 + * Informs the @c CEikListbox of a key press.
1.328 + *
1.329 + * @param aKeyEvent Details of the key event that is being handled.
1.330 + * @param aType Defines what kind of key event is being handled e.g.
1.331 + * @c EEventKeyUp.
1.332 + * @return @c EKeyWasConsumed if the key was handled by the method.
1.333 + * @c EKeyWasNotConsumed if the key was not handled.
1.334 + */
1.335 + IMPORT_C virtual TKeyResponse OfferKeyEventL(const TKeyEvent& aKeyEvent,
1.336 + TEventCode aType);
1.337 +
1.338 + /**
1.339 + * Handling of pointer event within the @c CEikListBox.
1.340 + * Used for e.g. selecting an item from the list box.
1.341 + *
1.342 + * @param aPointerEvent Details of the pointer event that is being handled.
1.343 + */
1.344 + IMPORT_C virtual void HandlePointerEventL(
1.345 + const TPointerEvent& aPointerEvent);
1.346 +
1.347 + /**
1.348 + * Creates an own window for the list box or draws the list box to an old
1.349 + * window defined by the @c aContainer.
1.350 + *
1.351 + * @param aContainer Defines the container where the list box will be drawn.
1.352 + */
1.353 + IMPORT_C virtual void SetContainerWindowL(const CCoeControl& aContainer);
1.354 +
1.355 + /**
1.356 + * Checks the minimum size needed for the list box.
1.357 + *
1.358 + * @return The two dimensional minimum size for the list box.
1.359 + */
1.360 + IMPORT_C virtual TSize MinimumSize();
1.361 +
1.362 + /**
1.363 + * This function sets a flag within the control which indicates
1.364 + * whether or not the control is dimmed (greyed out).
1.365 + *
1.366 + * @param aDimmed @c ETrue dimmed. @c EFalse not dimmed.
1.367 + */
1.368 + IMPORT_C virtual void SetDimmed(TBool aDimmed);
1.369 +
1.370 + /**
1.371 + * Used for scrolling through the items in the list box.
1.372 + *
1.373 + * @param aScrollBar Scroll bar for the list box.
1.374 + * @param aEventType Type of the event that occured.
1.375 + */
1.376 + IMPORT_C virtual void HandleScrollEventL(CEikScrollBar* aScrollBar,
1.377 + TEikScrollEvent aEventType);
1.378 +
1.379 + // model/view access functions
1.380 + /**
1.381 + * Gets the list box data model.
1.382 + *
1.383 + * @return Interface to the list box data model.
1.384 + */
1.385 + IMPORT_C MListBoxModel* Model() const;
1.386 +
1.387 + /**
1.388 + * Gets the list box view.
1.389 + *
1.390 + * @return Interface to the list box view.
1.391 + */
1.392 + IMPORT_C CListBoxView* View() const;
1.393 +
1.394 + // functions for accessing top/current/bottom item index
1.395 + /**
1.396 + * Gets the index number of the top item.
1.397 + *
1.398 + * @return Index number for the top item.
1.399 + */
1.400 + IMPORT_C TInt TopItemIndex() const;
1.401 +
1.402 + /**
1.403 + * Sets the selected item to be the top item.
1.404 + *
1.405 + * @param aItemIndex Index for the item to be set as the top item.
1.406 + */
1.407 + IMPORT_C virtual void SetTopItemIndex(TInt aItemIndex) const;
1.408 +
1.409 + /**
1.410 + * Gets for the bottom items index.
1.411 + *
1.412 + * @return Index for the bottom item.
1.413 + */
1.414 + IMPORT_C TInt BottomItemIndex() const;
1.415 +
1.416 + /**
1.417 + * Gets the index number of the selected item.
1.418 + *
1.419 + * @return Index of the selected item.
1.420 + */
1.421 + IMPORT_C TInt CurrentItemIndex() const;
1.422 +
1.423 + /**
1.424 + * Changes the current item index to the selected item index. Does not
1.425 + * redraw the list. If the item was not previously visible it is set to the
1.426 + * top item in the view.
1.427 + *
1.428 + * @param aItemIndex Defines the index of the selected item.
1.429 + */
1.430 + IMPORT_C void SetCurrentItemIndex(TInt aItemIndex) const;
1.431 +
1.432 + /**
1.433 + * Changes the current item index to the selected item index and
1.434 + * redraws the view.
1.435 + *
1.436 + * @param aItemIndex Defines the index of the selected item.
1.437 + */
1.438 + IMPORT_C void SetCurrentItemIndexAndDraw(TInt aItemIndex) const;
1.439 +
1.440 + // functions for dealing with the selection state
1.441 + /**
1.442 + * Gets for list boxes selection indexes.
1.443 + *
1.444 + * @return Pointer to the list boxes in array of selection indexes.
1.445 + */
1.446 + IMPORT_C const CListBoxView::CSelectionIndexArray* SelectionIndexes() const;
1.447 +
1.448 + /**
1.449 + * Assigns a array of selection indexes for the list box.
1.450 + *
1.451 + * @param aArrayOfSelectionIndexes The index array that is to be assigned
1.452 + * to the list Box.
1.453 + */
1.454 + IMPORT_C void SetSelectionIndexesL(
1.455 + CListBoxView::CSelectionIndexArray* aArrayOfSelectionIndexes);
1.456 +
1.457 + /**
1.458 + * Clears the selection from the view.
1.459 + */
1.460 + IMPORT_C void ClearSelection();
1.461 +
1.462 + // Functions for updating a list box's internal state after its model has
1.463 + // been updated, all of them will emit item change event to item change
1.464 + // observers.
1.465 + /**
1.466 + * Handles the addition of item to the list box.
1.467 + */
1.468 + IMPORT_C void HandleItemAdditionL();
1.469 +
1.470 + /**
1.471 + * Handles the removal of an item from the list box.
1.472 + */
1.473 + IMPORT_C void HandleItemRemovalL();
1.474 +
1.475 + /**
1.476 + * Handles the addition of new items to the list box and updates
1.477 + * selection indexes array.
1.478 + *
1.479 + * NOTE. This algorithm can not handle position of the list highlight
1.480 + * nor can it update the top item index correctly.
1.481 + *
1.482 + * @param aArrayOfNewIndexesAfterAddition Array of new indexes to be added.
1.483 + */
1.484 + IMPORT_C void HandleItemAdditionL(
1.485 + CArrayFix<TInt> &aArrayOfNewIndexesAfterAddition);
1.486 +
1.487 + /**
1.488 + * Handles the removal of items to the list box and updates
1.489 + * selection indexes array.
1.490 + *
1.491 + * NOTE. This algorithm cannot handle position of the list highlight
1.492 + * nor can it update the top item index correctly.
1.493 + *
1.494 + * @param aArrayOfOldIndexesBeforeRemoval Array of indexes to be removed.
1.495 + */
1.496 + IMPORT_C void HandleItemRemovalL(
1.497 + CArrayFix<TInt> &aArrayOfOldIndexesBeforeRemoval);
1.498 +
1.499 + /**
1.500 + * Deletes the item editor
1.501 + */
1.502 + IMPORT_C void Reset();
1.503 +
1.504 + /**
1.505 + * Adds an item change observer to the listbox. Duplicates are not checked
1.506 + * (i.e. adding the same observer multiple times is not prevented).
1.507 + *
1.508 + * @since 3.0
1.509 + * @param aObserver Must be non-NULL.
1.510 + */
1.511 + IMPORT_C void AddItemChangeObserverL( MListBoxItemChangeObserver* aObserver );
1.512 + /**
1.513 + * Removes an item change observer from the listbox.
1.514 + *
1.515 + * @since 3.0
1.516 + * @param aObserver The observer to be removed.
1.517 + * @return ETrue if removal ok, EFalse if observer was not removed (not
1.518 + * found from the list of observers).
1.519 + */
1.520 + IMPORT_C TBool RemoveItemChangeObserver( MListBoxItemChangeObserver* aObserver );
1.521 +
1.522 + // functions for accessing the item height
1.523 + /**
1.524 + * Sets the height of the item to the selected value.
1.525 + *
1.526 + * @param aHeight New height for the item.
1.527 + */
1.528 + IMPORT_C virtual void SetItemHeightL(TInt aHeight);
1.529 +
1.530 + /**
1.531 + * Gets height of the item.
1.532 + *
1.533 + * @return Height of the item.
1.534 + */
1.535 + IMPORT_C TInt ItemHeight() const;
1.536 +
1.537 + // functions for scrollbars
1.538 + /**
1.539 + * Creates a scrollbar frame.
1.540 + *
1.541 + * @param aPreAlloc Boolean defining if there should be initial
1.542 + * memory allocations.
1.543 + * @return The new scroll bar frame.
1.544 + */
1.545 + IMPORT_C CEikScrollBarFrame* CreateScrollBarFrameL(TBool aPreAlloc=EFalse);
1.546 +
1.547 + /**
1.548 + * Sets the given scroll bar frame for the list box with the given
1.549 + * ownership leve.
1.550 + *
1.551 + * @param aScrollBarFrame The new frame that is going to be used.
1.552 + * @param aOwnerShip Ownership level of the scroll bar frame.
1.553 + */
1.554 + IMPORT_C void SetScrollBarFrame(CEikScrollBarFrame* aScrollBarFrame, TScrollBarOwnerShip aOwnerShip);
1.555 +
1.556 + /**
1.557 + * Gets pointer for the scroll bar frame.
1.558 + *
1.559 + * @return Pointer to the scroll bar frame.
1.560 + */
1.561 + IMPORT_C CEikScrollBarFrame* const ScrollBarFrame();
1.562 +
1.563 + /**
1.564 + * Updates all scroll bars.
1.565 + */
1.566 + IMPORT_C virtual void UpdateScrollBarsL();
1.567 +
1.568 + // construction support functions
1.569 + /**
1.570 + * Gets the size of the rectangle required to display a pop out.
1.571 + *
1.572 + * @param aTargetItemIndex The item from which the popout originates.
1.573 + * @param aTargetYPos Vertical position of the item from which the popout
1.574 + * originates.
1.575 + * @param aListBoxRect The list box rectangle.
1.576 + * @param aMinHeightInNumOfItems The minimum number of items for the popout.
1.577 + */
1.578 + IMPORT_C void CalculatePopoutRect( TInt aTargetItemIndex,
1.579 + TInt aTargetYPos,
1.580 + TRect& aListBoxRect,
1.581 + TInt aMinHeightInNumOfItems = 1 );
1.582 + /**
1.583 + * Gets the size of the list box in pixels based on the height of
1.584 + * the list box in items and the length of the items in characters.
1.585 + *
1.586 + * Returns @c TSize element consisting of two elements, the height
1.587 + * and the width. Height is the number of items times the height
1.588 + * of the font in pixels. Width is the number of characters in a
1.589 + * single line times the width of the font in pixels.
1.590 + *
1.591 + * @param aWidthAsNumOfChars Width of list box in characters.
1.592 + * @param aHeightAsNumOfItems Height of list box in characters.
1.593 + * @return The size of the list box in pixels as TSize.
1.594 + */
1.595 + IMPORT_C TSize CalcSizeInPixels(TInt aWidthAsNumOfChars,
1.596 + TInt aHeightAsNumOfItems) const;
1.597 +
1.598 + /**
1.599 + * Gets the width of the list box in pixels based on the width of the list
1.600 + * box in characters.
1.601 + *
1.602 + * Returns the number of characters times the width of a character
1.603 + * in pixels.
1.604 + *
1.605 + * @param aNumOfChars The number of characters.
1.606 + * @return The width of the list box in pixels.
1.607 + */
1.608 + IMPORT_C TInt CalcWidthBasedOnNumOfChars(TInt aNumOfChars) const;
1.609 +
1.610 + /**
1.611 + * Gets the height of the list box in pixels based on the width of the
1.612 + * list box in characters.
1.613 + *
1.614 + * Returns the number of items times the height of the font in pixels.
1.615 + *
1.616 + * @param aNumOfItems The number of items.
1.617 + * @return The height of the list box in pixels.
1.618 + */
1.619 + IMPORT_C TInt CalcHeightBasedOnNumOfItems(TInt aNumOfItems) const;
1.620 +
1.621 + /**
1.622 + * Gets the width of the list box in pixels based on the width of the
1.623 + * list box text in pixels.
1.624 + *
1.625 + * returns the width of the whole list box in pixels, which includes
1.626 + * the text width and the width of elements in the list box that have
1.627 + * an effect on the overall width.
1.628 + *
1.629 + * @param aTextWidthInPixels Width of list box text in pixels.
1.630 + * @return Required width of whole list box in pixels.
1.631 + */
1.632 + IMPORT_C TInt CalcWidthBasedOnRequiredItemWidth(
1.633 + TInt aTextWidthInPixels) const;
1.634 +
1.635 + // drawing/scrolling functions
1.636 + /**
1.637 + * Draws a list box item, first scrolling the list to make it visible
1.638 + * if it is not already.
1.639 + *
1.640 + * @c DrawItem() panics if there is no list box view currently set.
1.641 + * @param aItemIndex Index of the item to reveal.
1.642 + */
1.643 + IMPORT_C void DrawItem(TInt aItemIndex) const;
1.644 +
1.645 + /**
1.646 + * Makes an item visible in the list, scrolling it if necessary.
1.647 + *
1.648 + * @param aItemIndex Index of the item to reveal.
1.649 + */
1.650 + IMPORT_C void ScrollToMakeItemVisible(TInt aItemIndex) const;
1.651 +
1.652 + /**
1.653 + * Redraws list item.
1.654 + * @param aItemIndex index of item to be redrawn.
1.655 + * @since 3.2
1.656 + */
1.657 + IMPORT_C void RedrawItem( TInt aItemIndex );
1.658 +
1.659 + // observer support
1.660 + /**
1.661 + * Sets the observer for the list box.
1.662 + *
1.663 + * @param aObserver Wanted observer for the list box.
1.664 + */
1.665 + IMPORT_C void SetListBoxObserver(MEikListBoxObserver* aObserver);
1.666 +
1.667 +
1.668 + /**
1.669 + * Gets the size of the vertical gap between items. This space is used
1.670 + * by the view to allow a box to be drawn around each item.
1.671 + *
1.672 + * @return Size of the vertical gap in pixels.
1.673 + */
1.674 + IMPORT_C TInt VerticalInterItemGap() const;
1.675 +
1.676 + // popouts only
1.677 + /**
1.678 + * Provides a call back mechanism to the button which just launched a
1.679 + * popout menu.
1.680 + *
1.681 + * @param aButton The button which just launched a popout menu.
1.682 + */
1.683 + IMPORT_C void SetLaunchingButton(CEikButtonBase* aButton);
1.684 +
1.685 + // Editing support
1.686 + /**
1.687 + * Selects an item editor for the list box.
1.688 + *
1.689 + * @param aEditor The editor that has been selected for usage.
1.690 + */
1.691 + IMPORT_C void SetItemEditor(MEikListBoxEditor* aEditor);
1.692 +
1.693 + /**
1.694 + * Resets the list boxes item editor.
1.695 + */
1.696 + IMPORT_C void ResetItemEditor();
1.697 + /**
1.698 + * Gets item editor for the current class.
1.699 + *
1.700 + * @return The item editor used by the list box class.
1.701 + */
1.702 + IMPORT_C MEikListBoxEditor* ItemEditor();
1.703 +
1.704 + /**
1.705 + * Creates an item editor and starts editing the current item.
1.706 + *
1.707 + * The editor can edit the current item up to a maximum length of
1.708 + * @c aMaxLength characters. Also reports an @c EEventEditingStarted event
1.709 + * to any list box observer by default.
1.710 + *
1.711 + * The function only creates a new editor if one does not already exist.
1.712 + *
1.713 + * @param aMaxLength Maximum length of characters to edit.
1.714 + */
1.715 + IMPORT_C virtual void EditItemL(TInt aMaxLength);
1.716 +
1.717 + /**
1.718 + * Stops editing and deletes the item editor.
1.719 + *
1.720 + * The function reports an @c EEventEditingStopped event to any list box
1.721 + * observer, and updates the list box model if @c aUpdateModel is @c ETrue.
1.722 + *
1.723 + * @param aUpdateModel If @c ETrue the list box model is updated.
1.724 + */
1.725 + IMPORT_C void StopEditingL(TBool aUpdateModel);
1.726 +
1.727 + // functions needed for Avkon shortcuts,
1.728 + // passing information from one list to another
1.729 +
1.730 + /**
1.731 + * No Implementation.
1.732 + *
1.733 + * @return Always returns 0.
1.734 + */
1.735 + IMPORT_C virtual TInt ShortcutValueForNextList();
1.736 +
1.737 + /**
1.738 + * No Implementation.
1.739 + *
1.740 + * @param aValue Not Used.
1.741 + */
1.742 + IMPORT_C virtual void SetShortcutValueFromPrevList(TInt aValue);
1.743 +
1.744 + // pop-up positioning support
1.745 + /**
1.746 + * Gets the position and the size of the list box.
1.747 + *
1.748 + * @return A rectangle with the correct position data as
1.749 + * well as size data for the list box.
1.750 + */
1.751 + IMPORT_C TRect HighlightRect() const;
1.752 +
1.753 + /**
1.754 + * Checks whether background drawing is suppressed on item level i.e. each
1.755 + * list item doesn't draw its background.
1.756 + *
1.757 + * @since S60 5.0
1.758 + * @return ETrue if background drawing is suppressed.
1.759 + */
1.760 + IMPORT_C TBool BackgroundDrawingSuppressed() const;
1.761 +
1.762 +public: // from CCoeControl
1.763 +
1.764 + /**
1.765 + * From @c CCoeControl
1.766 + *
1.767 + * Gets the list of logical colours employed in the drawing of the control,
1.768 + * paired with an explanation of how they are used. Appends the list to
1.769 + * @c aColorUseList.
1.770 + *
1.771 + * @param aColorUseList List of logical colours.
1.772 + */
1.773 + IMPORT_C virtual void GetColorUseListL(
1.774 + CArrayFix<TCoeColorUse>& aColorUseList) const;
1.775 + // not available before Release 005u
1.776 +
1.777 + /**
1.778 + * From @c CCoeControl
1.779 + *
1.780 + * Handles a change to the list box’s resources of type @c aType which are
1.781 + * shared across the environment, colours or fonts for example.
1.782 + *
1.783 + * @param aType The type of resources that have changed.
1.784 + */
1.785 + IMPORT_C virtual void HandleResourceChange(TInt aType);
1.786 + // not available before Release 005u
1.787 +
1.788 + /**
1.789 + * From @c CCoeControl
1.790 + *
1.791 + * Sets the control as ready to be drawn.
1.792 + *
1.793 + * The application should call this function on all controls that are not
1.794 + * components in a compound control.
1.795 + *
1.796 + * The purpose of this function is that controls are not always ready to
1.797 + * be drawn as soon as they have been constructed. For example, it may
1.798 + * not be possible to set the control's extent during construction, but
1.799 + * its extent should always be set before it is drawn. Similarly, if a
1.800 + * control is to be made invisible, this should be done before it is
1.801 + * activated.
1.802 + *
1.803 + * The default implementation sets a flag in the control to indicate it is
1.804 + * ready to be drawn. If the control is a compound control, the default
1.805 + * implementation also calls @c ActivateL() for all the control's components.
1.806 + * To get the control's components it uses @c CountComponentControls() and
1.807 + * @c ComponentControl(), which should be implemented by the compound control.
1.808 + *
1.809 + * @c ActivateL() is typically called from the control's @c ConstructL()
1.810 + * function.
1.811 + *
1.812 + * Notes:
1.813 + *
1.814 + * This function can be overridden. This is useful for doing late
1.815 + * initialisation of the control, using information that was not available
1.816 + * at the time the control was created. For example, a text editor might
1.817 + * override @c ActivateL() and use it to enquire whether it is focused: if
1.818 + * it is, it makes the cursor and any highlighting visible. At the time when
1.819 + * the editor is created, it doesn't know whether or not it has keyboard
1.820 + * focus.
1.821 + *
1.822 + * If overriding @c ActivateL(), the implementation must include a base
1.823 + * call to @c CCoeControl's @c ActivateL().
1.824 + */
1.825 + IMPORT_C virtual void ActivateL();
1.826 +
1.827 + /**
1.828 + * From @c CCoeControl.
1.829 + *
1.830 + * Gets the input capabilities of the control and all its components.
1.831 + *
1.832 + * @return The input capabilities of the control.
1.833 + */
1.834 + IMPORT_C TCoeInputCapabilities InputCapabilities() const;
1.835 +
1.836 +private:
1.837 + /**
1.838 + * From CAknControl
1.839 + */
1.840 + IMPORT_C void* ExtensionInterface( TUid aInterface );
1.841 +
1.842 +protected:
1.843 + // Shortcuts need access to Incremental matching
1.844 + // The shortcuts will be used inside OfferkeyEventL().
1.845 + friend class AknListBoxShortCutsImplementation;
1.846 + // Avkon layout uses SetVerticalMargin, which is protected.
1.847 + friend class AknListBoxLayouts;
1.848 +
1.849 + /**
1.850 + * Responds to a change in focus.
1.851 + *
1.852 + * This is called whenever the control gains or loses focus,
1.853 + * as a result of a call to @c SetFocus(). A typical use of
1.854 + * @c FocusChanged() is to change the appearance of the control,
1.855 + * for example by drawing a focus rectangle around it.
1.856 + *
1.857 + * The default implementation is empty, and should be
1.858 + * overridden by the @c CCoeControl-derived class.
1.859 + *
1.860 + * @param aDrawNow Contains the value that was passed to it
1.861 + * by @c SetFocus().
1.862 + */
1.863 + IMPORT_C virtual void FocusChanged(TDrawNow aDrawNow);
1.864 +
1.865 + /**
1.866 + * Responds to changes to the size and position of the contents
1.867 + * of this control.
1.868 + *
1.869 + * For a simple control this might include text or graphics.
1.870 + * For a compound control it sets the size and position of the
1.871 + * components. It has an empty default implementation and should
1.872 + * be implemented by the CCoeControl-derived class.
1.873 + *
1.874 + * The function is called whenever @c SetExtent(), @c SetSize(),
1.875 + * @c SetRect(), @c SetCornerAndSize(), or @c SetExtentToWholeScreen()
1.876 + * are called on the control. Note that the window server does not
1.877 + * generate size-changed events: @c SizeChanged() gets called only as
1.878 + * a result of calling the functions listed above. Therefore, if a
1.879 + * resize of one control affects the size of other controls, it is
1.880 + * up to the application to ensure that it handles the re-sizing
1.881 + * of all affected controls.
1.882 + */
1.883 + IMPORT_C virtual void SizeChanged();
1.884 +
1.885 + /**
1.886 + * Handles the change in case that the size of the view rectangle
1.887 + * for the list box changes.
1.888 + */
1.889 + IMPORT_C virtual void HandleViewRectSizeChangeL();
1.890 +
1.891 + /**
1.892 + * Gets the number of controls contained in a compound control.
1.893 + *
1.894 + * There are two ways to implement a compound control. One way is to
1.895 + * override this function. The other way is to use the @c CCoeControlArray
1.896 + * functionality (see the @c InitComponentArrayL method).
1.897 + *
1.898 + * @return The number of component controls contained by this control.
1.899 + */
1.900 + IMPORT_C virtual TInt CountComponentControls() const;
1.901 +
1.902 + /**
1.903 + * Gets an indexed component of a compound control.
1.904 + *
1.905 + * There are two ways to implement a compound control. One way is to
1.906 + * override this function. The other way is to use the @c CCoeControlArray
1.907 + * functionality (see the @c InitComponentArrayL method).
1.908 + *
1.909 + * Note: Within a compound control each component control is identified
1.910 + * by an index, where the index depends on the order the controls were
1.911 + * added: the first is given an index of 0, the next an index of 1, and
1.912 + * so on.
1.913 + *
1.914 + * @param aIndex The index of the control.
1.915 + * @return The component control with an index of aIndex.
1.916 + */
1.917 + IMPORT_C virtual CCoeControl* ComponentControl(TInt aIndex) const;
1.918 +
1.919 + // functions that implement first letter and incremental matching
1.920 + /**
1.921 + * Creates a buffer for checking how well two strings match up.
1.922 + */
1.923 + IMPORT_C void CreateMatchBufferL();
1.924 +
1.925 + /**
1.926 + * Empties the match buffer .
1.927 + */
1.928 + IMPORT_C void ClearMatchBuffer() const;
1.929 +
1.930 + /**
1.931 + * Checks matching for the given character.
1.932 + *
1.933 + * @param aCode Character code.
1.934 + */
1.935 + IMPORT_C void MatchTypedCharL(TUint aCode);
1.936 +
1.937 + /**
1.938 + * Undoes changes from the match buffer that have been caused
1.939 + * by the last match with a character.
1.940 + */
1.941 + IMPORT_C void UndoLastChar();
1.942 + /**
1.943 + * Checks if the last character matched with the string.
1.944 + *
1.945 + * @return @c ETrue if a match was found from the buffer with the character.
1.946 + */
1.947 + IMPORT_C TBool LastCharMatched() const;
1.948 +
1.949 + // functions needed for supporting scrollbars
1.950 + /**
1.951 + * Updates the position of this list box’s scroll bars’ thumbs to reflect
1.952 + * the horizontal and vertical position of the list view within the list.
1.953 + */
1.954 + IMPORT_C virtual void UpdateScrollBarThumbs() const;
1.955 +
1.956 + /**
1.957 + * Get horizontal scroll granularity in pixels.
1.958 + * The granularity is the minimum size of a horizontal move of the client
1.959 + * area.
1.960 + *
1.961 + * @return Grain size for horizontal scrolling in pixels.
1.962 + */
1.963 + IMPORT_C virtual TInt HorizScrollGranularityInPixels() const;
1.964 +
1.965 + /**
1.966 + * Gets the number of grains to move horizontally when a nudge button is
1.967 + * tapped.
1.968 + * For simple list boxes, this value is a fraction of the width of the
1.969 + * client area.
1.970 + *
1.971 + * @return Number of grains to move left or right on each nudge
1.972 + */
1.973 + IMPORT_C virtual TInt HorizontalNudgeValue() const;
1.974 +
1.975 + /**
1.976 + * Called by various functions of this class to ensure that the top
1.977 + * item index is always a sane value. The implementation in @c CEikListBox
1.978 + * tries to ensure the minimum amount of white space at the bottom of
1.979 + * the list box. Note that this function does not affect the
1.980 + * current item index.
1.981 + */
1.982 + IMPORT_C virtual void AdjustTopItemIndex() const;
1.983 +
1.984 + // navigation support functions
1.985 + /**
1.986 + * Simulates an arrow key event.
1.987 + *
1.988 + * If the list box flags include @c EMultipleSelection, this has the effect
1.989 + * of pressing @c SHIFT with the arrow key represented by @c aKeyCode.
1.990 + * Calls @c CEikListBox::OfferKeyEventL() with aKeyCode translated into a
1.991 + * key event.
1.992 + *
1.993 + * @param aKeyCode A key code.
1.994 + */
1.995 + IMPORT_C void SimulateArrowKeyEventL(TKeyCode aKeyCode);
1.996 +
1.997 + /**
1.998 + * Handles a left arrow key event.
1.999 + *
1.1000 + * The method used to handle the event depends on the selection mode, e.g.
1.1001 + * whether the user has pressed the @c SHIFT or @c CONTROL key.
1.1002 + *
1.1003 + * @param aSelectionMode Not used
1.1004 + */
1.1005 + IMPORT_C virtual void HandleLeftArrowKeyL(CListBoxView::TSelectionMode aSelectionMode);
1.1006 +
1.1007 + /**
1.1008 + * Handles a right arrow key event.
1.1009 + *
1.1010 + * The method used to handle the event depends on the selection mode,
1.1011 + * e.g. whether the user has pressed the @c SHIFT or @c CONTROL key.
1.1012 + *
1.1013 + * @param aSelectionMode Not used.
1.1014 + */
1.1015 + IMPORT_C virtual void HandleRightArrowKeyL(CListBoxView::TSelectionMode aSelectionMode);
1.1016 +
1.1017 + // construction support functions
1.1018 + /**
1.1019 + * Restores the list box properties shared by all subclasses from a resource
1.1020 + * reader. This function is not called within @c CEikListBox itself, but is
1.1021 + * used by subclasses which support construction from resources.
1.1022 + *
1.1023 + * @param aReader A resource reader.
1.1024 + */
1.1025 + IMPORT_C void RestoreCommonListBoxPropertiesL(TResourceReader& aReader);
1.1026 +
1.1027 + /**
1.1028 + * Second-phase constructor.
1.1029 + *
1.1030 + * This protected form is overridden non-virtually by the second-phase
1.1031 + * constructors of each subclass, and should be invoked by them using
1.1032 + * @c CEikListBox::ConstructL().
1.1033 + *
1.1034 + * @param aParent The parent control. May be NULL.
1.1035 + * @param aFlags Construction flags.
1.1036 + */
1.1037 + IMPORT_C virtual void ConstructL(const CCoeControl* aParent, TInt aFlags = 0);
1.1038 +
1.1039 + /**
1.1040 + * Completes the list box view’s construction.
1.1041 + *
1.1042 + * This function is called by @c ConstructL() to complete construction
1.1043 + * of the resource view, calling its @c ConstructL() with appropriate
1.1044 + * arguments and assigning it to @c iView. Also prepares the view for use.
1.1045 + */
1.1046 + IMPORT_C virtual void CreateViewL();
1.1047 +
1.1048 + /**
1.1049 + * Creates the list box view.
1.1050 + *
1.1051 + * The function is called by @c ConstructL() to create an instance of
1.1052 + * the appropriate list box view class for this list box. The returned
1.1053 + * instance is owned by this object, and does not have to have its
1.1054 + * second-phase constructor run. This function is called by @c CreateViewL().
1.1055 + *
1.1056 + * @return Pointer to a newly constructed list box view for this object.
1.1057 + */
1.1058 + IMPORT_C virtual CListBoxView* MakeViewClassInstanceL();
1.1059 +
1.1060 + /**
1.1061 + * Sets the view rectangle from the client rectangle making sure a whole
1.1062 + * number of items is displayed.
1.1063 + *
1.1064 + * @param aClientRect The client rectangle
1.1065 + */
1.1066 + IMPORT_C void SetViewRectFromClientRect(const TRect& aClientRect);
1.1067 +
1.1068 + /**
1.1069 + * Calculates the client area.
1.1070 + *
1.1071 + * This method is called by various functions of this class to
1.1072 + * recalculate the extent of the client area from @c iViewRect. This
1.1073 + * implementation takes into account any rounding of the viewing
1.1074 + * rectangle made to fit a whole number of items.
1.1075 + *
1.1076 + * @param aClientRect On return contains a size for the client area
1.1077 + * in pixels.
1.1078 + */
1.1079 + IMPORT_C virtual void RestoreClientRectFromViewRect( TRect& aClientRect) const;
1.1080 +
1.1081 + /**
1.1082 + * Rounds down the height of the rectangle (if necessary) so that
1.1083 + * only a whole number of items can be displayed inside the list box.
1.1084 + *
1.1085 + * @param aRect The rectangle to be modified.
1.1086 + * @return The number of pixels reduced.
1.1087 + */
1.1088 + IMPORT_C virtual TInt AdjustRectHeightToWholeNumberOfItems( TRect& aRect) const;
1.1089 +
1.1090 + // accessor for Laf members
1.1091 + /**
1.1092 + * Gets list box margins.
1.1093 + *
1.1094 + * @return The list box margins in pixels.
1.1095 + */
1.1096 + IMPORT_C TMargins8 ListBoxMargins() const;
1.1097 +
1.1098 + // various accessors for private data members
1.1099 + /**
1.1100 + * This function gets the horizontal margin. Use
1.1101 + * @c CEikListBox::ListBoxMargins() instead, as this
1.1102 + * provides a more accurate value due to the bit shifting involved.
1.1103 + *
1.1104 + * @deprecated Use @c CEikListBox::ListBoxMargins()
1.1105 + * @return The horizontal margin in pixels.
1.1106 + */
1.1107 + IMPORT_C TInt HorizontalMargin() const;
1.1108 +
1.1109 + /**
1.1110 + * This function gets the vertical margin. This function
1.1111 + * is deprecated, use @c CEikListBox::ListBoxMargins() instead,
1.1112 + * this provides a more accurate value due to the bit
1.1113 + * shifting involved.
1.1114 + *
1.1115 + * @deprecated Use @c CEikListBox::ListBoxMargins()
1.1116 + * @return The vertical margin in pixels.
1.1117 + */
1.1118 + IMPORT_C TInt VerticalMargin() const;
1.1119 +
1.1120 + /**
1.1121 + * Sets the horizontal margin.
1.1122 + *
1.1123 + * @param aMargin The required horizontal margin.
1.1124 + */
1.1125 + IMPORT_C void SetHorizontalMargin(TInt aMargin);
1.1126 +
1.1127 + /**
1.1128 + * Sets the vertical margin.
1.1129 + *
1.1130 + * @param aMargin The required vertical margin.
1.1131 + */
1.1132 + IMPORT_C void SetVerticalMargin(TInt aMargin);
1.1133 +
1.1134 + /**
1.1135 + * Gets a pointer to the match buffer. Returns
1.1136 + * NULL if the match buffer does not exist.
1.1137 + *
1.1138 + * @return Pointer to the match buffer.
1.1139 + */
1.1140 + IMPORT_C RIncrMatcherBase* MatchBuffer() const;
1.1141 +
1.1142 + /**
1.1143 + * Gets the view rectangle height adjustment.
1.1144 + *
1.1145 + * These are the adjustments that were made to the
1.1146 + * view rectangle when the @c SetViewRectFromClientRect()
1.1147 + * function was called.
1.1148 + *
1.1149 + * @return Height adjustment.
1.1150 + */
1.1151 + IMPORT_C TInt ViewRectHeightAdjustment() const;
1.1152 +
1.1153 + /**
1.1154 + * Gets the background colour.
1.1155 + *
1.1156 + * @return The background colour.
1.1157 + */
1.1158 + IMPORT_C TRgb BackColor() const;
1.1159 +
1.1160 + /**
1.1161 + * Sets the view rectangle height adjustment.
1.1162 + *
1.1163 + * @param aAdjustment New adjustment.
1.1164 + */
1.1165 + IMPORT_C void SetViewRectHeightAdjustment(TInt aAdjustment);
1.1166 +
1.1167 + // misc functions
1.1168 +
1.1169 + /**
1.1170 + * Reports a list box event to any observer of this list box.
1.1171 + * This function returns immediately if no observer is set.
1.1172 + *
1.1173 + * @param aEvent The event to report.
1.1174 + */
1.1175 + IMPORT_C virtual void ReportListBoxEventL( MEikListBoxObserver::TListBoxEvent aEvent );
1.1176 +
1.1177 + /**
1.1178 + * Redraws the specified area of this list box into the specified rectangle.
1.1179 + *
1.1180 + * @param aRect Rectangle to be redrawn. Specified relative to the
1.1181 + * origin of this control.
1.1182 + */
1.1183 + IMPORT_C virtual void Draw(const TRect& aRect) const;
1.1184 +
1.1185 + /**
1.1186 + * Clears the list box margins. The list box is redrawn only if redraws
1.1187 + * are enabled for the list box view.
1.1188 + */
1.1189 + IMPORT_C void ClearMargins() const;
1.1190 +
1.1191 + /**
1.1192 + * Sets an item as the current item, even if it is not currently
1.1193 + * visible. Redraws the list box to reflect the change. This
1.1194 + * should not be called from within another Draw function.
1.1195 + *
1.1196 + * @param aItemIndex The index of the list box item to update.
1.1197 + */
1.1198 + IMPORT_C virtual void UpdateCurrentItem(TInt aItemIndex) const;
1.1199 +
1.1200 + /**
1.1201 + * Handles drag events.
1.1202 + *
1.1203 + * This function is called by @c HandlePointerEventL() to handle pointer
1.1204 + * drag events appropriately.
1.1205 + *
1.1206 + * @param aPointerPos The position of the @c TPointerEvent for which this
1.1207 + * handler is invoked.
1.1208 + */
1.1209 + IMPORT_C virtual void HandleDragEventL(TPoint aPointerPos);
1.1210 +
1.1211 + /**
1.1212 + * Tests whether an item exists.
1.1213 + *
1.1214 + * @param aItemIndex Index to test.
1.1215 + * @return @c ETrue if the specified item exists, EFalse otherwise.
1.1216 + */
1.1217 + IMPORT_C TBool ItemExists(TInt aItemIndex) const;
1.1218 +
1.1219 + /**
1.1220 + * Draws the matcher cursor in the correct location for the current match.
1.1221 + * If there is no match buffer, this function returns immediately;
1.1222 + * otherwise the cursor is drawn on the current item using
1.1223 + * @c CListBoxView::DrawMatcherCursor() after scrolling to make the current
1.1224 + * item visible.
1.1225 + *
1.1226 + * A list box control’s matcher cursor is an on-screen cursor which is
1.1227 + * drawn to indicate to the user the location of the current text. Whether
1.1228 + * the cursor is drawn is dependent on the
1.1229 + * @c CListBoxView::TFlags::EHasMatcherCursor flag, which may be set on the
1.1230 + * list box’s view.
1.1231 + *
1.1232 + * Note, that CListBoxView::DrawMatcherCursor() is not implemented in S60.
1.1233 + */
1.1234 + IMPORT_C void DrawMatcherCursor() const;
1.1235 +
1.1236 + /**
1.1237 + * Gets the vertical gap between elements in the list box.
1.1238 + *
1.1239 + * @return The vertical gap between elements in the list box.
1.1240 + */
1.1241 + IMPORT_C static TInt InterItemGap();
1.1242 +
1.1243 + /**
1.1244 + * Updates the view colours in line with the colours in effect for the
1.1245 + * Uikon environment. Has no effect if there is no view.
1.1246 + */
1.1247 + IMPORT_C void UpdateViewColors();
1.1248 +
1.1249 + /**
1.1250 + * Updates the item drawer colours in line with the colours in effect
1.1251 + * for the Uikon environment. Has no effect if there is no item drawer.
1.1252 + */
1.1253 + IMPORT_C void UpdateItemDrawerColors();
1.1254 +
1.1255 + /**
1.1256 + * Notifies item change observers about item change. Subclasses must call
1.1257 + * this method if they have implemented item handling functions (e.g.
1.1258 + * @c HandleItemAdditionL or @c HandleItemRemovalL).
1.1259 + *
1.1260 + * @since S60 3.0
1.1261 + */
1.1262 + IMPORT_C void FireItemChange();
1.1263 +
1.1264 +
1.1265 +protected: // functions which deal with extension
1.1266 + /**
1.1267 + * Sets the reason for the list box’s loss of focus.
1.1268 + *
1.1269 + * This is required so the list box can determine whether
1.1270 + * loss of focus is due to an external control or an internal component.
1.1271 + *
1.1272 + * @param aReasonForFocusLost The reason for the loss of focus.
1.1273 + */
1.1274 + IMPORT_C void SetReasonForFocusLostL( TReasonForFocusLost aReasonForFocusLost );
1.1275 +
1.1276 + /**
1.1277 + * Gets the reason for the list box’s loss of focus.
1.1278 + *
1.1279 + * @return The reason for the loss of focus.
1.1280 + */
1.1281 + IMPORT_C TReasonForFocusLost ReasonForFocusLostL();
1.1282 +
1.1283 + /**
1.1284 + * Tests whether the list box match buffer exists.
1.1285 + *
1.1286 + * @return @c ETrue if the list box match buffer exists.
1.1287 + @c EFalse if the list box match buffer does not exist.
1.1288 + */
1.1289 + IMPORT_C TBool IsMatchBuffer() const;
1.1290 +
1.1291 + /**
1.1292 + * Checks for a list box extension. Attempts to create one if not present.
1.1293 + *
1.1294 + * This function leaves if an extension cannot be created.
1.1295 + */
1.1296 + void CheckCreateExtensionL();
1.1297 +
1.1298 + /**
1.1299 + * Checks for a list box extension. Creates one if not present.
1.1300 + *
1.1301 + * @return @c ETrue if a list box extension already existed or
1.1302 + * if there was no previous extension and a new extension
1.1303 + * class was created successfully.
1.1304 + * @c EFalse if there was no previous extension and a new one
1.1305 + * could not be constructed.
1.1306 + */
1.1307 + TBool CheckCreateExtension();
1.1308 +
1.1309 + /**
1.1310 + * Checks the list box match buffer exists. If a buffer does not
1.1311 + * exist, one is created.
1.1312 + */
1.1313 + void CheckCreateBufferL();
1.1314 +
1.1315 + /**
1.1316 + * Gets the list box match buffer.
1.1317 + *
1.1318 + * @return The list box match buffer.
1.1319 + */
1.1320 + CMatchBuffer* Buffer() const;
1.1321 +
1.1322 +protected:
1.1323 + /**
1.1324 + * Creates a scroll bar frame layout according to @c aLayout.
1.1325 + *
1.1326 + * @param aLayout Defines the layout.
1.1327 + */
1.1328 + IMPORT_C void CreateScrollBarFrameLayout(TEikScrollBarFrameLayout& aLayout) const;
1.1329 +
1.1330 + /**
1.1331 + * If MiddleSoftKey is either Mark or Unmark, this method sets MSK
1.1332 + * according to the current item selection state.
1.1333 + */
1.1334 + void UpdateMarkUnmarkMSKL() const;
1.1335 +
1.1336 +public:
1.1337 + /**
1.1338 + * @return Event modifiers for the @c CEikListBox.
1.1339 + */
1.1340 + IMPORT_C TInt EventModifiers();
1.1341 +
1.1342 + /*
1.1343 + * Returns ETrue if list has ES60StyleMultiselection flag.
1.1344 + */
1.1345 + IMPORT_C TBool IsMultiselection();
1.1346 +
1.1347 + /**
1.1348 + * Creates a scrollbar for the listbox. The caller may choose if the scrollbar is requested
1.1349 + * remotely via the mop chain from parent control
1.1350 + *
1.1351 + * @param aPreAlloc Is the scrollbar created immediately or when taking in to use
1.1352 + * @param aRemote If True, the scrollbar is obtained via mop-chain from
1.1353 + * parent control. If used, the listbox only sets the scrollbar
1.1354 + * values. The scrollbar position and size must set in the parent
1.1355 + * control's code.
1.1356 + *
1.1357 + * @return CEikScrollBarFrame* pointer to scrollbar frame object
1.1358 + */
1.1359 + IMPORT_C CEikScrollBarFrame* CreateScrollBarFrameL(TBool aPreAlloc, TBool aRemote);
1.1360 +
1.1361 + /**
1.1362 + * Creates a scrollbar for the listbox. The caller may choose if the scrollbar is requested
1.1363 + * remotely via the mop chain from parent control
1.1364 + *
1.1365 + * @param aPreAlloc Is the scrollbar created immediately or when taking in to use
1.1366 + * @param aRemote If True, the scrollbar is obtained via mop-chain from
1.1367 + * parent control. If used, the listbox only sets the scrollbar
1.1368 + * values. The scrollbar position and size must set in the parent
1.1369 + * control's code.
1.1370 + * @param aWindowOwning Does the created scrollbar create own window or
1.1371 + * is it compound control. The listbox uses a window owning
1.1372 + * scrollbar by default.
1.1373 + *
1.1374 + * @return CEikScrollBarFrame* pointer to scrollbar frame object
1.1375 + */
1.1376 + IMPORT_C CEikScrollBarFrame* CreateScrollBarFrameL(TBool aPreAlloc, TBool aRemote, TBool aWindowOwning);
1.1377 +
1.1378 + /**
1.1379 + * By default markable listbox has middle softkey observer, which handles
1.1380 + * Mark / Unmark functionality. By this method, the caller may disable default
1.1381 + * observer.
1.1382 + *
1.1383 + * @since S60 3.1
1.1384 + *
1.1385 + * @param aEnable If EFalse, disables default middle softkey observer
1.1386 + * for markable lists. ETrue enables observer again.
1.1387 + */
1.1388 + IMPORT_C void EnableMSKObserver(TBool aEnable);
1.1389 +
1.1390 + /**
1.1391 + * Called from MSK observer when shift+MSK have been pressed
1.1392 + *
1.1393 + * @Since S60 3.1
1.1394 + */
1.1395 + void DoShiftMSKMarkingL();
1.1396 +
1.1397 + /**
1.1398 + * This method is only called by CEikButtonGroupContainer when MSK observer
1.1399 + * is enabled and CEikButtonGroupContainer is deleted.
1.1400 + *
1.1401 + * @Since S60 3.1
1.1402 + */
1.1403 + void InformMSKButtonGroupDeletion();
1.1404 +
1.1405 + /**
1.1406 + * Adds a selection (item marking) observer to the listbox. Duplicates are not checked
1.1407 + * (i.e. adding the same observer multiple times is not prevented).
1.1408 + *
1.1409 + * @since 3.2
1.1410 + * @param aObserver Must be non-NULL.
1.1411 + */
1.1412 + IMPORT_C void AddSelectionObserverL( MListBoxSelectionObserver* aObserver );
1.1413 +
1.1414 + /**
1.1415 + * Removes a selection (item marking) observer from the listbox.
1.1416 + *
1.1417 + * @since 3.2
1.1418 + * @param aObserver The observer to be removed.
1.1419 + */
1.1420 + IMPORT_C void RemoveSelectionObserver( MListBoxSelectionObserver* aObserver );
1.1421 +
1.1422 + /**
1.1423 + * This switches listbox into selection mode. Basicly only changes MSK and
1.1424 + * informs selection observers about the change.
1.1425 + *
1.1426 + * @since 3.2
1.1427 + * @param aEnable ETrue when entering into selection mode, EFalse when leaving
1.1428 + */
1.1429 + void ChangeSelectionMode(TBool aEnable);
1.1430 +
1.1431 + /**
1.1432 + * Sets the number of list items that form one grid line.
1.1433 + *
1.1434 + * @since S60 5.0
1.1435 + * @param aItems Number of items in one grid line.
1.1436 + */
1.1437 + IMPORT_C void SetItemsInSingleLine(TInt aItems);
1.1438 +
1.1439 + /**
1.1440 + * Removes pointer event filtering for list items.
1.1441 + *
1.1442 + * When there are two pointer up events on the same item at short interval,
1.1443 + * listbox will only get the first one and drop the second one. This method forces listbox to handle all pointer up events.
1.1444 + *
1.1445 + * @since S60 5.0
1.1446 + *
1.1447 + * @param aItemIndexes Array of item indexes to be added.
1.1448 + **/
1.1449 + IMPORT_C void SetPointerEventFilterDisabledL( const CArrayFix<TInt>& aItemIndexes );
1.1450 +
1.1451 + /**
1.1452 + * Scrolls the view by the given amount of pixels while keeping the
1.1453 + * physics parameters up-to-date.
1.1454 + * This should be called when scrolling the list box view except for
1.1455 + * when it is done by list dragging (e.g. scrolling with scroll bar).
1.1456 + *
1.1457 + * @param aDeltaPixels Amount of pixels to scroll the view.
1.1458 + *
1.1459 + * @since 5.0
1.1460 + */
1.1461 + IMPORT_C void HandlePhysicsScrollEventL( TInt aDeltaPixels );
1.1462 +
1.1463 + /**
1.1464 + * Disables the kinetic scrolling functionality in the list.
1.1465 + * By default the feature is enabled.
1.1466 + *
1.1467 + * @param aDisabled @c ETrue to disable kinetic scrolling,
1.1468 + * @c EFalse otherwise.
1.1469 + *
1.1470 + * @since 5.0
1.1471 + */
1.1472 + IMPORT_C void DisableScrolling( TBool aDisabled );
1.1473 +
1.1474 + /**
1.1475 + * Checks if the kinetic scrolling is currently enabled in the list.
1.1476 + *
1.1477 + * @return @c ETrue if kinetic scrolling is enabled, @c EFalse otherwise.
1.1478 + *
1.1479 + * @since 5.0
1.1480 + */
1.1481 + IMPORT_C TBool ScrollingDisabled();
1.1482 +
1.1483 + /**
1.1484 + * Suspends transitions effects.
1.1485 + *
1.1486 + * @since S60 5.0
1.1487 + *
1.1488 + * @param aSuspend ETrue to suspend effects, EFalse to re-enable them.
1.1489 + */
1.1490 + IMPORT_C void SuspendEffects( TBool aSuspend );
1.1491 +
1.1492 +private:
1.1493 + IMPORT_C virtual void CEikListBox_Reserved(); // listbox use only
1.1494 + void HorizontalScroll(TInt aScrollAmountInPixels);
1.1495 + void DrawItemInView(TInt aItemIndex) const;
1.1496 + void ClearMargins(CWindowGc& aGc) const;
1.1497 + TKeyResponse DoOfferKeyEventL(const TKeyEvent& aKeyEvent,TEventCode aType);
1.1498 + void UpdateScrollBarColors(CEikScrollBar* aScrollBar);
1.1499 + void UpdateScrollBarsColors();
1.1500 +
1.1501 + void HandleItemRemovalWithoutSelectionsL();
1.1502 +
1.1503 + /**
1.1504 + * Scrolls the view by the given amount of pixels.
1.1505 + *
1.1506 + * @param aOffset Amount of offset in pixels.
1.1507 + * @param aDrawNow Whether or not the view is be drawn.
1.1508 + * If @c EFalse then only the logical state is updated.
1.1509 + *
1.1510 + * @internal
1.1511 + * @since 5.0
1.1512 + */
1.1513 + void ScrollView( const TInt aOffset, TBool aDrawNow );
1.1514 +
1.1515 + /**
1.1516 + * Handles pointer events if physics are enabled.
1.1517 + *
1.1518 + * @return @c ETrue if the event was consumed by kinetic scrolling.
1.1519 + *
1.1520 + * @internal
1.1521 + * @since 5.0
1.1522 + */
1.1523 + TBool HandlePhysicsPointerEventL( const TPointerEvent& aPointerEvent );
1.1524 +
1.1525 + /**
1.1526 + * Selects an item and draws highlight to it.
1.1527 + *
1.1528 + * @param aItemIndex Index of the highlighted item.
1.1529 + *
1.1530 + * @internal
1.1531 + * @since 5.0
1.1532 + */
1.1533 + void UpdateHighlightL( TInt aItemIndex );
1.1534 +
1.1535 +protected:
1.1536 + /** Flags for this list box */
1.1537 + TInt iListBoxFlags;
1.1538 +
1.1539 + /** This List box's view */
1.1540 + CListBoxView* iView;
1.1541 +
1.1542 + /** Item drawer for this list box */
1.1543 + CListItemDrawer* iItemDrawer;
1.1544 +
1.1545 + /** Data model for this list box */
1.1546 + MListBoxModel* iModel;
1.1547 +
1.1548 + /** Height of each item in the list */
1.1549 + TInt iItemHeight;
1.1550 +
1.1551 + /** The scroll bar used by this control */
1.1552 + CEikScrollBarFrame* iSBFrame;
1.1553 +
1.1554 + /** Identifies if the scroll bar is owned by this list */
1.1555 + TScrollBarOwnerShip iSBFrameOwned;
1.1556 +
1.1557 + /** The required height of this list box expressed in
1.1558 + * terms of a number of items.
1.1559 + */
1.1560 + TInt iRequiredHeightInNumOfItems;
1.1561 +
1.1562 + /**
1.1563 + * Defines which button launched the popout.
1.1564 + */
1.1565 + CEikButtonBase* iLaunchingButton; // only used by popouts
1.1566 +
1.1567 + /** The button which just launched a popout menu. */
1.1568 + MEikListBoxObserver* iListBoxObserver;
1.1569 +
1.1570 +private:
1.1571 +
1.1572 + TRgb iBackColor;
1.1573 +// TInt iHorizontalMargin;
1.1574 +// TInt iVerticalMargin;
1.1575 + TMargins8 iMargins ;
1.1576 + CListBoxExt* iListBoxExt;
1.1577 + TInt iViewRectHeightAdjustment;
1.1578 + MEikListBoxEditor* iItemEditor;
1.1579 + TBool* iLbxDestroyed;
1.1580 + TBool iLastCharMatched;
1.1581 + TInt iSpare;
1.1582 + };
1.1583 +
1.1584 +
1.1585 +
1.1586 +/**
1.1587 +* This is a list box that scrolls horizontally, displaying its items
1.1588 +* in as many vertical columns as needed. Columns are arranged across
1.1589 +* the control from left to right; within columns, items are arranged
1.1590 +* from top to bottom. The flow of items or text ‘snakes’ across the
1.1591 +* face of the control.
1.1592 +*
1.1593 +* This is a flexible control class that makes good use of short, wide
1.1594 +* display areas; for instance, subclasses of @c CEikSnakingListBox could
1.1595 +* be used for file lists or for a control panel. A standard user
1.1596 +* subclass, @c CEikSnakingTextListBox, also exists.
1.1597 +*
1.1598 +* @since Symbian 5.0
1.1599 +*/
1.1600 +class CEikSnakingListBox : public CEikListBox
1.1601 + {
1.1602 +public:
1.1603 + /**
1.1604 + * C++ standard constructor
1.1605 + */
1.1606 + IMPORT_C CEikSnakingListBox();
1.1607 +
1.1608 + /**
1.1609 + * Destructor
1.1610 + */
1.1611 + IMPORT_C ~CEikSnakingListBox();
1.1612 +
1.1613 + /**
1.1614 + * Creates an instance of the view class.
1.1615 + *
1.1616 + * This function is called during construction to create
1.1617 + * (but not second-phase construct) an instance of the correct view
1.1618 + * class for this list box control. In the case of the snaking list
1.1619 + * box, a @c CSnakingListBoxView is returned.
1.1620 + *
1.1621 + * This function overrides @c CEikListBox::MakeViewClassInstanceL().
1.1622 + *
1.1623 + * @return The view which will be used by the list box being created
1.1624 + */
1.1625 + IMPORT_C virtual CListBoxView* MakeViewClassInstanceL();
1.1626 +
1.1627 + /**
1.1628 + * Sets the top item’s index.
1.1629 + *
1.1630 + * @param aItemIndex Index of the item to set as the top item.
1.1631 + */
1.1632 + IMPORT_C virtual void SetTopItemIndex(TInt aItemIndex) const;
1.1633 +
1.1634 + /**
1.1635 + * Gets the width of this list box’s columns.
1.1636 + *
1.1637 + * @return Width of each column.
1.1638 + */
1.1639 + IMPORT_C TInt ColumnWidth() const;
1.1640 +
1.1641 + /**
1.1642 + * Sets the width of all columns in the list box.
1.1643 + *
1.1644 + * @param aColumnWidth New column width.
1.1645 + */
1.1646 + IMPORT_C void SetColumnWidth(TInt aColumnWidth);
1.1647 +
1.1648 +public: //from CCoeControl
1.1649 +
1.1650 + /**
1.1651 + * From @c CCoeControl.
1.1652 + *
1.1653 + * Handles pointer events.
1.1654 + *
1.1655 + * @param aPointerEvent The pointer event.
1.1656 + */
1.1657 + IMPORT_C void HandlePointerEventL(const TPointerEvent& aPointerEvent);
1.1658 +
1.1659 +protected:
1.1660 +
1.1661 + /**
1.1662 + * Handles a change in size of the viewing rectangle.
1.1663 + *
1.1664 + * This function is called by framework functions to update the content,
1.1665 + * view, and scroll bars of this list box after the viewing rectangle has
1.1666 + * changed size. This implementation ensures that the current item is
1.1667 + * visible after a resize.
1.1668 + */
1.1669 + IMPORT_C virtual void HandleViewRectSizeChangeL();
1.1670 +
1.1671 + /**
1.1672 + * Handles a left arrow key event.
1.1673 + *
1.1674 + * Moves the cursor into the correct column and clears any matcher buffer
1.1675 + * that may have been built up.
1.1676 + *
1.1677 + * @param aSelectionMode Not used.
1.1678 + */
1.1679 + IMPORT_C virtual void HandleLeftArrowKeyL(
1.1680 + CListBoxView::TSelectionMode aSelectionMode);
1.1681 +
1.1682 + /**
1.1683 + * Handles a right arrow key event.
1.1684 + *
1.1685 + * Moves the cursor into the correct column and clears any matcher buffer
1.1686 + * that may have been built up.
1.1687 + *
1.1688 + * @param aSelectionMode Not used.
1.1689 + */
1.1690 + IMPORT_C virtual void HandleRightArrowKeyL(
1.1691 + CListBoxView::TSelectionMode aSelectionMode);
1.1692 +
1.1693 + /**
1.1694 + * Gets the number of grains to move horizontally when a nudge button
1.1695 + * is tapped.
1.1696 + *
1.1697 + * For simple list boxes, this value is a fraction of the width of the
1.1698 + * client area.
1.1699 + *
1.1700 + * @return Number of grains to move left or right on each nudge.
1.1701 + */
1.1702 + IMPORT_C virtual TInt HorizontalNudgeValue() const;
1.1703 +
1.1704 + /**
1.1705 + * Gets the granularity for horizontal scrolls.
1.1706 + *
1.1707 + * The granularity is the minimum size of a horizontal move of the
1.1708 + * client area.
1.1709 + *
1.1710 + * @return Grain size for horizontal scrolling in pixels.
1.1711 + */
1.1712 + IMPORT_C virtual TInt HorizScrollGranularityInPixels() const;
1.1713 +
1.1714 + /**
1.1715 + * Called by various functions of this class to ensure that the top
1.1716 + * item index is always a sane value. The implementation in @c CEikListBox
1.1717 + * tries to ensure the minimum amount of white space at the bottom of
1.1718 + * the list box. Note that this function does not affect the current
1.1719 + * item index.
1.1720 + */
1.1721 + IMPORT_C virtual void AdjustTopItemIndex() const;
1.1722 +
1.1723 + /**
1.1724 + * Handles drag events.
1.1725 + *
1.1726 + * This function is called by @c HandlePointerEventL() to handle
1.1727 + * pointer drag events appropriately.
1.1728 + *
1.1729 + * @param aPointerPos The position of the @c TPointerEvent for which this
1.1730 + * handler is invoked.
1.1731 + */
1.1732 + IMPORT_C virtual void HandleDragEventL(TPoint aPointerPos);
1.1733 +
1.1734 + /**
1.1735 + * Calculates the client area.
1.1736 + *
1.1737 + * This method is called by various functions of this class to recalculate
1.1738 + * the extent of the client area from @c iViewRect. This implementation
1.1739 + * takes into account any rounding of the viewing rectangle made to fit a
1.1740 + * whole number of items.
1.1741 + *
1.1742 + * @param aClientRect On return contains a size for the client area in
1.1743 + * pixels.
1.1744 + */
1.1745 + IMPORT_C virtual void RestoreClientRectFromViewRect(
1.1746 + TRect& aClientRect) const;
1.1747 +
1.1748 + /**
1.1749 + * Rounds down the height of the rectangle (if necessary) so that only a
1.1750 + * whole number of items can be displayed inside the list box.
1.1751 + *
1.1752 + * @param aRect The rectangle to be modified.
1.1753 + * @return The number of pixels reduced.
1.1754 + */
1.1755 + IMPORT_C virtual TInt AdjustRectHeightToWholeNumberOfItems(
1.1756 + TRect& aRect) const;
1.1757 +
1.1758 + /**
1.1759 + * Move to next or previous item according to the given parameter.
1.1760 + *
1.1761 + * @param aPoint Position which defines the moving direction.
1.1762 + */
1.1763 + IMPORT_C void MoveToNextOrPreviousItemL(TPoint aPoint);
1.1764 +
1.1765 +protected: //from CCoeControl
1.1766 +
1.1767 + /**
1.1768 + * From @c CCoeControl
1.1769 + *
1.1770 + * Updates the viewing rectangle of this control appropriately. The function
1.1771 + * updates the viewing rectangle, and invokes @c HandleViewRectSizeChangeL().
1.1772 + */
1.1773 + IMPORT_C virtual void SizeChanged();
1.1774 +
1.1775 + /**
1.1776 + * From @c CCoeControl
1.1777 + *
1.1778 + * Gets the list of logical colours employed in the drawing of the control,
1.1779 + * paired with an explanation of how they are used. Appends the list to
1.1780 + * @c aColorUseList.
1.1781 + *
1.1782 + * @param aColorUseList List of logical colours.
1.1783 + */
1.1784 + IMPORT_C virtual void GetColorUseListL(
1.1785 + CArrayFix<TCoeColorUse>& aColorUseList) const;
1.1786 + // not available before Release 005u
1.1787 + /**
1.1788 + * From @c CCoeControl.
1.1789 + *
1.1790 + * Handles a change to the list box’s resources of type @c aType which are
1.1791 + * shared across the environment, colours or fonts for example.
1.1792 + *
1.1793 + * @param aType The type of resources that have changed.
1.1794 + */
1.1795 + IMPORT_C virtual void HandleResourceChange(TInt aType);
1.1796 + // not available before Release 005u
1.1797 +
1.1798 +private: // from CCoeControl
1.1799 + IMPORT_C void Reserved_1();
1.1800 +
1.1801 + IMPORT_C void Reserved_2();
1.1802 +
1.1803 +private:
1.1804 + /**
1.1805 + * From CAknControl
1.1806 + */
1.1807 + IMPORT_C void* ExtensionInterface( TUid aInterface );
1.1808 +
1.1809 +private:
1.1810 + IMPORT_C virtual void CEikListBox_Reserved(); // listbox use only
1.1811 + };
1.1812 +
1.1813 +#endif // __EIKLBX_H__