#include <CUScrollPane.h>

Inheritance diagram for cugl::scene2::ScrollPane:

Public Member Functions
	ScrollPane ()

	~ScrollPane ()

virtual void	dispose () override

virtual bool	initWithBounds (const Size size) override

virtual bool	initWithBounds (float width, float height) override

virtual bool	initWithBounds (const Rect rect) override

virtual bool	initWithBounds (float x, float y, float width, float height) override

bool	initWithInterior (const Size size, const Rect interior, bool mask=true)

bool	initWithInterior (const Rect bounds, const Rect interior, bool mask=true)

virtual bool	initWithData (const Scene2Loader *loader, const std::shared_ptr< JsonValue > &data) override

const Rect &	getInterior () const

void	setInterior (const Rect &bounds)

virtual Rect	getLayoutBounds () const override

bool	isConstrained () const

bool	setConstrained (bool value)

bool	isMasked () const

void	setMasked (bool value)

float	getZoom () const

float	getMinZoom () const

bool	setMinZoom (float value)

float	getMaxZoom () const

bool	setMaxZoom (float value)

const Affine2 &	getPaneTransform () const

Vec2	applyPan (const Vec2 &delta)

Vec2	applyPan (float dx, float dy)

float	applySpin (float angle)

float	applyZoom (float zoom)

void	resetPane ()

virtual void	render (const std::shared_ptr< SpriteBatch > &batch, const Affine2 &transform, Color4 tint) override

virtual void	render (const std::shared_ptr< SpriteBatch > &batch) override

Public Member Functions inherited from cugl::scene2::SceneNode
	SceneNode ()

	~SceneNode ()

virtual void	dispose ()

virtual bool	init ()

virtual bool	initWithPosition (const Vec2 pos)

bool	initWithPosition (float x, float y)

virtual bool	initWithBounds (const Size size)

virtual bool	initWithBounds (float width, float height)

virtual bool	initWithBounds (const Rect rect)

virtual bool	initWithBounds (float x, float y, float width, float height)

virtual bool	initWithData (const Scene2Loader *loader, const std::shared_ptr< JsonValue > &data)

virtual std::shared_ptr< SceneNode >	copy (const std::shared_ptr< SceneNode > &dst) const

unsigned int	getTag () const

void	setTag (unsigned int tag)

const std::string	getName () const

void	setName (const std::string name)

const std::string	getClassName () const

virtual std::string	toString (bool verbose=false) const

	operator std::string () const

const Vec2	getPosition () const

void	setPosition (const Vec2 &position)

void	setPosition (float x, float y)

float	getPositionX (void) const

void	setPositionX (float x)

float	getPositionY (void) const

void	setPositionY (float y)

Vec2	getWorldPosition () const

const Size	getContentSize () const

virtual void	setContentSize (const Size size)

virtual void	setContentSize (float width, float height)

float	getContentWidth () const

void	setContentWidth (float width)

float	getContentHeight () const

void	setContentHeight (float height)

virtual Rect	getLayoutBounds () const

Size	getSize () const

float	getWidth () const

float	getHeight () const

Rect	getBoundingBox () const

virtual void	setAnchor (const Vec2 anchor)

virtual void	setAnchor (float x, float y)

const Vec2	getAnchor () const

Vec2	getAnchorInPixels ()

Color4	getColor () const

virtual void	setColor (Color4 color)

Color4	getAbsoluteColor ()

bool	isVisible () const

void	setVisible (bool visible)

bool	hasRelativeColor () const

void	setRelativeColor (bool flag)

std::shared_ptr< Scissor >	getScissor () const

void	setScissor (const std::shared_ptr< Scissor > &scissor)

void	setScissor ()

const Vec2	getScale () const

float	getScaleX () const

float	getScaleY () const

void	setScale (float scale)

void	setScale (const Vec2 vec)

void	setScale (float sx, float sy)

float	getAngle ()

void	setAngle (float angle)

const Affine2 &	getTransform () const

const Affine2 &	getAlternateTransform () const

void	setAlternateTransform (const Affine2 &transform)

bool	withAlternateTransform ()

void	chooseAlternateTransform (bool active)

const Affine2 &	getNodeToParentTransform () const

Affine2	getParentToNodeTransform () const

Affine2	getNodeToWorldTransform () const

Affine2	getWorldToNodeTransform () const

Vec2	screenToNodeCoords (const Vec2 screenPoint) const

Vec2	worldToNodeCoords (const Vec2 worldPoint) const

Vec2	nodeToScreenCoords (const Vec2 nodePoint) const

Vec2	nodeToWorldCoords (const Vec2 nodePoint) const

Vec2	parentToNodeCoords (const Vec2 parentPoint) const

Vec2	nodeToParentCoords (const Vec2 nodePoint) const

size_t	getChildCount () const

std::shared_ptr< SceneNode >	getChild (unsigned int pos)

