Helper class to supply a platform independent range implementation. More...

#include <GUIRange.h>

Inheritance diagram for CGUIRange:

Public Types
enum	Base_t { BASE_AT_MINIMUM , BASE_AT_MAXIMUM }
	Whether base is at minimum or maximum of the range.

Public Member Functions
	CGUIRange ()

	CGUIRange (const CGUIRange &kSource)

	CGUIRange (eC_Int iLevelPercentage, eC_UInt uiStepSizeLevelPercentage, eC_Int iMinValue, eC_Int iMaxValue, Base_t eBase=BASE_AT_MINIMUM, eC_Bool bExtremeLevelsAreAlwaysValid=false)

	CGUIRange (eC_Int iValue, eC_Int iMinValue, eC_Int iMaxValue, eC_UInt uiStepSize=1, Base_t eBase=BASE_AT_MINIMUM, eC_Bool bExtremeLevelsAreAlwaysValid=false)

	CGUIRange (eC_Value vLevel, eC_Int iMinValue, eC_Int iMaxValue, eC_Value vStepSizeLevel, Base_t eBase=BASE_AT_MINIMUM, eC_Bool bExtremeLevelsAreAlwaysValid=false)

void	ClipToBounds (eC_Int &iValue) const

eC_Bool	Decrease ()

const Base_t &	GetBase () const

eC_Value	GetLevel () const

eC_UInt	GetLevelPercentage () const

eC_Bool	GetMaximumLevelIsAlwaysValid () const

eC_Int	GetMaxValue () const

eC_Int	GetMinValue () const

eC_UInt	GetStepSize () const

eC_Int	GetValue () const

eC_Bool	Increase ()

CGUIRange &	operator= (const CGUIRange &kSource)

virtual void	ReadFromStream ()

void	RoundToNextStep (eC_Int &iRangeValue) const

void	SetBase (Base_t eBase)

void	SetLevel (eC_Value vPercent)

void	SetLevelPercentage (eC_UInt uiPercentage)

void	SetMaximumLevelIsAlwaysValid (eC_Bool bNotOnlyMultiplesOfStepSize)

void	SetMaxValue (eC_Int iMaxValue)

void	SetMinValue (eC_Int iMinValue)

void	SetRange (eC_Int iMinValue, eC_Int iMaxValue)

void	SetStepSize (eC_UInt uiIntValues)

void	SetStepSizeLevel (eC_Value vPercent)

void	SetStepSizeLevelPercentage (eC_UInt uiPercentage)

void	SetValue (eC_Int iNewValue)

virtual void	WriteToStream (const eC_Bool bWriteClassID=false)

Public Member Functions inherited from CGUIStreamableObject
const eC_String &	GetXMLTag () const

virtual void	ReadFromStream ()

void	SetXMLTag (const eC_String &kXMLTag)

virtual void	WriteToStream (const eC_Bool bWriteClassID=false)

Additional Inherited Members
Static Public Attributes inherited from CGUIStreamableObject
static const eC_Char	XMLTAG_CLASSVERSION []

Protected Member Functions inherited from CGUIStreamableObject
eC_UInt	ReadStreamingHeader (const eC_UInt &uiClassVersion, const eC_UInt &uiClassMinVersion=0) const

void	WriteStreamingFooter (const eC_Bool &bWriteClassID) const

void	WriteStreamingHeader (const eC_Bool &bWriteClassID, const eC_Char *const pkClassIDTag, const eC_Int &iClassID, const eC_UInt &uiClassVersion) const

Detailed Description

Helper class to supply a platform independent range implementation.

A range is an interval of integer values which is bound by a minimum and a maximum value. The current value inside the range may only be set to valid values. Invalid values will be rounded to valid values.

The base for the level calculations may be set so that the level either grows from the maximum to the minimum value or vice versa. When the current value is set via SetValue() the passed argument is interpreted as an absolute value and the corresponding level is calculated. Now when the base is changed this value will be adjusted in order to represent the same level as before.

All set functions adjust the passed arguments if they are invalid and update all dependent member variables.

The level and range value will always be rounded to the next valid step as determined by the base and step size automatically.

The recommended call sequence is this:

Example:

// Create a range.
CGUIRange *pRange = CGUIRange(0,0,100,1,CGUIRange::BASE_AT_MINIMUM,false);
 
