This composite object arranges and animates its contained children in a "carousel" fashion. More...

#include <GUICarousel.h>

Inheritance diagram for CGUICarousel:

[legend]

Classes
struct	sSizeStorage
	Helper structure to store original sizes (before any zooming) of child objects. More...

struct	ZOrderEntry
	Helper structure to store carousel items and their corresponding scaling factors for zordering. More...

Public Member Functions
	CGUICarousel (CGUICompositeObject *const pkParent, const eC_Value &vX, const eC_Value &vY, const eC_Value &vWidth, const eC_Value &vHeight, const ObjectHandle_t &eID=NO_HANDLE)

virtual eC_Bool	AddObject (CGUIObject *pkObject)

eC_Bool	Decrease ()

virtual void	DoAnimate (const eC_Value &vTimes=eC_FromInt(1))

virtual eC_Bool	DoDrag (const eC_Value &vDeltaX, const eC_Value &vDeltaY, const eC_Value &vAbsX, const eC_Value &vAbsY)

virtual eC_Bool	DoDragEnd (const eC_Value &vAbsX, const eC_Value &vAbsY)

virtual eC_Bool	DoKeyDown (const GUIKeyIdentifier_t &eKeyID, const eC_UInt &uiModifiers)

void	EnableFlowMode (const eC_Bool bEnable)

void	GetOriginalSize (const eC_UInt uiIndex, eC_Value &vWidth, eC_Value &vHeight)

eC_Value	GetRadius () const

eC_Int	GetSelectedIndex () const

CGUIObject *	GetSelectedObject ()

eC_Value	GetTiltAngle () const

eC_Bool	Increase ()

virtual eC_Bool	IsHighlightable () const

void	JumpToObject (CGUIObject *pkObject)

virtual void	ReadFromStream ()

virtual void	RemoveObject (CGUIObject *pkObject)

void	RotateToObject (CGUIObject *pkObject)

virtual void	SetHeight (const eC_Value &vX)

void	SetNumberOfFlowModeEntries (const eC_UInt uiNOFEntries)

void	SetPerspectiveFactor (const eC_Value vPerspectiveFactor)

void	SetRadius (const eC_Value vRadius)

void	SetTiltAngle (const eC_Value vTiltAngle)

virtual eC_Bool	SetValue (const CGUIValue &rkValue)

void	SetVertical (const eC_Bool bVertical)

virtual void	SetWidth (const eC_Value &vX)

virtual void	WriteToStream (const eC_Bool bWriteClassID=false)

Public Member Functions inherited from CGUICompositeObject
	CGUICompositeObject ()

	CGUICompositeObject (CGUICompositeObject *const pkParent, const CGUIRect &kRect, const ObjectHandle_t &eID=NO_HANDLE)

	CGUICompositeObject (CGUICompositeObject *const pkParent, const eC_Value &vX, const eC_Value &vY, const eC_Value &vWidth, const eC_Value &vHeight, const ObjectHandle_t &eID=NO_HANDLE)

	CGUICompositeObject (const CGUICompositeObject &kSource)

virtual	~CGUICompositeObject ()
	This destructor is automatically virtual, as the base class destructor is virtual.

virtual eC_Bool	AddObject (CGUIObject *pkObject)

eC_Bool	BringToFront (CGUIObject *pkObject)

eC_Bool	CanBeCyclicFocussed () const

virtual eC_Bool	DoPostDraw ()

void	DrawOnTop (CGUIObject *pkObject)

void	DrawOnTopOf (CGUIObject const pkObject, CGUIObject const pDrawOnTopOf)

virtual CGUIObject *	FindObject (const eC_Value &vAbsX, const eC_Value &vAbsY)

void	Flip (const eC_Bool &rbVertical)

eC_Bool	FocusAny ()

virtual eC_Bool	FocusNext (CGUIObject *const pRefObj=NULL, const eC_Bool &bSubTreeOfRefObjDone=false)

virtual eC_Bool	FocusPrevious (CGUIObject *const pRefObj=NULL, const eC_Bool &bSubTreeOfRefObjDone=false)

CGUIObject *	GetAndCheckObjectByID (ObjectHandle_t eObjID, const eC_String &kObjectName)

const CGUIObject *	GetAndCheckObjectByID (ObjectHandle_t eObjID, const eC_String &kObjectName) const

CGUIObject *	GetChild (const eC_UInt uIndex)

CGUIObject *	GetChild (const eC_UInt uIndex) const

const ObjectPtrList &	GetChildObjectsList () const

const ObjectPtrList &	GetDrawOrderList () const

eC_Int	GetIndexOfChild (const CGUIObject *pkObject) const

eC_UInt	GetNumberOfChildren () const

CGUIObject *	GetObjectByID (const ObjectHandle_t &eID, const eC_Bool &bOnlyVisible=false)

const CGUIObject *	GetObjectByID (const ObjectHandle_t &eID, const eC_Bool &bOnlyVisible=false) const