const std::shared_ptr< SceneNode > &	getChild (unsigned int pos) const

template<typename T >
std::shared_ptr< T >	getChild (unsigned int pos) const

std::shared_ptr< SceneNode >	getChildByTag (unsigned int tag) const

template<typename T >
std::shared_ptr< T >	getChildByTag (unsigned int tag) const

std::shared_ptr< SceneNode >	getChildByName (const std::string name) const

template<typename T >
std::shared_ptr< T >	getChildByName (const std::string name) const

std::vector< std::shared_ptr< SceneNode > >	getChildren ()

const std::vector< std::shared_ptr< SceneNode > > &	getChildren () const

void	addChild (const std::shared_ptr< SceneNode > &child)

void	addChildWithTag (const std::shared_ptr< SceneNode > &child, unsigned int tag)

void	addChildWithName (const std::shared_ptr< SceneNode > &child, const std::string name)

void	swapChild (const std::shared_ptr< SceneNode > &child1, const std::shared_ptr< SceneNode > &child2, bool inherit=false)

SceneNode *	getParent ()

const SceneNode *	getParent () const

Scene2 *	getScene ()

const Scene2 *	getScene () const

void	removeFromParent ()

virtual void	removeChild (unsigned int pos)

void	removeChild (const std::shared_ptr< SceneNode > &child)

void	removeChildByTag (unsigned int tag)

void	removeChildByName (const std::string name)

virtual void	removeAllChildren ()

void	setPriority (float priority)

float	getPriority ()

virtual void	render (const std::shared_ptr< SpriteBatch > &batch, const Affine2 &transform, Color4 tint)

virtual void	render (const std::shared_ptr< SpriteBatch > &batch)

virtual void	draw (const std::shared_ptr< SpriteBatch > &batch, const Affine2 &transform, Color4 tint)

const std::shared_ptr< Layout > &	getLayout () const

void	setLayout (const std::shared_ptr< Layout > &layout)

virtual void	doLayout ()

Static Public Member Functions
static std::shared_ptr< ScrollPane >	allocWithBounds (const Size size)

static std::shared_ptr< ScrollPane >	allocWithBounds (float width, float height)

static std::shared_ptr< ScrollPane >	allocWithBounds (const Rect rect)

static std::shared_ptr< ScrollPane >	allocWithBounds (float x, float y, float width, float height)

static std::shared_ptr< ScrollPane >	allocWithInterior (const Size size, const Rect interior, bool mask=true)

static std::shared_ptr< ScrollPane >	allocWithInterior (const Rect bounds, const Rect interior, bool mask=true)

static std::shared_ptr< ScrollPane >	allocWithData (const Scene2Loader *loader, const std::shared_ptr< JsonValue > &data)

Static Public Member Functions inherited from cugl::scene2::SceneNode
static std::shared_ptr< SceneNode >	alloc ()

static std::shared_ptr< SceneNode >	allocWithPosition (const Vec2 pos)

static std::shared_ptr< SceneNode >	allocWithPosition (float x, float y)

static std::shared_ptr< SceneNode >	allocWithBounds (const Size size)

static std::shared_ptr< SceneNode >	allocWithBounds (float width, float height)

static std::shared_ptr< SceneNode >	allocWithBounds (const Rect rect)

static std::shared_ptr< SceneNode >	allocWithBounds (float x, float y, float width, float height)

static std::shared_ptr< SceneNode >	allocWithData (const Scene2Loader *loader, const std::shared_ptr< JsonValue > &data)

Protected Attributes
Rect	_interior

Affine2	_panetrans

bool	_constrained

bool	_reoriented

bool	_simple

float	_zoommin

float	_zoommax

float	_zoomamt

std::shared_ptr< Scissor >	_panemask

Protected Attributes inherited from cugl::scene2::SceneNode
Vec2	_position

Vec2	_anchor

Size	_contentSize

Color4	_tintColor

bool	_hasParentColor

bool	_isVisible

std::shared_ptr< Scissor >	_scissor

Vec2	_scale

float	_angle

Affine2	_transform

bool	_useTransform

Affine2	_combined

std::vector< std::shared_ptr< SceneNode > >	_children

SceneNode *	_parent

Scene2 *	_graph

std::shared_ptr< Layout >	_layout

int	_childOffset

unsigned int	_tag

std::string	_name

size_t	_hashOfName

std::string	_classname

float	_priority

std::shared_ptr< JsonValue >	_json

Detailed Description

This class is a node implements a scroll pane.

A scroll pane is a node that contains a larger backing view. The scroll pane uses an implicit scissor to guarantee that the user only sees what is in the content bounds of this node (e.g the rectangle that starts at (0,0) and has getContentSize()). This allows you to create internal windows that only show a portion of the backing contents.

