A generalized position indicator that can be used to render a simple scroll bar, progress bar, and other similar things. More...

#include <BppPositionIndicator.hpp>

Collaboration diagram for duds::ui::graphics::BppPositionIndicator:

[legend]

Public Member Functions
	BppPositionIndicator ()=default
	Makes a new indicator with its position, dimensions, and range left uninitialized. More...

	BppPositionIndicator (std::uint16_t minMarkerSize, bool backgroundState=false)
	Makes a new indicator with its position and dimensions left uninitialized. More...

	BppPositionIndicator (const ImageLocation &indicatorPos, const ImageDimensions &indicatorDim, std::uint16_t minMarkerSize=4, bool backgroundState=false)
	Makes a new position indicator. More...

bool	backgroundState () const
	Returns the pixel state used for the background of the indicator. More...

void	backgroundState (bool s)
	Changes the pixel state used for the background of the indicator. More...

const ImageDimensions &	dimensions () const
	Returns the dimensions (size) of the rendered indicator. More...

void	dimensions (const ImageDimensions &dim)
	Changes the dimensions of the rendered indicator. More...

bool	horizontal () const
	True when the indicator's marker will move horizontally. More...

bool	markerState () const
	Returns the pixel state used for the position marker of the indicator. More...

void	markerState (bool s)
	Changes the pixel state used for the position marker of the indicator. More...

std::uint16_t	maxPosition () const
	Returns the maximum position that will be represented by the indicator. More...

void	maxPosition (std::uint16_t p)
	Returns the maximum position that will be represented by the indicator. More...

std::uint16_t	minMarkerSize () const
	Returns the minimum size of the position marker in pixels. More...

void	minMarkerSize (std::uint16_t size)
	Changes the minimum size of the position marker in pixels. More...

const ImageLocation &	position () const
	Returns the upper left position where the indictor will be drawn. More...

void	position (const ImageLocation &pos)
	Changes the upper left position where the indictor will be drawn. More...

std::uint16_t	range () const
	Returns the range of positions that will be represented by the indicator. More...

void	range (std::uint16_t r)
	Changes the range of positions that will be represented by the indicator. More...

void	render (BppImage *dest, int start, int end=0)
	Renders the indicator with the marker showing the given position. More...

void	render (const BppImageSptr &dest, int start, int end=0)
	Renders the indicator with the marker showing the given position. More...

bool	vertical () const
	True when the indicator's marker will move vertically. More...

Private Member Functions
int	position (int pos, int len) const
	Computes the pixel position, along the length of the indicator, for the position mark. More...

Private Attributes
bool	bstate = false
	The pixel state used for the background, the area not covered by the indicator mark/slider thingy. More...

ImageDimensions	idim
	The size of the indicator. More...

ImageLocation	ipos
	The location to render the indicator. More...

std::uint16_t	minSize = 4
	The minimum length of the position marker. More...

std::uint16_t	rng
	The range of position values that may be used. More...

Detailed Description

A generalized position indicator that can be used to render a simple scroll bar, progress bar, and other similar things.

The indicator is drawn within given dimensions. If the dimensions are wider than they are tall, the position marker will move horizontally. Otherwise, it will move vertically. The whole area within the dimenions will be rendered. The marker will use set (true) pixels by default, and the rest of the area will use the opposite pixel state.

The position marker is drawn to represent a start and end position. These positions are placed within a range of 0 to range() - 1 so that they work well with common containers, like std::vector. The value for range() needs to be set by the program. The length of the marker will be scaled to represent the distance between the start and end positions, but will never be less than the set minimum length. The end position may be omitted to use the start position as a mid-point; in this case, the marker will always be its minimum length.

The marker will only be drawn in the first or last pixel along its axis if the position includes either the begining of the range or the end of the range, respectively. This is intended to be a hint to the user that the extreme end has been reached, and to make this hint visible even when large ranges are used and rounding errors are present.