eC_Bool	InsertChildAt (const eC_UInt cuiIndex, CGUIObject *pkChild)

void	InvalidateChildren ()
	Invalidates all chidren, but not this parent.

eC_Bool	IsAncestorOf (const CGUIObject *pkObject) const

virtual eC_Bool	IsCompositeObject () const

eC_Bool	LowerOneLevel (CGUIObject *pkObject)

CGUICompositeObject &	operator= (const CGUICompositeObject &kSource)

eC_Bool	RaiseOneLevel (CGUIObject *pkObject)

virtual void	ReadFromStream ()

virtual void	RefreshLayout (CGUILayouter::eMovedEdges_t eMovedEdges) const

void	RemoveAllChildren ()

virtual void	RemoveObject (CGUIObject *pkObject)

void	Rotate (const eC_UInt &ruiDegrees, const eC_Bool &rbFirst=false)

eC_Bool	SendToBack (CGUIObject *pkObject)

virtual void	SetClickThrough (const eC_Bool &bClickThrough)

virtual void	SetClickThrough (const eC_Bool &bClickThrough, const eC_Bool &bChildrenClickThrough)

void	SetCyclicFocus (const eC_Bool &bCyclicFocus)

virtual void	SetDisabled (const eC_Bool &bDisabled)

virtual void	SetDisabled (const eC_Bool &bDisabled, const eC_Bool &bChildrenDisabled)

virtual void	SetFocussable (const eC_Bool &bFocussable)

virtual void	SetFocussable (const eC_Bool &bFocussable, const eC_Bool &bChildrenFocussable)

virtual void	SetGrayedOut (const eC_Bool &bGrayedOut)

virtual void	SetGrayedOut (const eC_Bool &bGrayedOut, const eC_Bool &bChildrenGrayedOut)

virtual void	SetHeight (const eC_Value &vY)

virtual void	SetInvisible (const eC_Bool &bInvisible)

virtual void	SetInvisible (const eC_Bool &bInvisible, const eC_Bool &bChildrenInvisible)

virtual void	SetWidth (const eC_Value &vX)

virtual void	WriteToStream (const eC_Bool bWriteClassID=false)

Public Member Functions inherited from CGUIObject
	CGUIObject ()

	CGUIObject (CGUICompositeObject *const pkParent, const CGUIRect &kRect, const ObjectHandle_t &eID=NO_HANDLE)

	CGUIObject (CGUICompositeObject *const pkParent, const eC_Value &vX, const eC_Value &vY, const eC_Value &vWidth, const eC_Value &vHeight, const ObjectHandle_t &eID=NO_HANDLE)

	CGUIObject (const CGUIObject &kSource)

virtual	~CGUIObject ()

void	AddValueObserver (CGUIObserver *pkObserver)

eC_Bool	CalculateInvalidatedRect (CGUIRect &rRect) const

virtual eC_Bool	ClaimFocus ()

virtual void	CreateSnapshot (eC_UInt uiBackColor=0x00)

eC_Bool	DataPoolConnectorExists () const

void	DeleteSnapshot ()

virtual void	DisableSnapshotDrawing (eC_Bool bDeleteSnapshot=true)

virtual eC_Bool	DoDraw ()

virtual eC_Bool	DoDrawSnapshot ()

virtual void	EnableSnapshotDrawing ()

virtual CGUIObject *	FindObject (const eC_Value &vAbsX, const eC_Value &vAbsY)

virtual eC_Bool	FocusAny ()

virtual eC_Bool	FocusNext (CGUIObject *const pRefObj=NULL, const eC_Bool &bSubTreeOfRefObjDone=false)

virtual eC_Bool	FocusPrevious (CGUIObject *const pRefObj=NULL, const eC_Bool &bSubTreeOfRefObjDone=false)

CGUIRect	GetAbsRect () const

eC_Value	GetAbsXPos () const

eC_Value	GetAbsXPosCenter () const

eC_Value	GetAbsXPosREdge () const

eC_Value	GetAbsYPos () const

eC_Value	GetAbsYPosBEdge () const

eC_Value	GetAbsYPosCenter () const

eC_UByte	GetAlpha () const

CGUIBehaviourDecorator *	GetBehaviour ()

const CGUIBehaviourDecorator *	GetBehaviour () const

GUIBitmapPlaneID_t	GetBitmapID () const

CGUIBitmapPlane &	GetBitmapPlane () const

CGUIRect	GetCurrentAbsRect () const

eC_Value	GetCurrentAbsXPos () const

eC_Value	GetCurrentAbsXPosCenter () const

eC_Value	GetCurrentAbsXPosREdge () const

eC_Value	GetCurrentAbsYPos () const

eC_Value	GetCurrentAbsYPosBEdge () const

eC_Value	GetCurrentAbsYPosCenter () const

CDataPoolConnector &	GetDataPoolConnector ()

eC_Value	GetDistanceBottom () const

