Slider

touchgfx/containers/Slider.hpp

A slider is a graphical element with which the user may set a value by moving an indicator on a slider, or simply by clicking the slider. The slider can operate in horizontal or vertical mode. The slider has two bitmaps. One bitmap is used on one side of the indicator. The other is used on the other side. They can be used in indicating the part of the slider value range that is currently selected.

The slider operates on an integer value range that can be set by the user.

Inherits from: Container, Drawable

Protected Types

enum	SliderOrientation { HORIZONTAL, VERTICAL }
	Values that represent slider orientations.

Public Functions

virtual int16_t	getIndicatorMax() const
	Gets indicator maximum previous set using setupHorizontalSlider() or setupVerticalSlider().
virtual int16_t	getIndicatorMin() const
	Gets indicator minimum previously set using setupHorizontalSlider() or setupVerticalSlider().
virtual int16_t	getMaxValue() const
	Gets the maximum value previously set using setValueRange().
virtual int16_t	getMinValue() const
	Gets the minimum value previously set using setValueRange().
int	getValue()
	Gets the current value represented by the indicator.
virtual void	handleClickEvent(const ClickEvent & event)
	Defines the event handler interface for ClickEvents.
virtual void	handleDragEvent(const DragEvent & event)
	Defines the event handler interface for DragEvents.
void	setBitmaps(const Bitmap & sliderBackground, const Bitmap & sliderBackgroundSelected, const Bitmap & indicator)
	Sets all the bitmaps for the Slider.
void	setBitmaps(const BitmapId sliderBackground, const BitmapId sliderBackgroundSelected, const BitmapId indicator)
	Sets all the bitmaps for the Slider.
void	setNewValueCallback(GenericCallback< const Slider &, int > & callback)
	Associates an action to be performed when the slider changes its value.
void	setStartValueCallback(GenericCallback< const Slider &, int > & callback)
	Associates an action to be performed when an interaction with the slider is initiated (click or drag).
void	setStopValueCallback(GenericCallback< const Slider &, int > & callback)
	Associates an action to be performed when an interaction with the slider ends (click or drag).
virtual void	setupHorizontalSlider(int16_t backgroundX, int16_t backgroundY, int16_t indicatorY, int16_t indicatorMinX, int16_t indicatorMaxX)
	Sets up the slider in horizontal mode with the range going from the left to right.
virtual void	setupVerticalSlider(int16_t backgroundX, int16_t backgroundY, int16_t indicatorX, int16_t indicatorMinY, int16_t indicatorMaxY)
	Sets up the slider in vertical mode with the range going from the bottom to top.
virtual void	setValue(int16_t value)
	Places the indicator at the specified value relative to the specified value range.
virtual void	setValueRange(int16_t minValue, int16_t maxValue)
	Sets the value range of the slider.
virtual void	setValueRange(int16_t minValue, int16_t maxValue, int16_t newValue)
	Sets the value range of the slider.
	Slider()

Protected Functions

virtual int	getIndicatorPositionRangeSize() const
	Gets the indicator position range, i.e.
virtual int16_t	getIndicatorRadius() const
	Gets the indicator radius, which is half the size of the indicator.
virtual int	getValueRangeSize() const
	Gets the value range, i.e.
virtual int	positionToValue(int16_t position) const
	Translate a position (x coordinate in horizontal mode and y in vertical mode) in the indicator position range to the corresponding value in the value range.
virtual void	updateIndicatorPosition(int16_t position)
	Updates the indicator position described by position.
virtual int16_t	valueToPosition(int value) const
	Translate a value in the value range to the corresponding position in the indicator position range (x coordinate in horizontal mode and y in vertical mode).

Protected Attributes

Image	background
	The background image.
Image	backgroundSelected
	The backgroundSelected image.
Container	backgroundSelectedViewPort
	The backgroundSelected view port. Controls the visible part of the backgroundSelected image.
int16_t	currentValue
	The current value represented by the slider.
Image	indicator
	The indicator image.
int16_t	indicatorMaxPosition
	The maximum position of the indicator (either x coordinate in horizontal mode or y coordinate in vertical mode)
int16_t	indicatorMinPosition
	The minimum position of the indicator (either x coordinate in horizontal mode or y coordinate in vertical mode)
GenericCallback< const Slider &, int > *	newValueCallback
	The new value callback (called when the indicator is moved)
SliderOrientation	sliderOrientation
	The selected slider orientation.
GenericCallback< const Slider &, int > *	startValueCallback
	The start value callback (called when an interaction with the indicator is initiated)