Author: Jeff Jackowski

Definition at line 79 of file BppPositionIndicator.hpp.

Constructor & Destructor Documentation

◆ BppPositionIndicator() [1/3]

duds::ui::graphics::BppPositionIndicator::BppPositionIndicator ( )

default

Makes a new indicator with its position, dimensions, and range left uninitialized.

The minimum size is initialized to 4, and the background pixel state to clear (false).

Postcondition: Indicator position (position(const ImageLocation &)), dimensions (dimensions(const ImageDimensions &)), and range (range(std::uint16_t) or maxPosition(std::uint16_t)) must be set prior to rendering.

Note: The dimensions must be set prior to changing the minimum indicator size.

◆ BppPositionIndicator() [2/3]

duds::ui::graphics::BppPositionIndicator::BppPositionIndicator	(	std::uint16_t	minMarkerSize,
		bool	backgroundState = `false`
	)

inline

Makes a new indicator with its position and dimensions left uninitialized.

Postcondition: Indicator position (position(const ImageLocation &)) and dimensions (dimensions(const ImageDimensions &)) must be set prior to rendering.

Parameters

minMarkerSize	The minimum size, in pixels, of the position marker that will be drawn onto the indicator.
backgroundState	The pixel state for the background of the indicator. The marker state will be the opposite.

Definition at line 132 of file BppPositionIndicator.hpp.

◆ BppPositionIndicator() [3/3]

duds::ui::graphics::BppPositionIndicator::BppPositionIndicator	(	const ImageLocation &	indicatorPos,
		const ImageDimensions &	indicatorDim,
		std::uint16_t	minMarkerSize = `4`,
		bool	backgroundState = `false`
	)

Makes a new position indicator.

Parameters

indicatorPos	The position of where to render the indicator.
indicatorDim	The dimensions of the indicator.
minMarkerSize	The minimum size, in pixels, of the position marker that will be drawn onto the indicator.
backgroundState	The pixel state for the background of the indicator. The marker state will be the opposite.

Exceptions

BppPositionIndicatorDimensionTooSmall	The dimensions offer fewer than 3 pixels to move in either axis.
BppPositionIndicatorMarkerSizeError	The given minimum position marker size is zero, or is too large to fit within the given dimensions.

Definition at line 16 of file BppPositionIndicator.cpp.

Member Function Documentation

◆ backgroundState() [1/2]

bool duds::ui::graphics::BppPositionIndicator::backgroundState ( ) const

inline

Returns the pixel state used for the background of the indicator.

The position marker will use the opposite state.

Definition at line 202 of file BppPositionIndicator.hpp.

◆ backgroundState() [2/2]

void duds::ui::graphics::BppPositionIndicator::backgroundState ( bool s )

inline

Changes the pixel state used for the background of the indicator.

The position marker will use the opposite state.

Parameters

s	The new pixel state for the background.

Definition at line 210 of file BppPositionIndicator.hpp.

◆ dimensions() [1/2]

const ImageDimensions& duds::ui::graphics::BppPositionIndicator::dimensions ( ) const

inline

Returns the dimensions (size) of the rendered indicator.

Definition at line 171 of file BppPositionIndicator.hpp.

◆ dimensions() [2/2]

void duds::ui::graphics::BppPositionIndicator::dimensions ( const ImageDimensions & dim )

Changes the dimensions of the rendered indicator.

Parameters

dim	The new size to render the indicator. The position marker will be horizontally oriented if the dimensions are wider than they are tall, and vertical otherwise.

Exceptions

BppPositionIndicatorDimensionTooSmall The dimensions offer fewer than (2 + minMarkerSize()) pixels to move in either axis.

Definition at line 33 of file BppPositionIndicator.cpp.

◆ horizontal()

bool duds::ui::graphics::BppPositionIndicator::horizontal ( ) const

inline

True when the indicator's marker will move horizontally.

Definition at line 262 of file BppPositionIndicator.hpp.