eC_Value	GetDistanceRight () const

eC_Value	GetHalfHeight () const

eC_Value	GetHalfWidth () const

eC_Value	GetHeight () const

ObjectHandle_t	GetID () const

CGUILayouter *	GetLayouter ()

const CGUILayouter *	GetLayouter () const

ObjectHandle_t	GetNeighborBottomID () const

ObjectHandle_t	GetNeighborLeftID () const

ObjectHandle_t	GetNeighborRightID () const

ObjectHandle_t	GetNeighborTopID () const

CGUIObject *	GetObjectByID (const ObjectHandle_t &eID, const eC_Bool &bOnlyVisible=false)

const CGUIObject *	GetObjectByID (const ObjectHandle_t &eID, const eC_Bool &bOnlyVisible=false) const

CGUIRect	GetOriginRect () const

CGUICompositeObject *	GetParent ()

const CGUICompositeObject *	GetParent () const

CGUIRect	GetRelRect () const

eC_Value	GetRelXPos () const

eC_Value	GetRelXPosCenter () const

eC_Value	GetRelXPosREdge () const

eC_Value	GetRelYPos () const

eC_Value	GetRelYPosBEdge () const

eC_Value	GetRelYPosCenter () const

UUID_t	GetUUID () const

eC_Value	GetWidth () const

void	InvalidateArea ()

eC_Bool	IsClickable () const

eC_Bool	IsClickThrough () const

virtual eC_Bool	IsCompositeObject () const

eC_Bool	IsDescendantOf (const CGUIObject *const pAncestor) const

eC_Bool	IsDisabled () const

eC_Bool	IsDragable () const

eC_Bool	IsDragged () const

eC_Bool	IsDrawingSnapshot () const

eC_Bool	IsFocussable () const

eC_Bool	IsFocussed () const

eC_Bool	IsGrayedOut () const

virtual eC_Bool	IsHighlightable () const

eC_Bool	IsHighlighted () const

eC_Bool	IsInvisible () const

eC_Bool	IsPressed () const

eC_Bool	IsStopFocus () const

void	NotifyValueObservers (const CGUIValue &kValue, const eC_UInt uiX=0, const eC_UInt uiY=0)

CGUIObject &	operator= (const CGUIObject &kSource)

virtual void	ReadFromStream ()

virtual void	RefreshLayout (CGUILayouter::eMovedEdges_t eMovedEdges) const

void	RemoveValueObserver (CGUIObserver *pkObserver)

void	RenderToBitmap (eC_UInt uiBitmapID, eC_Value vXOffset=eC_FromInt(0), eC_Value vYOffset=eC_FromInt(0))

eC_Bool	RequestFocus ()

void	SetAlpha (eC_UByte ubAlpha)

void	SetBehaviour (CGUIBehaviourDecorator *pkBehaviour)

void	SetClickThrough (const eC_Bool &bClickThrough)

virtual void	SetDisabled (const eC_Bool &bDisabled)

virtual void	SetFocussable (const eC_Bool &bFocussable)

virtual void	SetGrayedOut (const eC_Bool &bGrayOut)

virtual void	SetHeight (const eC_Value &vY)

void	SetID (const ObjectHandle_t &eID)

virtual void	SetInvisible (const eC_Bool &bInvisible)

void	SetLayouter (CGUILayouter *pLayouter)

void	SetNeighborBottomID (const ObjectHandle_t eNewNeighborBottomID)

void	SetNeighborIDs (const ObjectHandle_t eNewNeighborLeftID, const ObjectHandle_t eNewNeighborRightID, const ObjectHandle_t eNewNeighborTopID, const ObjectHandle_t eNewNeighborBottomID)

void	SetNeighborLeftID (const ObjectHandle_t eNewNeighborLeftID)

void	SetNeighborRightID (const ObjectHandle_t eNewNeighborRightID)

void	SetNeighborTopID (const ObjectHandle_t eNewNeighborTopID)

virtual void	SetParent (CGUICompositeObject *const pkParent)

void	SetRelRect (const CGUIRect &kNewRect)

virtual void	SetRelXPos (const eC_Value &vX)

void	SetRelXPosCenter (const eC_Value &vXCenter)

void	SetRelXPosREdge (const eC_Value &vX)

virtual void	SetRelYPos (const eC_Value &vY)

void	SetRelYPosBEdge (const eC_Value &vY)

void	SetRelYPosCenter (const eC_Value &vYCenter)

void	SetStopFocus (const eC_Bool &bDontFocusToParent)

void	SetUUID (const UUID_t &kUUID)

virtual eC_Bool	SetValue (CDataPoolEntry &rkValue)

virtual eC_Bool	SetValue (const CGUIValue &rkValue)

virtual void	SetWidth (const eC_Value &vX)

virtual void	WriteToStream (const eC_Bool bWriteClassID=false)

Public Member Functions inherited from CGUIBehaviour
virtual eC_Bool	DoScale (const eC_Value &vDelta)

