CUGL 2.3
Cornell University Game Library
Loading...
Searching...
No Matches
Public Member Functions | Static Public Member Functions | Protected Attributes | List of all members
cugl::scene2::ScrollPane Class Reference

#include <CUScrollPane.h>

Inheritance diagram for cugl::scene2::ScrollPane:
cugl::scene2::SceneNode

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 RectgetInterior () 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 Affine2getPaneTransform () 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< SceneNodecopy (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< ScissorgetScissor () 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 Affine2getTransform () const
 
const Affine2getAlternateTransform () const
 
void setAlternateTransform (const Affine2 &transform)
 
bool withAlternateTransform ()
 
void chooseAlternateTransform (bool active)
 
const Affine2getNodeToParentTransform () 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< SceneNodegetChild (unsigned int pos)
 
const std::shared_ptr< SceneNode > & getChild (unsigned int pos) const
 
template<typename T >
std::shared_ptr< TgetChild (unsigned int pos) const
 
std::shared_ptr< SceneNodegetChildByTag (unsigned int tag) const
 
template<typename T >
std::shared_ptr< TgetChildByTag (unsigned int tag) const
 
std::shared_ptr< SceneNodegetChildByName (const std::string name) const
 
template<typename T >
std::shared_ptr< TgetChildByName (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)
 
SceneNodegetParent ()
 
const SceneNodegetParent () const
 
Scene2getScene ()
 
const Scene2getScene () 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< ScrollPaneallocWithBounds (const Size size)
 
static std::shared_ptr< ScrollPaneallocWithBounds (float width, float height)
 
static std::shared_ptr< ScrollPaneallocWithBounds (const Rect rect)
 
static std::shared_ptr< ScrollPaneallocWithBounds (float x, float y, float width, float height)
 
static std::shared_ptr< ScrollPaneallocWithInterior (const Size size, const Rect interior, bool mask=true)
 
static std::shared_ptr< ScrollPaneallocWithInterior (const Rect bounds, const Rect interior, bool mask=true)
 
static std::shared_ptr< ScrollPaneallocWithData (const Scene2Loader *loader, const std::shared_ptr< JsonValue > &data)
 
- Static Public Member Functions inherited from cugl::scene2::SceneNode
static std::shared_ptr< SceneNodealloc ()
 
static std::shared_ptr< SceneNodeallocWithPosition (const Vec2 pos)
 
static std::shared_ptr< SceneNodeallocWithPosition (float x, float y)
 
static std::shared_ptr< SceneNodeallocWithBounds (const Size size)
 
static std::shared_ptr< SceneNodeallocWithBounds (float width, float height)
 
static std::shared_ptr< SceneNodeallocWithBounds (const Rect rect)
 
static std::shared_ptr< SceneNodeallocWithBounds (float x, float y, float width, float height)
 
static std::shared_ptr< SceneNodeallocWithData (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
rectThe 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
sizeThe 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
widthThe width of the node in parent space
heightThe 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
xThe x-coordinate of the node origin in parent space
yThe y-coordinate of the node origin in parent space
widthThe width of the node in parent space
heightThe 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
loaderThe scene loader passing this JSON file
dataThe 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
boundsThe bounds of the node in parent space
interiorThe bounds of the interior in node space
maskWhether 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
sizeThe size of the node in parent space
interiorThe bounds of the interior in node space
maskWhether 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
deltaThe 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
dxThe x offset to apply
dyThe 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
angleThe 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
zoomThe 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
rectThe 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
widthThe width of the node in parent space
heightThe 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
xThe x-coordinate of the node origin in parent space
yThe y-coordinate of the node origin in parent space
widthThe width of the node in parent space
heightThe 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
loaderThe scene loader passing this JSON file
dataThe 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
boundsThe bounds of the node in parent space
interiorThe bounds of the interior in node space
maskWhether 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
sizeThe size of the node in parent space
interiorThe bounds of the interior in node space
maskWhether 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
batchThe 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
batchThe SpriteBatch to draw with.
transformThe global transformation matrix.
tintThe 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
valueWhether 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
valueWhether 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
valueThe 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
valueThe 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: