1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/epoc32/include/mw/eikfrlb.h Wed Mar 31 12:33:34 2010 +0100
1.3 @@ -0,0 +1,604 @@
1.4 +/*
1.5 +* Copyright (c) 2002 Nokia Corporation and/or its subsidiary(-ies).
1.6 +* All rights reserved.
1.7 +* This component and the accompanying materials are made available
1.8 +* under the terms of "Eclipse Public License v1.0"
1.9 +* which accompanies this distribution, and is available
1.10 +* at the URL "http://www.eclipse.org/legal/epl-v10.html".
1.11 +*
1.12 +* Initial Contributors:
1.13 +* Nokia Corporation - initial contribution.
1.14 +*
1.15 +* Contributors:
1.16 +*
1.17 +* Description:
1.18 +*
1.19 +*/
1.20 +
1.21 +// EIKFRLB.H
1.22 +//
1.23 +// Copyright (c) 1997-2001 Symbian Ltd. All rights reserved.
1.24 +//
1.25 +#if !defined(__EIKFRLB_H__)
1.26 +#define __EIKFRLB_H__
1.27 +
1.28 +#include <eiklbi.h>
1.29 +#include <eiklbv.h>
1.30 +#include <eiktxlbm.h>
1.31 +#include <eiktxlbx.h>
1.32 +
1.33 +class CFormattedCellListBoxData;
1.34 +
1.35 +/**
1.36 + * @c CFormattedCellListBoxItemDrawer draws a single list item and manages
1.37 + * list item properties.
1.38 + *
1.39 + * @lib avkon
1.40 + */
1.41 +class CFormattedCellListBoxItemDrawer : public CTextListItemDrawer
1.42 + {
1.43 +public:
1.44 +
1.45 + /**
1.46 + * C++ default constructor.
1.47 + *
1.48 + * @param aTextListBoxModel The list box model class.
1.49 + * @param aFont Font to be used in listbox.
1.50 + * @param aFormattedCellData Pointer to the list layout drawer class.
1.51 + */
1.52 + IMPORT_C CFormattedCellListBoxItemDrawer(
1.53 + MTextListBoxModel* aTextListBoxModel,
1.54 + const CFont* aFont,
1.55 + CFormattedCellListBoxData* aFormattedCellData);
1.56 +
1.57 + /**
1.58 + * Destructor.
1.59 + */
1.60 + IMPORT_C ~CFormattedCellListBoxItemDrawer();
1.61 +
1.62 + /**
1.63 + * Gets the list layout drawer.
1.64 + *
1.65 + * @return Pointer to the list layout drawer object.
1.66 + */
1.67 + IMPORT_C CFormattedCellListBoxData* FormattedCellData() const;
1.68 +
1.69 + /**
1.70 + * Gets the list layout drawer.
1.71 + *
1.72 + * @return Pointer to the list layout drawer object.
1.73 + */
1.74 + IMPORT_C CFormattedCellListBoxData* ColumnData() const;
1.75 + // for compability with columnlistbox itemdrawer
1.76 +
1.77 + /**
1.78 + * Draws an empty item to the list box.
1.79 + *
1.80 + * @param aItemIndex Not used.
1.81 + * @param aItemRectPos Position for the list box item rectangle.
1.82 + * @param aViewIsDimmed Not used.
1.83 + */
1.84 + IMPORT_C virtual void DrawEmptyItem(TInt aItemIndex, TPoint aItemRectPos,
1.85 + TBool aViewIsDimmed) const;
1.86 +
1.87 + /**
1.88 + * This function sets top item index.
1.89 + *
1.90 + * @param aTop Item index value.
1.91 + */
1.92 + IMPORT_C void SetTopItemIndex(TInt aTop);
1.93 +
1.94 + /**
1.95 + * List item index and color and style properties.
1.96 + */
1.97 + struct SListProperties
1.98 + {
1.99 + /** List box item index. */
1.100 + TInt iItem; // must be first
1.101 +
1.102 + /** Colour and style properties for the list item. */
1.103 + TListItemProperties iProperties;
1.104 + };
1.105 +
1.106 + /**
1.107 + * Clears all properties.
1.108 + */
1.109 + IMPORT_C void ClearAllPropertiesL();
1.110 +
1.111 + /**
1.112 + * The SetProperties is convenience method for normal cases.
1.113 + * NOTE that it does NOT work correctly if you can insert/delete
1.114 + * items from the list -- You need to update all properties if
1.115 + * any changes to the item text array happen! Often it is convenient
1.116 + * to override the @c Properties() method. Further, use this only
1.117 + * for small lists.
1.118 + *
1.119 + * It has been implemented as sorted list of (index,Property) pairs.
1.120 + *
1.121 + * If you're using find, aItemIndex for this method is the same as you give
1.122 + * in @c MdcaPoint() points the default @c Properties() does conversion
1.123 + * between indexes.
1.124 + *
1.125 + * @param aItemIndex List box item index.
1.126 + * @param properties Colour and style properties for the list box item.
1.127 + */
1.128 + IMPORT_C void SetPropertiesL(TInt aItemIndex, TListItemProperties properties);
1.129 +
1.130 + /**
1.131 + * Function for getting properties of a certain list box item.
1.132 + *
1.133 + * @param aItemIndex The listbox item index.
1.134 + * @return Colour and style properties of wanted
1.135 + * list box item.
1.136 + */
1.137 + IMPORT_C virtual TListItemProperties Properties(TInt aItemIndex) const;
1.138 +
1.139 + /**
1.140 + * Gets list box item cell size.
1.141 + *
1.142 + * @return The list box item cell size.
1.143 + */
1.144 + TSize LafItemSize() { return iItemCellSize; }
1.145 +
1.146 +public: // from CTextListItemDrawer
1.147 +
1.148 + /**
1.149 + * From @c CTextListItemDrawer.
1.150 + *
1.151 + * Draw an item in a list box.
1.152 + *
1.153 + * @param aItemIndex The index into the model's item array of the item
1.154 + * to draw.
1.155 + * @param aItemTextRect The item’s text rectangle.
1.156 + * @param aItemIsCurrent @c ETrue if the item is current. @c EFalse
1.157 + * otherwise.
1.158 + * @param aViewIsEmphasized @c ETrue if the view is emphasized. @c EFalse
1.159 + * otherwise.
1.160 + * @param aItemIsSelected @c ETrue if the item is selected. @c EFalse
1.161 + * otherwise.
1.162 + */
1.163 + IMPORT_C void DrawItemText(TInt aItemIndex,const TRect& aItemTextRect,
1.164 + TBool aItemIsCurrent, TBool aViewIsEmphasized,
1.165 + TBool aItemIsSelected) const;
1.166 +
1.167 + /**
1.168 + * From @c CTextListItemDrawer.
1.169 + *
1.170 + * Draws an item tick mark.
1.171 + *
1.172 + * A tick mark is used in multiple selection lists to indicate the item is
1.173 + * selected.
1.174 + *
1.175 + * This function is invoked by the framework to draw an item mark if
1.176 + * @c iDrawMark is set. The mark should be drawn into this list item
1.177 + * drawer's graphics context; by default, @c DrawItemMark() draws a tick
1.178 + * using the standard symbol font.
1.179 + *
1.180 + * This function does not need to be re-implemented for derived classes
1.181 + * which do not draw item marks.
1.182 + *
1.183 + * @param aItemIsSelected Whether the item to draw for is selected.
1.184 + * @param aViewIsDimmed Whether the item is dimmed.
1.185 + * @param aMarkPos Position of the mark.
1.186 + */
1.187 + IMPORT_C void DrawItemMark(TBool aItemIsSelected, TBool aViewIsDimmed,
1.188 + const TPoint& aMarkPos) const;
1.189 +
1.190 +public: // from CListItemDrawer
1.191 +
1.192 + /**
1.193 + * From @c CListItemDrawer.
1.194 + *
1.195 + * Gets the minimum size of a cell based on the font and the number of
1.196 + * characters in the cell.
1.197 + *
1.198 + * @return The minimum size for a cell in pixels.
1.199 + */
1.200 + IMPORT_C TSize MinimumCellSize() const;
1.201 +
1.202 + /**
1.203 + * From @c CListItemDrawer.
1.204 + *
1.205 + * Gets the width in pixels of the specified item.
1.206 + *
1.207 + * @param aItemIndex The index of the item for which the width is obtained.
1.208 + * @return The specified item's width in pixels.
1.209 + */
1.210 + IMPORT_C TInt ItemWidthInPixels(TInt aItemIndex) const;
1.211 +
1.212 + /**
1.213 + * From @c CListItemDrawer.
1.214 + *
1.215 + * Sets the item cell size.
1.216 + *
1.217 + * The cell size is the on-screen size of the entire item, including its
1.218 + * text and its item mark.
1.219 + *
1.220 + * @param aSizeInPixels New size for the item cell.
1.221 + */
1.222 + IMPORT_C void SetItemCellSize(const TSize& aSizeInPixels);
1.223 +
1.224 +protected:
1.225 +
1.226 + /**
1.227 + * Draws current item rectangle.
1.228 + *
1.229 + * @param aRect Current item rectangle.
1.230 + */
1.231 + void DrawCurrentItemRect(const TRect& aRect) const;
1.232 +
1.233 + /**
1.234 + * @c WordWrapListItem is used with @c CAknDouble* style listboxes.
1.235 + * If listbox does not have 2nd line defined, @c WordWrapListItem
1.236 + * wraps 1st line to 2nd line, if text does not fit to 1st line.
1.237 + * If listbox does have 2nd line defined, this method truncates
1.238 + * both lines.
1.239 + *
1.240 + * @internal
1.241 + * @param aTarget Where to place wrapped item string
1.242 + * @param aItemString Text to be wrapped
1.243 + * @param aFirstIndex index of 1st subcell to wrap
1.244 + * @param aSecondIndex index of 2nd subcell
1.245 + */
1.246 + void WordWrapListItem( TPtr& aTarget,
1.247 + const TDesC &aItemString,
1.248 + TInt aFirstIndex,
1.249 + TInt aSecondIndex,
1.250 + TInt aItemIndex ) const;
1.251 + /**
1.252 + * @internal
1.253 + */
1.254 + void DrawBackgroundAndSeparatorLines( const TRect& aItemTextRect,
1.255 + TBool aDrawSeparator ) const;
1.256 +
1.257 +
1.258 +private:
1.259 +
1.260 + IMPORT_C void CFormattedCellListBoxItemDrawer_Reserved();
1.261 +
1.262 +protected:
1.263 +
1.264 + /**
1.265 + * Top item index.
1.266 + */
1.267 + TInt iTopItemIndex;
1.268 +
1.269 + /**
1.270 + * Array for list box item's properties.
1.271 + * Own.
1.272 + */
1.273 + CArrayFix<SListProperties>* iPropertyArray;
1.274 +
1.275 +private:
1.276 +
1.277 + TInt iSpare;
1.278 + };
1.279 +
1.280 +
1.281 +/**
1.282 + * Avkon base class similar to uikon's column listbox.
1.283 + *
1.284 + * @code
1.285 + * ListBox <>--> View ---> ItemDrawer ---> Model
1.286 + * ListBox <>--> ItemDrawer <>---> Data
1.287 + * ListBox <>--> Model <>---> MDesCArray <--- Array <>---> Engine
1.288 + * @endcode
1.289 + *
1.290 + * Content for list items are tab-separated strings.
1.291 + *
1.292 + * See concrete classes derived from @c CEikFormattedCellListBox for details.
1.293 + *
1.294 + * Starting from 3.0 listbox uses highlight animations. Starting and stopping
1.295 + * animation is connected to focus events. To support highlight animations
1.296 + * properly you have to make sure that the list has focus when it has 'visual
1.297 + * focus'. Common issues:
1.298 + * - In many cases list is in a container which sits on top of the control
1.299 + * stack. The container receives all focus events and should hand them to the
1.300 + * list too. E.g.
1.301 + * @code void CContainer::FocusChanged( TDrawNow aDrawNow )
1.302 + * {
1.303 + * ... some code ...
1.304 + * if( iListBox )
1.305 + * iListBox->SetFocus( IsFocused(), aDrawNow );
1.306 + * }
1.307 + * @endcode
1.308 + * - When switching components programmatically, e.g. from one list to another
1.309 + * in the same view, make sure that you remove focus from the other
1.310 + * component.
1.311 + * - In more complex cases you may have to add a dummy interceptor control to
1.312 + * the top of control stack to hand focus events to list.
1.313 + * - Make sure you handle resource changes correctly. If resource handle chain
1.314 + * is solid it should reach @c CCoeControl::HandleResourceChange, which
1.315 + * informs child components about resource change.
1.316 + *
1.317 + * See methods
1.318 + * @c CEikListBox::ConstructL()
1.319 + * @c CEikTextListBox::SetItemTextArray()
1.320 + * @c CEikFormattedCellListBoxData::SetIconArray()
1.321 + *
1.322 + * Related flags for dialogs (@c avkon.hrh)
1.323 + * @c EAknDialogSelectionList
1.324 + * @c EAknDialogMenuList
1.325 + * @c EAknDialogMultiselectionList
1.326 + *
1.327 + * Check also:
1.328 + * @c CAknSelectionListDialog (@c aknselectionlist.h)
1.329 + * @c CAknMarkableListDialog (@c aknselectionlist.h)
1.330 + * @c CAknPopupList (@c aknpopup.h)
1.331 + * @c CAknListQueryDialog (@c aknquerydialog.h)
1.332 + * @c CAknColumnListBox (@c aknlists.h)
1.333 + *
1.334 + * @lib avkon
1.335 + */
1.336 +class CEikFormattedCellListBox : public CEikTextListBox
1.337 + {
1.338 +
1.339 +public:
1.340 +
1.341 + /**
1.342 + * C++ default constructor.
1.343 + */
1.344 + IMPORT_C CEikFormattedCellListBox();
1.345 +
1.346 + /**
1.347 + * Constructs list box from resource file. See @c LISTBOX resource
1.348 + * definition.
1.349 + *
1.350 + * Flags:
1.351 + * @c EAknListBoxSelectionList,
1.352 + * @c EAknListBoxMenuList,
1.353 + * @c EAknListBoxMarkableList,
1.354 + * @c EAknListBoxMultiselectionList,
1.355 + * @c EAknListBoxViewerFlags
1.356 + *
1.357 + * @param aReader Reference to resource reader @c TResourceReader object.
1.358 + */
1.359 + IMPORT_C void ConstructFromResourceL(TResourceReader& aReader);
1.360 +
1.361 + /**
1.362 + * By default Symbian 2nd phase constructor is private. Must be called
1.363 + * if resource data is not used.
1.364 + *
1.365 + * @param aParent Pointer to @c CCoeControl class, parent control.
1.366 + * @param aFlags Flags for @c CEikListBox constructor. Possible flags :
1.367 + * @c EAknListBoxSelectionList,
1.368 + * @c EAknListBoxMenuList,
1.369 + * @c EAknListBoxMarkableList,
1.370 + * @c EAknListBoxMultiselectionList,
1.371 + * @c EAknListBoxViewerFlags
1.372 + */
1.373 + IMPORT_C void ConstructL(const CCoeControl* aParent, TInt aFlags);
1.374 +
1.375 +public:
1.376 +
1.377 + /**
1.378 + * Gets model class of the list box.
1.379 + *
1.380 + * @return Pointer to list box model class instance.
1.381 + */
1.382 + IMPORT_C CTextListBoxModel* Model() const;
1.383 +
1.384 + /**
1.385 + * Gets list box item drawer.
1.386 + *
1.387 + * @return Pointer to item drawer object.
1.388 + */
1.389 + IMPORT_C CFormattedCellListBoxItemDrawer* ItemDrawer() const;
1.390 +
1.391 + /**
1.392 + * Sets icon sizes for visible list box items.
1.393 + */
1.394 + void SetIconSizes();
1.395 +
1.396 +public:
1.397 +
1.398 + /**
1.399 + * Enable or disable logical to visual reordering in listbox data text
1.400 + * drawing. By default, it is enabled. This has any effect only when
1.401 + * bidirectional text is rendered.
1.402 + *
1.403 + * If you convert text to visual order prior to passing it to the listbox
1.404 + * (for example by wrapping text to lines with methods in
1.405 + * @c AknBidiTextUtils), then you should disable conversion in listbox
1.406 + * by calling this method.
1.407 + *
1.408 + * @since S60 2.0
1.409 + * @param aUseConversion If @c ETrue enable conversion.
1.410 + */
1.411 + IMPORT_C void UseLogicalToVisualConversion( TBool aUseConversion );
1.412 +
1.413 +public:
1.414 +
1.415 + /**
1.416 + * This method needs to be called to enable extended drawing features such
1.417 + * as skinning, pictograph drawing and marquee text in the listbox draw
1.418 + * routine.
1.419 + *
1.420 + * Methods @c CEikFormattedCellListBox::ConstructL and
1.421 + * @c CEikFormattedCellListBox::ConstructFromResourceL call this method.
1.422 + * So, you only need to call this if your listbox implementation does not
1.423 + * call either of those.
1.424 + *
1.425 + * This method can be safely called more than once.
1.426 + * Item drawer must be created before calling this method, or a panic is
1.427 + * raised.
1.428 + *
1.429 + * @since S60 2.6
1.430 + * @panic EAknPanicListBoxItemDrawerNotCreated Panics if the item drawer
1.431 + * for the current class has not been defined.
1.432 + */
1.433 + IMPORT_C void EnableExtendedDrawingL();
1.434 +
1.435 + /**
1.436 + * Enables/disables list stretching. When a list is stretched its second line
1.437 + * is moved after the first line. This is intented for devices with a large
1.438 + * screen. This feature might be set as default by a product specific flag.
1.439 + *
1.440 + * Item drawer must be created before calling this method.
1.441 + *
1.442 + * @since S60 3.1
1.443 + * @param aEnabled ETrue to enable list stretching.
1.444 + */
1.445 + IMPORT_C void EnableStretching( const TBool aEnabled );
1.446 +
1.447 + /**
1.448 + * Hides the second row of a double style listbox. This feature is disabled
1.449 + * by default.
1.450 + *
1.451 + * @since S60 3.1
1.452 + * @param aHide ETrue to hide the second row.
1.453 + */
1.454 + IMPORT_C void HideSecondRow( const TBool aHide );
1.455 +protected:
1.456 +
1.457 + /**
1.458 + * Creates item draver for the listbox.
1.459 + */
1.460 + IMPORT_C virtual void CreateItemDrawerL();
1.461 +
1.462 + /**
1.463 + * From @c CEikListBox.
1.464 + *
1.465 + * Rounds down the height of the rectangle (if necessary) so that only
1.466 + * a whole number of items can be displayed inside the list box.
1.467 + *
1.468 + * @param aRect The rectangle to be modified.
1.469 + * @return The number of pixels reduced.
1.470 + */
1.471 + IMPORT_C virtual TInt AdjustRectHeightToWholeNumberOfItems(
1.472 + TRect &aRect) const;
1.473 +
1.474 +public: // from CEikListBox
1.475 +
1.476 + /**
1.477 + * From @c CEikListBox.
1.478 + *
1.479 + * Creates the list box view.
1.480 + *
1.481 + * @return Pointer to new list box view class instance.
1.482 + */
1.483 + IMPORT_C CListBoxView* MakeViewClassInstanceL();
1.484 +
1.485 + /**
1.486 + * From @c CEikListBox.
1.487 + *
1.488 + * Handles focus changes.
1.489 + *
1.490 + * The function emphasizes or de-emphasizes the view as needed,
1.491 + * and shows or hides the matcher cursor.
1.492 + *
1.493 + * @param aDrawNow If @c EDrawNow, a redraw is performed immediately.
1.494 + */
1.495 + IMPORT_C void FocusChanged(TDrawNow aDrawNow);
1.496 +
1.497 +public: // from CCoeControl
1.498 +
1.499 + /**
1.500 + * From @c CCoeControl.
1.501 + *
1.502 + * Gets the list of logical colors used to draw the control.
1.503 + *
1.504 + * @param aColorUseList The color list.
1.505 + */
1.506 + IMPORT_C void GetColorUseListL(
1.507 + CArrayFix<TCoeColorUse>& aColorUseList) const;
1.508 +
1.509 + /**
1.510 + * From @c CCoeControl.
1.511 + *
1.512 + * Handles a change to the control's resources.
1.513 + *
1.514 + * @param aType A message UID value.
1.515 + */
1.516 + IMPORT_C void HandleResourceChange(TInt aType);
1.517 +
1.518 + /**
1.519 + * From @c CCoeControl.
1.520 + *
1.521 + * Handles pointer events.
1.522 + *
1.523 + * @param aPointerEvent The pointer event.
1.524 + */
1.525 + IMPORT_C void HandlePointerEventL(const TPointerEvent& aPointerEvent);
1.526 +
1.527 +protected: // from MObjectProvider
1.528 +
1.529 + /**
1.530 + * From @c MObjectProvider.
1.531 + *
1.532 + * Retrieves an object of the same type as that encapsulated in aId. This
1.533 + * function is used to allow controls to ask their owners for access to
1.534 + * other objects that they own.
1.535 + *
1.536 + * @param aId An encapsulated object type ID.
1.537 + * @return Encapsulates the pointer to the object provided.
1.538 + * Note that the encapsulated pointer may be NULL.
1.539 + */
1.540 + IMPORT_C virtual TTypeUid::Ptr MopSupplyObject(TTypeUid aId);
1.541 +
1.542 +private:
1.543 +
1.544 + /**
1.545 + * From @c CAknControl
1.546 + */
1.547 + IMPORT_C void* ExtensionInterface( TUid aInterface );
1.548 +
1.549 +private: // listbox use only
1.550 +
1.551 + IMPORT_C virtual void CEikListBox_Reserved();
1.552 +
1.553 +private: // data
1.554 +
1.555 + TInt iSpare;
1.556 +};
1.557 +
1.558 +
1.559 +/**
1.560 + * @c CFormattedCellListBoxView draws all the list items and manages
1.561 + * the area of the screen allocated for list itself. In particular,
1.562 + * this class does not handle margins of the whole list.
1.563 + *
1.564 + * @lib avkon
1.565 + */
1.566 +class CFormattedCellListBoxView : public CListBoxView
1.567 + {
1.568 +
1.569 +public: // from CListBoxView
1.570 +
1.571 + /**
1.572 + * From @c CListBoxView.
1.573 + *
1.574 + * Draws every visible item into the specified rectangle.
1.575 + *
1.576 + * @param aClipRect The rectangle to draw into. This is not used.
1.577 + */
1.578 + IMPORT_C void Draw(const TRect* aClipRect = NULL) const;
1.579 +
1.580 + /**
1.581 + * From @c CListBoxView.
1.582 + *
1.583 + * Draws empty list.
1.584 + *
1.585 + * @param aClientRect The rectangle to draw into.
1.586 + */
1.587 + IMPORT_C virtual void DrawEmptyList(const TRect &aClientRect) const;
1.588 +
1.589 + /**
1.590 + * From @c CListBoxView.
1.591 + *
1.592 + * Recalculates the index of the bottom item in the list from the top item
1.593 + * index and the size of the display. This function is called by the owning
1.594 + * list box control when either the size of the list box or the number of
1.595 + * items in its model changes.
1.596 + */
1.597 + IMPORT_C virtual void CalcBottomItemIndex();
1.598 +
1.599 +private: // overridden from CListBoxView
1.600 +
1.601 + IMPORT_C virtual TAny* Reserved_1();
1.602 + };
1.603 +
1.604 +
1.605 +#endif // __EIKFRLB_H__
1.606 +
1.607 +// End of File