virtual eC_Bool	DoUserEvent (CGUIEvent *const pEvent)

virtual void	OnCreate ()

virtual void	OnDataPool (const DataPoolResource_t &eID)

virtual void	OnDelete ()

virtual void	OnHide ()

virtual void	OnShow ()

virtual eC_Bool	DoClick (const eC_Value &vAbsX=eC_FromInt(-1), const eC_Value &vAbsY=eC_FromInt(-1))

virtual eC_Bool	DoLongClick (const eC_Value &vAbsX=eC_FromInt(-1), const eC_Value &vAbsY=eC_FromInt(-1))

virtual eC_Bool	DoDoubleClick (const eC_Value &vAbsX=eC_FromInt(-1), const eC_Value &vAbsY=eC_FromInt(-1))

virtual eC_Bool	DoButtonDown (const eC_Value &vAbsX=eC_FromInt(-1), const eC_Value &vAbsY=eC_FromInt(-1))

virtual eC_Bool	DoButtonUp (const eC_Value &vAbsX=eC_FromInt(-1), const eC_Value &vAbsY=eC_FromInt(-1))

virtual eC_Bool	DoMouseEnter (const eC_Value &vAbsX=eC_FromInt(-1), const eC_Value &vAbsY=eC_FromInt(-1))

virtual eC_Bool	DoMouseLeave (const eC_Value &vAbsX=eC_FromInt(-1), const eC_Value &vAbsY=eC_FromInt(-1))

virtual eC_Bool	DoMouseMove (const eC_Value &vAbsX=eC_FromInt(-1), const eC_Value &vAbsY=eC_FromInt(-1))

virtual void	GetFocus ()

virtual void	LoseFocus ()

virtual eC_Bool	DoKeyUp (const GUIKeyIdentifier_t &eKeyIdentifier, const eC_UInt &uiModifiers)

virtual eC_Bool	DoChar (const eC_UInt &uiKey, const GUIKeyIdentifier_t &eKeyIdentifier, const eC_UInt &uiModifiers)

virtual eC_Bool	DoScroll (const eC_Value &vAbsX, const eC_Value &vAbsY, const eC_Value &vDelta, const eC_Bool &bModifierActive)

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)

Public Member Functions inherited from CGUIAnimatable
virtual	~CGUIAnimatable ()
	Destructor. Removes all existing animation callbacks.

virtual void	DoAnimate (const eC_Value &vTimes=eC_FromInt(1))

virtual eC_Bool	IsAnimating () const

virtual void	StartAnimation ()

virtual void	StopAnimation ()

Static Public Member Functions
static void	SetInvertInput (const eC_Bool bInvert)

Static Public Member Functions inherited from CGUIStreamableObject
static UUID_t	GenerateUUID ()

Protected Member Functions
virtual void	ArrangeChildren ()
	Arranges the child objects in an elliptic shape.

void	EnforceFocusBehaviour ()
	Ensures that only the selected child object is focusable.

eC_Value	GetDegreesPerChild ()

void	SetSelectedObject (CGUIObject *pkObject)

Protected Member Functions inherited from CGUICompositeObject
virtual eC_Bool	FourWayNext (FourWayFocus_t eFocusDirection)

ObjectPtrList &	GetChildObjectsList ()

virtual void	HandleDraw (const CGUIRect &ClipRect)

Protected Member Functions inherited from CGUIObject
virtual eC_Bool	CreateBitmapPlane ()

virtual eC_Bool	FourWayNext (FourWayFocus_t eFocusDirection)

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

Protected Attributes
eC_Bool	m_bDragging
	Internal flag indicating whether the carousel is currently being dragged.

eC_Bool	m_bFlowMode

eC_Bool	m_bKineticAnimation
	Indicates if the current animation is "kinetic" as the result of a preceeding drag event.

eC_Bool	m_bRotateByCursorKeys

eC_Bool	m_bVertical
	Indicates if the carousel is arranged horizontally or vertically.

eC_Int	m_iCarouselItemIndex
	Index of currently focused child object within child list.

eC_TListDoubleLinked< sSizeStorage >	m_OriginalSizes
	List of original object sizes (one entry per child object)

eC_UInt	m_uiNOFEntries

eC_Value	m_vDragSpeed
	Speed of the last drag event. Relevant for setting the speed of a subsequent kinetic animation.

eC_Value	m_vPerspectiveFactor

eC_Value	m_vRadius
	Pixel radius of carousel.

eC_Value	m_vRotationAngle
	Current rotation angle (in degrees) of carousel.

eC_Value	m_vTargetAngle
	Desired target angle (in degrees). This varies from the current rotation angle during rotation.

eC_Value	m_vTiltAngle
	Value by which the carousel is tilted around the X-Axis (internally stored in range 0-1)

Protected Attributes inherited from CGUIObject
UUID_t	m_kUUID
	UUID of object.