The contents of a scroll pane are its children. However, the scroll pane also has the concept of getInterior, representing the dimension and location of the backing window. These bounds should be large enough to contain all of the children, but this is not enforced. The significance of the backing bounds is that the scroll pane will never go outside of these bounds unless isConstrained is true. Panning and zooming will stop once it hits one of the boundary edges. This allows you to prevent the user from going "out of bounds" when navigating the scroll pane.

Scroll panes support layout managers just like any other scene graph node. However, layout is performed with respect to the interior bounds and not the content bounds.

Scroll panes typically have scroll bars that allow you to navigate their contents. While this makes sense on a desktop computer, it does not make sense on a mobile device. On mobile devices, scroll panes are navigated with gestures, such as panning, pinching, or rotating.

As a result, this class does not contain any visual features for navigating a scroll pane. It only has methods for controlling the position and orientation of the the backing window. If you need visual interfaces like a scroll bar, you can attach them separately to the scene graph. Scroll bars are just instances of Slider.

This scroll pane is generalized enough that it is not limited to panning. It supports all of the core mobile navigation gestures: panning, zooming, and spinning. These are controlled by the methods applyPan, applyZoom, and applySpin. At first glance, these might appear to be redundant with the transform methods setPosition, setScale, and setAngle. But they are not.

First of all, the transform methods are applied to this node while the navigation methods are applied to the contents (i.e. the children). More importantly, the navigation methods are applied to all of the children uniformly. For example, when we call setScale or setAngle on any child, it is with respect to the anchor of that child. However, the navigation methods use the anchor of this node, which is often reassigned by the gesture.

These distinctions mean that it is quite tricky to implement navigation features by manipulating the children directly. Indeed, this class was created in reaction to the difficulties that developers had when they added zoom features to their scrolling windows. The classic example of this is a large game map that the user navigates by panning, zooming in, and zooming out.

The trickiest feature of the scroll pane is rotation (spinning). Because the backing bounds are a rectangle, and pane does not show anything outside of these bounds, the edges can catch on the visible bounds and block the rotation. If this is a problem you should either ignore spin input in your application or set setConstrained to false. However, the latter will mean that the user can navigate outside of the backing area.

Constructor & Destructor Documentation

◆ ScrollPane()

cugl::scene2::ScrollPane::ScrollPane ( )

Creates an uninitialized node.

You must initialize this Node before use.

NEVER USE A CONSTRUCTOR WITH NEW. If you want to allocate a Node on the heap, use one of the static constructors instead.

◆ ~ScrollPane()

cugl::scene2::ScrollPane::~ScrollPane ( )

inline

Deletes this node, disposing all resources

Member Function Documentation

◆ allocWithBounds() [1/4]

static std::shared_ptr< ScrollPane > cugl::scene2::ScrollPane::allocWithBounds ( const Rect rect )

inlinestatic

Returns a newly allocated node with the given bounds.

The rectangle origin is the bottom left corner of the node in parent space, and corresponds to the origin of the Node space. The size defines its content width and height in node space. The node anchor is placed in the bottom left corner.

The interior bounds will be equivalent to the content bounds. That means that no scrolling can happen until setInterior is called. In addition, masking will be turned off.

Parameters

rect	The bounds of the node in parent space

Returns: a newly allocated node with the given bounds.

◆ allocWithBounds() [2/4]

static std::shared_ptr< ScrollPane > cugl::scene2::ScrollPane::allocWithBounds ( const Size size )

inlinestatic

Returns a newly allocated node with the given size.

The size defines the content size. The bounding box of the node is (0,0,width,height) and is anchored in the bottom left corner (0,0). The node is positioned at the origin in parent space.

The interior bounds will be equivalent to the content bounds. That means that no scrolling can happen until setInterior is called. In addition, masking will be turned off.

Parameters

size	The size of the node in parent space

Returns: a newly allocated node with the given size.

◆ allocWithBounds() [3/4]

static std::shared_ptr< ScrollPane > cugl::scene2::ScrollPane::allocWithBounds	(	float	width,
		float	height
	)

inlinestatic

Returns a newly allocated node with the given size.

The size defines the content size. The bounding box of the node is (0,0,width,height) and is anchored in the bottom left corner (0,0). The node is positioned at the origin in parent space.

The interior bounds will be equivalent to the content bounds. That means that no scrolling can happen until setInterior is called. In addition, masking will be turned off.

Parameters

width	The width of the node in parent space
height	The height of the node in parent space

Returns: a newly allocated node with the given size.

◆ allocWithBounds() [4/4]

static std::shared_ptr< ScrollPane > cugl::scene2::ScrollPane::allocWithBounds	(	float	x,
		float	y,
		float	width,
		float	height
	)

inlinestatic

Returns a newly allocated node with the given bounds.

The rectangle origin is the bottom left corner of the node in parent space, and corresponds to the origin of the Node space. The size defines its content width and height in node space. The node anchor is placed in the bottom left corner.

The interior bounds will be equivalent to the content bounds. That means that no scrolling can happen until setInterior is called. In addition, masking will be turned off.

