/*

 * Copyright (c) 2005-2006 Nokia Corporation and/or its subsidiary(-ies).

 * All rights reserved.

 * This component and the accompanying materials are made available

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

 * which accompanies this distribution, and is available

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

 *

 * Initial Contributors:

 * Nokia Corporation - initial contribution.

 *

 * Contributors:

 *

 * Description:  Slider editor class

 *

 */

 #ifndef __AKNSLIDER_H__

 #define __AKNSLIDER_H__

 // INCLUDES

 #include <eikbctrl.h>

 #include <eiklabel.h>

 #include <eikimage.h>

 #include <avkon.hrh> // For TAknOrientation

 // CONSTANTS

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

 // number, special characters and supplied text.

 const TInt KValueLabelTextMaxLength = 30;

 // Forward declarations

 class CGulIcon;

 class MAknsSkinInstance;

 class CAknSliderExtension;

 class CAknSliderData;

 struct TAknSliderGfx;

 // CLASS DECLARATION

 class CAknSlider : public CEikBorderedControl

     {

 public: // Enumerations

     /**

     * Elements that currently support custom graphics.

     *

     * @since 3.2

     */

     enum TSliderGfxElements

         {

         /**

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

         * to bottom cap in vertical layout.

         */

         EElemEmptyLeftCap,

         /**

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

         * to top cap in vertical layout.

         */

         EElemEmptyRightCap,

         /**

         * Line component of the slider, without filling.

         */

         EElemEmptyLine,

         /**

         * Line component of the slider, with filling.

         */

         EElemFilledLine,

         /**

         * Left cap component of the slider, with filling.

         */

         EElemFilledLeftCap,

         /**

         * Right cap component of the slider, with filling.

         */

         EElemFilledRightCap,

         /**

         * Marker component of the slider.

         */

         EElemMarker,

         /**

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

         * placed vertically in relation to slider itself.

         */

         EElemTickMark,

         /**

         * Marker component of the slider when dragged

         */

         EElemMarkerSelected

         };

     /**

     * Supported slider position indicators.

     *

     * @since 3.2

     */

     enum

         {

         /**

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

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

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

         * filled line and the right side empty line.

         *

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

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

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

         * line.

         */

         EPosFilling  = 0x01,

         /**

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

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

         * input.

         */

         EPosMarker   = 0x02            

         };

     /**

     * Event for slider thumb/marker dragging.

     *

     * @since 5.0

     */

     enum

         {

         /**

         * Slider thumb/marker drag start

         */

         EDragMarkerStart  = 1000,

         /**

         * Slider thumb/marker drag end

         */

         EDragMarkerEnd

         };

 public:

     /**

     * Default Constructor.

     */

     IMPORT_C CAknSlider();

     /**

     * Destructor.

     */

     IMPORT_C ~CAknSlider();

     /**

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

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

     *    it must be within the current range,

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

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

     *

     * @param aValue Sets the value of the slider.

     */

     IMPORT_C void SetValueL( TInt aValue );

     /**

     * Returns the value of the slider control

     *

     * @return Slider value.

     */

     IMPORT_C TInt Value() const;

     /**

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

     * the minimum value, or the method will Panic.

     *

     * @param aMinimumValue The minimum value of the slider control

     * @param aMaximumValue The maximum value of the slider control

     */

     IMPORT_C void SetRange( TInt aMinimumValue, TInt aMaximumValue );

     /**

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

     * the minimum value, or the method will Panic.

     *

     * @since 3.2

     * @param aMinimumValue The minimum value of the slider control

     * @param aMaximumValue The maximum value of the slider control

     */

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

     /**

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

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

     *

     * @param aStepSize The value of the step size

     */

     IMPORT_C void SetStepSize( TInt aStepSize );

     /**

     * Sets the text to the minimum label.

     *

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

     */

     IMPORT_C void SetMinimumTextL( const TDesC& aText );

     /**

     * Sets the text to the maximum label.

     *

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

     */

     IMPORT_C void SetMaximumTextL( const TDesC& aText );

     /**

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

     *

     * @param aDecimalPlaces The value of the decimal place

     */

     IMPORT_C void SetDecimalPlaces( TInt aDecimalPlaces );

     /**

     * Returns the value of decimal place.

     *

     * @return the value of decimal place.

     */

     IMPORT_C TInt DecimalPlaces() const;

     /**

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

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

     * elements might not be visible until the corresponding functionality is

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

     *

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

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

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

     * changes.

     *

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

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

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

     * be with horizontal or vertical layout, @see Orientation

     *

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

     *                 @c TGfxElements.

     *

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

     *                ownership is transferred to slider.

     *

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

     *              is transferred to slider.

     *

     * @par Exceptions:

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

     *   aBitmap is NULL.

     *

     * @since 3.2

     */

     IMPORT_C void SetGraphics( TInt aElement,

                                CFbsBitmap* aBitmap,

                                CFbsBitmap* aMask );

     /**

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

     * the element is discarded.

     *

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

     *                 @c TGfxElements.

     *

     * @par Exceptions:

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

     *

     * @since 3.2

     */

     IMPORT_C void UseDefaultGraphics( TInt aElement );

     /**

     * Queries whether some element is using default graphics.

     *

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

     *                 @c TGfxElements.

     *

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

     *         otherwise (custom graphics used).

     *

     * @par Exceptions:

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

     *

     * @since 3.2

     */

     IMPORT_C TBool UsesDefaultGraphics( TInt aElement ) const;

     /**

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

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

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

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

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

     * value is @c EPosMarker.

     *

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

     *               least one flag should be set.

     *

     * @par Exceptions:

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

     *   silently to @c EPosMarker.

     *

     * @since 3.2

     */

     IMPORT_C void SetPositionIndicators( TUint32 aFlags );

     /**

     * Queries the current status of position indicators.

     *

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

     *

     * @since 3.2

     */

     IMPORT_C TUint32 PositionIndicators() const;

     /**

     * Queries the current orientation status.

     *

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

     *

     * @since 3.2

     */

     IMPORT_C TAknOrientation Orientation() const;

     /**

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

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

     * enabling slider step handling is not changed.

     *

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

     *

     * @since 3.2

     */

     IMPORT_C void SetTicksEnabled( TBool aStatus );

     /**

     * Queries the current tick mark status.

     *

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

     *

     * @since 3.2

     */

     IMPORT_C TBool TicksEnabled() const;

     /**

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

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

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

     * default interval value is 0.

     *

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

     *

     * @since 3.2

     */

     IMPORT_C void SetTickInterval( TUint aInterval );

     /**

     * Queries the current tick interval value.

     *

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

     *

     * @since 3.2

     */

     IMPORT_C TUint TickInterval() const;

     /**

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

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

     * the caller.

     *

     * @param aValue Current value

     * @param aResourceId Slider resource that contains minimum and maximum

     *                    values

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

     *         caller.

     */

     IMPORT_C static CFbsBitmap* CreateBitmapL( TInt aValue,

                                                TInt aResourceId );

     /**

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

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

     * the caller.

     *

     * @param aValue Current value

     * @param aMinimumValue Slider minimum value

     * @param aMaximumValue Slider maximum value

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

     *         caller

     */

     IMPORT_C static CFbsBitmap* CreateBitmapL( TInt aValue,

                                                TInt aMinimumValue,

                                                TInt aMaximumValue );

     /**

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

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

     * caller.

     *

     * @param aValue Current value

     * @param aResourceId Slider resource that contains minimum and maximum

     *                    values

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

     */

     IMPORT_C static CGulIcon* CreateSetStyleListBoxIconL( TInt aValue,

                                                           TInt aResourceId );

     /**

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

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

     * caller.

     *

     * @param aValue Current value

     * @param aMinimumValue Slider minimum value

     * @param aMaximumValue Slider maximum value

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

     */

     IMPORT_C static CGulIcon* CreateSetStyleListBoxIconL( TInt aValue,

                                                           TInt aMinimumValue,

                                                           TInt aMaximumValue );

     /**

     * Call CCoeControl::EnableDragEvents()

     *

     * @since 3.2

     */                                                      

     IMPORT_C void EnableDrag();

 public:

     /**

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

     * is non-const.

     *

     * @return size of the control

     */

     TSize MinimumSize();

     /**

     * From CCoeControl, Handles key event.

     *

     * @param aKeyEvent The key event.

     * @param aType The type of the event.

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

     */

     TKeyResponse OfferKeyEventL( const TKeyEvent& aKeyEvent,

                                  TEventCode aType );

     /**

     * From CCoeControl, essential for Dialog/Form construction.

     *

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

     */

     IMPORT_C void ConstructFromResourceL( TResourceReader& aReader );

     /**

     * This function is used for constructing the control.

     *

     * @param aParent Pointer to the parent control.

     * @paran aValue Current value of the slider control.

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

     */

     IMPORT_C void ConstructFromResourceL( CCoeControl* aParent,

                                           TInt aValue,

                                           TResourceReader& aReader );

     /**

     * This function toggles between edit and view modes

     *

     * @param aType Specifies the mode.

     */

     IMPORT_C void HandleResourceChange( TInt aType );

     /**

      * This function will be called when focus changed.

      *

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

      */

     IMPORT_C virtual void FocusChanged(TDrawNow aDrawNow);

 public:

     /**

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

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

     *

     * @return Number of lines

     */

     IMPORT_C TInt NumberOfLines() const;

     /**

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

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

     * instantiated control

     *

     * @param aValue The value to format

     * @param aResourceId AKN_SLIDER resource id

     *

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

     */

     IMPORT_C static HBufC* CreateValueTextInHBufCL( TInt aValue,

                                                     TInt aResourceId );

     void SuppressDrawing( TBool aSuppress );

 protected:

     /**

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

     */

     void SizeChanged();

     /**

     * From CCoeControl, Drawing function which draws the control

     *

     * @param aRect Specified area to be drawn

     */

     void Draw( const TRect& aRect ) const;

    /**

     * From CCoeControl, Returns number of components.

     *

     * @return Number of component controls

     */

     IMPORT_C virtual TInt CountComponentControls() const;

     /**

     * From CCoeControl, Returns pointer to particular component

     *

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

     * @return Pointer to component control

     */

     IMPORT_C virtual CCoeControl* ComponentControl( TInt aIndex ) const;

 public:

     /**

     * From CCoeControl. Handles pointer event

     *

     * @param aPointerEvent Pointer event to be handled

     */

     IMPORT_C void HandlePointerEventL( const TPointerEvent& aPointerEvent );

     TInt StepSize() const;

 private:

     /**

     * From CAknControl

     */

     IMPORT_C void* ExtensionInterface( TUid aInterface );

 protected:

     /**

     * Sets the text to the value label

     */

     IMPORT_C void SetValueTextL();

 public:

     /**

     * Report event for thumb/marker dragging via HandleControlEventL

     *

     * @since 5.0

     */ 

     void ReportMarkerDragEvent( TBool aEnable );

 private:

     /**

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

     * container window for the labels.

     */

     void ConstructL();

     void InitializeBitmapsL();

     /**

     * static routine for setting the value text.

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

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

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

     *   KValueLabelTextMaxLength

     * @param aValue Slider value to format

     * @param aResourceData    resource Id to read from

     */

     static void DoSetValueTextL( TDes& valueBuf, TInt aValue,

                                  const CAknSliderData& aResourceData );

     /**

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

     * panics with EAknPanicObjectNotFullyConstructed if iData is not

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

     * has failed).

     */

     CAknSliderData* SliderData() const;

     /**

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

     * called without a formatting token.

     *

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

     * for the semantics of the parameters.

     *

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

     * to accept up to KValueLabelTextMaxLength characters.

     *

     * @param aOutput Output of format operation

     * @param aFormat Formatting descriptor.

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

     *                present in the formatting descriptor.

     */

     static void FormatWithOrWithoutTokenL( TDes& aOutput,

                                            const TDesC& aFormat,

                                            const TDesC& aValue );

     // layout methods

     void FormSliderLayout1();

     void FormSliderLayout2();

     void FormSliderLayout3();

     void SettingsItemSliderLayout();

     void VerticalSliderLayout();

     void HorizontalSliderLayout();

     void MIDPFormSliderLayout();

     void SetLabelColor();

     void CreateDecoratorImageFromResourceL( TInt aImageResourceId );

     // Internal access methods

     TInt Layout() const;

     TInt MaximumValue() const;

     TInt MinimumValue() const;

     TInt Range() const;

     // Starts a timer for feedback effect visualization.

     void StartTimerL();

     // Callback for feedback effect.

     static TInt IndicationDrawCallbackL( TAny* aThis );

     // Implementation of the feedback effect.

     void SmallDirectionIndicationL();

     void DrawHorizontalTickMarks( CWindowGc& aGc ) const;

     void DrawVerticalTickMarks( CWindowGc& aGc ) const;

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

     void GetMarkerRect( TRect& aRect ) const;

     TSize MarkerSize() const;

     TPoint MarkerPos() const;

     void DrawHorizontal( TBool aDrawMarker ) const;

     void DrawVertical( TBool aDrawMarker ) const;

     void DrawHorizontalLine( CWindowGc& aGc ) const;

     void DrawVerticalLine( CWindowGc& aGc ) const;

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

     // calculate the correct value according to the input point

     TInt CalcAlignedValue( const TPoint& aPoint ); 

     void StartFeedback( const TPointerEvent* aPointerEvent, TTimeIntervalMicroSeconds32 aTimeout );

     void StopFeedback();

     void ModifyFeedback();

     TInt FeedbackIntensity();

     /**

      * Provides the touch active area for setting item slider.

      * 

      * @return Touch active area rect.

      */

     TRect TouchActiveArea() const;

 private:

     CEikImage* iImage;

     CEikLabel* iValueLabel;

     CEikLabel* iMinLabel;

     CEikLabel* iMaxLabel;

     CFbsBitmap* iMarkerBmp;

     CFbsBitmap* iMarkerMaskBmp;

     TRect iMarkerArea;

     TRect iLineRect;

     TInt iValue;

     TBool iEditable;

     TRgb iColor;

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

     // in iData is really used

     HBufC* iSingularText;

     CAknSliderData* iData;

     CAknSliderExtension* iExt;

     TInt iSpare[4];

 };

 #endif // __AKNSLIDER_H__

 // End of File