1 aknslider.h

     1 /*

     2 * Copyright (c) 2005-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:  Slider editor class

    15 *

    16 */

    17 

    18 

    19 #ifndef __AKNSLIDER_H__

    20 #define __AKNSLIDER_H__

    21 

    22 // INCLUDES

    23 #include <eikbctrl.h>

    24 #include <eiklabel.h>

    25 #include <eikimage.h>

    26 #include <avkon.hrh> // For TAknOrientation

    27 

    28 // CONSTANTS

    29 

    30 // The following is max. length of the entire formatted value text including

    31 // number, special characters and supplied text.

    32 const TInt KValueLabelTextMaxLength = 30;

    33 

    34 // Forward declarations

    35 class CGulIcon;

    36 class MAknsSkinInstance;

    37 class CAknSliderExtension;

    38 class CAknSliderData;

    39 struct TAknSliderGfx;

    40 

    41 // CLASS DECLARATION

    42 class CAknSlider : public CEikBorderedControl

    43     {

    44 public: // Enumerations

    45     /**

    46     * Elements that currently support custom graphics.

    47     *

    48     * @since 3.2

    49     */

    50     enum TSliderGfxElements

    51         {

    52         /**

    53         * Left cap component of the slider, without filling. Left cap equals

    54         * to bottom cap in vertical layout.

    55         */

    56         EElemEmptyLeftCap,

    57 

    58         /**

    59         * Right cap component of the slider, without filling. Right cap equals

    60         * to top cap in vertical layout.

    61         */

    62         EElemEmptyRightCap,

    63         

    64         /**

    65         * Line component of the slider, without filling.

    66         */

    67         EElemEmptyLine,

    68         

    69         /**

    70         * Line component of the slider, with filling.

    71         */

    72         EElemFilledLine,

    73         

    74         /**

    75         * Left cap component of the slider, with filling.

    76         */

    77         EElemFilledLeftCap,

    78         

    79         /**

    80         * Right cap component of the slider, with filling.

    81         */

    82         EElemFilledRightCap,

    83         

    84         /**

    85         * Marker component of the slider.

    86         */

    87         EElemMarker,

    88         

    89         /**

    90         * Tick mark component of the slider. Small evenly spaced lines,

    91         * placed vertically in relation to slider itself.

    92         */

    93         EElemTickMark,

    94 

    95         /**

    96         * Marker component of the slider when dragged

    97         */

    98         EElemMarkerSelected

    99         };

   100 

   101     /**

   102     * Supported slider position indicators.

   103     *

   104     * @since 3.2

   105     */

   106     enum

   107         {

   108         /**

   109         * Flag for enabling/disabling line filling. With line filling different

   110         * graphics will be used for the the slider line's left and right sides

   111         * (the current marker position as pivot). The left side is considered

   112         * filled line and the right side empty line.

   113         *

   114         * When line filling is enabled the graphics element @c EElemFilledLine

   115         * is used for the left side and @c EElemEmptyLine for the right. If

   116         * line filling is disabled @c EElemEmptyLine is used for the whole

   117         * line.

   118         */

   119         EPosFilling  = 0x01,

   120         /**

   121         * Flag for enabling/disabling line marker (the knob). While disabled

   122         * marker is not visible, the marker area will still be used for touch

   123         * input.

   124         */

   125         EPosMarker   = 0x02            

   126         };

   127 

   128     /**

   129     * Event for slider thumb/marker dragging.

   130     *

   131     * @since 5.0

   132     */

   133     enum

   134         {

   135         /**

   136         * Slider thumb/marker drag start

   137         */

   138         EDragMarkerStart  = 1000,

   139         /**

   140         * Slider thumb/marker drag end

   141         */

   142         EDragMarkerEnd

   143         };

   144         

   145 public:

   146     /**

   147     * Default Constructor.

   148     */

   149     IMPORT_C CAknSlider();

   150 

   151     /**

   152     * Destructor.

   153     */

   154     IMPORT_C ~CAknSlider();

   155 

   156     /**

   157     * Sets the value of the slider control and also updates the iValueLabel

   158     * text. There are the following constraints on the value:

   159     *    it must be within the current range,

   160     *    it must be at a value that is minimum + N * stepsize.

   161     * If these are not both true, then the method will Panic

   162     *

   163     * @param aValue Sets the value of the slider.

   164     */

   165     IMPORT_C void SetValueL( TInt aValue );

   166 

   167     /**

   168     * Returns the value of the slider control

   169     *

   170     * @return Slider value.

   171     */

   172     IMPORT_C TInt Value() const;

   173 

   174     /**

   175     * Sets the range of the slider control. Maximum value must be greater than

   176     * the minimum value, or the method will Panic.

   177     *

   178     * @param aMinimumValue The minimum value of the slider control

   179     * @param aMaximumValue The maximum value of the slider control

   180     */

   181     IMPORT_C void SetRange( TInt aMinimumValue, TInt aMaximumValue );

   182 

   183     /**

   184     * Gets the range of the slider control. Maximum value must be greater than

   185     * the minimum value, or the method will Panic.

   186     *

   187     * @since 3.2

   188     * @param aMinimumValue The minimum value of the slider control

   189     * @param aMaximumValue The maximum value of the slider control

   190     */

   191     IMPORT_C void GetRange( TInt& aMinimumValue, TInt& aMaximumValue );

   192     

   193     /**

   194     * Sets the step size. The step size must divide evenly into the Range. This

   195     * routine should be called after SetRange if either is called.

   196     *

   197     * @param aStepSize The value of the step size

   198     */

   199     IMPORT_C void SetStepSize( TInt aStepSize );

   200 

   201     /**

   202     * Sets the text to the minimum label.

   203     *

   204     * @param aText The text passed is set to the minimum label

   205     */

   206     IMPORT_C void SetMinimumTextL( const TDesC& aText );

   207 

   208     /**

   209     * Sets the text to the maximum label.

   210     *

   211     * @param aText The text passed is set to the maximum label

   212     */

   213     IMPORT_C void SetMaximumTextL( const TDesC& aText );

   214 

   215     /**

   216     * Sets the value of decimal places. The legal range is 0 - 9 inclusive.

   217     *

   218     * @param aDecimalPlaces The value of the decimal place

   219     */

   220     IMPORT_C void SetDecimalPlaces( TInt aDecimalPlaces );

   221 

   222     /**

   223     * Returns the value of decimal place.

   224     *

   225     * @return the value of decimal place.

   226     */

   227     IMPORT_C TInt DecimalPlaces() const;

   228 

   229     /**

   230     * Allows setting custom graphics for a certain slider element. Existing

   231     * icons (custom or default) for the element are discarded. Note that some

   232     * elements might not be visible until the corresponding functionality is

   233     * enabled, see @c SetPositionIndicators and @c SetTicksEnabled.

   234     *

   235     * Slider takes care of scaling the given icons to the correct size,

   236     * provided that they have been created with @c AknIconUtils or @c AknsUtils

   237     * interfaces. It also handles re-scaling the icons if the slider layout

   238     * changes.

   239     *

   240     * If the custom icons are created by using skin items (e.g. using color

   241     * from skin), remember to change the icons whenever skin changes, see

   242     * @c CCoeControl::HandleResourceChange. In addition, note that slider can

   243     * be with horizontal or vertical layout, @see Orientation

   244     *

   245     * @param aElement The element ID to which the icons are assigned, one of

   246     *                 @c TGfxElements.

   247     *

   248     * @param aBitmap The icon used for the element, must be non-NULL,

   249     *                ownership is transferred to slider.

   250     *

   251     * @param aMask Optional mask for the aBitmap, can be NULL, ownership

   252     *              is transferred to slider.

   253     *

   254     * @par Exceptions:

   255     *   Will panic with EAknPanicInvalidValue if the element ID is invalid or

   256     *   aBitmap is NULL.

   257     *

   258     * @since 3.2

   259     */

   260     IMPORT_C void SetGraphics( TInt aElement,

   261                                CFbsBitmap* aBitmap,

   262                                CFbsBitmap* aMask );

   263     

   264     /**

   265     * Makes an element to use default graphics. Possible custom graphics for

   266     * the element is discarded.

   267     *

   268     * @param aElement The element ID which should use default graphics, one of

   269     *                 @c TGfxElements.

   270     *

   271     * @par Exceptions:

   272     *   Will panic with EAknPanicInvalidValue if the element index is invalid.

   273     *

   274     * @since 3.2

   275     */

   276     IMPORT_C void UseDefaultGraphics( TInt aElement );

   277 

   278     /**

   279     * Queries whether some element is using default graphics.

   280     *

   281     * @param aElement The element ID which should use default graphics, one of

   282     *                 @c TGfxElements.

   283     *

   284     * @return ETrue if default graphics is used for the element, EFalse

   285     *         otherwise (custom graphics used).

   286     *

   287     * @par Exceptions:

   288     *   Will panic with EAknPanicInvalidValue if the element index is invalid.

   289     *

   290     * @since 3.2

   291     */

   292     IMPORT_C TBool UsesDefaultGraphics( TInt aElement ) const;

   293 

   294     /**

   295     * Configures line position indicators, which display the slider's current

   296     * position. Possible indicators are defined in @c EPositionIndicator, at

   297     * least one of them must be defined (to display some position information).

   298     * Multiple values can be enabled by using bitwise or, e.g. @c EPosFilling |

   299     * EPosMarker. The new flags will fully override the old values. The default

   300     * value is @c EPosMarker.

   301     *

   302     * @param aFlags Bitmask containing flags from @c EPositionIndicator. At

   303     *               least one flag should be set.

   304     *

   305     * @par Exceptions:

   306     *   If none of the flags in @c EPositionIndicator is set, the code defaults

   307     *   silently to @c EPosMarker.

   308     *

   309     * @since 3.2

   310     */

   311     IMPORT_C void SetPositionIndicators( TUint32 aFlags );

   312     

   313    

   314     /**

   315     * Queries the current status of position indicators.

   316     *

   317     * @return Bitmask containing flags as defined in @c EPositionIndicator

   318     *

   319     * @since 3.2

   320     */

   321     IMPORT_C TUint32 PositionIndicators() const;

   322 

   323     /**

   324     * Queries the current orientation status.

   325     *

   326     * @return The current orientation, see @c TAknOrientation.

   327     *

   328     * @since 3.2

   329     */

   330     IMPORT_C TAknOrientation Orientation() const;

   331 

   332     /**

   333     * Enables/disables the tick marks. Tick marks are disabled by default.

   334     * Enabling tick marks affects only the visual appearance of slider. That is,

   335     * enabling slider step handling is not changed.

   336     *

   337     * @param aStatus ETrue to enable tick marks, EFalse to disable.

   338     *

   339     * @since 3.2

   340     */

   341     IMPORT_C void SetTicksEnabled( TBool aStatus );

   342 

   343     /**

   344     * Queries the current tick mark status.

   345     *

   346     * @return ETrue if tick marks are enabled, EFalse otherwise.

   347     *

   348     * @since 3.2

   349     */

   350     IMPORT_C TBool TicksEnabled() const;

   351 

   352     /**

   353     * Sets the tick interval used for drawing the tick marks. Tick interval is

   354     * in the slider range units (not in pixels). If interval value is set to 0,

   355     * the slider step size is used as tick interval, see @c SetStepSize. The

   356     * default interval value is 0.

   357     *

   358     * @param aInterval The value set as tick interval, always >= 0.

   359     *

   360     * @since 3.2

   361     */

   362     IMPORT_C void SetTickInterval( TUint aInterval );

   363 

   364     /**

   365     * Queries the current tick interval value.

   366     *

   367     * @return Current tick interval, always >= 0.

   368     *

   369     * @since 3.2

   370     */

   371     IMPORT_C TUint TickInterval() const;

   372 

   373     /**

   374     * Returns slider bitmap to "list pane for setting item" (setting option

   375     * item slider graphic). Ownership of the returned bitmap is transfered to

   376     * the caller.

   377     *

   378     * @param aValue Current value

   379     * @param aResourceId Slider resource that contains minimum and maximum

   380     *                    values

   381     * @return Slider bitmap. Ownership of the bitmap is transfered to the

   382     *         caller.

   383     */

   384     IMPORT_C static CFbsBitmap* CreateBitmapL( TInt aValue,

   385                                                TInt aResourceId );

   386 

   387     /**

   388     * Returns slider bitmap to "list pane for setting item" (setting option

   389     * item slider graphic). Ownership of the returned bitmap is transfered to

   390     * the caller.

   391     *

   392     * @param aValue Current value

   393     * @param aMinimumValue Slider minimum value

   394     * @param aMaximumValue Slider maximum value

   395     * @return Slider bitmap. Ownership of the bitmap is transfered to the

   396     *         caller

   397     */

   398     IMPORT_C static CFbsBitmap* CreateBitmapL( TInt aValue,

   399                                                TInt aMinimumValue,

   400                                                TInt aMaximumValue );

   401 

   402     /**

   403     * Returns slider icon to "list pane for setting item" (setting option item

   404     * slider graphic). Ownership of the returned icon is transfered to the

   405     * caller.

   406     *

   407     * @param aValue Current value

   408     * @param aResourceId Slider resource that contains minimum and maximum

   409     *                    values

   410     * @return Slider icon. Ownership of the icon is transfered to the caller

   411     */

   412     IMPORT_C static CGulIcon* CreateSetStyleListBoxIconL( TInt aValue,

   413                                                           TInt aResourceId );

   414 

   415     /**

   416     * Returns slider icon to "list pane for setting item" (setting option item

   417     * slider graphic). Ownership of the returned icon is transfered to the

   418     * caller.

   419     *

   420     * @param aValue Current value

   421     * @param aMinimumValue Slider minimum value

   422     * @param aMaximumValue Slider maximum value

   423     * @return Slider bitmap. Ownership of the icon is transfered to the caller

   424     */

   425     IMPORT_C static CGulIcon* CreateSetStyleListBoxIconL( TInt aValue,

   426                                                           TInt aMinimumValue,

   427                                                           TInt aMaximumValue );

   428     /**

   429     * Call CCoeControl::EnableDragEvents()

   430     *

   431     * @since 3.2

   432     */                                                      

   433     IMPORT_C void EnableDrag();

   434 

   435 public:

   436     /**

   437     * From CCoeControl, returns the size of the control. And yes, this method

   438     * is non-const.

   439     *

   440     * @return size of the control

   441     */

   442     TSize MinimumSize();

   443 

   444     /**

   445     * From CCoeControl, Handles key event.

   446     *

   447     * @param aKeyEvent The key event.

   448     * @param aType The type of the event.

   449     * @return Indicates whether the key event was used by this control or not

   450     */

   451     TKeyResponse OfferKeyEventL( const TKeyEvent& aKeyEvent,

   452                                  TEventCode aType );

   453 

   454     /**

   455     * From CCoeControl, essential for Dialog/Form construction.

   456     *

   457     * @param aReader which reads the values specified in the resource file

   458     */

   459     IMPORT_C void ConstructFromResourceL( TResourceReader& aReader );

   460 

   461     /**

   462     * This function is used for constructing the control.

   463     *

   464     * @param aParent Pointer to the parent control.

   465     * @paran aValue Current value of the slider control.

   466     * @param aReader which reads the values specified in the resource file.

   467     */

   468     IMPORT_C void ConstructFromResourceL( CCoeControl* aParent,

   469                                           TInt aValue,

   470                                           TResourceReader& aReader );

   471 

   472     /**

   473     * This function toggles between edit and view modes

   474     *

   475     * @param aType Specifies the mode.

   476     */

   477     IMPORT_C void HandleResourceChange( TInt aType );

   478 

   479     /**

   480      * This function will be called when focus changed.

   481      *

   482      * @param aDrawNow if the control needs to call DrawNow().

   483      */

   484     IMPORT_C virtual void FocusChanged(TDrawNow aDrawNow);

   485 

   486 public:

   487     /**

   488     * This function is used specifically in the forms. (For Forms/Dialogs to

   489     * use with LAF) Returns the number of lines on the control.

   490     *

   491     * @return Number of lines

   492     */

   493     IMPORT_C TInt NumberOfLines() const;

   494 

   495     /**

   496     * This routine can be used to combine the resource for a Slider with a

   497     * value to get the same value text that you would get if you had the

   498     * instantiated control

   499     *

   500     * @param aValue The value to format

   501     * @param aResourceId AKN_SLIDER resource id

   502     *

   503     * @return Transfer of ownership of descriptor containing the value text

   504     */

   505     IMPORT_C static HBufC* CreateValueTextInHBufCL( TInt aValue,

   506                                                     TInt aResourceId );

   507                                                     

   508     void SuppressDrawing( TBool aSuppress );

   509 

   510 protected:

   511     /**

   512     * From CCoeControl, Called by framework when the view size is changed.

   513     */

   514     void SizeChanged();

   515 

   516     /**

   517     * From CCoeControl, Drawing function which draws the control

   518     *

   519     * @param aRect Specified area to be drawn

   520     */

   521     void Draw( const TRect& aRect ) const;

   522 

   523    /**

   524     * From CCoeControl, Returns number of components.

   525     *

   526     * @return Number of component controls

   527     */

   528     IMPORT_C virtual TInt CountComponentControls() const;

   529 

   530     /**

   531     * From CCoeControl, Returns pointer to particular component

   532     *

   533     * @param aIndex Index whose control's pointer has to returned.

   534     * @return Pointer to component control

   535     */

   536     IMPORT_C virtual CCoeControl* ComponentControl( TInt aIndex ) const;

   537 

   538 public:

   539     /**

   540     * From CCoeControl. Handles pointer event

   541     *

   542     * @param aPointerEvent Pointer event to be handled

   543     */

   544     IMPORT_C void HandlePointerEventL( const TPointerEvent& aPointerEvent );

   545     TInt StepSize() const;

   546 

   547 private:

   548     /**

   549     * From CAknControl

   550     */

   551     IMPORT_C void* ExtensionInterface( TUid aInterface );

   552 

   553 protected:

   554     /**

   555     * Sets the text to the value label

   556     */

   557     IMPORT_C void SetValueTextL();

   558 

   559 public:

   560 

   561     /**

   562     * Report event for thumb/marker dragging via HandleControlEventL

   563     *

   564     * @since 5.0

   565     */ 

   566     void ReportMarkerDragEvent( TBool aEnable );

   567     

   568 private:

   569     /**

   570     * This function creates the bitmaps and labels. Also it sets the

   571     * container window for the labels.

   572     */

   573     void ConstructL();

   574 

   575     void InitializeBitmapsL();

   576 

   577     /**

   578     * static routine for setting the value text.

   579     * @param valueBuf Buffer to hold the result. Must be big enough to hold

   580     *   value label as formatted from the resources and value provided, though

   581     *   it is protected from overflow. Contained text will be truncated to

   582     *   KValueLabelTextMaxLength

   583     * @param aValue Slider value to format

   584     * @param aResourceData    resource Id to read from

   585     */

   586     static void DoSetValueTextL( TDes& valueBuf, TInt aValue,

   587                                  const CAknSliderData& aResourceData );

   588     

   589     /**

   590     * This method is used to trap all the accesses to the internal data. It

   591     * panics with EAknPanicObjectNotFullyConstructed if iData is not

   592     * constructed, that is, if 2nd stage construction has not taken place (or

   593     * has failed).

   594     */

   595     CAknSliderData* SliderData() const;

   596 

   597     /**

   598     * This class is a utility to protect StringLoader::Format from being

   599     * called without a formatting token.

   600     *

   601     * StringLoader is used in current implementation. See StringLoader::Format

   602     * for the semantics of the parameters.

   603     *

   604     * The other thing to note is that the output for descriptor must be able

   605     * to accept up to KValueLabelTextMaxLength characters.

   606     *

   607     * @param aOutput Output of format operation

   608     * @param aFormat Formatting descriptor.

   609     * @param aValue  Descriptor to substitute for the %U token potentially

   610     *                present in the formatting descriptor.

   611     */

   612     static void FormatWithOrWithoutTokenL( TDes& aOutput,

   613                                            const TDesC& aFormat,

   614                                            const TDesC& aValue );

   615 

   616     // layout methods

   617     void FormSliderLayout1();

   618     void FormSliderLayout2();

   619     void FormSliderLayout3();

   620     void SettingsItemSliderLayout();

   621     void VerticalSliderLayout();

   622     void HorizontalSliderLayout();

   623     void MIDPFormSliderLayout();

   624     

   625     void SetLabelColor();

   626 

   627    

   628     void CreateDecoratorImageFromResourceL( TInt aImageResourceId );

   629 

   630     // Internal access methods

   631     TInt Layout() const;

   632     TInt MaximumValue() const;

   633     TInt MinimumValue() const;

   634     TInt Range() const;

   635 

   636     // Starts a timer for feedback effect visualization.

   637     void StartTimerL();

   638 

   639     // Callback for feedback effect.

   640     static TInt IndicationDrawCallbackL( TAny* aThis );

   641 

   642     // Implementation of the feedback effect.

   643     void SmallDirectionIndicationL();

   644 

   645     void DrawHorizontalTickMarks( CWindowGc& aGc ) const;

   646     void DrawVerticalTickMarks( CWindowGc& aGc ) const;

   647 

   648     void TranslateValueL( TInt aDelta, TBool aFeedback = EFalse );

   649 

   650     void GetMarkerRect( TRect& aRect ) const;

   651     TSize MarkerSize() const;

   652     TPoint MarkerPos() const;

   653 

   654     void DrawHorizontal( TBool aDrawMarker ) const;

   655     void DrawVertical( TBool aDrawMarker ) const;

   656 

   657     void DrawHorizontalLine( CWindowGc& aGc ) const;

   658     void DrawVerticalLine( CWindowGc& aGc ) const;

   659 

   660     void FetchGfx( TAknSliderGfx& aGfx, TInt aElement, const TSize& aSize ) const;

   661     

   662     // calculate the correct value according to the input point

   663     TInt CalcAlignedValue( const TPoint& aPoint ); 

   664 

   665 private:

   666     CEikImage* iImage;

   667     CEikLabel* iValueLabel;

   668     CEikLabel* iMinLabel;

   669     CEikLabel* iMaxLabel;

   670     CFbsBitmap* iMarkerBmp;

   671     CFbsBitmap* iMarkerMaskBmp;

   672     TRect iMarkerArea;

   673     TRect iLineRect;

   674     TInt iValue;

   675     TBool iEditable;

   676     TRgb iColor;

   677 

   678     // Not used, kept for binary compatibility. Another pointer with same name

   679     // in iData is really used

   680     HBufC* iSingularText;

   681 

   682     CAknSliderData* iData;

   683     CAknSliderExtension* iExt;

   684 

   685     TInt iSpare[4];

   686 };

   687 

   688 #endif // __AKNSLIDER_H__

   689 

   690 // End of File