Parameters

x	The x-coordinate of the node origin in parent space
y	The y-coordinate of the node origin in parent space
width	The width of the node in parent space
height	The height of the node in parent space

Returns: a newly allocated node with the given bounds.

◆ allocWithData()

static std::shared_ptr< ScrollPane > cugl::scene2::ScrollPane::allocWithData	(	const Scene2Loader *	loader,
		const std::shared_ptr< JsonValue > &	data
	)

inlinestatic

Returns a newly node with the given JSON specification.

This initializer is designed to receive the "data" object from the JSON passed to Scene2Loader. This JSON format supports all of the attribute values of its parent class. In addition, it supports the following additional attributes:

 "interior":  A two or four-element number array for the interior bounds.
              A two-element array indicates the bounds start at the origin.
 "constrain": A boolean value, indicating whether to keep the interior in bounds.
 "mask":      A boolean value, indicating whether to hide out-of-bounds contents.
 "pan":       A two-element number array, representing the initial pan offset.
 "spin"       A float represeting the initial spin angle in radians.
 "zoom"       A float representing the initial zoom factor.
 "zoom max":  A float representing the maximum supported cumulative zoom.
 "zoom min":  A float representing the minimum supported cumulative zoom.

All attributes are optional. There are no required attributes. If any scroll adjustments are set (pan, spin, zoom) they will be applied in the following order: spin, then zoom, then pan.

Note that if the interior size and/or position pushes it outside of the content bounds, then the constrain setting will be ignored and set to false.

Parameters

loader	The scene loader passing this JSON file
data	The JSON object specifying the node

Returns: a newly node with the given JSON specification.

◆ allocWithInterior() [1/2]

static std::shared_ptr< ScrollPane > cugl::scene2::ScrollPane::allocWithInterior	(	const Rect	bounds,
		const Rect	interior,
		bool	mask = `true`
	)

inlinestatic

Returns a newly allocated node with the given bounds.

The rectangle origin is the bottom left corner of the node in parent space, and corresponds to the origin of the Node space. The size defines its content width and height in node space. The node anchor is placed in the bottom left corner.

The interior bounds will be as given. This interior will be placed in the default orientation as defined by resetPane. The interior will start off as constrained unless this is impossible (e.g. the interior is smaller than the content bounds).

The optional masking value can be set to false to allow the area outside of the content bounds to be visible.

Parameters

bounds	The bounds of the node in parent space
interior	The bounds of the interior in node space
mask	Whether to mask contents outside of node bounds

Returns: a newly allocated node with the given bounds.

◆ allocWithInterior() [2/2]

static std::shared_ptr< ScrollPane > cugl::scene2::ScrollPane::allocWithInterior	(	const Size	size,
		const Rect	interior,
		bool	mask = `true`
	)

inlinestatic

Returns a newly allocated node with the given size and interior

The size defines the content size. The bounding box of the node is (0,0,width,height) and is anchored in the bottom left corner (0,0). The node is positioned at the origin in parent space.

The interior bounds will be as given. This interior will be placed in the default orientation as defined by resetPane. The interior will start off as constrained unless this is impossible (e.g. the interior is smaller than the content bounds).

The optional masking value can be set to false to allow the area outside of the content bounds to be visible.

Parameters

size	The size of the node in parent space
interior	The bounds of the interior in node space
mask	Whether to mask contents outside of node bounds

Returns: a newly allocated node with the given size and interior

◆ applyPan() [1/2]

Vec2 cugl::scene2::ScrollPane::applyPan ( const Vec2 & delta )

Attempts to apply the given pan to the scroll pane.

The pan is an offset value applied to the interior bounds. Pan values are applied incrementally. You cannot set the absolute pan, as it is impossible to do this while supporting both zooming and spinning. If you want to set an absolute pan, you should call resetPane and then apply the pan.

If the scroll pane is constrained, then any pan that would show edges of the interior (such as going too far to the left or the right) will not be allowed. Instead, it is replaced with the closest legal pan (which is returned).

Parameters

delta The pan offset to apply

Returns: the actual pan applied

◆ applyPan() [2/2]

Vec2 cugl::scene2::ScrollPane::applyPan	(	float	dx,
		float	dy
	)

Attempts to apply the given pan to the scroll pane.

The pan is an offset value applied to the interior bounds. Pan values are applied incrementally. You cannot set the absolute pan, as it is impossible to do this while supporting both zooming and spinning. If you want to set an absolute pan, you should call resetPane and then apply the pan.

If the scroll pane is constrained, then any pan that would show edges of the interior (such as going too far to the left or the right) will not be allowed. Instead, it is replaced with the closest legal pan (which is returned).

Parameters

dx	The x offset to apply
dy	The y offset to apply

Returns: the actual pan applied

◆ applySpin()

float cugl::scene2::ScrollPane::applySpin ( float angle )

