1.1 --- a/epoc32/include/mw/eikclb.h Tue Nov 24 13:55:44 2009 +0000
1.2 +++ b/epoc32/include/mw/eikclb.h Tue Mar 16 16:12:26 2010 +0000
1.3 @@ -1,1 +1,513 @@
1.4 -eikclb.h
1.5 +/*
1.6 +* Copyright (c) 1997-1999 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:
1.19 +*
1.20 +*/
1.21 +
1.22 +
1.23 +#if !defined(__EIKCLB_H__)
1.24 +#define __EIKCLB_H__
1.25 +
1.26 +
1.27 +#include <eiklbi.h>
1.28 +#include <eiktxlbx.h>
1.29 +#include <eiklbed.h>
1.30 +
1.31 +class CColumnListBoxData;
1.32 +
1.33 +
1.34 +/**
1.35 + * Draws the contents of list box items.
1.36 + *
1.37 + * @since 5.0
1.38 + */
1.39 +class CColumnListBoxItemDrawer : public CTextListItemDrawer
1.40 + {
1.41 +
1.42 +public:
1.43 + /* C++ default constructor.
1.44 + *
1.45 + * @since 3.2
1.46 + */
1.47 +
1.48 + IMPORT_C CColumnListBoxItemDrawer();
1.49 +
1.50 + /**
1.51 + * C++ default constructor.
1.52 + *
1.53 + * Initialises the list box item drawer with the specified model,
1.54 + * font and data.
1.55 + *
1.56 + * @param aTextListBoxModel The model whose items will be drawn.
1.57 + * This provides the item text that is drawn using
1.58 + * @c DrawItemText().
1.59 + * @param aFont The font in which the items will be drawn.
1.60 + * @param aColumnData The column list box data. This comprises:
1.61 + * the column widths, gaps, fonts, aligments and bitmaps.
1.62 + */
1.63 +
1.64 + IMPORT_C CColumnListBoxItemDrawer(MTextListBoxModel* aTextListBoxModel,
1.65 + const CFont* aFont,
1.66 + CColumnListBoxData* aColumnData);
1.67 +
1.68 + /**
1.69 + * Destructor.
1.70 + */
1.71 + IMPORT_C ~CColumnListBoxItemDrawer();
1.72 +
1.73 + /**
1.74 + * Gets a pointer to the column list box data as set during construction.
1.75 + * Does not transfer ownership.
1.76 + *
1.77 + * @return The column list box data.
1.78 + */
1.79 + IMPORT_C CColumnListBoxData* ColumnData() const;
1.80 +
1.81 +public:
1.82 +
1.83 +
1.84 + /**
1.85 + * The structure holding given item properties.
1.86 + *
1.87 + * Used for storing information given through @c SetProperties() method.
1.88 + */
1.89 + struct SListProperties
1.90 + {
1.91 + /** Item identifier. */
1.92 + TInt iItem; // must be first
1.93 +
1.94 + /** Properties of the item. */
1.95 + TListItemProperties iProperties;
1.96 + };
1.97 +
1.98 + /**
1.99 + * Clears all properties from the @c CColumnListBoxItemDrawer.
1.100 + */
1.101 + IMPORT_C void ClearAllPropertiesL();
1.102 +
1.103 +
1.104 + /**
1.105 + * Set the property for an item with @c aItemIndex
1.106 + *
1.107 + * @param aItemIndex Item index
1.108 + * @param aProperty The new property setting
1.109 + * The SetProperties is convinience method for normal cases.
1.110 + * NOTE that it does NOT work correctly if you can insert/delete
1.111 + * items from the list -- You need to update all properties if
1.112 + * any changes to the item text array happen! Often it is convinient
1.113 + * to override the Properties() method. Further, use this only
1.114 + * for small lists as it causes O(n) time if you need to set
1.115 + * all properties.
1.116 + */
1.117 + IMPORT_C void SetPropertiesL(TInt aItemIndex,
1.118 + TListItemProperties aProperty);
1.119 +
1.120 + /**
1.121 + * Get properties for an item.
1.122 + *
1.123 + * @param aItemIndex Item's index for identifying.
1.124 + * @return Wanted property set.
1.125 + */
1.126 + IMPORT_C virtual TListItemProperties Properties(TInt aItemIndex) const;
1.127 +
1.128 +public: // from CTextListItemDrawer
1.129 +
1.130 + /**
1.131 + * From @c CTextListItemDrawer.
1.132 + *
1.133 + * Draw item text.
1.134 + *
1.135 + * @param aItemIndex Index of the item to draw.
1.136 + * @param aItemTextRect Area to draw into.
1.137 + * @param aItemIsCurrent @c ETrue if the item is current.
1.138 + * @param aViewIsEmphasized @c ETrue if the view is emphasised.
1.139 + * @param aItemIsSelected @c ETrue if the item is selected.
1.140 + */
1.141 + IMPORT_C void DrawItemText(TInt aItemIndex,
1.142 + const TRect& aItemTextRect,
1.143 + TBool aItemIsCurrent,
1.144 + TBool aViewIsEmphasized,
1.145 + TBool aItemIsSelected) const;
1.146 + // the next one is for avkon
1.147 +
1.148 + /**
1.149 + * Not used in S60.
1.150 + */
1.151 + IMPORT_C void DrawItemMark(TBool aItemIsSelected,
1.152 + TBool aViewIsDimmed,
1.153 + const TPoint& aMarkPos) const;
1.154 +
1.155 +public: // from CListItemDrawer
1.156 +
1.157 + /**
1.158 + * From @c CListItemDrawer.
1.159 + *
1.160 + * Gets the minimum cell size.
1.161 + *
1.162 + * @return The minimum size for a cell. This is
1.163 + * TSize(0, 0) in @c CListItemDrawer.
1.164 + */
1.165 + IMPORT_C TSize MinimumCellSize() const;
1.166 +
1.167 + /**
1.168 + * From @c CListItemDrawer.
1.169 + *
1.170 + * Gets the width of the specified item.
1.171 + *
1.172 + * @param aItemIndex The index of the item whose width is to be returned.
1.173 + * @return The width of the item. This is 0 in @c CListItemDrawer
1.174 + */
1.175 + IMPORT_C TInt ItemWidthInPixels(TInt aItemIndex) const;
1.176 +
1.177 + /**
1.178 + * From @c CListItemDrawer.
1.179 + *
1.180 + * Sets the item cell size.
1.181 + *
1.182 + * The cell size is the on-screen size of the entire item, including its
1.183 + * text and its item mark.
1.184 + *
1.185 + * @param aSizeInPixels New size for the item cell.
1.186 + */
1.187 + IMPORT_C void SetItemCellSize(const TSize& aSizeInPixels);
1.188 +
1.189 + /**
1.190 + * Get Item Cell Size.
1.191 + *
1.192 + * @return Cell size of an item.
1.193 + */
1.194 + TSize LafItemSize() { return iItemCellSize; }
1.195 +
1.196 +private: // from CListItemDrawer
1.197 +
1.198 + IMPORT_C TAny* Reserved_1();
1.199 +
1.200 +private: // defining reserved method.
1.201 +
1.202 + IMPORT_C void CColumnListBoxItemDrawer_Reserved();
1.203 +
1.204 +protected:
1.205 +
1.206 + /**
1.207 + * Draw the item background.
1.208 + *
1.209 + * Internal member, not intended for use.
1.210 + *
1.211 + * @param aRect Drawing area.
1.212 + */
1.213 + void DrawCurrentItemRect(const TRect& aRect) const;
1.214 +
1.215 + /**
1.216 + * Array of properties.
1.217 + */
1.218 + CArrayFix<SListProperties>* iPropertyArray;
1.219 +
1.220 + /**
1.221 + * Not used.
1.222 + */
1.223 + TInt iSpare;
1.224 + };
1.225 +
1.226 +
1.227 +/**
1.228 + * Column list box control.
1.229 + *
1.230 + * This is a list box whose lines consist of cells that are grouped vertically
1.231 + * into columns. The columns can be either textual or graphical, and column
1.232 + * widths and fonts can be set explicitly through @c CColumnListBoxData.
1.233 + *
1.234 + * Starting from 3.0 listbox uses highlight animations. Starting and stopping
1.235 + * animation is connected to focus events. To support highlight animations
1.236 + * properly you have to make sure that the list has focus when it has 'visual
1.237 + * focus'. Common issues:
1.238 + * - In many cases list is in a container which sits on top of the control
1.239 + * stack. The container receives all focus events and should hand them to the
1.240 + * list too. E.g.
1.241 + * void CContainer::FocusChanged( TDrawNow aDrawNow )
1.242 + * {
1.243 + * ... some code ...
1.244 + * if( iListBox )
1.245 + * iListBox->SetFocus( IsFocused(), aDrawNow );
1.246 + * }
1.247 + * - When switching components programmatically, e.g. from one list to another
1.248 + * in the same view, make sure that you remove focus from the other
1.249 + * component.
1.250 + * - In more complex cases you may have to add a dummy interceptor control to
1.251 + * the top of control stack to hand focus events to list.
1.252 + * - Make sure you handle resource changes correctly. If resource handle chain
1.253 + * is solid it should reach CCoeControl::HandleResourceChange, which informs
1.254 + */
1.255 +class CEikColumnListBox : public CEikTextListBox
1.256 + {
1.257 +public:
1.258 + /**
1.259 + * C++ default constructor.
1.260 + */
1.261 + IMPORT_C CEikColumnListBox();
1.262 +
1.263 + /**
1.264 + * Second-phase construction from a resource.
1.265 + *
1.266 + * This function completes the construction of a column list box,
1.267 + * initialising any members from the specified resource reader.
1.268 + *
1.269 + * @param aReader A resource file reader
1.270 + */
1.271 + IMPORT_C void ConstructFromResourceL( TResourceReader& aReader );
1.272 +
1.273 + /**
1.274 + * By default Symbian 2nd phase constructor is private.
1.275 + *
1.276 + * This function completes the construction of a column list box.
1.277 + *
1.278 + * @param aParent Parent control for the column list box.
1.279 + * @param aFlags Flags for the column list box.
1.280 + */
1.281 + IMPORT_C void ConstructL( const CCoeControl* aParent,TInt aFlags=0);
1.282 + /**
1.283 + * Not supported in S60.
1.284 + */
1.285 + IMPORT_C void EditItemL(TInt aColumn, TInt aMaxLength);
1.286 +protected:
1.287 +
1.288 + /**
1.289 + * This member is internal and not intended for use.
1.290 + */
1.291 + IMPORT_C virtual void CreateItemDrawerL();
1.292 +
1.293 + /**
1.294 + * Creates a new @c CTextListBoxModel
1.295 + */
1.296 + IMPORT_C virtual void CreateModelL();
1.297 +
1.298 +public:
1.299 +
1.300 + /**
1.301 + * Gets the list box model.
1.302 + *
1.303 + * @return Pointer to the model used by this list box
1.304 + */
1.305 + IMPORT_C CTextListBoxModel* Model() const;
1.306 +
1.307 + /**
1.308 + * Gets the object used by this list box to draw its items.
1.309 + *
1.310 + * @return A pointer to the list box drawer.
1.311 + */
1.312 + IMPORT_C CColumnListBoxItemDrawer* ItemDrawer() const;
1.313 +
1.314 + /**
1.315 + * This method needs to be called to enable extended drawing features
1.316 + * such as skinning, pictograph drawing and marquee text in the listbox
1.317 + * draw routine.
1.318 + *
1.319 + * Methods @c CEikFormattedCellListBox::ConstructL and
1.320 + * @c CEikFormattedCellListBox::ConstructFromResourceL call this method.
1.321 + * So, you only need to call this if your listbox implementation does not
1.322 + * call either of those.
1.323 + *
1.324 + * This method can be safely called more than once.
1.325 + * Item drawer must be created before calling this method, or a
1.326 + * panic is raised.
1.327 + *
1.328 + * @since S60 2.6
1.329 + */
1.330 + IMPORT_C void EnableExtendedDrawingL();
1.331 +
1.332 + /**
1.333 + * Helper function that setst icon sizes for visible list items
1.334 + */
1.335 + void SetIconSizes();
1.336 +
1.337 + /**
1.338 + * Enables/disables list stretching. When a column list is stretched its
1.339 + * layout is optimized to take advantage of the extra screen space.
1.340 + * This is intented for devices with a large screen. This feature might be
1.341 + * set as default by a product specific flag.
1.342 + *
1.343 + * Item drawer must be created before calling this method.
1.344 + *
1.345 + * @since S60 3.1
1.346 + * @param aEnabled ETrue to enable list stretching.
1.347 + */
1.348 + IMPORT_C void EnableStretching( const TBool aEnabled );
1.349 +public: // from CEikListBox
1.350 +
1.351 + /**
1.352 + * From @c CEikListBox.
1.353 + *
1.354 + * Creates the list box view.
1.355 + * The function is called by @ ConstructL() to create an instance of
1.356 + * the appropriate list box view class for this list box. The returned
1.357 + * instance is owned by this object, and does not have to have its
1.358 + * second-phase constructor run. This function is called by
1.359 + * @c CreateViewL().
1.360 + *
1.361 + * @return Pointer to a newly constructed list box
1.362 + * view for this object.
1.363 + */
1.364 + IMPORT_C CListBoxView* MakeViewClassInstanceL();
1.365 +
1.366 + /**
1.367 + * From @c CEikListBox
1.368 + *
1.369 + * Handles focus changes.
1.370 + *
1.371 + * The function emphasises or de-emphasises the view as needed, and
1.372 + * shows or hides the matcher cursor.
1.373 + *
1.374 + * @param aDrawNow If @c EDrawNow, a redraw is performed immediately
1.375 + */
1.376 + IMPORT_C void FocusChanged(TDrawNow aDrawNow);
1.377 +
1.378 +public: // from CCoeControl
1.379 +
1.380 + /**
1.381 + * From @c CCoeControl.
1.382 + *
1.383 + * Not used in S60
1.384 + * @param aColorUseList The colour list
1.385 + */
1.386 + IMPORT_C void GetColorUseListL(
1.387 + CArrayFix<TCoeColorUse>& aColorUseList) const;
1.388 +
1.389 + /**
1.390 + * From @c CCoeControl.
1.391 + *
1.392 + * Handles a change to the control's resources.
1.393 + *
1.394 + * The types of resources handled are those which are shared across
1.395 + * the environment, e.g. colours or fonts. For colour scheme changes,
1.396 + * @c DrawDeferred() is called in order to redraw the control.
1.397 + *
1.398 + * If overriding @c HandleResourceChange(), the implementation must
1.399 + * include a base call to @c CCoeControl's @c HandleResourceChange().
1.400 + *
1.401 + * @param aType A message UID value
1.402 + */
1.403 + IMPORT_C void HandleResourceChange(TInt aType);
1.404 +
1.405 + /**
1.406 + * From @c CCoeControl.
1.407 + *
1.408 + * Retrieves an object of the same type as that encapsulated in @c aId.
1.409 + *
1.410 + * This function is used to allow controls to ask their owners for
1.411 + * access to other objects that they own.
1.412 + *
1.413 + * Other than in the case where NULL is returned, the object returned
1.414 + * must be of the same object type - that is, the @c ETypeId member of the
1.415 + * object pointed to by the pointer returned by this function must be
1.416 + * equal to the @c iUid member of @c aUid.
1.417 + *
1.418 + * @param aUid An encapsulated object type ID.
1.419 + * @return Pointer to the type UID of the wanted object.
1.420 + */
1.421 + IMPORT_C TTypeUid::Ptr MopSupplyObject(TTypeUid aUid);
1.422 +
1.423 + /**
1.424 + * From @c CCoeControl.
1.425 + *
1.426 + * Handles pointer events.
1.427 + *
1.428 + * This function gets called whenever a pointer event occurs in the
1.429 + * control, i.e. when the pointer is within the control's extent, or when
1.430 + * the control has grabbed the pointer. The control should implement this
1.431 + * function to handle pointer events.
1.432 + *
1.433 + * Note: events of type @c EButton1Down are processed before
1.434 + * @c HandlePointerEventL() is called, in order to transfer keyboard
1.435 + * focus to the control in which the @c EButton1Down event occurred.
1.436 + *
1.437 + * If overriding @c HandlePointerEventL(), the implementation must
1.438 + * include a base call to @c CCoeControl's @c HandlePointerEventL().
1.439 + *
1.440 + * @param aPointerEvent The pointer event
1.441 + */
1.442 + IMPORT_C void HandlePointerEventL(const TPointerEvent& aPointerEvent);
1.443 +private:
1.444 + /**
1.445 + * From CAknControl
1.446 + */
1.447 + IMPORT_C void* ExtensionInterface( TUid aInterface );
1.448 +private:
1.449 + IMPORT_C virtual void CEikListBox_Reserved(); // listbox use only
1.450 +private: // data
1.451 + TInt iSpare;
1.452 + };
1.453 +
1.454 +/**
1.455 + * The @c CEikColumnListBoxEditor class implements an item editor for
1.456 + * column list boxes.
1.457 + * Not supported in S60
1.458 + * @since ER5U
1.459 + */
1.460 +class CEikColumnListBoxEditor : public CEikListBoxTextEditor
1.461 + {
1.462 +public:
1.463 + IMPORT_C CEikColumnListBoxEditor(MListBoxModel* aModel);
1.464 + IMPORT_C ~CEikColumnListBoxEditor();
1.465 + IMPORT_C void ConstructL(TInt aColumn); // just set column index
1.466 +public: // from MEikListBoxEditor
1.467 + IMPORT_C TPtrC ItemText();
1.468 + IMPORT_C TBool UpdateModelL();
1.469 +public: // From CCoeControl
1.470 + IMPORT_C void HandlePointerEventL(const TPointerEvent& aPointerEvent);
1.471 +protected:
1.472 + IMPORT_C TInt Column() const;
1.473 +private:
1.474 + /**
1.475 + * From CAknControl
1.476 + */
1.477 + IMPORT_C void* ExtensionInterface( TUid aInterface );
1.478 +private:
1.479 + TInt iColumnIndex; // refers to list box column
1.480 + };
1.481 +
1.482 +class CColumnListBoxView : public CListBoxView
1.483 + {
1.484 +public: // from CListBoxView
1.485 +
1.486 + /**
1.487 + * From @c CListBoxView
1.488 + * Draws every visible item into the specified rectangle.
1.489 + *
1.490 + * As implemented in @c CListBoxView, this function's argument is
1.491 + * ignored and the internal viewing rectangle is used. See @c SetViewRect().
1.492 + *
1.493 + * @param aClipRect = NULL The rectangle to draw into, this is ignored
1.494 + */
1.495 + IMPORT_C void Draw(const TRect* aClipRect = NULL) const;
1.496 +
1.497 + /**
1.498 + * From @c CListBoxView
1.499 + * Recalculates the index of the bottom item in the list from the top item
1.500 + * index and the size of the display.
1.501 + *
1.502 + * This function is called by the owning list box control when either the
1.503 + * size of the list box or the number of items in its model changes.
1.504 + */
1.505 + IMPORT_C virtual void CalcBottomItemIndex();
1.506 +
1.507 +private: // overridden from CListBoxView
1.508 +
1.509 + IMPORT_C virtual TAny* Reserved_1();
1.510 +
1.511 +private: // data
1.512 + TInt iSpare;
1.513 + };
1.514 +
1.515 +#endif // __EIKCLB_H__
1.516 +
1.517 +// End of File
1.518 \ No newline at end of file