1 eikscrlb.h

     1 /*

     2 * Copyright (c) 1997-2006 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(__EIKSCRLB_H__)

    20 #define __EIKSCRLB_H__

    21 

    22 #if !defined(__EIKBCTRL_H__)

    23 #include <eikbctrl.h>

    24 #endif

    25 

    26 #if !defined(__EIKSBOBS_H__)

    27 #include <eiksbobs.h>

    28 #endif

    29 

    30 #if !defined(__AKNSCBUT_H__)

    31 #include <aknscbut.h>

    32 #endif

    33 

    34 #include <lafpublc.h>

    35 

    36 class CEikCba;

    37 class CAknDoubleSpanScrollIndicator;

    38 class CEikScrollBarExtensionImpl;

    39 class CEikScrollBarExtension;

    40 class CAknDoubleSpanScrollBarExtension;

    41 

    42 const TInt KEikScrollEventFromVBar=0;

    43 const TInt KEikScrollEventFromHBar=0x01;

    44 const TInt KEikScrollEventBarMask=0x01;

    45 

    46 // sets all bits in EButtonsXxx range

    47 const TInt KButtonPositionMask=KLafScrollBarButtonPositionMask; 

    48 

    49 // sets all bits in determining which components exist

    50 const TInt KDisplayComponentsMask=0x1f; 

    51 

    52 

    53 /**

    54  * Scroll bar models encapsulate the range of integers which a scroll bar can 

    55  * represent, from zero to n, and the current position of the scroll bar thumb

    56  * within that range.

    57  *

    58  * Supported from Symbian 5.0.

    59  */

    60 class TEikScrollBarModel

    61     {

    62 	

    63 public:

    64 	

    65     /**

    66      * C++ default constructor. Creates, allocates and initialises a new @c 

    67      * TEikScrollBarModel.

    68      */

    69     inline TEikScrollBarModel();

    70 

    71     /**

    72      * Constructor. Creates, allocates and initialises a new @c 

    73      * TEikScrollBarModel.

    74      *

    75      * @param aScrollSpan The span of this model, numbered from zero.

    76      * @param aThumbSpan Number of positions spanned by the thumb.In default

    77      *        this is zero.

    78      * @param aThumbPosition Position of the thumb within the model span. In

    79      *        default this is zero.

    80      */	

    81     IMPORT_C TEikScrollBarModel(TInt aScrollSpan,

    82                                 TInt aThumbSpan=0,

    83                                 TInt aThumbPosition=0);

    84 

    85     /**

    86      * Tests two models for equality. The two models are the current model and

    87      * the model specified by @c aModel.

    88      *

    89      * @param The model against which the current model is tested. 

    90      *

    91      * @return @c ETrue if the two models are equal.

    92      */	

    93     IMPORT_C TBool operator==(const TEikScrollBarModel aModel) const;

    94 

    95     /**

    96      * Tests two models for inequality. The two models are the current model 

    97      * and the model specified by @c aModel.

    98      *

    99      * @param The model against which the current model is tested. 

   100      * @return @c ETrue if the two models are not equal.

   101      */	

   102     inline TBool operator!=(const TEikScrollBarModel aModel) const; 

   103 

   104 public:

   105 

   106     /** 

   107      * Tests whether the scroll bar model is useful. Scroll bar models are only

   108      * useful if their thumb span is smaller than their entire span.

   109      *

   110      * @return Whether this scroll bar can be used.

   111      */

   112     IMPORT_C TBool ScrollBarUseful() const;

   113 

   114     /**

   115      * Gets the maximum position possible for the low edge of the thumb within

   116      * the total span.

   117      *

   118      * @return Maximum value possible for @c iThumbPosition.

   119      */

   120     IMPORT_C TInt MaxThumbPos() const;

   121 

   122     /**

   123      * Ensures that the thumb position remains within its valid range by

   124      * altering it if necessary.

   125      */

   126     IMPORT_C void CheckBounds();

   127 

   128     /** 

   129      * Type of scroll bar model. The different models store the scrolling

   130      * information in different way, so correct model must be used with correct

   131      * scrollbar type.

   132      */

   133     enum TEikScrollBarModelType

   134         {

   135 

   136         /** This model type is for storing data for the arrowhead scrollbar. */

   137         EEikScrollBarModel               = 0x00000000,

   138 

   139         /** This model type is for storing data for the spanned scrollbar. */

   140         EAknDoubleSpanScrollBarModel     = 0x80000000

   141         };        

   142 

   143     /**

   144      * Gets type of scroll bar model which is one of the enum values from @c 

   145      * TEikScrollBarModelType enum.

   146      */

   147     TEikScrollBarModel::TEikScrollBarModelType ScrollBarModelType() const;

   148 

   149 public:

   150 

   151     /** Entire range of integers for this model. */

   152     TInt iScrollSpan;

   153 

   154     /** Range spanned by the thumb. */

   155     TInt iThumbSpan;

   156 

   157     /** Position of the low edge of the thumb within 0...@c iScrollSpan. */

   158     TInt iThumbPosition;            

   159     };

   160 

   161 inline TEikScrollBarModel::TEikScrollBarModel() {}

   162 inline TBool TEikScrollBarModel::operator!=(const TEikScrollBarModel aModel) const { return !(*this==aModel); }

   163 

   164 

   165 //

   166 // TAknDoubleSpanScrollBarModel class

   167 //

   168 // This class is binary compatible with TEikScrollBarModel and can

   169 // be used in places where TEikScrollBarModel is used but few restrictions exist:

   170 //

   171 // - Base class (TEikScrollBarModel) public members must NOT be accessed directly.

   172 // - Base class (TEikScrollBarModel) public methods must NOT be called.

   173 //

   174 // If this model is not supported by the scrollbar system, then values are stored

   175 // as in the base class for compatibility resons. See ModelIsSupported()-method 

   176 // documentation for more information.

   177 //

   178 class TAknDoubleSpanScrollBarModel : public TEikScrollBarModel

   179 	{

   180 

   181 public:

   182     

   183    /**

   184     * Default constructor.

   185     */

   186     IMPORT_C TAknDoubleSpanScrollBarModel();

   187 

   188    /**

   189     * Constructor which converts TEikScrollBarModel into TAknDoubleSpanScrollBarModel.

   190     *

   191     * @since    2.6

   192     * @param    aEikModel a model that will be converted.

   193     * 

   194     * Allowed range for TEikScrollBarModel values is from 0x1FFF7FFF to -0x1FFF7FFF. 

   195     * Values outside the allowed range will be truncated to max or min value. 

   196     * Value will be internally  stored with 15 bit accuracy, this means 

   197     * that the actual stored value may differ from the value given as parameter.

   198     * 

   199     * Values will be converted as:

   200     * 

   201     * TEikScrollBarModel        TAknDoubleSpanScrollBarModel

   202     * ------------------        ----------------------------

   203     * iScrollSpan          ->    ScrollSpan

   204     * iThumbPosition       ->    FocusPosition

   205     * iThumbSpan           ->    WindowSize

   206     * 0                    ->    FieldPosition            

   207     * 0                    ->    FieldSize

   208     *

   209     *

   210     * Values will be internally  stored with 15 bit accuracy, this means that the 

   211     * actual stored value may differ from the value given inside parameter.

   212     *

   213     */

   214     IMPORT_C TAknDoubleSpanScrollBarModel(const TEikScrollBarModel& aEikModel);

   215     

   216     

   217    /**

   218     *  Set methods for model attributes. These MUST be used instead of setting

   219     *  base class model values directly.

   220     *

   221     *  @since    2.6

   222     *  @param    aValue Value to be stored. Allowed range 0x1FFF7FFF to -0x1FFF7FFF. 

   223     *                   Value outside the allowed range will be truncated to max

   224     *                   or min value. Value will be internally  stored with 

   225     *                   15 bit accuracy, this means that the actual stored value

   226     *                   may differ from the value given as parameter.

   227     *

   228     *                   This inaccuracy means that e.g. following can happen:

   229     *                       TInt value1 = 23456789;                   

   230     *                       TInt value2 = 0;                   

   231     *

   232     *                       model.SetScrollSpan(value1);

   233     *                       value2 = model.ScrollSpan();

   234     *                       if (value1 != value2)

   235     *                           {

   236     *                           // we can end up here !!!!  

   237     *                           }

   238     *

   239     */

   240     IMPORT_C void SetScrollSpan(TInt aValue);    // Size of the scrolled list. 

   241     IMPORT_C void SetFocusPosition(TInt aValue); // Position of the current field in the list.

   242     IMPORT_C void SetWindowSize(TInt aValue);    // Size of the visible part of the list. 

   243     IMPORT_C void SetFieldSize(TInt aValue);     // Size of the current field. (Optional double span)

   244     IMPORT_C void SetFieldPosition(TInt aValue); // Position inside the current field. (Optional double span)  

   245     

   246     

   247    /**

   248     *  Get methods for model attributes. These MUST be used instead of getting

   249     *  base class model values directly.

   250     *

   251     * @since    2.6

   252     * @return   Values from range 0x1FFF7FFF to -0x1FFF7FFF. 

   253     *           Values are internally  stored with 15 bit accuracy, this means that 

   254     *           the returned value may differ from the value which was set using the

   255     *           corresponding set method. Difference can be about 0x3FFF in the high

   256     *           end of the range.

   257     *

   258     */

   259     IMPORT_C TInt ScrollSpan() const;    // Size of the scrolled list.

   260     IMPORT_C TInt FocusPosition() const; // Position of the current field in the list.

   261     IMPORT_C TInt WindowSize() const;    // Size of the visible part of the list. 

   262     IMPORT_C TInt FieldSize() const;     // Size of the current field. (Optional double span)

   263     IMPORT_C TInt FieldPosition() const; // Position inside the current field. (Optional double span)

   264 

   265 

   266    /**

   267     * This method can be used to query if this model type is supported by the device. If model 

   268     * is not supported then this model and the behaviour of ALL methods defaults to TEikScrollBarModel 

   269     * behaviour with following rules:

   270     *

   271     * TAknDoubleSpanScrollBarModel              TEikScrollBarModel

   272     * ----------------------------              ------------------  

   273     * ScrollSpan methods                ->      iScrollSpan

   274     * FocusPosition methods             ->      iThumbPosition

   275     * WindowSize methods                ->      iThumbSize

   276     * FieldPosition methods             ->      N/A

   277     * FieldSize methods                 ->      N/A

   278     *

   279     * @since    2.6

   280     * @return   ETrue if this model is supported by the devices scrollbar system. Otherwise EFalse is

   281     *           returned.

   282     *

   283     */

   284     static TBool ModelIsSupported();

   285 

   286 private:   

   287    /**

   288     * Gets the internal scale value. 

   289     *

   290     * @since    2.6

   291     * @return   Internal scaling value.

   292     *

   293     */

   294     TUint16 Scale() const;

   295 

   296    /**

   297     * Sets the internal scale value. 

   298     *

   299     * @since    2.6

   300     * @param    aScale  New internal scaling value.

   301     *

   302     */

   303     void SetScale(TUint16 aScale);    

   304 

   305 private:   

   306    /**

   307     *  Get methods for model attributes values without scaling.

   308     *

   309     *  @since    2.6

   310     *  @return   Stored value without scaling. 

   311     *

   312     */

   313     TInt16 ScrollSpanValue() const;

   314     TInt16 FocusPositionValue() const;

   315     TInt16 FieldPositionValue() const;

   316     TInt16 FieldSizeValue() const;

   317     TInt16 WindowSizeValue() const;

   318 

   319    /**

   320     *  Set methods for model attributes values without scaling.

   321     *

   322     *  @since    2.6

   323     *  @param    aValue Value without scaling to be stored. 

   324     *

   325     */

   326     void SetScrollSpanValue(TInt16 aValue);

   327     void SetFocusPositionValue(TInt16 aValue);

   328     void SetFieldPositionValue(TInt16 aValue);

   329     void SetFieldSizeValue(TInt16 aValue);

   330     void SetWindowSizeValue(TInt16 aValue);

   331 

   332    /**

   333     *  Gets two lowest bytes from TInt and constructs TInt16 from those.

   334     *

   335     *  @since    2.6

   336     *  @param    aInt  Value from which the lowest bytes are extracted.     

   337     *  @return   TInt16 constructed from two lowest bytes.

   338     */

   339     TInt16 LowBytes(TInt aInt) const;

   340 

   341    /**

   342     *  Gets two highest bytes from TInt and constructs TInt16 from those.

   343     *

   344     *  @since    2.6

   345     *  @param    aInt  Value from which the highest bytes are extracted.     

   346     *  @return   TInt16 constructed from two highest bytes.

   347     */    

   348     TInt16 HighBytes(TInt aInt) const;

   349     

   350     

   351    /**

   352     *  Sets two lowest bytes of TInt.

   353     *

   354     *  @since    2.6

   355     *  @param    aInt    TInt of which the lowest bytes are set.     

   356     *  @param    aValue  Value for the lowest bytes.     

   357     */    

   358     void SetLowBytes(TInt& aInt, TInt16 aValue);

   359 

   360    /**

   361     *  Sets two highest bytes of TInt.

   362     *

   363     *  @since    2.6

   364     *  @param    aInt    TInt of which the highest bytes are set.     

   365     *  @param    aValue  Value for the highest bytes.     

   366     */        

   367     void SetHighBytes(TInt& aInt, TInt16 aValue);

   368     

   369     

   370    /**

   371     *  Constructs a scaled TInt16 value from given TInt value. Changes

   372     *  internal member variable values using ReScale()-method if needed.

   373     *

   374     *  @since    2.6

   375     *  @param    aNonScaledValue    Value which will be changed to scaled one.

   376     *  @return   Scaled value.

   377     */        

   378     TInt16 PrepareScaledValue(TInt aNonScaledValue);

   379     

   380    /**

   381     *  Changes the used scale value and updates all stored attribute values

   382     *  if needed.

   383     *

   384     *  @since    2.6

   385     *  @param    aNewScale    New value to be used scaling.

   386     *

   387     */        

   388     void ReScale(TUint16 aNewScale);

   389     

   390    /**

   391     *  Sets the scrollbar type.

   392     *

   393     *  @since    2.6

   394     *  @param    aModelType    Scrollbar type. Supported types are 

   395     *                          EEikScrollBarModel and EAknDoubleSpanScrollBarModel.

   396     *

   397     */        

   398     void SetScrollBarModelType(TEikScrollBarModelType aModelType);

   399 

   400    /**

   401     *  Checks if given parameter is between internal min and max values.

   402     *

   403     *  @since    2.6

   404     *  @param    aValue        Value to be checked.

   405     *  @return                 Checked value which will be between internal min 

   406     *                          and max values. 

   407     *

   408     */        

   409     TInt CheckMinMaxValue(TInt aValue);

   410     };

   411 

   412 

   413 //

   414 // CEikScrollBar

   415 //

   416 

   417 class CEikScrollThumb;

   418 class CEikScrollBarFrame;

   419   

   420 /**

   421  * The CEikScrollBar class implements a scroll bar. Scroll bars are used when

   422  * the contents of a view require a greater area than can be physically 

   423  * displayed. Scroll bars allow a user to move different parts of the content

   424  * into the view and to indicate what proportion of the total contents are 

   425  * visible at any one time.

   426  */

   427 class CEikScrollBar : public CEikBorderedControl, public MCoeControlObserver

   428 	{

   429 friend class CEikScrollBarExtension;

   430 friend class CAknDoubleSpanScrollBarExtension;

   431     

   432 public:

   433 

   434     /** Scroll bar orientation. */

   435     enum TOrientation

   436         {

   437         /** Scroll bar is oriented vertically. */

   438         EVertical = SLafScrollBar::EVertical,

   439 

   440         /** Scroll bar is oriented horizontally. */

   441         EHorizontal = SLafScrollBar::EHorizontal

   442         };

   443 

   444     /** Type of the scroll bar.*/	

   445     enum TScrollBarType

   446         {

   447         /** Normal scrollbar. */		

   448         ENormalScrollBar =0x0,

   449 

   450         /** Used scrollbar type is an old one. (arrows in the CBA-area) */		

   451         EArrowHead =0x200,

   452 

   453         /** 

   454          * The created scrollbar is the current and commonly used in Series 60

   455          * platform, spanned scrollbar. (scrollable bar on the right side of

   456          *  the control, like in windows etc.).

   457          */		

   458         EDoubleSpan =0x400

   459         };

   460 

   461     /** 

   462      * Scroll bar initialisation flags. The default is for the scroll bar

   463      * to have both a shaft and a thumb. 

   464      */	

   465     enum TEikScrollBarFlags

   466     	{

   467     	/**  */	

   468     	EEikScrollBarDefaultBehaviour = 

   469     	    SLafScrollBar::EEikScrollBarDefaultBehaviour,

   470 

   471     	/** Does not display nudge buttons.*/	

   472     	EEikScrollBarNoNudgeButtons =

   473     	    SLafScrollBar::EEikScrollBarNoNudgeButtons,

   474 

   475     	/** Has buttons which move it a page at a time. */	

   476     	EEikScrollBarHasPageButtons =

   477     	    SLafScrollBar::EEikScrollBarHasPageButtons,	

   478 

   479     	/** Has buttons which move it its entire extent. */	

   480     	EEikScrollBarHasHomeEndButtons =

   481     	    SLafScrollBar::EEikScrollBarHasHomeEndButtons,

   482 

   483     	/** Central area is empty. */	

   484     	EEikScrollBarNoShaftOrThumb =

   485     	    SLafScrollBar::EEikScrollBarNoShaftOrThumb,	

   486 

   487     	/** Central area has no scroll thumb. */	

   488     	EEikScrollBarShaftButNoThumb =

   489     	    SLafScrollBar::EEikScrollBarShaftButNoThumb,	

   490 

   491     	/** Buttons are placed at the start of the bar. */	

   492     	EButtonsAtStartOfShaft =

   493     	    SLafScrollBar::EButtonsAtStartOfShaft,	

   494 

   495     	/** Buttons are placed at the end of the bar. */	

   496     	EButtonsAtEndOfShaft =

   497     	    SLafScrollBar::EButtonsAtEndOfShaft,			

   498 

   499     	/** 

   500     	 * Buttons are placed at either end of the bar @c

   501     	 * (EButtonsAtStartOfShaft | @c EButtonsAtEndOfShaft).

   502     	 */	

   503     	EButtonsEitherSideOfShaft =

   504     	    SLafScrollBar::EButtonsEitherSideOfShaft,

   505 

   506     	/** 

   507     	 * Buttons do not automatically dim when scroll bar is at its maximum

   508     	 * extent.

   509     	 */	

   510     	ENoAutoDimming =

   511     	    SLafScrollBar::ENoAutoDimming,

   512     	    

   513     	/** Enable the nudge buttons. */

   514     	EEnableNudgeButtons = 0x0200,

   515     	

   516     	/** Disable the expanded touch area. */

   517     	EDisableExpandedTouchArea = 0x0400

   518     	};

   519 

   520     /** Type of the scroll extension area.*/

   521      enum TScrollBarExtensionAreaType

   522         {

   523         /** Normal scrollbar extension area. */

   524         ENormalExpandedTouchArea,

   525 

   526         /** Scale scrollbar extension area. */

   527         EScaleExpandedTouchArea,

   528 

   529         /** none scrollbar extension area. */

   530         ENoExpandedTouchArea

   531         };

   532 

   533     typedef TEikScrollBarFlags TAknScrollBarFlags;

   534 

   535 public:

   536 

   537     /**

   538      * Destructor.

   539      */

   540     IMPORT_C ~CEikScrollBar();

   541 

   542     /**

   543      * C++ default constructor.

   544      */	

   545     IMPORT_C CEikScrollBar();

   546 

   547 public:

   548 

   549     /** 

   550      * Second phase constructor of the scroll bar. 

   551      *

   552      * @param aScrollBarObserver The scroll bar observer which is to be 

   553      *        informed of scroll events by this scroll bar. 

   554      * @param aParent Parent control for this new scroll bar. 

   555      * @param aOrientation Orientation of the new scroll bar. 

   556      * @param aLength Not used. 

   557      * @param aScrollBarFlags Not used. 

   558      */

   559     IMPORT_C virtual void ConstructL(

   560                 MEikScrollBarObserver* aScrollBarObserver,

   561                 const CCoeControl* aParent,

   562                 TOrientation aOrientation,

   563                 TInt aLength,

   564                 TInt aScrollBarFlags=EEikScrollBarDefaultBehaviour);

   565 

   566     /** 

   567      * Not implemented.

   568      * 

   569      * @param aLength Not used.

   570      */

   571     IMPORT_C void SetLengthL(TInt aLength);

   572 

   573     /** 

   574      * Change the scrollbar model.

   575      * 

   576      * @param aModel The new model to use.

   577      */

   578     IMPORT_C void SetModelL(const TEikScrollBarModel* aModel);

   579 

   580     /** 

   581      * Change the scrollbar model.

   582      * 

   583      * @param aModel The new model to use.

   584      */

   585     IMPORT_C void SetModel(const TEikScrollBarModel* aModel);

   586 

   587     /** 

   588      * Change the model at once to avoid a double update of the scroll bar.

   589      * 

   590      * @param aLength Not used. 

   591      * @param aModel New scroll bar model.

   592      */

   593     IMPORT_C void SetLengthAndModelL(TInt aLength,

   594                                      const TEikScrollBarModel* aModel);

   595 

   596     /** 

   597      * Not implemented.

   598      * 

   599      * @param aThumbPos Not used.

   600      */

   601     IMPORT_C void SetModelThumbPosition(TInt aThumbPos);

   602 

   603     /** 

   604      * Not implemented.

   605      * 

   606      * @param aFocusPosition Not used.

   607      */

   608     IMPORT_C void SetFocusPosToThumbPos(TInt aFocusPosition);

   609 

   610     /** 

   611      * Gets the default width of the scroll bar.

   612      * 

   613      * @return Default scroll bar breadth.

   614      */

   615     IMPORT_C static TInt DefaultScrollBarBreadth();

   616 

   617     /**

   618      * Allows scroll bar observer to be changed also after the construction. 

   619      * This function is not exported, but the applications can use it via

   620      * @c CEikScrollBarFrame::SetScrollBarFrameObserver function.

   621      *

   622      * @param aScrollBarObserver New observer replacing the previous (if any).

   623      */

   624     void SetScrollBarObserver(MEikScrollBarObserver* aScrollBarObserver);

   625 

   626     /**

   627      * Gets the scroll bar model used by this scroll bar.

   628      */

   629     inline const TEikScrollBarModel* Model() const;

   630 

   631     /** 

   632      * Gets the position within the scroll bar model. This function would

   633      * normally be called by an @c MEikScrollBarObserver implementation in 

   634      * response to a scroll bar event.

   635      * 

   636      * @return Current position within the scroll bar model’s range.

   637      */

   638     IMPORT_C TInt ThumbPosition() const;

   639 

   640     /** 

   641      * Gets the height of a horizontal scrollbar or width of a vertical 

   642      * scrollbar.

   643      * 

   644      * @return Scroll bar breadth.

   645      */

   646     IMPORT_C TInt ScrollBarBreadth() const;

   647 

   648     /** 

   649      * Not implemented.

   650      * 

   651      * @param aScrollBarFlags Not used.

   652      *

   653      * @return Zero.

   654      */

   655     IMPORT_C static TInt MinVisibleLength(const TInt aScrollBarFlags);

   656 

   657     /** 

   658      * Not implemented.

   659      * 

   660      * @param aDimmed Not used.

   661      */

   662     IMPORT_C void SetDecreaseButtonsDimmed(TBool aDimmed);

   663 

   664     /** 

   665      * Not implemented.

   666      * 

   667      * @param aDimmed Not used.

   668      */

   669     IMPORT_C void SetIncreaseButtonsDimmed(TBool aDimmed);

   670 

   671     /** 

   672      * Not implemented.

   673      * 

   674      * @param aDimmed Not used.

   675      */

   676     IMPORT_C void SetAllButtonsDimmed(TBool aDimmed);

   677 

   678     /** 

   679      * Gets handle to the controls that draw arrows in the both ends of spanned

   680      * scrollbar. These arrows are for pen support to enable exact moving of

   681      * the scrollbar with pen. The arrow is tapped with the pen to move the

   682      * scrollbar with one step.

   683      *

   684      * @return Pointer to the increace button.

   685      */

   686     inline CAknScrollButton* IncreaseNudgeButton() const;

   687     	

   688     /** 

   689      * Gets handle to the controls that draw arrows in the both ends of spanned

   690      * scrollbar. These arrows are for pen support to enable exact moving of

   691      * the scrollbar with pen. The arrow is tapped with the pen to move the

   692      * scrollbar with one step.

   693      *

   694      * @return Pointer to the decreace button.

   695      */

   696     inline CAknScrollButton* DecreaseNudgeButton() const;

   697 

   698     // This function should only be used by CEikCba

   699     /** 

   700      * Sets command button area. This function should only be used by @c 

   701      * CEikCba.

   702      * 

   703      * @param aCba Command button area.

   704      * @panic EEikPanicScrollBarExtensionNotCreated Extension of 

   705      *        the scroll bar not created.

   706      */

   707     IMPORT_C void SetContainingCba(CEikCba* aCba);

   708 

   709     /** 

   710      * From @c CCoeControl.

   711      *

   712      * Sets this control as visible or invisible.

   713      * 

   714      * If @c MakeVisible() is used to make a component visible, and the control

   715      * captures the pointer (see @c CapturesPointer()), @c MakeVisible() throws

   716      * away any pending pointer events for that control.

   717      * 

   718      * @param aVisible @c ETrue to make the control visible, @c EFalse to make 

   719      *        it invisible.

   720      */

   721     IMPORT_C void MakeVisible(TBool aVisible);

   722 

   723     // 

   724     /** 

   725      * From @c CCoeControl

   726      *

   727      * Called by the framework to handle pointer events. 

   728      * 

   729      * @param aPointerEvent A pointer event.

   730      */

   731     IMPORT_C void HandlePointerEventL(const TPointerEvent& aPointerEvent);

   732 

   733     /**

   734      * Not implemented.

   735      *

   736      * @param aType The extension area to use.

   737      */

   738 

   739     IMPORT_C void SetExtensionAreaType(TScrollBarExtensionAreaType aType);

   740 protected:      

   741 

   742     /** 

   743      * From @c CCoeControl

   744      *

   745      * Gets the specified scrollbar component. Each component control is 

   746      * identified by an index, where the index depends on the order the 

   747      * controls were added: the first is given an index of 0, the next an index

   748      * of 1.

   749      * 

   750      * @param aIndex The index of the control to get.

   751      *

   752      * @return The component control with an index of aIndex.

   753      */

   754     IMPORT_C CCoeControl* ComponentControl(TInt aIndex) const;

   755 

   756     /** 

   757      * From @cCCoeControl.

   758      *

   759      * Gets the number of controls contained in this scrollbar.

   760      * 

   761      * @return The number of component controls contained by this scrollbar.

   762      */

   763     IMPORT_C TInt CountComponentControls() const;

   764 

   765 private: // from MCoeControlObserver

   766     IMPORT_C virtual void HandleControlEventL(CCoeControl* aControl, 

   767                                               TCoeEvent aEventType);

   768 private: // virtual - reserved from CCoeControl

   769     IMPORT_C virtual void Reserved_2();

   770 private:

   771     /**

   772     * From CAknControl

   773     */

   774     IMPORT_C void* ExtensionInterface( TUid aInterface );

   775 

   776 protected:

   777 

   778     /**

   779      * The scroll bar frame is a control assemblage manager that relates a 

   780      * control, or control body, to two scroll bars and a corner window. A 

   781      * corner window is that part of the screen that is common to both the 

   782      * horizontal, and the vertical elements of a scroll bar.

   783      *

   784      * This class helps with access to, and set up of, scroll bars and also

   785      * with the layout of the scrolled control or control body. A scroll bar

   786      * frame is not a control, but it does implement the standard control 

   787      * composite pattern to manage the assemblage.

   788      */

   789     friend class CEikScrollBarFrame;

   790 

   791     // enums

   792     /** 

   793      * Flags to determine whether there are visible components and whether to

   794      * dim the increase, or decrease, buttons.

   795      */

   796     enum TPrivateScrollBarFlags

   797         {

   798 

   799         /** There are no visible components in the scroll bar. */

   800         ENoComponentsToDisplay          =0x10000,

   801 

   802         /** Dim the increase buttons. */

   803         EIncreaseButtonsDimmed          =0x20000,

   804 

   805         /** Dim the decrease buttons. */

   806         EDecreaseButtonsDimmed          =0x40000

   807         };

   808 

   809     /** Determines where on a scroll bar a pointer down event occurred. */

   810     enum TPointerDownOn

   811         {

   812         /** No pointer down event occurred on the scroll bar. */

   813         ENone,

   814 

   815         /** A pointer down event occurred on the home button. */

   816         EHomeButton,

   817 

   818         /** A pointer down event occurred on the decrease page button. */

   819         EDecreasePageButton,

   820 

   821         /** A pointer down event occurred on the decrease nudge button. */

   822         EDecreaseNudgeButton,

   823 

   824         /** A pointer down event occurred on the decrease shaft button. */

   825         EDecreaseShaft,

   826 

   827         /** A pointer down event occurred on the scroll bar thumb. */

   828         EThumb,

   829 

   830         /** A pointer down event occurred on the increase shaft button. */

   831         EIncreaseShaft,

   832 

   833         /** A pointer down event occurred on the increase nudge button. */

   834         EIncreaseNudgeButton,

   835 

   836         /** A pointer down event occurred on the increase page button. */

   837         EIncreasePageButton,

   838 

   839         /** A pointer down event occurred on the end button. */

   840         EEndButton

   841         };

   842 

   843     /** Determines whether to redraw the scroll bar shaft. */

   844     enum TShaftRedrawRequired

   845         {

   846         /** Do not redraw the scroll bar shaft. */

   847         ENoRedrawRequired,

   848 

   849         /** Redraw the scroll bar shaft. */

   850         ERedrawShaft

   851         };

   852 

   853     /** Determines which buttons are displayed. */

   854     enum TWhichButtons

   855         {

   856         /** Display the increase buttons only. */

   857         EIncreaseOnly,

   858 

   859         /** Display the decrease buttons only. */

   860         EDecreaseOnly,

   861 

   862         /** Display all buttons. */

   863         EAll

   864         };

   865 

   866     /** 

   867      * Encapsulates pointers to the scroll bar buttons. A maximum of three 

   868      * pairs of buttons are available, you may choose to use only one pair or

   869      * two pairs.

   870      */

   871     struct SEikScrollBarButtons

   872         {

   873         /** Pointer to the decrease nudge button. */

   874         CAknScrollButton* iDecreaseNudge;

   875 

   876         /** Pointer to the increase nudge button. */

   877         CAknScrollButton* iIncreaseNudge;

   878         };

   879 

   880 

   881 private:

   882     // construction/destruction

   883     IMPORT_C virtual void CreateButtonL(CAknScrollButton*& aButton,

   884                                         CAknScrollButton::TType aType);

   885 

   886     void SizeChanged();

   887 

   888     // set state functions

   889     void DoSetModel(const TEikScrollBarModel* aModel);

   890 

   891     CEikCba* Cba() const;

   892 

   893     // These functions are for use only be CEikScrollBarFrame (a friend class)

   894     void AddExternalFrameL(CEikScrollBarFrame* aFrame);

   895     void RemoveExternalFrame(CEikScrollBarFrame* aFrame);

   896 

   897     void DisconnectExternalFrames();

   898 

   899 protected:

   900 

   901     /** 

   902      * Allocates and constructs all the required components of the scrollbar.

   903      */

   904     void CreateRequiredComponentsL();

   905 

   906     /** 

   907      * Destroys a button.

   908      *

   909      * @param aButton A button that will be destroyed.

   910      */

   911     void DestroyButton(CAknScrollButton*& aButton);

   912 

   913     /** 

   914      * Not implemented 

   915      * 

   916      * @param aButton Not used. 

   917      */

   918     IMPORT_C virtual void SetButtonPositionL(CAknScrollButton* aButton);

   919 

   920 public:

   921 

   922     /** 

   923      * Gets the scroll bar type.

   924      * 

   925      * @return Value of the enum @c TScrollBarType.

   926      */

   927     TScrollBarType ScrollBarType();

   928 

   929 public:

   930 

   931     /** Not used, but cannot be removed due binary compatibility issues. */

   932     TDblQueLink iSBLink;

   933 

   934 protected:

   935 

   936     /** Scroll bar buttons struct. */

   937     SEikScrollBarButtons iButtons;

   938 

   939     /** Scroll bar orientation. */

   940     TOrientation iOrientation;

   941 

   942 private:

   943     TEikScrollBarModel iModel;

   944 

   945 protected:    

   946 

   947     /** A pointer to @c CEikScrollBarExtensionImpl class. */

   948     CEikScrollBarExtensionImpl* iExtension;

   949   };

   950 

   951 

   952 /**

   953  * The CEikArrowHeadScrollBar class is a scroll bar which uses only

   954  * two small nudge button arrows to scroll up and down. It has no shaft.

   955  * It therefore takes up very little space.

   956  *

   957  * @since ER5U 

   958  * @ internal

   959  * Internal to Symbian

   960  *

   961  */

   962 class CEikArrowHeadScrollBar : public CEikScrollBar

   963 	{

   964 public:

   965 	IMPORT_C CEikArrowHeadScrollBar(CCoeControl* aParentWindow);

   966 	IMPORT_C ~CEikArrowHeadScrollBar();

   967 public: // from CEikScrollBar

   968 	IMPORT_C void ConstructL(MEikScrollBarObserver* aScrollBarObserver,const CCoeControl* aParent,

   969 				TOrientation aOrientation,TInt aLength,TInt aScrollBarFlags=EEikScrollBarDefaultBehaviour);

   970 public: // From CCoeControl

   971     IMPORT_C void HandlePointerEventL(const TPointerEvent& aPointerEvent);	

   972 private: // from CEikScrollBar

   973 	void CreateButtonL(CAknScrollButton*& aButton,CAknScrollButton::TType aType);

   974 	void SetButtonPositionL(CAknScrollButton* aButton);

   975 private:

   976 private:

   977     /**

   978     * From CAknControl

   979     */

   980     IMPORT_C void* ExtensionInterface( TUid aInterface );

   981 private:

   982 	CCoeControl* iParentControl;

   983     TInt iSpare;

   984 	};

   985 

   986 

   987 /**

   988  * The CAknDoubleSpanScrollBar class is a scroll bar without buttons, 

   989  * but it has a shaft. Additionally it has in its shaft a double 

   990  * span feature which means that there can be another thumb inside the thumb 

   991  * if needed.

   992  *

   993  * This class uses TAknDoubleSpanScrollBarModel instead of TEikScrollBarModel

   994  * as its internal scrollbar model. TAknDoubleSpanScrollBarModel in binary 

   995  * compatible with TEikScrollBarModel. User must take care that TAknDoubleSpanScrollBarModel 

   996  * is really used in API calls in places where TEikScrollBarModel is declared.

   997  * 

   998  * @since 2.6 

   999  *

  1000  */

  1001 class CAknDoubleSpanScrollBar : public CEikScrollBar

  1002 	{

  1003 public:

  1004 	IMPORT_C CAknDoubleSpanScrollBar(CCoeControl* aParentWindow);

  1005 	IMPORT_C ~CAknDoubleSpanScrollBar();

  1006 

  1007    /**

  1008     * Sets fixed layout to scrollbar. If set, then scrollbar size

  1009     * changes done by the CEikScrollBarFrame class are disabled. 

  1010     *

  1011     * @since    2.6

  1012     * @param    aScrollBarRect     Scrollbar rectangle.         

  1013     *

  1014     */     

  1015     IMPORT_C void SetFixedLayoutRect(TRect aScrollBarRect);

  1016 

  1017    /**

  1018     * Method for constructing the object.

  1019     *

  1020     * @since    2.6

  1021     * @param    aWindowOwning       True if scrollbar is to be a window owning control. 

  1022     * @param    aScrollBarObserver  Same as in CEikScrollBar::ConstructL()

  1023     * @param    aParent             Same as in CEikScrollBar::ConstructL()

  1024     * @param    aOrientation        Same as in CEikScrollBar::ConstructL()

  1025     * @param    aLength             Same as in CEikScrollBar::ConstructL()    

  1026     * @param    aScrollBarFlags     Same as in CEikScrollBar::ConstructL()

  1027     *

  1028     */     

  1029     IMPORT_C void ConstructL(TBool aWindowOwning, MEikScrollBarObserver* aScrollBarObserver,const CCoeControl* aParent,

  1030 				TOrientation aOrientation,TInt aLength,TInt aScrollBarFlags=EEikScrollBarDefaultBehaviour);

  1031 

  1032    /**

  1033     * Sets scroll popup info text to be shown while dragging with stylus.

  1034     * Popup is shown until next pointer up event.

  1035     * KNullDesC parameter can be used to hide popup earlier.

  1036     * 

  1037     * @since    3.2

  1038     * @param    aText               Text to be shown

  1039     *

  1040     */  

  1041     IMPORT_C void SetScrollPopupInfoTextL( const TDesC& aText );

  1042 

  1043    /**

  1044     * Gets the fixed layoutrect of the scrollbar.    

  1045     * @since    2.6

  1046     * @return   Scrollbar rectangle. 

  1047     *

  1048     */     

  1049     TRect FixedLayoutRect();

  1050 

  1051 public: // from CEikScrollBar

  1052 	IMPORT_C void ConstructL(MEikScrollBarObserver* aScrollBarObserver,const CCoeControl* aParent,

  1053 				TOrientation aOrientation,TInt aLength,TInt aScrollBarFlags=EEikScrollBarDefaultBehaviour);

  1054     IMPORT_C void MakeVisible(TBool aVisible);

  1055 

  1056 public: // from CCoeControl

  1057     IMPORT_C void HandlePointerEventL(const TPointerEvent& aPointerEvent);    

  1058 

  1059 protected: // from CCoeControl

  1060 	IMPORT_C CCoeControl* ComponentControl(TInt aIndex) const;

  1061     IMPORT_C TInt CountComponentControls() const;

  1062 

  1063 private:  // from CCoeControl

  1064     IMPORT_C void SizeChanged();

  1065     

  1066 public:

  1067 	

  1068 	TBool DrawBackgroundState();

  1069 	

  1070 	void DrawBackground(TBool aDrawHorizontal);

  1071 	

  1072 private:

  1073     /**

  1074     * From CAknControl

  1075     */

  1076     IMPORT_C void* ExtensionInterface( TUid aInterface );

  1077 private: // from CEikScrollBar

  1078 	void CreateButtonL(CAknScrollButton*& aButton,CAknScrollButton::TType aType);

  1079 	void SetButtonPositionL(CAknScrollButton* aButton);

  1080 

  1081    /**

  1082     * Sets scrollbar background transparency as given in the parameter.

  1083     * 

  1084     * @param    aTransparentBackground   If ETrue then scrollbar will have transparent background.

  1085     * @since    2.6

  1086     *

  1087     */     

  1088     void SetTransparentBackground(TBool aTransparentBackground);

  1089 

  1090     /**

  1091     * Calculates scrollbar's extension area relative to its own position.

  1092     */

  1093     TRect ExtensionArea() const;

  1094 private:

  1095 	CCoeControl* iParentControl;

  1096     TInt iSpare;

  1097 	};

  1098 

  1099 

  1100 //

  1101 // Inlines

  1102 //

  1103 

  1104 

  1105 inline const TEikScrollBarModel* CEikScrollBar::Model() const

  1106 	{ return &iModel; }

  1107 

  1108 inline CAknScrollButton* CEikScrollBar::IncreaseNudgeButton() const

  1109 	{ return iButtons.iIncreaseNudge; }

  1110 

  1111 inline CAknScrollButton* CEikScrollBar::DecreaseNudgeButton() const

  1112 	{ return iButtons.iDecreaseNudge; }

  1113 

  1114 

  1115 #endif