Attempts to apply the given spin to the scroll pane.

The spin is an angle of rotation. The angle is measured in radians, just like SceneNode#getAngle. However, the angle is applied to the interior content, and not the scroll pane itself.

If the scroll pane is constrained, then any spin angle that would show edges of the interior (typically when the size of the interior is smaller than the circumscribed circle containing the content bounds) will not be allowed. Instead, it is replaced with the closest legal angle in the same direction (which is returned).

The value SceneNode#getAnchor defines the origin of the spin. The input handler should reset the anchor to spin about different portions of the content region.

Parameters

angle The spin angle in radians

Returns: the actual spin applied

◆ applyZoom()

float cugl::scene2::ScrollPane::applyZoom ( float zoom )

Attempts to apply the given zoom to the scroll pane.

A zoom factor is a scaling factor. Values greater than 1 zoom in, enlarging the content. Values less than 1 (but still postive) zoom out, shrinking the content. Negative zoom values are not supported.

If the scroll pane is constrained, then any zoom factor that would show edges of the interior (typically when zooming out) will not be allowed. Instead, it is replaced with the closest legal zoom factor (which is returned).

At all times, the scroll pane keeps track of the cumulative zoom in or out. This cumulative zoom must stay with the range of getMinZoom and getMaxZoom. If it were to go outside this range, it is replaced with the closest legal zoom factor (which is returned).

The value SceneNode#getAnchor defines the origin of the zoom. The input handler should reset the anchor to zoom in on different portions of the content region.

Parameters

zoom	The zoom factor

Returns: the actual zoom factor applied

◆ dispose()

virtual void cugl::scene2::ScrollPane::dispose ( )

overridevirtual

Disposes all of the resources used by this node.

A disposed Node can be safely reinitialized. Any children owned by this node will be released. They will be deleted if no other object owns them.

It is unsafe to call this on a Node that is still currently inside of a scene graph.

Reimplemented from cugl::scene2::SceneNode.

◆ getInterior()

const Rect & cugl::scene2::ScrollPane::getInterior ( ) const

inline

Returns the interior bounds of this scroll pane.

A scroll pane is essentially a view port that shows a portion of a content area. This content area is defined by the interior rectangle. All children positions are defined relative to this content area and not the node itself.

If the node is constrained, it will never show any area outside of the interior bounds. Any attempts to pan, spin, or zoom the interior in such a way to violate this are prohibited. For example, if a pan pushes the interior so far that an edge of the interior would be showing in the content bounds, then this pan will be aborted.

Returns: the interior bounds of this scroll pane.

◆ getLayoutBounds()

virtual Rect cugl::scene2::ScrollPane::getLayoutBounds ( ) const

inlineoverridevirtual

Returns the untransformed bounds of this node for layout purposes.

The layout bounds are used by the layout managers to place children in this node. For example, an anchored layout will put a child with anchors "top" and "right" at the top right corners of these bounds.

In this class, the layout bounds correspond to getInterior. This allows the layout managers to properly layout the content regardless of the current scroll settings.

Reimplemented from cugl::scene2::SceneNode.

◆ getMaxZoom()

float cugl::scene2::ScrollPane::getMaxZoom ( ) const

inline

Returns the maximum supported cumulative zoom

A zoom factor is a scaling factor. Values greater than 1 zoom in, enlarging the content. Values less than 1 (but still postive) zoom out, shrinking the content. Negative zoom values are not supported.

At all times, the scroll pane keeps track of the cumulative zoom in or out. This cumulative zoom must stay always be less than the maximum zoom. Attempts to zoom further in than this amount will be denied.

Returns: the maximum supported cumulative zoom

◆ getMinZoom()

float cugl::scene2::ScrollPane::getMinZoom ( ) const

inline

Returns the minimum supported cumulative zoom

A zoom factor is a scaling factor. Values greater than 1 zoom in, enlarging the content. Values less than 1 (but still postive) zoom out, shrinking the content. Negative zoom values are not supported.

At all times, the scroll pane keeps track of the cumulative zoom in or out. This cumulative zoom must stay always be greater than the minimum zoom. Attempts to zoom further out than this amount will be denied.

Returns: the minimum supported cumulative zoom

◆ getPaneTransform()

const Affine2 & cugl::scene2::ScrollPane::getPaneTransform ( ) const

inline

Returns the transform matrix for the interior.

The transform matrix is applied to the interior to transform the contents from the node coordinate space to the interior window coordinate space. This transform is adjusted by calling applyPan, applyZoom, and applySpin.

This matrix will be the identity if resetPane is called on an unconstrained node. However, if the node is constrained then the default transform will insure that the interior is within bounds.

Returns: the transform matrix for the interior.

◆ getZoom()

float cugl::scene2::ScrollPane::getZoom ( ) const

inline

Returns the current cumulative zoom for this node.

This value is useful when you want to control the rate of change of zoom relative to what has been applied.