// Sets the current value of the range to a new absolute value.
pRange->SetValue((eC_Int)90);
 
// Sets the percent value of the level in the range of 0.0 to 1.0.
pRange->SetLevel(0.8);
 
// Sets the percentage value of the level in the range of 0 to 100.
pRange->SetLevelPercentage(80);
 
// Sets the style base at maximum value.
pRange->SetBase(CGUIRange::BASE_AT_MAXIMUM);

Constructor & Destructor Documentation

◆ CGUIRange() [1/5]

CGUIRange::CGUIRange ( )

inline

Standard constructor. Initializes all variables to sensible values.

◆ CGUIRange() [2/5]

CGUIRange::CGUIRange	(	eC_Int	iValue,
		eC_Int	iMinValue,
		eC_Int	iMaxValue,
		eC_UInt	uiStepSize = `1`,
		Base_t	eBase = `BASE_AT_MINIMUM`,
		eC_Bool	bExtremeLevelsAreAlwaysValid = `false`
	)

inline

CGUIRange constructor.

Parameters

iValue	The current value of the range.
iMinValue	The minimum value of iValue.
iMaxValue	The maximum value of iValue.
uiStepSize	The step size in units of the range.
eBase	The base of the level and the step size.
bExtremeLevelsAreAlwaysValid	True, if the maximum is also a valid current value, no matter what the step size is. False, else.

◆ CGUIRange() [3/5]

CGUIRange::CGUIRange	(	eC_Int	iLevelPercentage,
		eC_UInt	uiStepSizeLevelPercentage,
		eC_Int	iMinValue,
		eC_Int	iMaxValue,
		Base_t	eBase = `BASE_AT_MINIMUM`,
		eC_Bool	bExtremeLevelsAreAlwaysValid = `false`
	)

inline

CGUIRange constructor.

Parameters

iLevelPercentage	The percentage level [0..100] to be converted to the current value.
uiStepSizeLevelPercentage	The step size given as a percentage level [0..100].
iMinValue	The minimum value of iValue.
iMaxValue	The maximum value of iValue.
eBase	The base of the level and the step size.
bExtremeLevelsAreAlwaysValid	True, if the maximum is also a valid current value, no matter what the step size is. False, else.

◆ CGUIRange() [4/5]

CGUIRange::CGUIRange	(	eC_Value	vLevel,
		eC_Int	iMinValue,
		eC_Int	iMaxValue,
		eC_Value	vStepSizeLevel,
		Base_t	eBase = `BASE_AT_MINIMUM`,
		eC_Bool	bExtremeLevelsAreAlwaysValid = `false`
	)

inline

CGUIRange constructor.

Parameters

vLevel	The percent level [0.0 .. 1.0] to be converted to the current value.
iMinValue	The minimum value of iValue.
iMaxValue	The maximum value of iValue.
vStepSizeLevel	The step size given as a percent value [0.0 .. 1.0].
eBase	The base of the level and the step size.
bExtremeLevelsAreAlwaysValid	True, if the maximum is also a valid current value, no matter what the step size is. False, else.

◆ CGUIRange() [5/5]

CGUIRange::CGUIRange ( const CGUIRange & kSource )

inline

Copy-constructor of the CGUIRange class.

Parameters

kSource Source object to be copied.

Member Function Documentation

◆ ClipToBounds()

void CGUIRange::ClipToBounds ( eC_Int & iValue ) const

inline

Clips passed value to set min and max values

Parameters

iValue the value to clip

◆ Decrease()

eC_Bool CGUIRange::Decrease ( )

See also: CGUIBehaviour::Decrease

Returns: True if within range, False otherwise

◆ GetBase()

const Base_t & CGUIRange::GetBase ( ) const

inline

Returns: Whether base is at minimum or maximum of the range

◆ GetLevel()

eC_Value CGUIRange::GetLevel ( ) const

inline

Returns the cached percent value of the level in the range of 0.0 to 1.0.

Returns: The percent value corresponding to m_iValue. The return value has been rounded to the machine accuracy of eC_Value therefore it may always be inaccurate. Conversion from decimal floating point numbers to binary floating point numbers may also introduce inaccuracies, e.g. 0.1 decimal cannot be saved as an exact binary IEEE 754 floating point number as it has an infinite number of digits to the right of the dot when saved as a binary floating point number.

