/*
* 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