Returns: the current cumulative zoom for this node.

◆ initWithBounds() [1/4]

virtual bool cugl::scene2::ScrollPane::initWithBounds ( const Rect rect )

overridevirtual

Initializes a node with the given bounds.

The rectangle origin is the bottom left corner of the node in parent space, and corresponds to the origin of the Node space. The size defines its content width and height in node space. The node anchor is placed in the bottom left corner.

The interior bounds will be equivalent to the content bounds. That means that no scrolling can happen until setInterior is called. In addition, masking will be turned off and the interior is unconstrained.

Parameters

rect	The bounds of the node in parent space

Returns: true if initialization was successful.

Reimplemented from cugl::scene2::SceneNode.

◆ initWithBounds() [2/4]

virtual bool cugl::scene2::ScrollPane::initWithBounds ( const Size size )

overridevirtual

Initializes a node with the given size.

The size defines the content size. The bounding box of the node is
(0,0,width,height) and is anchored in the bottom left corner (0,0).
The node is positioned at the origin in parent space.

The interior bounds will be equivalent to the content bounds. That
means that no scrolling can happen until {@link #setInterior} is
called. In addition, masking will be turned off and the interior

is unconstrained.

@param size  The size of the node in parent space

@return true if initialization was successful.

Reimplemented from cugl::scene2::SceneNode.

◆ initWithBounds() [3/4]

virtual bool cugl::scene2::ScrollPane::initWithBounds	(	float	width,
		float	height
	)

inlineoverridevirtual

Initializes a node with the given size.

The size defines the content size. The bounding box of the node is (0,0,width,height) and is anchored in the bottom left corner (0,0). The node is positioned at the origin in parent space.

The interior bounds will be equivalent to the content bounds. That means that no scrolling can happen until setInterior is called. In addition, masking will be turned off and the interior is unconstrained.

Parameters

width	The width of the node in parent space
height	The height of the node in parent space

Returns: true if initialization was successful.

Reimplemented from cugl::scene2::SceneNode.

◆ initWithBounds() [4/4]

virtual bool cugl::scene2::ScrollPane::initWithBounds	(	float	x,
		float	y,
		float	width,
		float	height
	)

inlineoverridevirtual

Initializes a node with the given bounds.

The rectangle origin is the bottom left corner of the node in parent space, and corresponds to the origin of the Node space. The size defines its content width and height in node space. The node anchor is placed in the bottom left corner.

The interior bounds will be equivalent to the content bounds. That means that no scrolling can happen until setInterior is called. In addition, masking will be turned off and the interior is unconstrained.

Parameters

x	The x-coordinate of the node origin in parent space
y	The y-coordinate of the node origin in parent space
width	The width of the node in parent space
height	The height of the node in parent space

Returns: true if initialization was successful.

Reimplemented from cugl::scene2::SceneNode.

◆ initWithData()

virtual bool cugl::scene2::ScrollPane::initWithData	(	const Scene2Loader *	loader,
		const std::shared_ptr< JsonValue > &	data
	)

overridevirtual

Initializes a node with the given JSON specificaton.

This initializer is designed to receive the "data" object from the JSON passed to Scene2Loader. This JSON format supports all of the attribute values of its parent class. In addition, it supports the following additional attributes:

 "interior":  A two or four-element number array for the interior bounds.
              A two-element array indicates the bounds start at the origin.
 "constrain": A boolean value, indicating whether to keep the interior in bounds.
 "mask":      A boolean value, indicating whether to hide out-of-bounds contents.
 "pan":       A two-element number array, representing the initial pan offset.
 "spin"       A float represeting the initial spin angle in radians.
 "zoom"       A float representing the initial zoom factor.
 "zoom max":  A float representing the maximum supported cumulative zoom.
 "zoom min":  A float representing the minimum supported cumulative zoom.

All attributes are optional. There are no required attributes. If any scroll adjustments are set (pan, spin, zoom) they will be applied in the following order: spin, then zoom, then pan.

Note that if the interior size and/or position pushes it outside of the content bounds, then the constrain setting will be ignored and set to false.

Parameters

loader	The scene loader passing this JSON file
data	The JSON object specifying the node

Returns: true if initialization was successful.

Reimplemented from cugl::scene2::SceneNode.

◆ initWithInterior() [1/2]

bool cugl::scene2::ScrollPane::initWithInterior	(	const Rect	bounds,
		const Rect	interior,
		bool	mask = `true`
	)

Initializes a node with the given bounds.

The rectangle origin is the bottom left corner of the node in parent space, and corresponds to the origin of the Node space. The size defines its content width and height in node space. The node anchor is placed in the bottom left corner.

The interior bounds will be as given. This interior will be placed in the default orientation as defined by resetPane. The interior will start off as constrained unless this is impossible (e.g. the interior is smaller than the content bounds).

The optional masking value can be set to false to allow the area outside of the content bounds to be visible.

Parameters

bounds	The bounds of the node in parent space
interior	The bounds of the interior in node space
mask	Whether to mask contents outside of node bounds

Returns: true if initialization was successful.

◆ initWithInterior() [2/2]

bool cugl::scene2::ScrollPane::initWithInterior	(	const Size	size,
		const Rect	interior,
		bool	mask = `true`
	)

Initializes a node with the given size and interior

The size defines the content size. The bounding box of the node is (0,0,width,height) and is anchored in the bottom left corner (0,0). The node is positioned at the origin in parent space.

The interior bounds will be as given. This interior will be placed in the default orientation as defined by resetPane. The interior will start off as constrained unless this is impossible (e.g. the interior is smaller than the content bounds).

The optional masking value can be set to false to allow the area outside of the content bounds to be visible.

Parameters

size	The size of the node in parent space
interior	The bounds of the interior in node space
mask	Whether to mask contents outside of node bounds

Returns: true if initialization was successful.

◆ isConstrained()

bool cugl::scene2::ScrollPane::isConstrained ( ) const

inline

Returns true if this scroll pane is constrained.

A constrained scroll pane will never show any area outside of the interior bounds. Any attempts to pan, spin, or zoom the interior in such a way to violate this are prohibited. For example, if a pan pushes the interior so far that an edge of the interior would be showing in the content bounds, then this pan will be aborted.

Returns: true if this scroll pane is constrained

◆ isMasked()

bool cugl::scene2::ScrollPane::isMasked ( ) const

inline

Returns true if this scroll pane is masked.

A masked scroll pane will never show any content outside of the content bounds. This node will activate an implicit scissor whose bounds are the size of the content bounds to avoid drawing this content.

A scroll pane has only one scissor at a given time. So if a scissor is masked, then it will ignore the SceneNode#getScissor attribute defined in its parent class. The scissor should be unmasked if you want to support a custom scissor.

Returns: true if this scroll pane is masked.

◆ render() [1/2]

virtual void cugl::scene2::ScrollPane::render ( const std::shared_ptr< SpriteBatch > & batch )

inlineoverridevirtual

Draws this Node and all of its children with the given SpriteBatch.

You almost never need to override this method. You should override the method draw(shared_ptr<SpriteBatch>,const Affine2&,Color4) if you need to define custom drawing code. In fact, overriding this method can break the functionality of OrderedNode.

Parameters

batch The SpriteBatch to draw with.

Reimplemented from cugl::scene2::SceneNode.

◆ render() [2/2]

virtual void cugl::scene2::ScrollPane::render	(	const std::shared_ptr< SpriteBatch > &	batch,
		const Affine2 &	transform,
		Color4	tint
	)

overridevirtual

Draws this Node and all of its children with the given SpriteBatch.

You almost never need to override this method. You should override the method draw(shared_ptr<SpriteBatch>,const Affine2&,Color4) if you need to define custom drawing code. In fact, overriding this method can break the functionality of OrderedNode.

Parameters

batch	The SpriteBatch to draw with.
transform	The global transformation matrix.
tint	The tint to blend with the Node color.

Reimplemented from cugl::scene2::SceneNode.

◆ resetPane()

void cugl::scene2::ScrollPane::resetPane ( )

Resets the interior to the default position.

The default position is typically the untransformed interior, meaing that getPaneTransform returns the identity. However, if the pane is constrained, a small or badly-positioned interior may cause some out-of-bounds areas to be shown. In that case, this method will pan (not zoom or spin) the interior so that it is in bounds.

If this cannot be accomplised (because the interior is too small), then this method will set the constrained attribute to false.

◆ setConstrained()

bool cugl::scene2::ScrollPane::setConstrained ( bool value )

Sets the constrained attribute, returning true on success.

A constrained scroll pane will never show any area outside of the interior bounds. Any attempts to pan, spin, or zoom the interior in such a way to violate this are prohibited. For example, if a pan pushes the interior so far that an edge of the interior would be showing in the content bounds, then this pan will be aborted.

If the scroll pane is currently showing any out-of-bound areas (e.g. the interior does not properly contain all four corners of the content bounds), then the interior will be reset to its untransformed position. If this still shows any out-of-bound areas (e.g. the interior is too small), then this method will fail.

Parameters

value Whether to constrain this scroll pane

Returns: true if the constrained attribute was changed

◆ setInterior()

void cugl::scene2::ScrollPane::setInterior ( const Rect & bounds )

Sets the interior bounds of this scroll pane.

A scroll pane is essentially a view port that shows a portion of a content area. This content area is defined by the interior rectangle. All children positions are defined relative to this content area and not the node itself.

If the node is constrained, it will never show any area outside of the interior bounds. Any attempts to pan, spin, or zoom the interior in such a way to violate this are prohibited. For example, if a pan pushes the interior so far that an edge of the interior would be showing in the content bounds, then this pan will be aborted.

If the interior position would force a constrained node to show any out-of-bounds content (e.g. the interior does not properly contain all four corners of the content bounds), then the pan value will be adjusted so that the bottom left corner is at the origin. If the interior is still too small to cover the content bounds then this method will set constrained to false.

◆ setMasked()

void cugl::scene2::ScrollPane::setMasked ( bool value )

Sets whether this scroll pane is masked.

A masked scroll pane will never show any content outside of the content bounds. This node will activate an implicit scissor whose bounds are the size of the content bounds to avoid drawing this content.

A scroll pane has only one scissor at a given time. So if a scissor is masked, then it will ignore the SceneNode#getScissor attribute defined in its parent class. The scissor should be unmasked if you want to support a custom scissor. Setting this value to true will only ignore the custom scissor; it will not erase it.

Parameters

value Whether this scroll pane is masked.

◆ setMaxZoom()

bool cugl::scene2::ScrollPane::setMaxZoom ( float value )

Attempts to set the maximum supported cumulative zoom

A zoom factor is a scaling factor. Values greater than 1 zoom in, enlarging the content. Values less than 1 (but still postive) zoom out, shrinking the content. Negative zoom values are not supported.

At all times, the scroll pane keeps track of the cumulative zoom in or out. This cumulative zoom must stay always be less than the maximum zoom. Attempts to zoom further in than this amount will be denied.

This setter will fail if the value is less than the current cumulative zoom in use.

Parameters

value The maximum supported cumulative zoom

Returns: true If this maximum zoom successfully changed

◆ setMinZoom()

bool cugl::scene2::ScrollPane::setMinZoom ( float value )

Attempts to set the minimum supported cumulative zoom

A zoom factor is a scaling factor. Values greater than 1 zoom in, enlarging the content. Values less than 1 (but still postive) zoom out, shrinking the content. Negative zoom values are not supported.

At all times, the scroll pane keeps track of the cumulative zoom in or out. This cumulative zoom must stay always be greater than the minimum zoom. Attempts to zoom further out than this amount will be denied.

This setter will fail if either the minimum zoom factor is negative, or the value is greater than the current cumulative zoom in use.

Parameters

value The minimum supported cumulative zoom

Returns: true If this minimum zoom successfully changed

Member Data Documentation

◆ _constrained

bool cugl::scene2::ScrollPane::_constrained

protected

Whether the node is constrained, forcing the interior within bounds

◆ _interior

Rect cugl::scene2::ScrollPane::_interior

protected

The interior rectangle representing the internal content bounds

◆ _panemask

std::shared_ptr<Scissor> cugl::scene2::ScrollPane::_panemask

protected

The masking scissor for this scroll pane

◆ _panetrans

Affine2 cugl::scene2::ScrollPane::_panetrans

protected

The transform to apply to the interior rectangle

◆ _reoriented

bool cugl::scene2::ScrollPane::_reoriented

protected

Whether any transforms have been applied to the interior

◆ _simple

bool cugl::scene2::ScrollPane::_simple

protected

Whether the only transform applied to the interior is panning

◆ _zoomamt

float cugl::scene2::ScrollPane::_zoomamt

protected

The current cumulative zoom value

◆ _zoommax

float cugl::scene2::ScrollPane::_zoommax

protected

The maximum supported zoom amount

◆ _zoommin

float cugl::scene2::ScrollPane::_zoommin

protected

The minimum supported zoom amount

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

cugl/include/cugl/scene2/ui/CUScrollPane.h

Public Member Functions

Static Public Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ ScrollPane()

◆ ~ScrollPane()

Member Function Documentation

◆ allocWithBounds() [1/4]

◆ allocWithBounds() [2/4]

◆ allocWithBounds() [3/4]

◆ allocWithBounds() [4/4]

◆ allocWithData()

◆ allocWithInterior() [1/2]

◆ allocWithInterior() [2/2]

◆ applyPan() [1/2]

◆ applyPan() [2/2]

◆ applySpin()

◆ applyZoom()

◆ dispose()

◆ getInterior()

◆ getLayoutBounds()

◆ getMaxZoom()

◆ getMinZoom()

◆ getPaneTransform()

◆ getZoom()

◆ initWithBounds() [1/4]

◆ initWithBounds() [2/4]

◆ initWithBounds() [3/4]

◆ initWithBounds() [4/4]

◆ initWithData()

◆ initWithInterior() [1/2]

◆ initWithInterior() [2/2]

◆ isConstrained()

◆ isMasked()

◆ render() [1/2]

◆ render() [2/2]

◆ resetPane()

◆ setConstrained()

◆ setInterior()

◆ setMasked()

◆ setMaxZoom()

◆ setMinZoom()

Member Data Documentation

◆ _constrained

◆ _interior

◆ _panemask

◆ _panetrans

◆ _reoriented

◆ _simple

◆ _zoomamt

◆ _zoommax

◆ _zoommin