GenericCallback< const Slider &, int > *	stopValueCallback
	The stop value callback (called when an interaction with the indicator ends)
int16_t	valueRangeMax
	The value range max.
int16_t	valueRangeMin
	The value range min.

Additional inherited members

Public Functions inherited from Container

virtual void	add(Drawable & d)
	Adds a Drawable instance as child to this Container.
	Container()
virtual bool	contains(const Drawable & d)
	Query if a given Drawable has been added directly to this Container.
virtual void	draw(const Rect & invalidatedArea) const
	Draw this drawable.
virtual void	forEachChild(GenericCallback< Drawable & > * function)
	Executes the specified callback function for each child in the Container.
virtual Drawable *	getFirstChild()
	Obtain a pointer to the first child of this container.
virtual void	getLastChild(int16_t x, int16_t y, Drawable ** last)
	Gets the last child in the list of children in this Container.
virtual void	getLastChildNear(int16_t x, int16_t y, Drawable * last, int16_t fingerAdjustmentX, int16_t * fingerAdjustmentY)
	Works similar to getLastChild() but also considers the current set finger size in HAL.
virtual Rect	getSolidRect() const
	Get (the largest possible) rectangle that is guaranteed to be solid (opaque).
virtual void	insert(Drawable * previous, Drawable & d)
	Inserts a Drawable after a specific child node.
virtual void	remove(Drawable & d)
	Removes a Drawable from the container by removing it from the linked list of children.
virtual void	removeAll()
	Removes all children in the Container by resetting their parent and sibling pointers.
virtual void	unlink()
	Removes all children by unlinking the first child.

Protected Functions inherited from Container

virtual Rect	getContainedArea() const
	Gets a rectangle describing the total area covered by the children of this container.
virtual void	moveChildrenRelative(int16_t deltaX, int16_t deltaY)
	Calls moveRelative on all children.

Protected Attributes inherited from Container

Drawable *	firstChild
	Pointer to the first child of this container. Subsequent children can be found through firstChild's nextSibling.

Public Functions inherited from Drawable

void	center()
	Centers the Drawable inside its parent.
void	centerX()
	Center the Drawable horizontally inside its parent.
void	centerY()
	Center the Drawable vertically inside its parent.
virtual void	childGeometryChanged()
	This function can be called on parent nodes to signal that the size or position of one or more of its children has changed.
virtual void	draw(const Rect & invalidatedArea) const =0
	Draw this drawable.
	Drawable()
	Initializes a new instance of the Drawable class.
void	drawToDynamicBitmap(BitmapId id)
	Render the Drawable object into a dynamic bitmap.
void	expand(int margin =0)
	Expands the Drawable to have the same size as its parent with a given margin around the edge.
Rect	getAbsoluteRect() const
	Helper function for obtaining the rectangle this Drawable covers, expressed in absolute coordinates.
virtual Drawable *	getFirstChild()
	Function for obtaining the first child of this drawable if any.
int16_t	getHeight() const
	Gets the height of this Drawable.
virtual void	getLastChild(int16_t x, int16_t y, Drawable ** last) =0
	Function for obtaining the the last child of this drawable that intersects with the specified point.
Drawable *	getNextSibling()
	Gets the next sibling node.
Drawable *	getParent() const
	Returns the parent node.
const Rect &	getRect() const
	Gets the rectangle this Drawable covers, in coordinates relative to its parent.
virtual Rect	getSolidRect() const =0
	Get (the largest possible) rectangle that is guaranteed to be solid (opaque).
virtual Rect	getSolidRectAbsolute()
	Helper function for obtaining the largest solid rect (as implemented by getSolidRect()) expressed in absolute coordinates.
virtual void	getVisibleRect(Rect & rect) const
	Function for finding the visible part of this drawable.
int16_t	getWidth() const
	Gets the width of this Drawable.
int16_t	getX() const
	Gets the x coordinate of this Drawable, relative to its parent.
int16_t	getY() const
	Gets the y coordinate of this Drawable, relative to its parent.
virtual void	handleGestureEvent(const GestureEvent & event)
	Defines the event handler interface for GestureEvents.
virtual void	handleTickEvent()
	Called periodically by the framework if the Drawable instance has subscribed to timer ticks.
virtual void	invalidate() const
	Tell the framework that this entire Drawable needs to be redrawn.
virtual void	invalidateContent() const
	Tell the framework that the contents of the Drawable needs to be redrawn.