Referenced by render().

◆ markerState() [1/2]

bool duds::ui::graphics::BppPositionIndicator::markerState ( ) const

inline

Returns the pixel state used for the position marker of the indicator.

The background will use the opposite state.

Definition at line 217 of file BppPositionIndicator.hpp.

◆ markerState() [2/2]

void duds::ui::graphics::BppPositionIndicator::markerState ( bool s )

inline

Changes the pixel state used for the position marker of the indicator.

The background will use the opposite state.

Parameters

s	The new pixel state for the marker.

Definition at line 225 of file BppPositionIndicator.hpp.

◆ maxPosition() [1/2]

std::uint16_t duds::ui::graphics::BppPositionIndicator::maxPosition ( ) const

inline

Returns the maximum position that will be represented by the indicator.

The ends of the range are zero and maxPosition().

Definition at line 248 of file BppPositionIndicator.hpp.

◆ maxPosition() [2/2]

void duds::ui::graphics::BppPositionIndicator::maxPosition ( std::uint16_t p )

inline

Returns the maximum position that will be represented by the indicator.

The ends of the range are zero and maxPosition().

Parameters

p	The new maximum position value.

Definition at line 256 of file BppPositionIndicator.hpp.

◆ minMarkerSize() [1/2]

std::uint16_t duds::ui::graphics::BppPositionIndicator::minMarkerSize ( ) const

inline

Returns the minimum size of the position marker in pixels.

Definition at line 187 of file BppPositionIndicator.hpp.

Referenced by BppPositionIndicator().

◆ minMarkerSize() [2/2]

void duds::ui::graphics::BppPositionIndicator::minMarkerSize ( std::uint16_t size )

Changes the minimum size of the position marker in pixels.

Parameters

size	The new size in pixels.

Exceptions

BppPositionIndicatorMarkerSizeError The given minimum position marker size is zero, or is too large to fit within the current dimensions.

Definition at line 46 of file BppPositionIndicator.cpp.

◆ position() [1/3]

int duds::ui::graphics::BppPositionIndicator::position	(	int	pos,
		int	len
	)		const

private

Computes the pixel position, along the length of the indicator, for the position mark.

Parameters

pos	The position from 0 to rng - 1.
len	The length of the indicator in pixels.

Definition at line 67 of file BppPositionIndicator.cpp.

◆ position() [2/3]

const ImageLocation& duds::ui::graphics::BppPositionIndicator::position ( ) const

inline

Returns the upper left position where the indictor will be drawn.

Definition at line 159 of file BppPositionIndicator.hpp.

Referenced by render().

◆ position() [3/3]

void duds::ui::graphics::BppPositionIndicator::position ( const ImageLocation & pos )

inline

Changes the upper left position where the indictor will be drawn.

Definition at line 165 of file BppPositionIndicator.hpp.

◆ range() [1/2]

std::uint16_t duds::ui::graphics::BppPositionIndicator::range ( ) const

inline

Returns the range of positions that will be represented by the indicator.

The ends of the range are zero and range() - 1.

Definition at line 232 of file BppPositionIndicator.hpp.

◆ range() [2/2]

void duds::ui::graphics::BppPositionIndicator::range ( std::uint16_t r )

Changes the range of positions that will be represented by the indicator.

The ends of the range are zero and range() - 1. This works well with sizes from standard C++ containers.

Parameters

r	The new range.

Exceptions

BppPositionIndicatorRangeTooSmall The given range is zero.

Definition at line 58 of file BppPositionIndicator.cpp.

◆ render() [1/2]

void duds::ui::graphics::BppPositionIndicator::render	(	BppImage *	dest,
		int	start,
		int	end = `0`
	)

Renders the indicator with the marker showing the given position.

The start position is used for the top or left of the marker, and the end position is for the bottom or right. If the end position is equal or less than the start position, then the start is used as a mid-point for the marker. The marker is always at least minMarkerSize() pixels long.

