/*

* 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