CUGL 2.1
Cornell University Game Library
Public Types | Public Member Functions | Static Public Member Functions | Protected Attributes | List of all members
cugl::scene2::Button Class Reference

#include <CUButton.h>

Inheritance diagram for cugl::scene2::Button:
cugl::scene2::SceneNode

Public Types

typedef std::function< void(const std::string &name, bool down)> Listener
 

Public Member Functions

 Button ()
 
 ~Button ()
 
virtual void dispose () override
 
virtual bool init () override
 
bool init (const std::shared_ptr< SceneNode > &up)
 
bool init (const std::shared_ptr< SceneNode > &up, Color4 down)
 
bool init (const std::shared_ptr< SceneNode > &up, const std::shared_ptr< SceneNode > &down)
 
bool initWithData (const Scene2Loader *loader, const std::shared_ptr< JsonValue > &data) override
 
virtual void setColor (Color4 color) override
 
const Path2getPushable () const
 
void setPushable (const Path2 &bounds)
 
void setPushable (const std::vector< Vec2 > &vertices)
 
virtual void doLayout () override
 
bool containsScreen (const Vec2 point)
 
bool containsScreen (float x, float y)
 
bool isDown () const
 
void setDown (bool down)
 
bool isToggle () const
 
void setToggle (bool value)
 
bool hasListener () const
 
const Listener getListener (Uint32 key) const
 
const std::vector< ListenergetListeners () const
 
Uint32 addListener (Listener listener)
 
bool removeListener (Uint32 key)
 
void clearListeners ()
 
bool activate ()
 
bool deactivate ()
 
bool isActive () const
 
- Public Member Functions inherited from cugl::scene2::SceneNode
 SceneNode ()
 
 ~SceneNode ()
 
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 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
 
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< T > getChild (unsigned int pos) const
 
std::shared_ptr< SceneNodegetChildByTag (unsigned int tag) const
 
template<typename T >
std::shared_ptr< T > getChildByTag (unsigned int tag) const
 
std::shared_ptr< SceneNodegetChildByName (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)
 
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)
 

Static Public Member Functions

static std::shared_ptr< Buttonalloc (const std::shared_ptr< SceneNode > &up)
 
static std::shared_ptr< Buttonalloc (const std::shared_ptr< SceneNode > &up, Color4 down)
 
static std::shared_ptr< Buttonalloc (const std::shared_ptr< SceneNode > &up, const std::shared_ptr< SceneNode > &down)
 