Static Protected Attributes
static eC_Bool	ms_bInvertInput
	Inverts the direction of keyboard input for ALL carousels.

Additional Inherited Members
Public Types inherited from CGUIObject
enum	FourWayFocus_t { FOCUS_LEFT , FOCUS_RIGHT , FOCUS_UP , FOCUS_DOWN }

Static Public Attributes inherited from CGUICompositeObject
static const eC_Char	XMLTAG_CHILDREN []
	XML comment tag to be used before writing children to a stream.

static const eC_Char	XMLTAG_ENDCHILDREN []
	XML comment tag to be used after writing children to a stream.

Static Public Attributes inherited from CGUIObject
static const eC_Char	XMLTAG_ALPHA []
	XML tag to be used writing alpha-value into a stream.

static const eC_Char	XMLTAG_CLICKTHROUGH []
	XML tag to be used writing clickthrough-state into a stream.

static const eC_Char	XMLTAG_CONTROLCLASSID []
	XML tag to be used when writing a control class ID into a stream.

static const eC_Char	XMLTAG_DISABLED []
	XML tag to be used writing disabled-state into a stream.

static const eC_Char	XMLTAG_FOCUSSABLE []
	XML tag to be used writing focussable-state into a stream.

static const eC_Char	XMLTAG_GRAYEDOUT []
	XML tag to be used writing grayedout-state into a stream.

static const eC_Char	XMLTAG_HEIGHT []
	XML tag to be used writing height into a stream.

static const eC_Char	XMLTAG_INVISIBLE []
	XML tag to be used writing invisible-state into a stream.

static const eC_Char	XMLTAG_OBJECTID []
	XML tag to be used writing object id into a stream.

static const eC_Char	XMLTAG_OVERRIDDENNEIGHBORS []
	XML tag to be used writing overridden neighbors into a stream.

static const eC_Char	XMLTAG_UUID []
	XML tag to be used when writing a UUID into a stream.

static const eC_Char	XMLTAG_WIDTH []
	XML tag to be used writing width into a stream.

static const eC_Char	XMLTAG_XPOS []
	XML tag to be used writing x-position into a stream.

static const eC_Char	XMLTAG_YPOS []
	XML tag to be used writing y-position into a stream.

Static Public Attributes inherited from CGUIBehaviour
static const eC_Char	XMLTAG_BEHAVIOURCLASSID []
	XML tag to be used when writing a behaviour class ID into a stream.

static const eC_Char	XMLTAG_BEHAVIOURCOUNT []
	XML tag for count.

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

Detailed Description

This composite object arranges and animates its contained children in a "carousel" fashion.

The "carousel" control is a container which automatically arranges all its children in an elliptic (Pseudo 3D) manner. It supports animation effects like speed-up or slow-down during changing the focus between its children. The carousel is very common to present e.g., Coverflows (Class: CGUICarousel).

The CGUICarousel class is a container which automatically arranges all its children in an elliptic (Pseudo 3D) manner. This is a useful control for allowing users to choose between several entries in a menu, or to browse through huge number of entries (e.g. cover-art browsing) when deploying the carousel in "flow-mode". (see below for further details)

The Following code creates a simple carousel and fills it with buttons

// Create the carousel
CGUICarousel* pCarousel = new CGUICarousel(pkParent, 0,0, GetWidth(), GetHeight());
 
// Create some child objects. Note that their positions will be overwritten anyway.
new CGUIBaseButton(pCarousel, eC_FromInt(0), eC_FromInt(0), eC_FromInt(100), eC_FromInt(100), "1", NULL);
new CGUIBaseButton(pCarousel, eC_FromInt(0), eC_FromInt(0), eC_FromInt(100), eC_FromInt(100), "2", NULL);
new CGUIBaseButton(pCarousel, eC_FromInt(0), eC_FromInt(0), eC_FromInt(100), eC_FromInt(100), "3", NULL);
new CGUIBaseButton(pCarousel, eC_FromInt(0), eC_FromInt(0), eC_FromInt(100), eC_FromInt(100), "4", NULL);
new CGUIBaseButton(pCarousel, eC_FromInt(0), eC_FromInt(0), eC_FromInt(100), eC_FromInt(100), "5", NULL);
 
// Set a radius, so that the buttons do not appear too crowded
pCarousel->SetRadius(eC_FromInt(100));

Using the carousel in flow-mode

When working with huge numbers of children in a carousel, you will notice that the carousel tends to appear very crowded. This is where the "flow mode" comes in handy. When used in "flow mode", the carousel can contain very large numbers of entries of which only a few are visible at any time. You can specify the number of virtual entries in the carousel, which will affect the spacing between the visual children, and therefore also number of simultaneously visible ones. If for instance you are having a total of 1000 entries in your carousel, and set the number of virtual entries to 10, the carousel will arrange its content as if it had only 10 children, by spreading out these 10 along the carousel's 360 degrees. But in fact you will only see the currently selected (=frontmost) child object, plus the two children to its left and the two children to it's right side.

