diff -r e1b950c65cb4 -r 837f303aceeb epoc32/include/mw/eikfrlb.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/epoc32/include/mw/eikfrlb.h Wed Mar 31 12:33:34 2010 +0100 @@ -0,0 +1,604 @@ +/* +* Copyright (c) 2002 Nokia Corporation and/or its subsidiary(-ies). +* All rights reserved. +* This component and the accompanying materials are made available +* under the terms of "Eclipse Public License v1.0" +* which accompanies this distribution, and is available +* at the URL "http://www.eclipse.org/legal/epl-v10.html". +* +* Initial Contributors: +* Nokia Corporation - initial contribution. +* +* Contributors: +* +* Description: +* +*/ + +// EIKFRLB.H +// +// Copyright (c) 1997-2001 Symbian Ltd. All rights reserved. +// +#if !defined(__EIKFRLB_H__) +#define __EIKFRLB_H__ + +#include +#include +#include +#include + +class CFormattedCellListBoxData; + +/** + * @c CFormattedCellListBoxItemDrawer draws a single list item and manages + * list item properties. + * + * @lib avkon + */ +class CFormattedCellListBoxItemDrawer : public CTextListItemDrawer + { +public: + + /** + * C++ default constructor. + * + * @param aTextListBoxModel The list box model class. + * @param aFont Font to be used in listbox. + * @param aFormattedCellData Pointer to the list layout drawer class. + */ + IMPORT_C CFormattedCellListBoxItemDrawer( + MTextListBoxModel* aTextListBoxModel, + const CFont* aFont, + CFormattedCellListBoxData* aFormattedCellData); + + /** + * Destructor. + */ + IMPORT_C ~CFormattedCellListBoxItemDrawer(); + + /** + * Gets the list layout drawer. + * + * @return Pointer to the list layout drawer object. + */ + IMPORT_C CFormattedCellListBoxData* FormattedCellData() const; + + /** + * Gets the list layout drawer. + * + * @return Pointer to the list layout drawer object. + */ + IMPORT_C CFormattedCellListBoxData* ColumnData() const; + // for compability with columnlistbox itemdrawer + + /** + * Draws an empty item to the list box. + * + * @param aItemIndex Not used. + * @param aItemRectPos Position for the list box item rectangle. + * @param aViewIsDimmed Not used. + */ + IMPORT_C virtual void DrawEmptyItem(TInt aItemIndex, TPoint aItemRectPos, + TBool aViewIsDimmed) const; + + /** + * This function sets top item index. + * + * @param aTop Item index value. + */ + IMPORT_C void SetTopItemIndex(TInt aTop); + + /** + * List item index and color and style properties. + */ + struct SListProperties + { + /** List box item index. */ + TInt iItem; // must be first + + /** Colour and style properties for the list item. */ + TListItemProperties iProperties; + }; + + /** + * Clears all properties. + */ + IMPORT_C void ClearAllPropertiesL(); + + /** + * The SetProperties is convenience method for normal cases. + * NOTE that it does NOT work correctly if you can insert/delete + * items from the list -- You need to update all properties if + * any changes to the item text array happen! Often it is convenient + * to override the @c Properties() method. Further, use this only + * for small lists. + * + * It has been implemented as sorted list of (index,Property) pairs. + * + * If you're using find, aItemIndex for this method is the same as you give + * in @c MdcaPoint() points the default @c Properties() does conversion + * between indexes. + * + * @param aItemIndex List box item index. + * @param properties Colour and style properties for the list box item. + */ + IMPORT_C void SetPropertiesL(TInt aItemIndex, TListItemProperties properties); + + /** + * Function for getting properties of a certain list box item. + * + * @param aItemIndex The listbox item index. + * @return Colour and style properties of wanted + * list box item. + */ + IMPORT_C virtual TListItemProperties Properties(TInt aItemIndex) const; + + /** + * Gets list box item cell size. + * + * @return The list box item cell size. + */ + TSize LafItemSize() { return iItemCellSize; } + +public: // from CTextListItemDrawer + + /** + * From @c CTextListItemDrawer. + * + * Draw an item in a list box. + * + * @param aItemIndex The index into the model's item array of the item + * to draw. + * @param aItemTextRect The item’s text rectangle. + * @param aItemIsCurrent @c ETrue if the item is current. @c EFalse + * otherwise. + * @param aViewIsEmphasized @c ETrue if the view is emphasized. @c EFalse + * otherwise. + * @param aItemIsSelected @c ETrue if the item is selected. @c EFalse + * otherwise. + */ + IMPORT_C void DrawItemText(TInt aItemIndex,const TRect& aItemTextRect, + TBool aItemIsCurrent, TBool aViewIsEmphasized, + TBool aItemIsSelected) const; + + /** + * From @c CTextListItemDrawer. + * + * Draws an item tick mark. + * + * A tick mark is used in multiple selection lists to indicate the item is + * selected. + * + * This function is invoked by the framework to draw an item mark if + * @c iDrawMark is set. The mark should be drawn into this list item + * drawer's graphics context; by default, @c DrawItemMark() draws a tick + * using the standard symbol font. + * + * This function does not need to be re-implemented for derived classes + * which do not draw item marks. + * + * @param aItemIsSelected Whether the item to draw for is selected. + * @param aViewIsDimmed Whether the item is dimmed. + * @param aMarkPos Position of the mark. + */ + IMPORT_C void DrawItemMark(TBool aItemIsSelected, TBool aViewIsDimmed, + const TPoint& aMarkPos) const; + +public: // from CListItemDrawer + + /** + * From @c CListItemDrawer. + * + * Gets the minimum size of a cell based on the font and the number of + * characters in the cell. + * + * @return The minimum size for a cell in pixels. + */ + IMPORT_C TSize MinimumCellSize() const; + + /** + * From @c CListItemDrawer. + * + * Gets the width in pixels of the specified item. + * + * @param aItemIndex The index of the item for which the width is obtained. + * @return The specified item's width in pixels. + */ + IMPORT_C TInt ItemWidthInPixels(TInt aItemIndex) const; + + /** + * From @c CListItemDrawer. + * + * Sets the item cell size. + * + * The cell size is the on-screen size of the entire item, including its + * text and its item mark. + * + * @param aSizeInPixels New size for the item cell. + */ + IMPORT_C void SetItemCellSize(const TSize& aSizeInPixels); + +protected: + + /** + * Draws current item rectangle. + * + * @param aRect Current item rectangle. + */ + void DrawCurrentItemRect(const TRect& aRect) const; + + /** + * @c WordWrapListItem is used with @c CAknDouble* style listboxes. + * If listbox does not have 2nd line defined, @c WordWrapListItem + * wraps 1st line to 2nd line, if text does not fit to 1st line. + * If listbox does have 2nd line defined, this method truncates + * both lines. + * + * @internal + * @param aTarget Where to place wrapped item string + * @param aItemString Text to be wrapped + * @param aFirstIndex index of 1st subcell to wrap + * @param aSecondIndex index of 2nd subcell + */ + void WordWrapListItem( TPtr& aTarget, + const TDesC &aItemString, + TInt aFirstIndex, + TInt aSecondIndex, + TInt aItemIndex ) const; + /** + * @internal + */ + void DrawBackgroundAndSeparatorLines( const TRect& aItemTextRect, + TBool aDrawSeparator ) const; + + +private: + + IMPORT_C void CFormattedCellListBoxItemDrawer_Reserved(); + +protected: + + /** + * Top item index. + */ + TInt iTopItemIndex; + + /** + * Array for list box item's properties. + * Own. + */ + CArrayFix* iPropertyArray; + +private: + + TInt iSpare; + }; + + +/** + * Avkon base class similar to uikon's column listbox. + * + * @code + * ListBox <>--> View ---> ItemDrawer ---> Model + * ListBox <>--> ItemDrawer <>---> Data + * ListBox <>--> Model <>---> MDesCArray <--- Array <>---> Engine + * @endcode + * + * Content for list items are tab-separated strings. + * + * See concrete classes derived from @c CEikFormattedCellListBox for details. + * + * Starting from 3.0 listbox uses highlight animations. Starting and stopping + * animation is connected to focus events. To support highlight animations + * properly you have to make sure that the list has focus when it has 'visual + * focus'. Common issues: + * - In many cases list is in a container which sits on top of the control + * stack. The container receives all focus events and should hand them to the + * list too. E.g. + * @code void CContainer::FocusChanged( TDrawNow aDrawNow ) + * { + * ... some code ... + * if( iListBox ) + * iListBox->SetFocus( IsFocused(), aDrawNow ); + * } + * @endcode + * - When switching components programmatically, e.g. from one list to another + * in the same view, make sure that you remove focus from the other + * component. + * - In more complex cases you may have to add a dummy interceptor control to + * the top of control stack to hand focus events to list. + * - Make sure you handle resource changes correctly. If resource handle chain + * is solid it should reach @c CCoeControl::HandleResourceChange, which + * informs child components about resource change. + * + * See methods + * @c CEikListBox::ConstructL() + * @c CEikTextListBox::SetItemTextArray() + * @c CEikFormattedCellListBoxData::SetIconArray() + * + * Related flags for dialogs (@c avkon.hrh) + * @c EAknDialogSelectionList + * @c EAknDialogMenuList + * @c EAknDialogMultiselectionList + * + * Check also: + * @c CAknSelectionListDialog (@c aknselectionlist.h) + * @c CAknMarkableListDialog (@c aknselectionlist.h) + * @c CAknPopupList (@c aknpopup.h) + * @c CAknListQueryDialog (@c aknquerydialog.h) + * @c CAknColumnListBox (@c aknlists.h) + * + * @lib avkon + */ +class CEikFormattedCellListBox : public CEikTextListBox + { + +public: + + /** + * C++ default constructor. + */ + IMPORT_C CEikFormattedCellListBox(); + + /** + * Constructs list box from resource file. See @c LISTBOX resource + * definition. + * + * Flags: + * @c EAknListBoxSelectionList, + * @c EAknListBoxMenuList, + * @c EAknListBoxMarkableList, + * @c EAknListBoxMultiselectionList, + * @c EAknListBoxViewerFlags + * + * @param aReader Reference to resource reader @c TResourceReader object. + */ + IMPORT_C void ConstructFromResourceL(TResourceReader& aReader); + + /** + * By default Symbian 2nd phase constructor is private. Must be called + * if resource data is not used. + * + * @param aParent Pointer to @c CCoeControl class, parent control. + * @param aFlags Flags for @c CEikListBox constructor. Possible flags : + * @c EAknListBoxSelectionList, + * @c EAknListBoxMenuList, + * @c EAknListBoxMarkableList, + * @c EAknListBoxMultiselectionList, + * @c EAknListBoxViewerFlags + */ + IMPORT_C void ConstructL(const CCoeControl* aParent, TInt aFlags); + +public: + + /** + * Gets model class of the list box. + * + * @return Pointer to list box model class instance. + */ + IMPORT_C CTextListBoxModel* Model() const; + + /** + * Gets list box item drawer. + * + * @return Pointer to item drawer object. + */ + IMPORT_C CFormattedCellListBoxItemDrawer* ItemDrawer() const; + + /** + * Sets icon sizes for visible list box items. + */ + void SetIconSizes(); + +public: + + /** + * Enable or disable logical to visual reordering in listbox data text + * drawing. By default, it is enabled. This has any effect only when + * bidirectional text is rendered. + * + * If you convert text to visual order prior to passing it to the listbox + * (for example by wrapping text to lines with methods in + * @c AknBidiTextUtils), then you should disable conversion in listbox + * by calling this method. + * + * @since S60 2.0 + * @param aUseConversion If @c ETrue enable conversion. + */ + IMPORT_C void UseLogicalToVisualConversion( TBool aUseConversion ); + +public: + + /** + * This method needs to be called to enable extended drawing features such + * as skinning, pictograph drawing and marquee text in the listbox draw + * routine. + * + * Methods @c CEikFormattedCellListBox::ConstructL and + * @c CEikFormattedCellListBox::ConstructFromResourceL call this method. + * So, you only need to call this if your listbox implementation does not + * call either of those. + * + * This method can be safely called more than once. + * Item drawer must be created before calling this method, or a panic is + * raised. + * + * @since S60 2.6 + * @panic EAknPanicListBoxItemDrawerNotCreated Panics if the item drawer + * for the current class has not been defined. + */ + IMPORT_C void EnableExtendedDrawingL(); + + /** + * Enables/disables list stretching. When a list is stretched its second line + * is moved after the first line. This is intented for devices with a large + * screen. This feature might be set as default by a product specific flag. + * + * Item drawer must be created before calling this method. + * + * @since S60 3.1 + * @param aEnabled ETrue to enable list stretching. + */ + IMPORT_C void EnableStretching( const TBool aEnabled ); + + /** + * Hides the second row of a double style listbox. This feature is disabled + * by default. + * + * @since S60 3.1 + * @param aHide ETrue to hide the second row. + */ + IMPORT_C void HideSecondRow( const TBool aHide ); +protected: + + /** + * Creates item draver for the listbox. + */ + IMPORT_C virtual void CreateItemDrawerL(); + + /** + * From @c CEikListBox. + * + * Rounds down the height of the rectangle (if necessary) so that only + * a whole number of items can be displayed inside the list box. + * + * @param aRect The rectangle to be modified. + * @return The number of pixels reduced. + */ + IMPORT_C virtual TInt AdjustRectHeightToWholeNumberOfItems( + TRect &aRect) const; + +public: // from CEikListBox + + /** + * From @c CEikListBox. + * + * Creates the list box view. + * + * @return Pointer to new list box view class instance. + */ + IMPORT_C CListBoxView* MakeViewClassInstanceL(); + + /** + * From @c CEikListBox. + * + * Handles focus changes. + * + * The function emphasizes or de-emphasizes the view as needed, + * and shows or hides the matcher cursor. + * + * @param aDrawNow If @c EDrawNow, a redraw is performed immediately. + */ + IMPORT_C void FocusChanged(TDrawNow aDrawNow); + +public: // from CCoeControl + + /** + * From @c CCoeControl. + * + * Gets the list of logical colors used to draw the control. + * + * @param aColorUseList The color list. + */ + IMPORT_C void GetColorUseListL( + CArrayFix& aColorUseList) const; + + /** + * From @c CCoeControl. + * + * Handles a change to the control's resources. + * + * @param aType A message UID value. + */ + IMPORT_C void HandleResourceChange(TInt aType); + + /** + * From @c CCoeControl. + * + * Handles pointer events. + * + * @param aPointerEvent The pointer event. + */ + IMPORT_C void HandlePointerEventL(const TPointerEvent& aPointerEvent); + +protected: // from MObjectProvider + + /** + * From @c MObjectProvider. + * + * Retrieves an object of the same type as that encapsulated in aId. This + * function is used to allow controls to ask their owners for access to + * other objects that they own. + * + * @param aId An encapsulated object type ID. + * @return Encapsulates the pointer to the object provided. + * Note that the encapsulated pointer may be NULL. + */ + IMPORT_C virtual TTypeUid::Ptr MopSupplyObject(TTypeUid aId); + +private: + + /** + * From @c CAknControl + */ + IMPORT_C void* ExtensionInterface( TUid aInterface ); + +private: // listbox use only + + IMPORT_C virtual void CEikListBox_Reserved(); + +private: // data + + TInt iSpare; +}; + + +/** + * @c CFormattedCellListBoxView draws all the list items and manages + * the area of the screen allocated for list itself. In particular, + * this class does not handle margins of the whole list. + * + * @lib avkon + */ +class CFormattedCellListBoxView : public CListBoxView + { + +public: // from CListBoxView + + /** + * From @c CListBoxView. + * + * Draws every visible item into the specified rectangle. + * + * @param aClipRect The rectangle to draw into. This is not used. + */ + IMPORT_C void Draw(const TRect* aClipRect = NULL) const; + + /** + * From @c CListBoxView. + * + * Draws empty list. + * + * @param aClientRect The rectangle to draw into. + */ + IMPORT_C virtual void DrawEmptyList(const TRect &aClientRect) const; + + /** + * From @c CListBoxView. + * + * Recalculates the index of the bottom item in the list from the top item + * index and the size of the display. This function is called by the owning + * list box control when either the size of the list box or the number of + * items in its model changes. + */ + IMPORT_C virtual void CalcBottomItemIndex(); + +private: // overridden from CListBoxView + + IMPORT_C virtual TAny* Reserved_1(); + }; + + +#endif // __EIKFRLB_H__ + +// End of File