◆ GetLevelPercentage()

eC_UInt CGUIRange::GetLevelPercentage ( ) const

inline

Returns the percentage value of the level in the range of 0 to 100.

Returns: The integer percentage value corresponding to m_iValue. The intermediate value of the calculation (m_vPercentValue) may be inacurate and the final result is rounded to an integer value therefore the return value may always be slightly inaccurate.

See also: GetLevel

◆ GetMaximumLevelIsAlwaysValid()

eC_Bool CGUIRange::GetMaximumLevelIsAlwaysValid ( ) const

inline

See also: m_bMaximumLevelIsAlwaysValid

Returns: True if maximum level is always valid

◆ GetMaxValue()

eC_Int CGUIRange::GetMaxValue ( ) const

inline

Returns: The maximum value

◆ GetMinValue()

eC_Int CGUIRange::GetMinValue ( ) const

inline

Returns: The minimum value

◆ GetStepSize()

eC_UInt CGUIRange::GetStepSize ( ) const

inline

Returns: Step size

See also: SetStepSize

◆ GetValue()

eC_Int CGUIRange::GetValue ( ) const

inline

Gets the current value of the range.

See also: SetValue

Returns: The value

◆ Increase()

eC_Bool CGUIRange::Increase ( )

See also: CGUIBehaviour::Increase

Returns: True if within range, False otherwise

◆ operator=()

CGUIRange & CGUIRange::operator= ( const CGUIRange & kSource )

inline

Operator= method of the CGUIRange class.

Parameters

kSource Source object to be copied.

Returns: Copied object.

◆ ReadFromStream()

virtual void CGUIRange::ReadFromStream ( )

virtual

Reads attributes from the streaming file. Only for use with GUIFactoryManager.

See also: CGUIObject::ReadFromStream()

Reimplemented from CGUIStreamableObject.

◆ RoundToNextStep()

void CGUIRange::RoundToNextStep ( eC_Int & iRangeValue ) const

Rounds the given value to the next valid value with regard to the current stepsize. Rounding will be done in direction to the base.

Parameters

iRangeValue Value to round

◆ SetBase()

void CGUIRange::SetBase ( Base_t eBase )

Determines if the base is at the lowest or highest value. SetBase() divides the range into steps top down or bottom up. In derived classes this setting might be used to determine if a control fills from left to right or bottom to top or vice versa. SetValue() always works with absolute values so that when passing the minimum value to it, it always sets the corresponding member variable to the valid minimum. GetValue() will return this absolute value which may correspond to 0% or 100% level. When changing the base from one border to the other, then m_iValue will be adjusted to the next valid step in direction to the new base point.

See also: SetStepSize

Parameters

eBase Whether base is at minimum or maximum of the range

◆ SetLevel()

void CGUIRange::SetLevel ( eC_Value vPercent )

Sets the percent value of the level in the range of 0.0 to 1.0.

Parameters

vPercent Percent value that determines m_iValue. Invalid values will be rounded to the next valid value as determined by the step size of the algorithm.

See also: SetValue

◆ SetLevelPercentage()

void CGUIRange::SetLevelPercentage ( eC_UInt uiPercentage )

Sets the percentage value of the level in the range of 0 to 100. This value will be saved as m_iValue and thus rounded to the corresponding integer value of the range.

See also: SetLevel

Parameters

uiPercentage The percentage

◆ SetMaximumLevelIsAlwaysValid()

void CGUIRange::SetMaximumLevelIsAlwaysValid ( eC_Bool bNotOnlyMultiplesOfStepSize )

inline

See also: m_bMaximumLevelIsAlwaysValid

Parameters

bNotOnlyMultiplesOfStepSize True for "always valid"

◆ SetMaxValue()

void CGUIRange::SetMaxValue ( eC_Int iMaxValue )

inline

SetMaxValue() sets the maximum value. This value corresponds to the controls internal level of 100%. If the new maximum is smaller than the set minimum, the maximum is set to minimum, thus maximum and minimum are equal. The current value will also be adjusted so that it is inside the bounds. This value should not be higher than half of eC_MAXVALUE or lower than half of -eC_MAXVALUE.

See also: SetValue

Parameters

iMaxValue The maximum value

◆ SetMinValue()