The Following code creates a carousel in flow mode

// Create the carousel
CGUICarousel* pCarousel = new CGUICarousel(pkPage2, 0, 0, eC_FromInt(500), eC_FromInt(200));
 
// Add a lot of content
CGUIObject* pCarouselEntry = NULL;
for (int i=0; i < 100; i++)
{
    pCarouselEntry = new CGUIImage(pCarousel, eC_FromInt(0), eC_FromInt(0), eC_FromInt(100), eC_FromInt(50), SOME_IMAGE_ID, true);
    // The entries shall receive click events, and forward drag events to the carousel
    pCarouselEntry->SetDisabled(false);
}
 
// Set a sensible radius
pCarousel->SetRadius(eC_FromInt(200));
// Tilt the carousel
pCarousel->SetTiltAngle(eC_FromInt(75));
// Arrange the children as if the carousel had only 10 entries
pCarousel->SetNumberOfFlowModeEntries(10);
// Switch to flow mode
pCarousel->EnableFlowMode(true);

Technical details regarding the CGUICarousel

To achieve the carousel effect, the size and position of added child object's will be overwritten (for zooming and rotating). The user may then cycle through the child objects, which causes the carousel to rotate around its vertical axis. One object - namely the one in the front - is always the currently selected one. All objects except for the selected one will be set to non-focusable to enhance focusing behaviour. This ensures that at any time, only the selected object will receive the focus.

Constructor & Destructor Documentation

◆ CGUICarousel()

CGUICarousel::CGUICarousel	(	CGUICompositeObject *const	pkParent,
		const eC_Value &	vX,
		const eC_Value &	vY,
		const eC_Value &	vWidth,
		const eC_Value &	vHeight,
		const ObjectHandle_t &	eID = `NO_HANDLE`
	)

Constructor

Parameters

pkParent	Pointer to the designated parent object
vX	X-position relative to its parent object
vY	Y-position relative to its parent object
vWidth	Width of the slider
vHeight	Height of the slider
eID	Object identifier

Member Function Documentation

◆ AddObject()

virtual eC_Bool CGUICarousel::AddObject ( CGUIObject * pkObject )

virtual

Add a new Object to the list of child objects. This will automatically set the child's parent-pointer to this object.

Parameters

pkObject The object to be added

Returns: False if the object is already a child of this control or pkObject is NULL, otherwise true.

Reimplemented from CGUICompositeObject.

◆ Decrease()

eC_Bool CGUICarousel::Decrease ( )

virtual

Rotate carousel entries counter-clockwise

Returns: true

Reimplemented from CGUIBehaviour.

◆ DoAnimate()

virtual void CGUICarousel::DoAnimate ( const eC_Value & vTimes = eC_FromInt(1) )

virtual

Called when the timer of an animation callback belonging to this animatable has expired.

Parameters

vTimes The factor of the registered callback time in relation to the actually elapsed time. For example, the elapsed time is 80ms, and the standard time is 50ms, then vTimes is 1.6. If the given time in GETTIMER.AddAnimationCallback is 0, It will be set to -1.

Reimplemented from CGUIAnimatable.

◆ DoDrag()

virtual eC_Bool CGUICarousel::DoDrag	(	const eC_Value &	vDeltaX,
		const eC_Value &	vDeltaY,
		const eC_Value &	vAbsX,
		const eC_Value &	vAbsY
	)

virtual

Called when the object receives a Drag event. Drags are typically created if the mouse is being used while a mouse-button is being pressed, or if the user moves his finger over a touchscreen.

Parameters

vDeltaX	relative movement in x-direction since the last call of DoDrag/ButtonDown
vDeltaY	relative movement in y-direction since the last call of DoDrag/ButtonDown
vAbsX	current X-position in screen coordinates of the mouse
vAbsY	current Y-position in screen coordinates of the mouse

Returns: True If the event has been handled.
false Else.

Reimplemented from CGUIBehaviour.

◆ DoDragEnd()

virtual eC_Bool CGUICarousel::DoDragEnd	(	const eC_Value &	vAbsX,
		const eC_Value &	vAbsY
	)

virtual

Called on the dragged object (=the object on which the initial ButtonDown-event occurred) when the mouse button is released after a drag event.

Parameters

vAbsX	current X-position in screen coordinates of the mouse
vAbsY	current Y-position in screen coordinates of the mouse

Returns: True If the event has been handled.
false Else.

Reimplemented from CGUIBehaviour.

◆ DoKeyDown()

virtual eC_Bool CGUICarousel::DoKeyDown	(	const GUIKeyIdentifier_t &	eKeyID,
		const eC_UInt &	uiModifiers
	)

virtual

Used to operate carousel via 4-way-navigation keys, if desired.

Parameters

eKeyID	The Guiliani key identifier.
uiModifiers	The key modifiers bitfield.

Returns: True If the event has been handled.
false Else.

Reimplemented from CGUIBehaviour.

