1 eikclb.h

     1 /*

     2 * Copyright (c) 1997-1999 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 the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:

    15 *

    16 */

    17 

    18 

    19 #if !defined(__EIKCLB_H__)

    20 #define __EIKCLB_H__

    21 

    22 

    23 #include <eiklbi.h>

    24 #include <eiktxlbx.h>

    25 #include <eiklbed.h>

    26 

    27 class CColumnListBoxData;

    28 

    29 

    30 /**

    31  * Draws the contents of list box items.

    32  *

    33  * @since 5.0

    34  */

    35 class CColumnListBoxItemDrawer : public CTextListItemDrawer

    36     {

    37 

    38 public:

    39     /* C++ default constructor.

    40     *

    41     *  @since 3.2

    42     */

    43             

    44     IMPORT_C CColumnListBoxItemDrawer();

    45             

    46     /**

    47      * C++ default constructor.

    48      *

    49      * Initialises the list box item drawer with the specified model, 

    50      * font and data.

    51      *

    52      * @param aTextListBoxModel The model whose items will be drawn. 

    53      *        This provides the item text that is drawn using 

    54      *        @c DrawItemText().

    55      * @param aFont The font in which the items will be drawn. 

    56      * @param aColumnData The column list box data. This comprises: 

    57      *        the column widths, gaps, fonts, aligments and bitmaps.

    58      */

    59 

    60     IMPORT_C CColumnListBoxItemDrawer(MTextListBoxModel* aTextListBoxModel, 

    61                                       const CFont* aFont, 

    62                                       CColumnListBoxData* aColumnData);

    63  

    64     /**

    65      * Destructor.

    66      */

    67     IMPORT_C ~CColumnListBoxItemDrawer();

    68 

    69     /**

    70      * Gets a pointer to the column list box data as set during construction.

    71      * Does not transfer ownership.

    72      *

    73      * @return The column list box data.

    74      */

    75     IMPORT_C CColumnListBoxData* ColumnData() const;

    76 

    77 public:

    78 

    79 

    80     /** 

    81      * The structure holding given item properties. 

    82      *

    83      * Used for storing information given through @c SetProperties() method.

    84      */

    85 	struct SListProperties 

    86 	    {

    87         /** Item identifier. */

    88 	    TInt iItem; // must be first

    89 

    90         /** Properties of the item. */

    91 	    TListItemProperties iProperties;

    92 	    };

    93 

    94     /**

    95      * Clears all properties from the @c CColumnListBoxItemDrawer.

    96      */

    97     IMPORT_C void ClearAllPropertiesL();

    98 	

    99    

   100     /**

   101      * Set the property for an item with @c aItemIndex 

   102      *

   103      * @param aItemIndex Item index

   104      * @param aProperty The new property setting

   105      * The SetProperties is convinience method for normal cases.

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

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

   108      * any changes to the item text array happen! Often it is convinient

   109      * to override the Properties() method. Further, use this only

   110      * for small lists as it causes O(n) time if you need to set

   111      * all properties.

   112      */

   113     IMPORT_C void SetPropertiesL(TInt aItemIndex, 

   114                                  TListItemProperties aProperty);

   115 

   116     /**

   117      * Get properties for an item. 

   118      *

   119      * @param aItemIndex Item's index for identifying.

   120      * @return Wanted property set.

   121      */

   122     IMPORT_C virtual TListItemProperties Properties(TInt aItemIndex) const;

   123 

   124 public: // from CTextListItemDrawer

   125 

   126     /**

   127      * From @c CTextListItemDrawer.

   128      * 

   129      * Draw item text.

   130      *

   131      * @param aItemIndex Index of the item to draw. 

   132      * @param aItemTextRect Area to draw into. 

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

   134      * @param aViewIsEmphasized @c ETrue if the view is emphasised.

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

   136      */

   137     IMPORT_C void DrawItemText(TInt aItemIndex,

   138                                const TRect& aItemTextRect,

   139                                TBool aItemIsCurrent,

   140                                TBool aViewIsEmphasized, 

   141                                TBool aItemIsSelected) const;

   142     // the next one is for avkon

   143 

   144     /**

   145      * Not used in S60.

   146      */

   147     IMPORT_C void DrawItemMark(TBool aItemIsSelected, 

   148                                TBool aViewIsDimmed, 

   149                                const TPoint& aMarkPos) const;

   150 

   151 public: // from CListItemDrawer

   152 

   153     /**

   154      * From @c CListItemDrawer.

   155      *

   156      * Gets the minimum cell size.

   157      *

   158      * @return The minimum size for a cell. This is 

   159      *         TSize(0, 0) in @c CListItemDrawer.

   160      */

   161     IMPORT_C TSize MinimumCellSize() const;

   162 	

   163     /**

   164      * From @c CListItemDrawer.

   165      *

   166      * Gets the width of the specified item.

   167      *

   168      * @param aItemIndex The index of the item whose width is to be returned. 

   169      * @return The width of the item. This is 0 in @c CListItemDrawer

   170      */

   171     IMPORT_C TInt ItemWidthInPixels(TInt aItemIndex) const;	

   172     

   173     /**

   174      * From @c CListItemDrawer.

   175      *

   176      * Sets the item cell size. 

   177      *

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

   179      * text and its item mark.

   180      *

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

   182      */

   183     IMPORT_C void SetItemCellSize(const TSize& aSizeInPixels);

   184 	

   185     /**

   186      * Get Item Cell Size.

   187      *

   188      * @return Cell size of an item.

   189      */

   190     TSize LafItemSize() { return iItemCellSize; }

   191 

   192 private: // from CListItemDrawer

   193 

   194     IMPORT_C TAny* Reserved_1();

   195 

   196 private: // defining reserved method.

   197 

   198     IMPORT_C void CColumnListBoxItemDrawer_Reserved();

   199 

   200 protected:

   201 

   202     /**

   203      * Draw the item background.

   204      *

   205      * Internal member, not intended for use.

   206      *

   207      * @param aRect Drawing area. 

   208      */

   209     void DrawCurrentItemRect(const TRect& aRect) const;

   210 	

   211     /** 

   212      * Array of properties.

   213      */

   214     CArrayFix<SListProperties>* iPropertyArray;

   215 	

   216     /** 

   217      * Not used. 

   218      */ 

   219     TInt iSpare;

   220     };

   221 

   222 

   223 /**

   224  * Column list box control.

   225  *

   226  * This is a list box whose lines consist of cells that are grouped vertically 

   227  * into columns. The columns can be either textual or graphical, and column 

   228  * widths and fonts can be set explicitly through @c CColumnListBoxData.

   229  *

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

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

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

   233  * focus'. Common issues:

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

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

   236  *   list too. E.g.

   237  *             void CContainer::FocusChanged( TDrawNow aDrawNow )

   238  *                 {

   239  *                 ... some code ...

   240  *                 if( iListBox )

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

   242  *                 }

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

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

   245  *   component.

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

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

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

   249  *   is solid it should reach CCoeControl::HandleResourceChange, which informs

   250  */

   251 class CEikColumnListBox : public CEikTextListBox

   252     {

   253 public:

   254     /**

   255      * C++ default constructor.

   256      */

   257     IMPORT_C CEikColumnListBox();

   258     

   259     /**

   260      * Second-phase construction from a resource.

   261      * 

   262      * This function completes the construction of a column list box, 

   263      * initialising any members from the specified resource reader.

   264      *

   265      * @param aReader A resource file reader

   266      */

   267     IMPORT_C void ConstructFromResourceL( TResourceReader& aReader );

   268     

   269     /**

   270      * By default Symbian 2nd phase constructor is private.

   271      *

   272      * This function completes the construction of a column list box.

   273      *

   274      * @param aParent Parent control for the column list box.

   275      * @param aFlags Flags for the column list box. 

   276      */

   277     IMPORT_C void ConstructL( const CCoeControl* aParent,TInt aFlags=0);

   278     /**

   279     * Not supported in S60.

   280     */

   281     IMPORT_C void EditItemL(TInt aColumn, TInt aMaxLength);

   282 protected:

   283 

   284     /**

   285      * This member is internal and not intended for use.

   286      */

   287     IMPORT_C virtual void CreateItemDrawerL();

   288 

   289     /**

   290      * Creates a new @c CTextListBoxModel 

   291      */

   292     IMPORT_C virtual void CreateModelL();

   293 

   294 public:

   295 

   296     /**

   297      * Gets the list box model.

   298      *

   299      * @return Pointer to the model used by this list box

   300      */

   301     IMPORT_C CTextListBoxModel* Model() const;

   302  

   303     /**

   304      * Gets the object used by this list box to draw its items.

   305      *

   306      * @return A pointer to the list box drawer.

   307      */

   308     IMPORT_C CColumnListBoxItemDrawer* ItemDrawer() const;

   309 

   310     /**

   311      * This method needs to be called to enable extended drawing features 

   312      * such as skinning, pictograph drawing and marquee text in the listbox 

   313      * draw routine.

   314      *

   315      * Methods @c CEikFormattedCellListBox::ConstructL and

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

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

   318      * call either of those.

   319      * 

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

   321      * Item drawer must be created before calling this method, or a 

   322      * panic is raised.

   323      *

   324      * @since S60 2.6

   325      */

   326     IMPORT_C void EnableExtendedDrawingL();

   327 

   328     /**

   329      * Helper function that setst icon sizes for visible list items

   330      */

   331     void SetIconSizes();

   332 

   333     /**

   334     * Enables/disables list stretching. When a column list is stretched its 

   335     * layout is optimized to take advantage of the extra screen space.

   336     * This is intented for devices with a large screen. This feature might be 

   337     * set as default by a product specific flag.

   338     *

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

   340     *

   341     * @since S60 3.1

   342     * @param aEnabled ETrue to enable list stretching.

   343     */

   344     IMPORT_C void EnableStretching( const TBool aEnabled );

   345 public: // from CEikListBox

   346 

   347     /**

   348      * From @c CEikListBox.

   349      * 

   350      * Creates the list box view.

   351      * The function is called by @ ConstructL() to create an instance of 

   352      * the appropriate list box view class for this list box. The returned

   353      * instance is owned by this object, and does not have to have its 

   354      * second-phase constructor run. This function is called by 

   355      * @c CreateViewL().

   356      *

   357      * @return Pointer to a newly constructed list box 

   358      *         view for this object. 

   359      */

   360     IMPORT_C CListBoxView* MakeViewClassInstanceL();

   361     

   362     /**

   363      * From @c CEikListBox

   364      * 

   365      * Handles focus changes.

   366      *

   367      * The function emphasises or de-emphasises the view as needed, and 

   368      * shows or hides the matcher cursor.

   369      *

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

   371      */

   372     IMPORT_C void FocusChanged(TDrawNow aDrawNow);

   373 

   374 public:	// from CCoeControl

   375 

   376     /**

   377      * From @c CCoeControl.

   378      *

   379      * Not used in S60

   380      * @param aColorUseList The colour list

   381      */

   382     IMPORT_C void GetColorUseListL(

   383                         CArrayFix<TCoeColorUse>& aColorUseList) const;

   384 

   385     /**

   386      * From @c CCoeControl.

   387      *

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

   389      *

   390      * The types of resources handled are those which are shared across 

   391      * the environment, e.g. colours or fonts. For colour scheme changes, 

   392      * @c DrawDeferred() is called in order to redraw the control.

   393      * 

   394      * If overriding @c HandleResourceChange(), the implementation must 

   395      * include a base call to @c CCoeControl's @c HandleResourceChange().

   396      * 

   397      * @param aType A message UID value

   398      */

   399     IMPORT_C void HandleResourceChange(TInt aType);

   400 	

   401     /**

   402      * From @c CCoeControl.

   403      *

   404      * Retrieves an object of the same type as that encapsulated in @c aId.

   405      * 

   406      * This function is used to allow controls to ask their owners for 

   407      * access to other objects that they own.

   408      * 

   409      * Other than in the case where NULL is returned, the object returned 

   410      * must be of the same object type - that is, the @c ETypeId member of the 

   411      * object pointed to by the pointer returned by this function must be 

   412      * equal to the @c iUid member of @c aUid.

   413      * 

   414      * @param aUid An encapsulated object type ID.

   415      * @return Pointer to the type UID of the wanted object. 

   416      */

   417     IMPORT_C TTypeUid::Ptr MopSupplyObject(TTypeUid aUid);

   418     

   419     /**

   420      * From @c CCoeControl.

   421      *

   422      * Handles pointer events.

   423      *

   424      * This function gets called whenever a pointer event occurs in the 

   425      * control, i.e. when the pointer is within the control's extent, or when 

   426      * the control has grabbed the pointer. The control should implement this 

   427      * function to handle pointer events.

   428      * 

   429      * Note: events of type @c EButton1Down are processed before 

   430      * @c HandlePointerEventL() is called, in order to transfer keyboard 

   431      * focus to the control in which the @c EButton1Down event occurred.

   432      * 

   433      * If overriding @c HandlePointerEventL(), the implementation must 

   434      * include a base call to @c CCoeControl's @c HandlePointerEventL().

   435      *

   436      * @param aPointerEvent The pointer event

   437      */

   438     IMPORT_C void HandlePointerEventL(const TPointerEvent& aPointerEvent);

   439 private:

   440     /**

   441     * From CAknControl

   442     */

   443     IMPORT_C void* ExtensionInterface( TUid aInterface );

   444 private:

   445     IMPORT_C virtual void CEikListBox_Reserved(); // listbox use only

   446 private: // data

   447     TInt iSpare;

   448     };

   449 

   450 /**

   451  * The @c CEikColumnListBoxEditor class implements an item editor for 

   452  * column list boxes. 

   453  * Not supported in S60

   454  * @since ER5U

   455  */

   456 class CEikColumnListBoxEditor : public CEikListBoxTextEditor

   457     {

   458 public:

   459     IMPORT_C CEikColumnListBoxEditor(MListBoxModel* aModel);

   460     IMPORT_C ~CEikColumnListBoxEditor();

   461     IMPORT_C void ConstructL(TInt aColumn);   // just set column index

   462 public: // from MEikListBoxEditor

   463     IMPORT_C TPtrC ItemText();

   464     IMPORT_C TBool UpdateModelL();

   465 public: // From CCoeControl

   466     IMPORT_C void HandlePointerEventL(const TPointerEvent& aPointerEvent);    

   467 protected:

   468     IMPORT_C TInt Column() const;

   469 private:

   470     /**

   471     * From CAknControl

   472     */

   473     IMPORT_C void* ExtensionInterface( TUid aInterface );

   474 private:

   475     TInt iColumnIndex; // refers to list box column

   476     };

   477 

   478 class CColumnListBoxView : public CListBoxView

   479     {

   480 public: // from CListBoxView

   481 

   482     /**

   483      * From @c CListBoxView 

   484      * Draws every visible item into the specified rectangle. 

   485      *

   486      * As implemented in @c CListBoxView, this function's argument is 

   487      * ignored and the internal viewing rectangle is used. See @c SetViewRect().

   488      *

   489      * @param aClipRect = NULL The rectangle to draw into, this is ignored

   490      */

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

   492     

   493     /**

   494      * From @c CListBoxView

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

   496      * index and the size of the display. 

   497      *

   498      * This function is called by the owning list box control when either the 

   499      * size of the list box or the number of items in its model changes.

   500      */

   501 	IMPORT_C virtual void CalcBottomItemIndex();

   502 

   503 private: // overridden from CListBoxView	

   504 

   505     IMPORT_C virtual TAny* Reserved_1();

   506 

   507 private: // data

   508     TInt iSpare;

   509     };

   510 

   511 #endif // __EIKCLB_H__

   512 

   513 // End of File