void CGUIRange::SetMinValue ( eC_Int iMinValue )

inline

SetMinValue() sets the minimum value. This value corresponds to the controls internal level of 0%. If the new minimum is bigger than the set maximum, the minimum is set to maximum, thus minimum and maximum are equal. The current value will also be adjusted so that it is inside the bounds. This value should not be higher than half of eC_MAXVALUE or lower than half of -eC_MAXVALUE.

See also: SetValue

Parameters

iMinValue The minimum value

◆ SetRange()

void CGUIRange::SetRange	(	eC_Int	iMinValue,
		eC_Int	iMaxValue
	)

Sets the minimum and maximum allowed values of this range. The current value will also be adjusted so that it is inside the bounds.

Parameters

iMinValue	New minimum allowed value in the range
iMaxValue	New maximum allowed value in the range

Remarks: If iMinValue is greater than iMaxValue, the values are swapped so that the range is valid.

◆ SetStepSize()

void CGUIRange::SetStepSize ( eC_UInt uiIntValues )

The level m_iValue may be Increase()d and Decrease()d in steps as set by the following function. The step size must be at least one and at most as big as the range, if not it will be clipped to these bounds.

Parameters

uiIntValues The distance between the valid values of the range. These absolute values are also called steps.

See also: SetBase, SetValue, SetLevel

◆ SetStepSizeLevel()

void CGUIRange::SetStepSizeLevel ( eC_Value vPercent )

The step size vPercent will be converted to the best match of the step size for range values so that the level may be Increase()d and Decrease()d in these steps.

Parameters

vPercent The step size in the interval [0.0 ... 1.0] by that the percentage level value is altered approximately. This value is interpreted as a percentage value, that is, the internal level.

See also: SetStepSize

◆ SetStepSizeLevelPercentage()

void CGUIRange::SetStepSizeLevelPercentage ( eC_UInt uiPercentage )

The step size uiPercentage will be converted to the next match of the step size for range values so that the level may be Increase()d and Decrease()d in these steps.

Note: The minimum and maximum range values should be set before calling this function.

Parameters

uiPercentage The step size in the interval [0..100] by that the percentage level value is altered approximately. This value is interpreted as a percentage value, that is, the internal level.

See also: SetStepSize

◆ SetValue()

void CGUIRange::SetValue ( eC_Int iNewValue )

Sets the current value of the range to a new absolute value. The value will be rounded according to the step size and base in use and will be clipped to the bounds as set by SetMinValue and SetMaxValue. This value should not be higher than half of eC_MAXVALUE or lower than half of -eC_MAXVALUE.

See also: SetStepSize, SetBase, SetMaximumLevelIsAlwaysValid,; SetMinValue, SetMaxValue

Parameters

iNewValue The new value

◆ WriteToStream()

virtual void CGUIRange::WriteToStream ( const eC_Bool bWriteClassID = false )

virtual

Writes attributes to the streaming file. A CGUIStreamWriter has to be initialized.

Parameters

bWriteClassID This flag is used to switch writing of the class ID, leading and trailing tags. When implementing a new streamable object, check this flag. If it is true, first write the class ID, then continue with this object's attributes, and finally call the base class implementation with this flag set to false (this is the default).

Reimplemented from CGUIStreamableObject.

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

GUIRange.h

Public Types

Public Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ CGUIRange() [1/5]

◆ CGUIRange() [2/5]

◆ CGUIRange() [3/5]

◆ CGUIRange() [4/5]

◆ CGUIRange() [5/5]

Member Function Documentation

◆ ClipToBounds()

◆ Decrease()

◆ GetBase()

◆ GetLevel()

◆ GetLevelPercentage()

◆ GetMaximumLevelIsAlwaysValid()

◆ GetMaxValue()

◆ GetMinValue()

◆ GetStepSize()

◆ GetValue()

◆ Increase()

◆ operator=()

◆ ReadFromStream()

◆ RoundToNextStep()

◆ SetBase()

◆ SetLevel()

◆ SetLevelPercentage()

◆ SetMaximumLevelIsAlwaysValid()

◆ SetMaxValue()

◆ SetMinValue()

◆ SetRange()

◆ SetStepSize()

◆ SetStepSizeLevel()

◆ SetStepSizeLevelPercentage()

◆ SetValue()

◆ WriteToStream()