A common look for a progress bar is achived by using 0 for the start position, and the progress value for the end position.

Precondition: Either range(std::uint16_t) or maxPosition(std::uint16_t) has been called.

Parameters

dest	The destination image.
start	The start position. It should be between 0 and range() - 1. Values beyond the range will be clipped to the ends of the range.
end	The end position. It should be bewteen start and range() - 1 for a marker with its size scaled based on the positions. It should be 0 if the marker needs to be placed only based on the start position.

Definition at line 83 of file BppPositionIndicator.cpp.

◆ render() [2/2]

void duds::ui::graphics::BppPositionIndicator::render	(	const BppImageSptr &	dest,
		int	start,
		int	end = `0`
	)

inline

Renders the indicator with the marker showing the given position.

The start position is used for the top or left of the marker, and the end position is for the bottom or right. If the end position is equal or less than the start position, then the start is used as a mid-point for the marker. The marker is always at least minMarkerSize() pixels long.

A common look for a progress bar is achived by using 0 for the start position, and the progress value for the end position.

Precondition: Either range(std::uint16_t) or maxPosition(std::uint16_t) has been called.

Parameters

dest	The destination image.
start	The start position. It should be between 0 and range() - 1. Values beyond the range will be clipped to the ends of the range.
end	The end position. It should be bewteen start and range() - 1 for a marker with its size scaled based on the positions. It should be 0 if the marker needs to be placed only based on the start position.

Definition at line 316 of file BppPositionIndicator.hpp.

◆ vertical()

bool duds::ui::graphics::BppPositionIndicator::vertical ( ) const

inline

True when the indicator's marker will move vertically.

Definition at line 268 of file BppPositionIndicator.hpp.

Referenced by minMarkerSize(), and render().

Member Data Documentation

◆ bstate

bool duds::ui::graphics::BppPositionIndicator::bstate = false

private

The pixel state used for the background, the area not covered by the indicator mark/slider thingy.

Definition at line 100 of file BppPositionIndicator.hpp.

Referenced by render().

◆ idim

ImageDimensions duds::ui::graphics::BppPositionIndicator::idim

private

The size of the indicator.

Definition at line 87 of file BppPositionIndicator.hpp.

Referenced by dimensions(), minMarkerSize(), and render().

◆ ipos

ImageLocation duds::ui::graphics::BppPositionIndicator::ipos

private

The location to render the indicator.

Definition at line 83 of file BppPositionIndicator.hpp.

Referenced by render().

◆ minSize

std::uint16_t duds::ui::graphics::BppPositionIndicator::minSize = 4

private

The minimum length of the position marker.

Definition at line 95 of file BppPositionIndicator.hpp.

Referenced by dimensions(), minMarkerSize(), and render().

◆ rng

std::uint16_t duds::ui::graphics::BppPositionIndicator::rng

private

The range of position values that may be used.

Definition at line 91 of file BppPositionIndicator.hpp.

Referenced by position(), and range().

The documentation for this class was generated from the following files:

Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ BppPositionIndicator() [1/3]

◆ BppPositionIndicator() [2/3]

◆ BppPositionIndicator() [3/3]

Member Function Documentation

◆ backgroundState() [1/2]

◆ backgroundState() [2/2]

◆ dimensions() [1/2]

◆ dimensions() [2/2]

◆ horizontal()

◆ markerState() [1/2]

◆ markerState() [2/2]

◆ maxPosition() [1/2]

◆ maxPosition() [2/2]

◆ minMarkerSize() [1/2]

◆ minMarkerSize() [2/2]

◆ position() [1/3]

◆ position() [2/3]

◆ position() [3/3]

◆ range() [1/2]

◆ range() [2/2]

◆ render() [1/2]

◆ render() [2/2]

◆ vertical()

Member Data Documentation

◆ bstate

◆ idim

◆ ipos

◆ minSize

◆ rng