◆ EnableFlowMode()

void CGUICarousel::EnableFlowMode ( const eC_Bool bEnable )

inline

Enables / Disables flow mode for this carousel.

Parameters

bEnable TRUE if flow mode shall be enabled, FALSE to disable it

◆ GetDegreesPerChild()

eC_Value CGUICarousel::GetDegreesPerChild ( )

protected

Calculates the number of degrees per child object.

Returns: 360/NumberOfChildren in normal-mode, and 360/NOFEntries in flowmode

◆ GetOriginalSize()

void CGUICarousel::GetOriginalSize	(	const eC_UInt	uiIndex,
		eC_Value &	vWidth,
		eC_Value &	vHeight
	)

inline

Get original size of object at given index. Since the width and height of the child-objects within the carousel get recalculated according to perspective.

Parameters

uiIndex	index of object
vWidth	width of object
vHeight	height of object

◆ GetRadius()

eC_Value CGUICarousel::GetRadius ( ) const

inline

Returns the carousel's current radius

Returns: current radius

◆ GetSelectedIndex()

eC_Int CGUICarousel::GetSelectedIndex ( ) const

inline

Get index of child-object which is currently in front.

Returns: index of child object which is currently in front

◆ GetSelectedObject()

CGUIObject * CGUICarousel::GetSelectedObject ( )

inline

Get child object which is currently in front.

Returns: Pointer to child object which is currently in front

◆ GetTiltAngle()

eC_Value CGUICarousel::GetTiltAngle ( ) const

inline

Returns the carousel's current tilt-angle

Returns: current tilt-angle

◆ Increase()

eC_Bool CGUICarousel::Increase ( )

virtual

Rotate carousel entries clockwise

Returns: true

Reimplemented from CGUIBehaviour.

◆ IsHighlightable()

virtual eC_Bool CGUICarousel::IsHighlightable ( ) const

inlinevirtual

This method checks if an object is highlightable. This refers to whether it can be highlighted via the event handler. If true the event handler may mark this object as the currently highlighted one. Thus, there is no special flag in CGUIObject that determines if an object is highlightable. The default determination is that the control is in none of the following states:

invisible
grayed-out
disabled if so the return value will be true. NOTE: when an object is not highlightable, it will never receive DoMouseEnter and DoMouseLeave-events
Returns
True if highlightable, False otherwise

Reimplemented from CGUIObject.

◆ JumpToObject()

void CGUICarousel::JumpToObject ( CGUIObject * pkObject )

Selects the given object and Immediately (without animation) rotates the carousel, so that the given object is at the front

Parameters

pkObject Pointer to child object of carousel which shall be rotated to the front

◆ ReadFromStream()

virtual void CGUICarousel::ReadFromStream ( )

virtual

Reads composite object attributes and children from stream.

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

See also: CGUIObject::ReadFromStream()

Exceptions

CGUIStreamingControlException When catching a CGUIStreamingControlException from a child, this method adds the object from the exception, resets the object pointer to 'this', then re-throws.

Reimplemented from CGUICompositeObject.

◆ RemoveObject()

virtual void CGUICarousel::RemoveObject ( CGUIObject * pkObject )

virtual

Removes an object from the list of child objects. This will not delete the object! If you wish to physically delete an object, you should use the C++ delete operator. The destructor of the object will then remove the object from the child list by calling this method.

Parameters

pkObject The object to be removed

Reimplemented from CGUICompositeObject.

◆ RotateToObject()

void CGUICarousel::RotateToObject ( CGUIObject * pkObject )

Selects the given object and smoothly rotates the carousel, so that the given object is at the front

Parameters

pkObject Pointer to child object of carousel which shall be rotated to the front

◆ SetHeight()

virtual void CGUICarousel::SetHeight ( const eC_Value & vY )

virtual

Overridden SetHeight method. A composite object will call DoLayout() on itself when its width/height is changed if its associated layouter is independent of the parent's size. Afterwards in any case its direct children's DoLayout() of their layouters are called.

Parameters

vY	The new height

Reimplemented from CGUICompositeObject.

◆ SetInvertInput()

static void CGUICarousel::SetInvertInput ( const eC_Bool bInvert )

inlinestatic

Inverts keyboard input direction for all carousels.

Parameters

bInvert True Inverts keyboard input direction for all carousels.

◆ SetNumberOfFlowModeEntries()

void CGUICarousel::SetNumberOfFlowModeEntries ( const eC_UInt uiNOFEntries )

inline

Sets number of "virtual" entries within carousel in flow mode. Please refer to CGUICarousel's class documentation and examples for further information.

Parameters

uiNOFEntries Number of virtual carousel entries.

◆ SetPerspectiveFactor()

void CGUICarousel::SetPerspectiveFactor ( const eC_Value vPerspectiveFactor )

inline