virtual void	invalidateRect(Rect & invalidatedArea) const
	Request that a region of this drawable is redrawn.
bool	isTouchable() const
	Gets whether this Drawable receives touch events or not.
bool	isVisible() const
	Gets whether this Drawable is visible.
virtual void	moveRelative(int16_t x, int16_t y)
	Moves the drawable.
virtual void	moveTo(int16_t x, int16_t y)
	Moves the drawable.
virtual void	setHeight(int16_t height)
	Sets the height of this drawable.
void	setPosition(const Drawable & drawable)
	Sets the position of the Drawable to the same as the given Drawable.
void	setPosition(int16_t x, int16_t y, int16_t width, int16_t height)
	Sets the size and position of this Drawable, relative to its parent.
void	setTouchable(bool touch)
	Controls whether this Drawable receives touch events or not.
void	setVisible(bool vis)
	Controls whether this Drawable should be visible.
virtual void	setWidth(int16_t width)
	Sets the width of this drawable.
void	setWidthHeight(const Bitmap & bitmap)
	Sets the dimensions (width and height) of the Drawable without changing the x and y coordinates).
void	setWidthHeight(const Drawable & drawable)
	Sets the dimensions (width and height) of the Drawable without changing the x and y coordinates).
void	setWidthHeight(const Rect & other)
	Sets the dimensions (width and height) of the Drawable without changing the x and y coordinates).
void	setWidthHeight(int16_t width, int16_t height)
	Sets the dimensions (width and height) of the Drawable without changing the x and y coordinates).
virtual void	setX(int16_t x)
	Sets the x coordinate of this Drawable, relative to its parent.
void	setXY(const Drawable & drawable)
	Sets the x and y coordinates of this Drawable.
void	setXY(int16_t x, int16_t y)
	Sets the x and y coordinates of this Drawable, relative to its parent.
virtual void	setY(int16_t y)
	Sets the y coordinate of this Drawable, relative to its parent.
virtual void	translateRectToAbsolute(Rect & r) const
	Helper function for converting a region of this Drawable to absolute coordinates.
virtual	~Drawable()
	Finalizes an instance of the Drawable class.

Protected Attributes inherited from Drawable

Drawable *	nextSibling
	Pointer to the next Drawable.
Drawable *	parent
	Pointer to this drawable's parent.
Rect	rect
	The coordinates of this Drawable, relative to its parent.
bool	touchable
	True if this drawable should receive touch events.
bool	visible
	True if this drawable should be drawn.

Protected Types Documentation

SliderOrientation

enum SliderOrientation

Values that represent slider orientations.

HORIZONTAL	The Slider can be moved horizontally between left and right.
VERTICAL	The Slider can be moved vertically between top and bottom.

Public Functions Documentation

getIndicatorMax

virtual int16_t getIndicatorMax	(			)	const

Gets indicator maximum previous set using setupHorizontalSlider() or setupVerticalSlider().

Returns:

The calculated indicator maximum.

See also:

setupHorizontalSlider, setupVerticalSlider, getIndicatorMin

getIndicatorMin

virtual int16_t getIndicatorMin	(			)	const

Gets indicator minimum previously set using setupHorizontalSlider() or setupVerticalSlider().

Returns:

The indicator minimum.

See also:

setupHorizontalSlider, setupVerticalSlider, getIndicatorMax

getMaxValue

virtual int16_t getMaxValue	(			)	const

Gets the maximum value previously set using setValueRange().

Returns:

The maximum value.

See also:

setValueRange, getMinValue

getMinValue

virtual int16_t getMinValue	(			)	const

Gets the minimum value previously set using setValueRange().

Returns:

The minimum value.

See also:

setValueRange, getMaxValue

getValue

int getValue	(			)

Gets the current value represented by the indicator.

Returns:

The current value.

handleClickEvent

virtual void handleClickEvent	(	const ClickEvent &	event	)

Defines the event handler interface for ClickEvents.

The default implementation ignores the event. The event is only received if the Drawable is touchable and visible.

Parameters:

event	The ClickEvent received from the HAL.

Reimplements: touchgfx::Drawable::handleClickEvent

handleDragEvent

virtual void handleDragEvent	(	const DragEvent &	event	)

Defines the event handler interface for DragEvents.

The default implementation ignores the event. The event is only received if the drawable is touchable and visible.

Parameters:

event	The DragEvent received from the HAL.

Reimplements: touchgfx::Drawable::handleDragEvent

setBitmaps