static std::shared_ptr< SceneNodeallocWithData (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

bool _down
 
bool _toggle
 
std::shared_ptr< SceneNode_upnode
 
std::shared_ptr< SceneNode_downnode
 
std::shared_ptr< JsonValue_upform
 
std::shared_ptr< JsonValue_downform
 
Color4 _upcolor
 
Color4 _downcolor
 
std::string _upchild
 
std::string _downchild
 
Path2 _bounds
 
bool _active
 
bool _mouse
 
Uint32 _inputkey
 
Uint32 _nextKey
 
std::unordered_map< Uint32, Listener_listeners
 
- 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 represents a simple clickable button

A button is either two nodes (one for up, one for down) that swap whenever the button is pressed, or a single node that changes color on a press. The nodes are typically either images (e.g PolygonNode or instances of class Label. These nodes are stored as children of this button, which in turn should be part of a larger scene graph.

The button can track its own state, via the activate() method, relieving you of having to manually check mouse presses/touches. However, the appropriate input device must be active before you can activate the button, as it needs to attach internal listeners.

When a button tracks its own state, it is classified as either a normal or a toggle button. A normal button is down only when it is pressed. A toggle button changes state when pressed, and retains that state until the next press.

The user can define the clickable region to be any arbitrary polygon. This allows the click response to better match complex images.

Member Typedef Documentation

◆ Listener

This type represents a listener for state change in the Button class.

In CUGL, listeners are implemented as a set of callback functions, not as objects. This allows each listener to implement as much or as little functionality as it wants. For simplicity, Button nodes only support a single listener. If you wish for more than one listener, then your listener should handle its own dispatch.

The function type is equivalent to

 std::function<void(const std::string& name, bool down)>
Parameters
nameThe button name
clicksWhether the button is now down

Constructor & Destructor Documentation

◆ Button()

cugl::scene2::Button::Button ( )

Creates an uninitialized button with no size or texture information.

You must initialize this button 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.

◆ ~Button()

cugl::scene2::Button::~Button ( )
inline

Deletes this button, disposing all resources

Member Function Documentation

◆ activate()

bool cugl::scene2::Button::activate ( )

Activates this button to listen for mouse/touch events.

This method attaches a listener to either the Mouse or Touchscreen inputs to monitor when the button is pressed and/or released. The button will favor the mouse, but will use the touch screen if no mouse input is active. If neither input is active, this method will fail.

When active, the button will change its state on its own, without requiring the user to use setDown(bool). If there is a Listener attached, it will call that function upon any state changes.

Returns
true if the button was successfully activated

◆ addListener()

Uint32 cugl::scene2::Button::addListener ( Listener  listener)

Returns a key for a listener after adding it to this button.

This listener is invoked when the button state changes (up or down).

C++ cannot hash functions types. Therefore, the listener will be identified by a unique key, returned by this function. You should remember this key to remove the listener if necessary.

Parameters
listenerThe listener to add
Returns
the key for the listener

◆ alloc() [1/3]

static std::shared_ptr<Button> cugl::scene2::Button::alloc ( const std::shared_ptr< SceneNode > &  up)
inlinestatic

Returns a newly allocated button with the given up node.

The button will look exactly like the given node when it is not pressed. When pressed, it will darken the up node a bit.

Parameters
upThe button when it is not pressed
Returns
a newly allocated button with the given up node.

◆ alloc() [2/3]

static std::shared_ptr<Button> cugl::scene2::Button::alloc ( const std::shared_ptr< SceneNode > &  up,
Color4  down 
)
inlinestatic

Returns a newly allocated button with the given node and color

The button will look exactly like the given node when it is not pressed. When pressed, it will tint the up node by the specified color.

Parameters
upThe button when it is not pressed
downThe button tint when it is pressed
Returns
a newly allocated button with the given node and color

◆ alloc() [3/3]

static std::shared_ptr<Button> cugl::scene2::Button::alloc ( const std::shared_ptr< SceneNode > &  up,
const std::shared_ptr< SceneNode > &  down 
)
inlinestatic

Returns a newly allocated button with the given nodes

The button will look exactly like the up node when it is not pressed. It will look like the down node when it is pressed. The size of this button is the size of the larger of the two nodes.

Parameters
upThe button when it is not pressed
downThe button when it is pressed
Returns
a newly allocated button with the given nodes

◆ allocWithData()

static std::shared_ptr<SceneNode> cugl::scene2::Button::allocWithData ( const Scene2Loader loader,
const std::shared_ptr< JsonValue > &  data 
)
inlinestatic

Returns a newly allocated 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:

 "up":       A string referencing the name of a child node OR
             a 4-element integer array with values from 0..255
 "down":     A string referencing the name of a child node OR
             a 4-element integer array with values from 0..255
 "pushable": An even array of polygon vertices (numbers)

The attribute 'up' is REQUIRED. All other attributes are optional.

Parameters
loaderThe scene loader passing this JSON file
dataThe JSON object specifying the node
Returns
a newly allocated node with the given JSON specificaton.

◆ clearListeners()

void cugl::scene2::Button::clearListeners ( )

Clears all listeners for this button.

These listeners are invoked when the button state changes (up or down). This method does not require you to remember the keys assigned to the individual listeners.

Returns
true if the listener was succesfully removed

◆ containsScreen() [1/2]

bool cugl::scene2::Button::containsScreen ( const Vec2  point)

Returns true if this button contains the given screen point

This method is used to manually check for mouse presses/touches. It converts a point in screen coordinates to the node coordinates and checks if it is in the bounds of the button.

Parameters
pointThe point in screen coordinates
Returns
true if this button contains the given screen point

◆ containsScreen() [2/2]

bool cugl::scene2::Button::containsScreen ( float  x,
float  y 
)
inline

Returns true if this button contains the given screen point

This method is used to manually check for mouse presses/touches. It converts a point in screen coordinates to the node coordinates and checks if it is in the bounds of the button.

Parameters
xThe x-value in screen coordinates
yThe y-value in screen coordinates
Returns
true if this button contains the given screen point

◆ deactivate()

bool cugl::scene2::Button::deactivate ( )

Deactivates this button, ignoring future mouse/touch events.

This method removes its internal listener from either the Mouse or Touchscreen inputs to monitor when the button is pressed and/or released. The input affected is the one that received the listener upon activation.

When deactivated, the button will no longer change its state on its own. However, the user can still change the state manually with the setDown(bool) method. In addition, any Listener attached will still respond to manual state changes.

Returns
true if the button was successfully deactivated

◆ dispose()

virtual void cugl::scene2::Button::dispose ( )
overridevirtual

Disposes all of the resources used by this node.

A disposed button 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 button that is still currently inside of a scene graph.

Reimplemented from cugl::scene2::SceneNode.

◆ doLayout()

virtual void cugl::scene2::Button::doLayout ( )
overridevirtual

Arranges the child of this node using the layout manager.

This process occurs recursively and top-down. A layout manager may end up resizing the children. That is why the parent must finish its layout before we can apply a layout manager to the children.

Reimplemented from cugl::scene2::SceneNode.

◆ getListener()

const Listener cugl::scene2::Button::getListener ( Uint32  key) const

Returns the listener for the given key

This listener is invoked when the button state changes (up or down).

If there is no listener for the given key, it returns nullptr.

Parameters
keyThe identifier for the listener
Returns
the listener for the given key

◆ getListeners()

const std::vector<Listener> cugl::scene2::Button::getListeners ( ) const

Returns all listeners for this button

These listeners are invoked when the button state changes (up or down).

Returns
the listeners for this button

◆ getPushable()

const Path2& cugl::scene2::Button::getPushable ( ) const
inline

Returns the region responding to mouse clicks.

The pushable region is the area of this node that responds to mouse clicks. By allowing it to be an arbitrary path, we are capable of defining buttons with complex shapes. The path should be specified counter-clockwise.

Returns
the region responding to mouse clicks.

◆ hasListener()

bool cugl::scene2::Button::hasListener ( ) const
inline

Returns true if this button has a listener

This listener is invoked when the button state changes (up or down).

Returns
true if this button has a listener

◆ init() [1/4]

virtual bool cugl::scene2::Button::init ( )
inlineoverridevirtual

Deactivates the default initializer.

This initializer may not be used for a button. A button must have a child node for the up state at the very minimum.

Returns
false

Reimplemented from cugl::scene2::SceneNode.

◆ init() [2/4]

bool cugl::scene2::Button::init ( const std::shared_ptr< SceneNode > &  up)
inline

Initializes a button with the given up node.

The button will look exactly like the given node when it is not pressed. When pressed, it will darken the up node a bit.

Parameters
upThe button when it is not pressed
Returns
true if the button is initialized properly, false otherwise.

◆ init() [3/4]

bool cugl::scene2::Button::init ( const std::shared_ptr< SceneNode > &  up,
Color4  down 
)

Initializes a button with the given node and color

The button will look exactly like the given node when it is not pressed. When pressed, it will tint the up node by the specified color.

Parameters
upThe button when it is not pressed
downThe button tint when it is pressed
Returns
true if the button is initialized properly, false otherwise.

◆ init() [4/4]

bool cugl::scene2::Button::init ( const std::shared_ptr< SceneNode > &  up,
const std::shared_ptr< SceneNode > &  down 
)

Initializes a button with the given nodes

The button will look exactly like the up node when it is not pressed. It will look like the down node when it is pressed. The size of this button is the size of the larger of the two nodes.

Parameters
upThe button when it is not pressed
downThe button when it is pressed
Returns
true if the button is initialized properly, false otherwise.

◆ initWithData()

bool cugl::scene2::Button::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:

 "up":       A string referencing the name of a child node OR
             a 4-element integer array with values from 0..255
 "down":     A string referencing the name of a child node OR
             a 4-element integer array with values from 0..255
 "pushable": An even array of polygon vertices (numbers)

The attribute 'up' is REQUIRED. All other attributes are optional.

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.

◆ isActive()

bool cugl::scene2::Button::isActive ( ) const
inline

Returns true if this button has been activated.

Returns
true if this button has been activated.

◆ isDown()

bool cugl::scene2::Button::isDown ( ) const
inline

Return true if this button is currently down.

Buttons only have two states: up and down. The default state is up.

Changing this value will change how the button is displayed on the screen. It will also invoke the Listener if one is currently attached.

Returns
true if this button is currently down.

◆ isToggle()

bool cugl::scene2::Button::isToggle ( ) const
inline

Returns true if this is a toggle button

A normal button is down only when it is pressed. A toggle button changes state when pressed, and retains that state until the next press.

This attribute is only relevant for activated buttons

Returns
true if this is a toggle button

◆ removeListener()

bool cugl::scene2::Button::removeListener ( Uint32  key)

Removes a listener from this button.

This listener is invoked when the button state changes (up or down).

Listeners must be identified by the key returned by the addListener method. If this button does not have a listener for the given key, this method will fail.

Parameters
keyThe key of the listener to remove
Returns
true if the listener was succesfully removed

◆ setColor()

virtual void cugl::scene2::Button::setColor ( Color4  color)
overridevirtual

Sets the color tinting this node.

This color will be multiplied with the parent (this node on top) if hasRelativeColor() is true.

The default color is white, which means that all children have their natural color.

Parameters
colorthe color tinting this node.

Reimplemented from cugl::scene2::SceneNode.

◆ setDown()

void cugl::scene2::Button::setDown ( bool  down)

Sets whether this button is currently down.

Buttons only have two states: up and down. The default state is up.

Changing this value will change how the button is displayed on the screen. It will also invoke the Listener if one is currently attached.

Parameters
downWhether this button is currently down.

◆ setPushable() [1/2]

void cugl::scene2::Button::setPushable ( const Path2 bounds)

Sets the region responding to mouse clicks.

The pushable region is the area of this node that responds to mouse clicks. By allowing it to be an arbitrary path, we are capable of defining buttons with complex shapes. The path should be specified counter-clockwise.

Parameters
boundsThe region responding to mouse clicks.

◆ setPushable() [2/2]

void cugl::scene2::Button::setPushable ( const std::vector< Vec2 > &  vertices)

Sets the region responding to mouse clicks.

The pushable region is the area of this node that responds to mouse clicks. By allowing it to be an arbitrary path, we are capable of defining buttons with complex shapes. The path should be specified counter-clockwise.

Parameters
verticesThe region responding to mouse clicks.

◆ setToggle()

void cugl::scene2::Button::setToggle ( bool  value)
inline

Sets whether this is a toggle button

A normal button is down only when it is pressed. A toggle button changes state when pressed, and retains that state until the next press.

This attribute is only relevant for activated buttons

Parameters
valuewhether this is a toggle button

Member Data Documentation

◆ _active

bool cugl::scene2::Button::_active
protected

Whether the button is actively checking for state changes

◆ _bounds

Path2 cugl::scene2::Button::_bounds
protected

The button bounds (for rounder buttons)

◆ _down

bool cugl::scene2::Button::_down
protected

Whether or not the button is currently down

◆ _downchild

std::string cugl::scene2::Button::_downchild
protected

Key for the down (clicked) child

◆ _downcolor

Color4 cugl::scene2::Button::_downcolor
protected

The button color when the button is down

◆ _downform

std::shared_ptr<JsonValue> cugl::scene2::Button::_downform
protected

Layout information for the down button

◆ _downnode

std::shared_ptr<SceneNode> cugl::scene2::Button::_downnode
protected

The node representing the button when it is down (may be null)

◆ _inputkey

Uint32 cugl::scene2::Button::_inputkey
protected

The listener key when the button is checking for state changes

◆ _listeners

std::unordered_map<Uint32,Listener> cugl::scene2::Button::_listeners
protected

The listener callbacks for state changes

◆ _mouse

bool cugl::scene2::Button::_mouse
protected

Whether we are using the mouse (as opposed to the touch screen)

◆ _nextKey

Uint32 cugl::scene2::Button::_nextKey
protected

The next available key for a listener

◆ _toggle

bool cugl::scene2::Button::_toggle
protected

Whether or not the button is a toggle switch

◆ _upchild

std::string cugl::scene2::Button::_upchild
protected

Key for the up (unclicked) child

◆ _upcolor

Color4 cugl::scene2::Button::_upcolor
protected

The button color when the button is up

◆ _upform

std::shared_ptr<JsonValue> cugl::scene2::Button::_upform
protected

Layout information for the up button

◆ _upnode

std::shared_ptr<SceneNode> cugl::scene2::Button::_upnode
protected

The node representing the button when it is up (cannot be null)


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