Specifies the strength of perspective distortion which is applied to objects within tilted carousels. Objects in the background will appear smaller than those in the foreground. Objects in untilted carousels, and objects that reside on the X-Axis of tilted carousels, will be displayed in their original size. Sensible values are typically in the range of >0 to 1, where 0 means no perspective effect at all, and larger values result in stronger zooming / shrinking. Note that Z-Ordering will not work if perspective-Factor is 0.

Parameters

vPerspectiveFactor Perspective zooming factor (sensible range of values is typically >0 to 1)

◆ SetRadius()

void CGUICarousel::SetRadius ( const eC_Value vRadius )

inline

Sets the radius of the carousel The carousel's radius is set to half of the carousel's width per default during construction.

Parameters

vRadius Radius in pixels

◆ SetSelectedObject()

void CGUICarousel::SetSelectedObject ( CGUIObject * pkObject )

protected

Sets the selected object without actually rotating the object.

Parameters

pkObject Pointer to child object of carousel which shall be rotated to the front

◆ SetTiltAngle()

void CGUICarousel::SetTiltAngle ( const eC_Value vTiltAngle )

Sets the angle by which the carousel is tilted. (By default along the X-Axis. If SetVertical() has been set to True the carousel is tilted along the Y-Axis.

Parameters

vTiltAngle Tilting angle in Degrees (0-180) with 0 being NO tilt, and 180 degrees being the maximum.

◆ SetValue()

virtual eC_Bool CGUICarousel::SetValue ( const CGUIValue & rkValue )

inlinevirtual

Rotates the carousel to the child at the given Index.

See also: RotateToObject()

Parameters

rkValue The CGUIValue containing the new value

Returns: Always True.

Reimplemented from CGUIObject.

◆ SetVertical()

void CGUICarousel::SetVertical ( const eC_Bool bVertical )

inline

Switches between vertical and horizontal arrangement of the carousel.

Parameters

bVertical True arranges the carousel vertically, False arranges it horizontally.

◆ SetWidth()

virtual void CGUICarousel::SetWidth ( const eC_Value & vX )

virtual

Overridden SetWidth method. A composite object will call DoLayout() on itself when its width/height is changed if its associated layouter is independent of the parent's size. Afterwards in any case its direct children's DoLayout() of their layouters are called.

Parameters

vX	The new width

Reimplemented from CGUICompositeObject.

◆ WriteToStream()

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

virtual

Writes all object attributes to the streaming file. StreamWriter has to be initialized. Only for use with GUIStreamWriter.

Parameters

bWriteClassID This flag is used to select if writing of ControlID, leading and trailing tags is performed. Only GUIStreamWriter and GUICompositeObject have to set this flag true.

See also: CGUIStreamWriter

Reimplemented from CGUICompositeObject.

Member Data Documentation

◆ m_bFlowMode

eC_Bool CGUICarousel::m_bFlowMode

protected

Flowmode enables the carousel to contain more children than it physically could in reality. This enables user to create carousels with a virtually unlimited number of entries in them.

◆ m_bRotateByCursorKeys

eC_Bool CGUICarousel::m_bRotateByCursorKeys

protected

Flag indicating whether left/right cursor keys should be used to rotate the carousel as well This might interfere with standard focusing behaviour.

◆ m_uiNOFEntries

eC_UInt CGUICarousel::m_uiNOFEntries

protected

Only relevant in FlowMode. This defines a virtual number of entries in the carousel, used e.g. for calculating the spacing between them.

◆ m_vPerspectiveFactor

eC_Value CGUICarousel::m_vPerspectiveFactor

protected

The perspectivefactor defines the perspective scaling which is applied to carousel children. Larger factors result in a stronger perspective effect, while values close to 0 will result in an almost orthogonal projection.

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

GUICarousel.h

Classes

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Static Protected Attributes

Additional Inherited Members

Detailed Description

Using the carousel in flow-mode

Technical details regarding the CGUICarousel

Constructor & Destructor Documentation

◆ CGUICarousel()

Member Function Documentation

◆ AddObject()

◆ Decrease()

◆ DoAnimate()

◆ DoDrag()

◆ DoDragEnd()

◆ DoKeyDown()

◆ EnableFlowMode()

◆ GetDegreesPerChild()

◆ GetOriginalSize()

◆ GetRadius()

◆ GetSelectedIndex()

◆ GetSelectedObject()

◆ GetTiltAngle()

◆ Increase()

◆ IsHighlightable()

◆ JumpToObject()

◆ ReadFromStream()

◆ RemoveObject()

◆ RotateToObject()

◆ SetHeight()

◆ SetInvertInput()

◆ SetNumberOfFlowModeEntries()

◆ SetPerspectiveFactor()

◆ SetRadius()

◆ SetSelectedObject()

◆ SetTiltAngle()

◆ SetValue()

◆ SetVertical()

◆ SetWidth()

◆ WriteToStream()

Member Data Documentation

◆ m_bFlowMode

◆ m_bRotateByCursorKeys

◆ m_uiNOFEntries

◆ m_vPerspectiveFactor