void setBitmaps	(	const Bitmap &	sliderBackground ,
		const Bitmap &	sliderBackgroundSelected ,
		const Bitmap &	indicator
		)

Sets all the bitmaps for the Slider.

The Slider shows the sliderBackgroundSelected bitmap in the region of the Slider that is selected, that is the area to the left of the indicator for a horizontal Slider and below the indicator for a vertical Slider. The sliderBackground is shown on the other side of the Slider. To ignore this effect simply use the same bitmap for both the sliderBackground and the sliderBackgroundSelected.

Parameters:

sliderBackground	The slider background with the slider range unselected.
sliderBackgroundSelected	The slider background with the slider range selected.
indicator	The indicator.

setBitmaps

void setBitmaps	(	const BitmapId	sliderBackground ,
		const BitmapId	sliderBackgroundSelected ,
		const BitmapId	indicator
		)

Sets all the bitmaps for the Slider.

The Slider shows the sliderBackgroundSelected bitmap in the region of the Slider that is selected, that is the area to the left of the indicator for a horizontal Slider and below the indicator for a vertical Slider. The sliderBackground is shown on the other side of the Slider. To ignore this effect simply use the same bitmap for both the sliderBackground and the sliderBackgroundSelected.

Parameters:

sliderBackground	The slider background with the slider range unselected.
sliderBackgroundSelected	The slider background with the slider range selected.
indicator	The indicator.

setNewValueCallback

void setNewValueCallback	(	GenericCallback< const Slider &, int > &	callback	)

Associates an action to be performed when the slider changes its value.

Parameters:

callback	The callback to be executed. The callback will be given a reference to the Slider and the current value of the slider.

See also:

GenericCallback

setStartValueCallback

void setStartValueCallback	(	GenericCallback< const Slider &, int > &	callback	)

Associates an action to be performed when an interaction with the slider is initiated (click or drag).

Parameters:

callback	The callback to be executed. The callback will be given a reference to the Slider and the current value of the slider at interaction start.

See also:

GenericCallback

setStopValueCallback

void setStopValueCallback	(	GenericCallback< const Slider &, int > &	callback	)

Associates an action to be performed when an interaction with the slider ends (click or drag).

Parameters:

callback	The callback to be executed. The callback will be given a reference to the Slider and the current value of the slider at interaction end.

See also:

GenericCallback

setupHorizontalSlider

virtual void setupHorizontalSlider	(	int16_t	backgroundX ,
		int16_t	backgroundY ,
		int16_t	indicatorY ,
		int16_t	indicatorMinX ,
		int16_t	indicatorMaxX
		)

Sets up the slider in horizontal mode with the range going from the left to right.

Places the backgrounds and the indicator inside the Slider container. It is possible to place the end points of the indicator outside the background image if it needs to go beyond the boundaries of the background. The width and height of the Slider will be adjusted appropriately so that both the background and the indicator will be fully visible in both the minimum and maximum indicator positions.

Calls setValue() with the current value (default 0) and triggers the newSliderValue callback.

Parameters:

backgroundX	The background x coordinate inside the slider.
backgroundY	The background y coordinate inside the slider.
indicatorY	The indicator y coordinate inside the slider.
indicatorMinX	The indicator minimum x coordinate inside the slider. This is the position used when the slider is at its minimum value. Must be less than indicatorMaxX.
indicatorMaxX	The indicator maximum x coordinate inside the slider. This is the position used when the slider is at its maximum value. Must be greater than indicatorMinX.

Note

The x and y position of the Slider will either be the left/top of the background or the left/top of the indicator in its minimum x coordinate.

setupVerticalSlider

virtual void setupVerticalSlider	(	int16_t	backgroundX ,
		int16_t	backgroundY ,
		int16_t	indicatorX ,
		int16_t	indicatorMinY ,
		int16_t	indicatorMaxY
		)

Sets up the slider in vertical mode with the range going from the bottom to top.

Places the backgrounds and the indicator inside the Slider container. It is possible to place the end points of the indicator outside the background image if it needs to go beyond the boundaries of the background. The width and height of the Slider will be adjusted appropriately so that both the background and the indicator will be fully visible in both the minimum and maximum indicator positions.

Calls setValue with the current value (default 0) and triggers the newSliderValue callback.

Parameters:

backgroundX	The background x coordinate inside the slider.
backgroundY	The background y coordinate inside the slider.
indicatorX	The indicator x coordinate inside the slider.
indicatorMinY	The indicator minimum y coordinate inside the slider. This is the position used when the slider is at its maximum value. Must be less than indicatorMaxX.
indicatorMaxY	The indicator maximum y coordinate inside the slider. This is the position used when the slider is at its minimum value. Must be greater than indicatorMinX.

