1 /*

     2 * Copyright (c) 2002 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description: 

    15 *

    16 */

    17 

    18 // EIKFRLB.H

    19 //

    20 // Copyright (c) 1997-2001 Symbian Ltd.  All rights reserved.

    21 //

    22 #if !defined(__EIKFRLB_H__)

    23 #define __EIKFRLB_H__

    24 

    25 #include <eiklbi.h>

    26 #include <eiklbv.h>

    27 #include <eiktxlbm.h>

    28 #include <eiktxlbx.h>

    29 

    30 class CFormattedCellListBoxData;

    31 

    32 /**

    33  *  @c CFormattedCellListBoxItemDrawer draws a single list item and manages

    34  *  list item properties.

    35  *

    36  *  @lib avkon

    37  */

    38 class CFormattedCellListBoxItemDrawer : public CTextListItemDrawer

    39 	{

    40 public:

    41 

    42     /**

    43      * C++ default constructor.

    44      * 

    45      * @param aTextListBoxModel The list box model class.

    46      * @param aFont Font to be used in listbox.

    47      * @param aFormattedCellData Pointer to the list layout drawer class.

    48      */

    49 	IMPORT_C CFormattedCellListBoxItemDrawer(

    50             MTextListBoxModel* aTextListBoxModel, 

    51             const CFont* aFont, 

    52             CFormattedCellListBoxData* aFormattedCellData);

    53 	

    54     /**

    55      * Destructor.

    56      */

    57     IMPORT_C ~CFormattedCellListBoxItemDrawer();

    58 

    59     /**

    60      * Gets the list layout drawer.

    61      * 

    62      * @return Pointer to the list layout drawer object.

    63      */

    64 	IMPORT_C CFormattedCellListBoxData* FormattedCellData() const;

    65 

    66     /**

    67      * Gets the list layout drawer.

    68      * 

    69      * @return Pointer to the list layout drawer object.

    70      */

    71 	IMPORT_C CFormattedCellListBoxData* ColumnData() const; 

    72     // for compability with columnlistbox itemdrawer

    73 

    74     /**

    75      * Draws an empty item to the list box.

    76      * 

    77      * @param aItemIndex Not used.

    78      * @param aItemRectPos Position for the list box item rectangle.

    79      * @param aViewIsDimmed Not used.

    80      */

    81     IMPORT_C virtual void DrawEmptyItem(TInt aItemIndex, TPoint aItemRectPos, 

    82                                         TBool aViewIsDimmed) const;

    83 

    84     /**

    85      * This function sets top item index.

    86      * 

    87      * @param aTop Item index value.

    88      */

    89 	IMPORT_C void SetTopItemIndex(TInt aTop);

    90 

    91     /**

    92      * List item index and color and style properties.

    93      */

    94 	struct SListProperties 

    95 	    {

    96         /** List box item index. */

    97         TInt iItem; // must be first

    98 

    99         /** Colour and style properties for the list item. */

   100         TListItemProperties iProperties;

   101 	    };

   102 

   103     /**

   104      * Clears all properties.

   105      */

   106 	IMPORT_C void ClearAllPropertiesL();

   107 

   108     /** 

   109      * The SetProperties is convenience method for normal cases.

   110      * NOTE that it does NOT work correctly if you can insert/delete

   111      * items from the list -- You need to update all properties if

   112      * any changes to the item text array happen! Often it is convenient

   113      * to override the @c Properties() method. Further, use this only

   114      * for small lists.

   115      *

   116      * It has been implemented as sorted list of (index,Property) pairs.

   117      * 

   118      * If you're using find, aItemIndex for this method is the same as you give

   119      * in @c MdcaPoint() points the default @c Properties() does conversion 

   120      * between indexes.

   121      * 

   122      * @param aItemIndex List box item index.

   123      * @param properties Colour and style properties for the list box item.

   124      */

   125     IMPORT_C void SetPropertiesL(TInt aItemIndex, TListItemProperties properties);

   126 

   127     /**

   128      * Function for getting properties of a certain list box item.

   129      * 

   130      * @param aItemIndex The listbox item index.

   131      * @return Colour and style properties of wanted

   132      *         list box item.

   133      */

   134 	IMPORT_C virtual TListItemProperties Properties(TInt aItemIndex) const;

   135 

   136     /**

   137      * Gets list box item cell size.

   138      * 

   139      * @return The list box item cell size.

   140      */

   141 	TSize LafItemSize() { return iItemCellSize; }

   142 

   143 public: // from CTextListItemDrawer

   144 

   145     /**

   146      * From @c CTextListItemDrawer.

   147      *

   148      * Draw an item in a list box.

   149      * 

   150      * @param aItemIndex The index into the model's item array of the item 

   151      *        to draw.

   152      * @param aItemTextRect The item’s text rectangle. 

   153      * @param aItemIsCurrent @c ETrue if the item is current. @c EFalse 

   154      *        otherwise.

   155      * @param aViewIsEmphasized @c ETrue if the view is emphasized. @c EFalse

   156      *        otherwise.

   157      * @param aItemIsSelected @c ETrue if the item is selected. @c EFalse 

   158      *        otherwise.

   159      */

   160 	IMPORT_C void DrawItemText(TInt aItemIndex,const  TRect& aItemTextRect,

   161                                TBool aItemIsCurrent, TBool aViewIsEmphasized, 

   162                                TBool aItemIsSelected) const;

   163 

   164     /**

   165      * From @c CTextListItemDrawer.

   166      *

   167      * Draws an item tick mark. 

   168      *

   169      * A tick mark is used in multiple selection lists to indicate the item is

   170      * selected.

   171      *

   172      * This function is invoked by the framework to draw an item mark if 

   173      * @c iDrawMark is set. The mark should be drawn into this list item 

   174      * drawer's graphics context; by default, @c DrawItemMark() draws a tick 

   175      * using the standard symbol font.

   176      * 

   177      * This function does not need to be re-implemented for derived classes 

   178      * which do not draw item marks.

   179      * 

   180      * @param aItemIsSelected Whether the item to draw for is selected.

   181      * @param aViewIsDimmed Whether the item is dimmed. 

   182      * @param aMarkPos Position of the mark.

   183      */

   184 	IMPORT_C void DrawItemMark(TBool aItemIsSelected, TBool aViewIsDimmed, 

   185                                const TPoint& aMarkPos) const;

   186 

   187 public: // from CListItemDrawer

   188 

   189     /**

   190      * From @c CListItemDrawer.

   191      *

   192      * Gets the minimum size of a cell based on the font and the number of 

   193      * characters in the cell.

   194      * 

   195      * @return The minimum size for a cell in pixels.

   196      */

   197 	IMPORT_C TSize MinimumCellSize() const;

   198 

   199     /**

   200      * From @c CListItemDrawer.

   201      *

   202      * Gets the width in pixels of the specified item.

   203      * 

   204      * @param aItemIndex The index of the item for which the width is obtained.

   205      * @return The specified item's width in pixels.

   206      */

   207 	IMPORT_C TInt ItemWidthInPixels(TInt aItemIndex) const; 

   208 

   209     /**

   210      * From @c CListItemDrawer.

   211      *

   212      * Sets the item cell size.

   213      *

   214      * The cell size is the on-screen size of the entire item, including its 

   215      * text and its item mark.

   216      * 

   217      * @param aSizeInPixels New size for the item cell.

   218      */

   219     IMPORT_C void SetItemCellSize(const TSize& aSizeInPixels);

   220 

   221 protected:

   222     

   223     /**

   224      * Draws current item rectangle.

   225      * 

   226      * @param aRect Current item rectangle.

   227      */

   228 	void DrawCurrentItemRect(const TRect& aRect) const;

   229 

   230     /**

   231      * @c WordWrapListItem is used with @c CAknDouble* style listboxes.

   232      * If listbox does not have 2nd line defined, @c WordWrapListItem

   233      * wraps 1st line to 2nd line, if text does not fit to 1st line.

   234      * If listbox does have 2nd line defined, this method truncates

   235      * both lines.

   236      *

   237      * @internal

   238      * @param aTarget Where to place wrapped item string

   239      * @param aItemString Text to be wrapped

   240      * @param aFirstIndex index of 1st subcell to wrap

   241      * @param aSecondIndex index of 2nd subcell

   242      */

   243     void WordWrapListItem( TPtr& aTarget, 

   244                            const TDesC &aItemString, 

   245                            TInt aFirstIndex, 

   246                            TInt aSecondIndex,

   247                            TInt aItemIndex ) const;

   248     /**

   249     * @internal

   250     */

   251     void DrawBackgroundAndSeparatorLines( const TRect& aItemTextRect ) const;

   252                         

   253 

   254 private:

   255 

   256 	IMPORT_C void CFormattedCellListBoxItemDrawer_Reserved();

   257 

   258 protected:

   259 

   260     /**

   261      * Top item index.

   262      */

   263 	TInt iTopItemIndex;

   264 

   265     /**

   266      * Array for list box item's properties.

   267      * Own.

   268      */

   269 	CArrayFix<SListProperties>* iPropertyArray;

   270 

   271 private:

   272 

   273 	TInt iSpare;

   274 	};

   275 

   276 

   277 /** 

   278  * Avkon base class similar to uikon's column listbox.

   279  *

   280  * @code

   281  *  ListBox <>--> View ---> ItemDrawer ---> Model

   282  *  ListBox <>--> ItemDrawer <>---> Data

   283  *  ListBox <>--> Model <>---> MDesCArray <--- Array <>---> Engine

   284  * @endcode

   285  * 

   286  * Content for list items are tab-separated strings.

   287  *

   288  * See concrete classes derived from @c CEikFormattedCellListBox for details.

   289  *

   290  * Starting from 3.0 listbox uses highlight animations. Starting and stopping

   291  * animation is connected to focus events. To support highlight animations

   292  * properly you have to make sure that the list has focus when it has 'visual

   293  * focus'. Common issues:

   294  * - In many cases list is in a container which sits on top of the control

   295  *   stack. The container receives all focus events and should hand them to the

   296  *   list too. E.g. 

   297  * @code       void CContainer::FocusChanged( TDrawNow aDrawNow )

   298  *                 {

   299  *                 ... some code ...

   300  *                 if( iListBox )

   301  *                     iListBox->SetFocus( IsFocused(), aDrawNow );

   302  *                 }

   303  * @endcode

   304  * - When switching components programmatically, e.g. from one list to another

   305  *   in the same view, make sure that you remove focus from the other

   306  *   component.

   307  * - In more complex cases you may have to add a dummy interceptor control to

   308  *   the top of control stack to hand focus events to list.

   309  * - Make sure you handle resource changes correctly. If resource handle chain

   310  *   is solid it should reach @c CCoeControl::HandleResourceChange, which 

   311  *   informs child components about resource change.

   312  *

   313  * See methods

   314  *   @c CEikListBox::ConstructL()

   315  *   @c CEikTextListBox::SetItemTextArray()

   316  *   @c CEikFormattedCellListBoxData::SetIconArray()

   317  * 

   318  * Related flags for dialogs (@c avkon.hrh)

   319  *   @c EAknDialogSelectionList

   320  *   @c EAknDialogMenuList

   321  *   @c EAknDialogMultiselectionList

   322  *

   323  * Check also:

   324  *   @c CAknSelectionListDialog (@c aknselectionlist.h)

   325  *   @c CAknMarkableListDialog  (@c aknselectionlist.h)

   326  *   @c CAknPopupList           (@c aknpopup.h)

   327  *   @c CAknListQueryDialog     (@c aknquerydialog.h)

   328  *   @c CAknColumnListBox       (@c aknlists.h)

   329  *

   330  *  @lib avkon

   331  */

   332 class CEikFormattedCellListBox : public CEikTextListBox 

   333 	{

   334 

   335 public:

   336 

   337     /**

   338      * C++ default constructor.

   339      */

   340 	IMPORT_C CEikFormattedCellListBox();

   341 

   342     /**

   343      * Constructs list box from resource file. See @c LISTBOX resource 

   344      * definition.

   345      *

   346      * Flags: 

   347      *    @c EAknListBoxSelectionList, 

   348      *    @c EAknListBoxMenuList, 

   349      *    @c EAknListBoxMarkableList, 

   350      *    @c EAknListBoxMultiselectionList, 

   351      *    @c EAknListBoxViewerFlags

   352      * 

   353      * @param aReader Reference to resource reader @c TResourceReader object.

   354      */

   355 	IMPORT_C void ConstructFromResourceL(TResourceReader& aReader);

   356 	

   357     /** 

   358      * By default Symbian 2nd phase constructor is private. Must be called 

   359      * if resource data is not used.

   360      * 

   361      * @param aParent Pointer to @c CCoeControl class, parent control.

   362      * @param aFlags Flags for @c CEikListBox constructor. Possible flags : 

   363      *        @c EAknListBoxSelectionList, 

   364      *        @c EAknListBoxMenuList, 

   365      *        @c EAknListBoxMarkableList, 

   366      *        @c EAknListBoxMultiselectionList, 

   367      *        @c EAknListBoxViewerFlags

   368 	 */

   369 	IMPORT_C void ConstructL(const CCoeControl* aParent, TInt aFlags);

   370 

   371 public:

   372 

   373     /**

   374      * Gets model class of the list box.

   375      * 

   376      * @return Pointer to list box model class instance.

   377      */

   378 	IMPORT_C CTextListBoxModel* Model() const;

   379 

   380     /**

   381     * Gets list box item drawer.

   382     * 

   383     * @return Pointer to item drawer object.

   384     */

   385 	IMPORT_C CFormattedCellListBoxItemDrawer* ItemDrawer() const;

   386 

   387     /**

   388     * Sets icon sizes for visible list box items.

   389     */

   390     void SetIconSizes();

   391 

   392 public:

   393 

   394 	/**

   395      * Enable or disable logical to visual reordering in listbox data text

   396      * drawing. By default, it is enabled. This has any effect only when 

   397      * bidirectional text is rendered.

   398      *

   399      * If you convert text to visual order prior to passing it to the listbox

   400      * (for example by wrapping text to lines with methods in 

   401      * @c AknBidiTextUtils), then you should disable conversion in listbox 

   402      * by calling this method.

   403      *

   404      * @since S60 2.0

   405      * @param aUseConversion If @c ETrue enable conversion. 

   406      */

   407 	IMPORT_C void UseLogicalToVisualConversion( TBool aUseConversion );

   408 

   409 public:

   410 

   411     /**

   412      * This method needs to be called to enable extended drawing features such

   413      * as skinning, pictograph drawing and marquee text in the listbox draw

   414      * routine.

   415      *

   416      * Methods @c CEikFormattedCellListBox::ConstructL and

   417      * @c CEikFormattedCellListBox::ConstructFromResourceL call this method. 

   418      * So, you only need to call this if your listbox implementation does not 

   419      * call either of those.

   420      * 

   421      * This method can be safely called more than once.

   422      * Item drawer must be created before calling this method, or a panic is 

   423      * raised.

   424      *

   425      * @since S60 2.6

   426      * @panic EAknPanicListBoxItemDrawerNotCreated Panics if the item drawer 

   427      *        for the current class has not been defined.

   428      */

   429     IMPORT_C void EnableExtendedDrawingL();

   430     

   431     /**

   432     * Enables/disables list stretching. When a list is stretched its second line

   433     * is moved after the first line. This is intented for devices with a large

   434     * screen. This feature might be set as default by a product specific flag.

   435     *

   436     * Item drawer must be created before calling this method.

   437     *

   438     * @since S60 3.1

   439     * @param aEnabled ETrue to enable list stretching.

   440     */

   441     IMPORT_C void EnableStretching( const TBool aEnabled );

   442 

   443     /**

   444     * Hides the second row of a double style listbox. This feature is disabled

   445     * by default.

   446     *

   447     * @since S60 3.1

   448     * @param aHide ETrue to hide the second row.

   449     */

   450     IMPORT_C void HideSecondRow( const TBool aHide );

   451 protected:

   452 

   453     /**

   454      * Creates item draver for the listbox.

   455      */

   456 	IMPORT_C virtual void CreateItemDrawerL();

   457 

   458     /**

   459      * From @c CEikListBox.

   460      *

   461      * Rounds down the height of the rectangle (if necessary) so that only

   462      * a whole number of items can be displayed inside the list box.

   463      *

   464      * @param aRect The rectangle to be modified.

   465      * @return The number of pixels reduced.

   466      */

   467 	IMPORT_C virtual TInt AdjustRectHeightToWholeNumberOfItems(

   468                                     TRect &aRect) const;

   469 

   470 public: // from CEikListBox

   471 

   472     /**

   473      * From @c CEikListBox.

   474      *

   475      * Creates the list box view.

   476      * 

   477      * @return Pointer to new list box view class instance.

   478      */

   479 	IMPORT_C CListBoxView* MakeViewClassInstanceL();

   480 

   481     /**

   482      * From @c CEikListBox.

   483      *

   484      * Handles focus changes.

   485      *

   486      * The function emphasizes or de-emphasizes the view as needed, 

   487      * and shows or hides the matcher cursor.

   488      *

   489      * @param aDrawNow If @c EDrawNow, a redraw is performed immediately.

   490      */

   491     IMPORT_C void FocusChanged(TDrawNow aDrawNow);

   492 

   493 public: // from CCoeControl

   494 

   495     /**

   496      * From @c CCoeControl.

   497      *

   498      * Gets the list of logical colors used to draw the control.

   499      * 

   500      * @param aColorUseList The color list.

   501      */

   502 	IMPORT_C void GetColorUseListL(

   503         CArrayFix<TCoeColorUse>& aColorUseList) const;

   504 	

   505     /**

   506      * From @c CCoeControl.

   507      *

   508      * Handles a change to the control's resources.

   509      *

   510      * @param aType A message UID value.

   511      */

   512     IMPORT_C void HandleResourceChange(TInt aType);

   513     

   514     /**

   515      * From @c CCoeControl.

   516      *

   517      * Handles pointer events.

   518      *

   519      * @param aPointerEvent The pointer event.

   520      */

   521     IMPORT_C void HandlePointerEventL(const TPointerEvent& aPointerEvent);

   522 

   523 protected: // from MObjectProvider

   524 

   525     /**

   526      * From @c MObjectProvider.

   527      *

   528      * Retrieves an object of the same type as that encapsulated in aId. This 

   529      * function is used to allow controls to ask their owners for access to 

   530      * other objects that they own.

   531      * 

   532      * @param aId An encapsulated object type ID.

   533      * @return Encapsulates the pointer to the object provided. 

   534      *         Note that the encapsulated pointer may be NULL.

   535      */

   536 	IMPORT_C virtual TTypeUid::Ptr MopSupplyObject(TTypeUid aId);

   537 

   538 private: 

   539 

   540     /**

   541      * From @c CAknControl

   542      */

   543 	IMPORT_C void* ExtensionInterface( TUid aInterface );

   544 

   545 private: // listbox use only

   546 

   547 	IMPORT_C virtual void CEikListBox_Reserved(); 

   548 

   549 private: // data

   550 

   551     TInt iSpare;

   552 };

   553 

   554 

   555 /**

   556  *  @c CFormattedCellListBoxView draws all the list items and manages

   557  *  the area of the screen allocated for list itself. In particular,

   558  *  this class does not handle margins of the whole list.

   559  *

   560  *  @lib avkon

   561  */

   562 class CFormattedCellListBoxView : public CListBoxView

   563 	{

   564 

   565 public: // from CListBoxView

   566 

   567     /**

   568      * From @c CListBoxView.

   569      *

   570      * Draws every visible item into the specified rectangle. 

   571      *

   572      * @param aClipRect The rectangle to draw into. This is not used.

   573      */

   574 	IMPORT_C void Draw(const TRect* aClipRect = NULL) const;

   575 

   576     /**

   577      * From @c CListBoxView.

   578      *

   579      * Draws empty list. 

   580      *

   581      * @param aClientRect The rectangle to draw into.

   582      */

   583 	IMPORT_C virtual void DrawEmptyList(const TRect &aClientRect) const;

   584 	

   585     /**

   586      * From @c CListBoxView.

   587      *

   588      * Recalculates the index of the bottom item in the list from the top item

   589      * index and the size of the display. This function is called by the owning

   590      * list box control when either the size of the list box or the number of 

   591      * items in its model changes. 

   592      */

   593     IMPORT_C virtual void CalcBottomItemIndex();

   594 

   595 private: // overridden from CListBoxView

   596 

   597 	IMPORT_C virtual TAny* Reserved_1();

   598 	};

   599 

   600 

   601 #endif  // __EIKFRLB_H__

   602 

   603 // End of File