Note

The x and y position of the Slider will either be the left/top of the background or the left/top of the indicator in its minimum y coordinate.

setValue

virtual void setValue	(	int16_t	value	)

Places the indicator at the specified value relative to the specified value range.

Values beyond the value range will be rounded to the min/max value in the value range.

Parameters:

value	The value.

Note

The value update triggers a newSliderValue callback just as a drag or click does. If the value range is larger than the number of pixels specified for the indicator min and indicator max, some values will not be represented by the slider and thus is not possible to set with this method. In this case the value will be rounded to the nearest value that is represented in the current setting.

See also:

setValueRange

setValueRange

virtual void setValueRange	(	int16_t	minValue ,
		int16_t	maxValue
		)

Sets the value range of the slider.

Values accepted and returned by the slider will be in this range.

The slider will set its value to the current value or round to minValue or maxValue if the current value is outside the new range.

Parameters:

minValue	The minimum value. Must be less than maxValue.
maxValue	The maximum value. Must be greater than minValue.

Note

If the range is larger than the number of pixels specified for the indicator min and indicator max, some values will not be represented by the slider.

setValueRange

virtual void setValueRange	(	int16_t	minValue ,
		int16_t	maxValue ,
		int16_t	newValue
		)

Sets the value range of the slider.

Values accepted and returned by the slider will be in this range.

The slider will set its value to the specified new value.

Parameters:

minValue	The minimum value. Must be less than maxValue.
maxValue	The maximum value. Must be greater than minValue.
newValue	The new value.

Note

If the range is larger than the number of pixels specified for the indicator min and max some values will not be represented by the slider.

Slider

Slider	(			)

Protected Functions Documentation

getIndicatorPositionRangeSize

virtual int getIndicatorPositionRangeSize	(			)	const

Gets the indicator position range, i.e.

the difference between max and min for the position of the indicator.

Returns:

The indicator position range.

getIndicatorRadius

virtual int16_t getIndicatorRadius	(			)	const

Gets the indicator radius, which is half the size of the indicator.

Returns:

The the indicator radius.

getValueRangeSize

virtual int getValueRangeSize	(			)	const

Gets the value range, i.e.

the difference between max and min for the value range.

Returns:

The value range.

positionToValue

virtual int positionToValue	(	int16_t	position	)

Translate a position (x coordinate in horizontal mode and y in vertical mode) in the indicator position range to the corresponding value in the value range.

Parameters:

position	The position.

Returns:

The value that corresponds to the coordinate.

updateIndicatorPosition

virtual void updateIndicatorPosition	(	int16_t	position	)

Updates the indicator position described by position.

Calls the newSliderValueCallback with the new value.

Parameters:

position	The position (x coordinate in horizontal mode and y coordinate in vertical mode).

valueToPosition

virtual int16_t valueToPosition	(	int	value	)

Translate a value in the value range to the corresponding position in the indicator position range (x coordinate in horizontal mode and y in vertical mode).

Parameters:

value	The value.

Returns:

The coordinate that corresponds to the value.

Protected Attributes Documentation

background

Image background

The background image.

backgroundSelected

Image backgroundSelected

The backgroundSelected image.

backgroundSelectedViewPort

Container backgroundSelectedViewPort

The backgroundSelected view port. Controls the visible part of the backgroundSelected image.

currentValue

int16_t currentValue

The current value represented by the slider.

indicator

Image indicator

The indicator image.

indicatorMaxPosition

int16_t indicatorMaxPosition

The maximum position of the indicator (either x coordinate in horizontal mode or y coordinate in vertical mode)

indicatorMinPosition

int16_t indicatorMinPosition

The minimum position of the indicator (either x coordinate in horizontal mode or y coordinate in vertical mode)

newValueCallback

GenericCallback< const Slider &, int > * newValueCallback

The new value callback (called when the indicator is moved)

sliderOrientation

SliderOrientation sliderOrientation

The selected slider orientation.

startValueCallback

GenericCallback< const Slider &, int > * startValueCallback

The start value callback (called when an interaction with the indicator is initiated)

stopValueCallback

GenericCallback< const Slider &, int > * stopValueCallback

The stop value callback (called when an interaction with the indicator ends)

valueRangeMax

int16_t valueRangeMax

The value range max.

valueRangeMin

int16_t valueRangeMin

The value range min.