Base class for all ui widgets. More...

#include <Widget.h>

Inherits ProtectedNode, and LayoutParameterProtocol.

Inherited by AbstractCheckButton, Button, EditBox, ImageView, InputField, LayoutGroup, LoadingBar, RadioButtonGroup, RichText, Slider, TabView, Text, TextAtlas, and TextBMFont.

Public Types
enum class	FocusDirection
	Widget focus direction.
enum class	PositionType
	Widget position type for layout.
enum class	SizeType
	Widget size type for layout.
enum class	PointerPhase
	Pointer event phase.
enum class	TextureResType
	Texture resource type. More...
enum class	BrightStyle
	Widget bright style.
using	PointerEventHandler = std::function<void(Object*, PointerPhase)>
	Widget pointer event callback.
using	WidgetClickCallback = std::function<void(Object*)>
	Widget click event callback.

Public Member Functions
	Widget ()
	Default constructor @lua new.
virtual	~Widget ()
	Default destructor @lua NA.
virtual void	setEnabled (bool enabled)
	Sets whether the widget is enabled.
bool	isEnabled () const
	Determines if the widget is enabled or not.
void	setBright (bool bright)
	Sets whether the widget is bright.
bool	isBright () const
	Determines if the widget is bright.
virtual void	setPointerEnabled (bool enabled)
	Sets whether the widget is touch enabled.
void	setBrightStyle (BrightStyle style)
	To set the bright style of widget.
BrightStyle	getBrightStyle () const
	Get the bright style of widget.
bool	isPointerEnabled () const
	Determines if the widget is pointer enabled.
bool	isHighlighted () const
	Determines if the widget is highlighted.
void	setHighlighted (bool highlight)
	Sets whether the widget is highlighted.
float	getLeftBoundary () const
	Gets the left boundary position of this widget in parent's coordination system.
float	getBottomBoundary () const
	Gets the bottom boundary position of this widget in parent's coordination system.
float	getRightBoundary () const
	Gets the right boundary position of this widget in parent's coordination system.
float	getTopBoundary () const
	Gets the top boundary position of this widget in parent's coordination system.
void	visit (const ax::SceneRenderState &state, const Mat4 &parentTransform, uint32_t parentFlags) override
	Visits this node's children and draw them recursively.
void	addPointerEventListener (const PointerEventHandler &handler)
	Set a callback to pointer event listener.
void	addHoverEventListener (const HoverEventHandler &handler)
	Set a callback for pointer hover events.
void	addClickEventListener (const ClickEventHandler &handler)
	Set a click event handler to the widget.
virtual void	addCCSEventListener (const WidgetEventCallback &callback)
	Set a custom event callback for Cocos Studio compatibility.
void	setPosition (const Vec2 &pos) override
	Changes the position (x,y) of the widget in OpenGL coordinates.
void	setPositionNormalized (const Vec2 &position) override
	Sets the position (x,y) using values between 0 and 1.
void	setPositionPercent (const Vec2 &percent)
	Set the percent(x,y) of the widget in OpenGL coordinates.
const Vec2 &	getPositionPercent ()
	Gets the percent (x,y) of the widget in OpenGL coordinates.
void	setPositionType (PositionType type)
	Changes the position type of the widget.
PositionType	getPositionType () const
	Gets the position type of the widget.
virtual void	setFlippedX (bool flippedX)
	Sets whether the widget should be flipped horizontally or not.
virtual bool	isFlippedX () const
	Returns the flag which indicates whether the widget is flipped horizontally or not.
virtual void	setFlippedY (bool flippedY)
	Sets whether the widget should be flipped vertically or not.
virtual bool	isFlippedY () const
	Return the flag which indicates whether the widget is flipped vertically or not.
void	setScaleX (float scaleX) override
	Sets the scale (x) of the node.
void	setScaleY (float scaleY) override
	Sets the scale (y) of the node.
void	setScale (float scale) override
	Sets the scale (x,y,z) of the node.
void	setScale (float scalex, float scaley) override
	Sets the scale (x,y) of the node.
float	getScaleX () const override
	Returns the scale factor on X axis of this node.
float	getScaleY () const override
	Returns the scale factor on Y axis of this node.
float	getScale () const override
	Gets the scale factor of the node, when X and Y have the same scale factor.
bool	isClippingParentContainsPoint (PointerEvent *event)
	Checks a point if in parent's area.
const Vec2 &	getTouchBeganPosition () const
	Gets the touch began point of widget when widget is selected.
void	setContentSize (const Vec2 &contentSize) override
	Changes the size that is widget's size.
virtual void	setSizePercent (const Vec2 &percent)
	Changes the percent that is widget's percent size.
void	setSizeType (SizeType type)
	Changes the size type of widget.
SizeType	getSizeType () const
	Gets the size type of widget.
const Vec2 &	getCustomSize () const
	Get the user defined widget size.
virtual const Vec2 &	getLayoutSize ()
	Get the content size of widget.
const Vec2 &	getSizePercent ()
	Get size percent of widget.
void	setLayoutParameter (LayoutParameter *parameter)
	Sets a LayoutParameter to widget.
LayoutParameter *	getLayoutParameter () const override
	Gets LayoutParameter of widget.
virtual Node *	getRenderNode ()
	Gets the internal render node of widget.
Vec2	getPreferredSize () const
	Gets the preferred size of the internal render node.
std::string	getDescription () const override
	Returns the string representation of widget class name.
Widget *	clone ()
	Create a new widget copy of the original one.
void	onEnter () override
	@lua NA
void	onExit () override
	@lua NA
void	updateSizeAndPosition ()
	Update all children's contents size and position recursively.
void	updateSizeAndPosition (const Vec2 &parentSize)
	Update all children's contents size and position recursively.
void	setActionTag (int tag)
	Set the tag of action.
int	getActionTag () const
	Get the action tag.
void	setPropagatePointerEvents (bool isPropagate)
	Allow widget touch events to propagate to its parents.
bool	isPropagatePointerEvents () const
	Return whether the widget is propagate touch events to its parents or not.
bool	isFocused () const
	Query whether widget is focused or not.
void	setFocused (bool focus)
	Toggle widget focus status.
bool	isFocusEnabled () const
	Query widget's focus enable state.
void	setFocusEnabled (bool enable)
	Allow widget to accept focus.
virtual Widget *	findNextFocusedWidget (FocusDirection direction, Widget *current)
	When a widget is in a layout, you could call this method to get the next focused widget within a specified direction.
void	requestFocus ()
	when a widget calls this method, it will get focus immediately.
virtual void	setAutoSize (bool enable)
	Toggle auto size mode.
bool	isAutoSize () const
	Query whether auto size mode is enabled.
void	setCallbackName (std::string_view callbackName)
	Set callback name.
std::string_view	getCallbackName () const
	Query callback name.
void	setCallbackType (std::string_view callbackType)
	Set callback type.
std::string_view	getCallbackType () const
	Query callback type.
void	setLayoutComponentEnabled (bool enable)
	Toggle layout component enable.
bool	isLayoutComponentEnabled () const
	Query whether layout component is enabled or not.
void	propagatePointerEvent (Widget sender, PointerEvent event)
	Propagate touch events to its parents.
void	onFocusChange (Widget widgetLostFocus, Widget widgetGetFocus)
	This method is called when a focus change event happens.
void	dispatchFocusEvent (Widget widgetLoseFocus, Widget widgetGetFocus)
	Dispatch a FocusEvent through a EventDispatcher.
virtual void	setScaleZ (float scaleZ)
	Changes the scale factor on Z axis of this node.
virtual float	getScaleZ () const
	Returns the scale factor on Z axis of this node.
Public Member Functions inherited from ProtectedNode
void	cleanup () override
	Stops all running actions and schedulers.
void	onEnterTransitionDidFinish () override
	Event callback that is invoked when the Node enters in the 'stage'.
void	onExitTransitionDidStart () override
	Event callback that is called every time the Node leaves the 'stage'.
void	updateDisplayedOpacity (uint8_t parentOpacity) override
	Update the displayed opacity of node with it's parent opacity;.
void	updateDisplayedColor (const Color32 &parentColor) override
	Update node's displayed color with its parent color.
void	setCameraMask (unsigned short mask, bool applyChildren=true) override
	Modify the camera mask for current node.
void	setGlobalZOrder (float globalZOrder) override
	Defines the order in which the nodes are renderer.
virtual void	addProtectedChild (Node *child)
	Adds a child to the container with z-order as 0.
virtual void	addProtectedChild (Node *child, int localZOrder)
	Adds a child to the container with a local z-order.
virtual void	addProtectedChild (Node *child, int localZOrder, int tag)
	Adds a child to the container with z order and tag.
virtual Node *	getProtectedChildByTag (int tag)
	Gets a child from the container with its tag.
virtual Node *	getProtectedChildByName (std::string_view name)
	Gets a child from the container with its name.
virtual void	removeProtectedChild (Node *child, bool cleanup=true)
	Removes a child from the container.
virtual void	removeProtectedChildByTag (int tag, bool cleanup=true)
	Removes a child from the container by tag value.
virtual void	removeAllProtectedChildren ()
	Removes all children from the container with a cleanup.
virtual void	removeAllProtectedChildrenWithCleanup (bool cleanup)
	Removes all children from the container, and do a cleanup to all running actions depending on the cleanup parameter.
virtual void	reorderProtectedChild (Node *child, int localZOrder)
	Reorders a child according to a new z value.
virtual void	sortAllProtectedChildren ()
	Sorts the children array once before drawing, instead of every time when a child is added or reordered.
Public Member Functions inherited from Node
virtual bool	isRunning () const
	Returns whether or not the node is "running".
virtual void	draw (const SceneRenderState &state, const Mat4 &transform, uint32_t flags)
	Override this method to draw your own node.
virtual Scene *	getScene () const
	Returns the Scene that contains the Node.
virtual Rect	getBoundingBox () const
	Returns an AABB (axis-aligned bounding-box) in its parent's coordinate system.
virtual Rect	getWorldBoundingBox () const
	Returns an AABB (axis-aligned bounding-box) in its world's coordinate system.
virtual void	setEventDispatcher (EventDispatcher *dispatcher)
	Set event dispatcher for scene.
virtual EventDispatcher *	getEventDispatcher () const
	Get the event dispatcher of scene.
virtual uint8_t	getOpacity () const
	Return the node's opacity.
virtual uint8_t	getDisplayedOpacity () const
	Return the node's display opacity.
virtual void	setOpacity (uint8_t opacity)
	Change node opacity.
bool	isCascadeOpacityEnabled () const
	Whether cascadeOpacity is enabled or not.
virtual void	setCascadeOpacityEnabled (bool cascadeOpacityEnabled)
	Change node's cascadeOpacity property.
virtual const Color32 &	getColor () const
	Query node's color value.
virtual const Color32 &	getDisplayedColor () const
	Query node's displayed color.
virtual void	setColor (const Color32 &color)
	Change the color of node.
bool	isCascadeColorEnabled () const
	Query whether cascadeColor is enabled or not.
virtual void	setCascadeColorEnabled (bool cascadeColorEnabled)
	Sets whether to enable color cascade.
virtual void	setOpacityModifyRGB (bool value)
	If you want the opacity affect the color property, then set to true.
virtual bool	isOpacityModifyRGB () const
	If node opacity will modify the RGB color value, then you should override this method and return true.
void	setOnEnterCallback (const std::function< void()> &callback)
	Set the callback of event onEnter.
const std::function< void()> &	getOnEnterCallback () const
	Get the callback of event onEnter.
void	setOnExitCallback (const std::function< void()> &callback)
	Set the callback of event onExit.
const std::function< void()> &	getOnExitCallback () const
	Get the callback of event onExit.
void	setOnEnterTransitionDidFinishCallback (const std::function< void()> &callback)
	Set the callback of event EnterTransitionDidFinish.
const std::function< void()> &	getOnEnterTransitionDidFinishCallback () const
	Get the callback of event EnterTransitionDidFinish.
void	setOnExitTransitionDidStartCallback (const std::function< void()> &callback)
	Set the callback of event ExitTransitionDidStart.
const std::function< void()> &	getOnExitTransitionDidStartCallback () const
	Get the callback of event ExitTransitionDidStart.
void	setOnCleanupCallback (const std::function< void()> &callback)
	Set the callback invoked by cleanup before actions and scheduled callbacks are released.
unsigned short	getCameraMask () const
	get & set camera mask, the node is visible by the camera whose camera flag & node's camera mask is true
void	applyMaskOnEnter (bool applyChildren)
	Should addChild() make the child follow it's parent's mask?
virtual bool	setProgramState (rhi::ProgramState *programState, bool ownPS=false)
	Sets ProgramState with retain.
rhi::ProgramState *	setProgramStateByProgramId (uint64_t progId)
	Sets ProgramState by programId.
void	resetChild (Node *child, bool cleanup)
	Performs pointer hit testing for this node under the specified camera.
virtual void	setLocalZOrder (int localZOrder)
	LocalZOrder is the 'key' used to sort the node relative to its siblings.
void	updateOrderOfArrival ()
	!
virtual int	getLocalZOrder () const
	Gets the local Z order of this node.
virtual float	getGlobalZOrder () const
	Returns the Node's Global Z Order.
virtual const Vec2 &	getPosition () const
	Gets the position (x,y) of the node in its parent's coordinate system.
virtual const Vec2 &	getPositionNormalized () const
	Returns the normalized position.
virtual void	setPosition (float x, float y)
	Sets the position (x,y) of the node in its parent's coordinate system.
virtual void	getPosition (float x, float y) const
	Gets position in a more efficient way, returns two number instead of a Vec2 object.
virtual void	setPositionX (float x)
	Gets/Sets x or y coordinate individually for position.
virtual float	getPositionX () const
	Gets the x coordinate of the node in its parent's coordinate system.
virtual void	setPositionY (float y)
	Sets the y coordinate of the node in its parent's coordinate system.
virtual float	getPositionY () const
	Gets the y coordinate of the node in its parent's coordinate system.
virtual void	setPosition3D (const Vec3 &position)
	Sets the position (X, Y, and Z) in its parent's coordinate system.
virtual Vec3	getPosition3D () const
	Returns the position (X,Y,Z) in its parent's coordinate system.
virtual void	setPositionZ (float positionZ)
	Sets the 'z' coordinate in the position.
virtual float	getPositionZ () const
	Gets position Z coordinate of this node.
virtual void	setSkewX (float skewX)
	Changes the X skew angle of the node in degrees.
virtual float	getSkewX () const
	Returns the X skew angle of the node in degrees.
virtual void	setSkewY (float skewY)
	Changes the Y skew angle of the node in degrees.
virtual float	getSkewY () const
	Returns the Y skew angle of the node in degrees.
virtual void	setAnchorPoint (const Vec2 &anchorPoint)
	Sets the anchor point in percent.
virtual const Vec2 &	getAnchorPoint () const
	Returns the anchor point in percent.
virtual const Vec2 &	getAnchorPointInPoints () const
	Returns the anchorPoint in absolute pixels.
virtual const Vec2 &	getContentSize () const
	Returns the untransformed size of the node.
virtual void	setVisible (bool visible)
	Sets whether the node is visible.
virtual bool	isVisible () const
	Determines if the node is visible.
virtual void	setRotation (float rotation)
	Sets the rotation (angle) of the node in degrees.
virtual float	getRotation () const
	Returns the rotation of the node in degrees.
virtual void	setRotation3D (const Vec3 &rotation)
	Sets the rotation (X,Y,Z) in degrees.
virtual Vec3	getRotation3D () const
	Returns the rotation (X,Y,Z) in degrees.
virtual void	setRotationQuat (const Quat &quat)
	Set rotation by quaternion.
virtual Quat	getRotationQuat () const
	Return the rotation by quaternion, Note that when _rotationZ_X == _rotationZ_Y, the returned quaternion equals to RotationZ_X * RotationY * RotationX, it equals to RotationY * RotationX otherwise.
virtual void	setRotationSkewX (float rotationX)
	Sets the X rotation (angle) of the node in degrees which performs a horizontal rotational skew.
virtual float	getRotationSkewX () const
	Gets the X rotation (angle) of the node in degrees which performs a horizontal rotation skew.
virtual void	setRotationSkewY (float rotationY)
	Sets the Y rotation (angle) of the node in degrees which performs a vertical rotational skew.
virtual float	getRotationSkewY () const
	Gets the Y rotation (angle) of the node in degrees which performs a vertical rotational skew.
virtual void	setIgnoreAnchorPointForPosition (bool ignore)
	Sets whether the anchor point will be (0,0) when you position this node.
virtual bool	isIgnoreAnchorPointForPosition () const
	Gets whether the anchor point will be (0,0) when you position this node.
virtual int	getTag () const
	Returns a tag that is used to identify the node easily.
virtual void	setTag (int tag)
	Changes the tag that is used to identify the node easily.
virtual std::string_view	getName () const
	Returns a string that is used to identify the node.
virtual void	setName (std::string_view name)
	Changes the name that is used to identify the node easily.
virtual void *	getUserData ()
	Returns a custom user data pointer.
virtual const void *	getUserData () const
	@lua NA
virtual void	setUserData (void *userData)
	Sets a custom user data pointer.
virtual Object *	getUserObject ()
	Returns a user assigned Object.
virtual const Object *	getUserObject () const
	@lua NA
virtual void	setUserObject (Object *userObject)
	Returns a user assigned Object.
virtual void	setActionManager (ActionManager *actionManager)
	Sets the ActionManager object that is used by all actions.
virtual ActionManager *	getActionManager ()
	Gets the ActionManager object that is used by all actions.
virtual Action *	runAction (Action *action)
	Executes an action, and returns the action that is executed.
void	stopAllActions ()
	Stops and removes all actions from the running action list .
void	stopAction (Action *action)
	Stops and removes an action from the running action list.
void	stopActionByTag (int tag)
	Removes an action from the running action list by its tag.
void	stopAllActionsByTag (int tag)
	Removes all actions from the running action list by its tag.
void	stopActionsByFlags (unsigned int flags)
	Removes all actions from the running action list by its flags.
Action *	getActionByTag (int tag)
	Gets an action from the running action list by its tag.
ssize_t	getNumberOfRunningActions () const
	Returns the numbers of actions that are running plus the ones that are schedule to run (actions in actionsToAdd and actions arrays).
ssize_t	getNumberOfRunningActionsByTag (int tag) const
	Returns the numbers of actions that are running plus the ones that are schedule to run (actions in actionsToAdd and actions arrays) with a specific tag.
virtual void	setScheduler (Scheduler *scheduler)
	Sets a Scheduler object that is used to schedule all "updates" and timers.
virtual Scheduler *	getScheduler ()
	Gets a Scheduler object.
bool	isScheduled (SEL_SCHEDULE selector) const
	Checks whether a selector is scheduled.
bool	isScheduled (std::string_view key) const
	Checks whether a lambda function is scheduled.
void	scheduleUpdate ()
	Schedules the "update" method.
void	scheduleUpdateWithPriority (int priority)
	Schedules the "update" method with a custom priority.
void	schedule (SEL_SCHEDULE selector, float interval, unsigned int repeat, float delay)
	Schedules a custom selector.
void	schedule (SEL_SCHEDULE selector, float interval)
	Schedules a custom selector with an interval time in seconds.
void	scheduleOnce (SEL_SCHEDULE selector, float delay)
	Schedules a selector that runs only once, with a delay of 0 or larger.
void	scheduleOnce (const std::function< void(float)> &callback, float delay, std::string_view key)
	Schedules a lambda function that runs only once, with a delay of 0 or larger.
void	schedule (SEL_SCHEDULE selector)
	Schedules a custom selector, the scheduled selector will be ticked every frame.
void	schedule (const std::function< void(float)> &callback, std::string_view key)
	Schedules a lambda function.
void	schedule (const std::function< void(float)> &callback, float interval, std::string_view key)
	Schedules a lambda function.
void	schedule (const std::function< void(float)> &callback, float interval, unsigned int repeat, float delay, std::string_view key)
	Schedules a lambda function.
void	unschedule (SEL_SCHEDULE selector)
	Unschedules a custom selector.
void	unschedule (std::string_view key)
	Unschedules a lambda function.
void	unscheduleAllCallbacks ()
	Unschedule all scheduled selectors and lambda functions: custom selectors, and the 'update' selector and lambda functions.
virtual void	resume ()
	Resumes all scheduled selectors, actions and event listeners.
virtual void	pause ()
	Pauses all scheduled selectors, actions and event listeners.
virtual void	update (float delta)
	Update method will be called automatically every frame if "scheduleUpdate" is called, and the node is "live".
virtual void	updateTransform ()
	Calls children's updateTransform() method recursively.
virtual const Mat4 &	getNodeToParentTransform () const
	Returns the matrix that transform the node's (local) space coordinates into the parent's space coordinates.
virtual Mat4	getNodeToParentTransform (Node *ancestor) const
	Returns the matrix that transform the node's (local) space coordinates into the parent's space coordinates.
virtual AffineTransform	getNodeToParentAffineTransform (Node *ancestor) const
	Returns the affine transform matrix that transform the node's (local) space coordinates into the parent's space coordinates.
virtual void	setNodeToParentTransform (const Mat4 &transform)
	Sets the transformation matrix manually.
virtual const Mat4 &	getParentToNodeTransform () const
	Returns the matrix that transform parent's space coordinates to the node's (local) space coordinates.
virtual Mat4	getNodeToWorldTransform () const
	Returns the world affine transform matrix.
virtual Mat4	getWorldToNodeTransform () const
	Returns the inverse world affine transform matrix.
Vec2	convertToNodeSpace (const Vec2 &worldPoint) const
	Converts a Vec2 to node (local) space coordinates.
Vec2	convertToWorldSpace (const Vec2 &nodePoint) const
	Converts a Vec2 to world space coordinates.
Vec2	convertToNodeSpaceAR (const Vec2 &worldPoint) const
	Converts a Vec2 to node (local) space coordinates.
Vec2	convertToWorldSpaceAR (const Vec2 &nodePoint) const
	Converts a local Vec2 to world space coordinates.The result is in Points.
Vec2	convertPointerToNodeSpace (PointerEvent *event) const
	convenience methods which take a Touch instead of Vec2.
Vec2	convertPointerToNodeSpaceAR (PointerEvent *event) const
	converts a Touch (world coordinates) into a local coordinate.
Vec2	getWorldPosition () const
	Gets position of node in world space.
void	setWorldPosition (const Vec2 &position)
	Sets position of node in world space.
void	setAdditionalTransform (const Mat4 *additionalTransform)
	Sets an additional transform matrix to the node.
Component *	getComponent (std::string_view name)
	Gets a component by its name.
virtual bool	addComponent (Component *component)
	Adds a component.
virtual bool	removeComponent (std::string_view name)
	Removes a component by its name.
virtual bool	removeComponent (Component *component)
	Removes a component by its pointer.
virtual void	removeAllComponents ()
	Removes all components.
virtual void	addChild (Node *child)
	Adds a child to the container with z-order as 0.
virtual void	addChild (Node *child, int localZOrder)
	Adds a child to the container with a local z-order.
virtual void	addChild (Node *child, int localZOrder, int tag)
	Adds a child to the container with z order and tag.
virtual void	addChild (Node *child, int localZOrder, std::string_view name)
	Adds a child to the container with z order and tag.
virtual Node *	getChildByTag (int tag) const
	Gets a child from the container with its tag.
template<typename T>
T	getChildByTag (int tag) const
	Gets a child from the container with its tag that can be cast to Type T.
virtual Node *	getChildByName (std::string_view name) const
	Gets a child from the container with its name.
template<typename T>
T	getChildByName (std::string_view name) const
	Gets a child from the container with its name that can be cast to Type T.
virtual void	enumerateChildren (std::string_view name, std::function< bool(Node *node)> callback) const
	Search the children of the receiving node to perform processing for nodes which share a name.
virtual Vector< Node * > &	getChildren ()
	Returns the array of the node's children.
virtual ssize_t	getChildrenCount () const
	Returns the amount of children.
virtual void	setParent (Node *parent)
	Sets the parent node.
virtual Node *	getParent ()
	Returns a pointer to the parent node.
virtual void	removeFromParent ()
	Removes this node itself from its parent node with a cleanup.
virtual void	removeFromParentAndCleanup (bool cleanup)
	Removes this node itself from its parent node.
virtual void	removeChild (Node *child, bool cleanup=true)
	Removes a child from the container.
virtual void	removeChildByTag (int tag, bool cleanup=true)
	Removes a child from the container by tag value.
virtual void	removeChildByName (std::string_view name, bool cleanup=true)
	Removes a child from the container by tag value.
virtual void	removeAllChildren ()
	Removes all children from the container with a cleanup.
virtual void	removeAllChildrenWithCleanup (bool cleanup)
	Removes all children from the container, and do a cleanup to all running actions depending on the cleanup parameter.
virtual void	reorderChild (Node *child, int localZOrder)
	Reorders a child according to a new z value.
virtual void	sortAllChildren ()
	Sorts the children array once before drawing, instead of every time when a child is added or reordered.
Public Member Functions inherited from Object
void	retain ()
	Retains the ownership.
void	release ()
	Releases the ownership immediately.
Object *	autorelease ()
	Releases the ownership sometime soon automatically.
unsigned int	getReferenceCount () const
	Returns the Object's current reference count.
uint64_t	getObjectID () const noexcept
	Returns the process-local diagnostic identifier assigned at construction.
virtual	~Object ()
	Destructor.
Public Member Functions inherited from LayoutParameterProtocol
virtual	~LayoutParameterProtocol ()
	Default destructor.

Static Public Member Functions
static Widget *	create ()
	Create and return a empty Widget instance pointer.
static Widget *	getCurrentFocusedWidget ()
	Return a current focused widget in your UI scene.
Static Public Member Functions inherited from ProtectedNode
static ProtectedNode *	create ()
	Creates a ProtectedNode with no argument.
static Node *	create ()
	Allocates and initializes a node.
static int	getAttachedNodeCount ()
	Gets count of nodes those are attached to scene graph.
template<typename _T>
static void	sortNodes (ax::Vector< _T * > &nodes)
	Sorts helper function.

Public Attributes
std::function< void(Widget , Widget )>	onFocusChanged
	When a widget lose/get focus, this method will be called.
std::function< Widget *(FocusDirection)>	onNextFocusedWidget
	use this function to manually specify the next focused widget regards to each direction

Additional Inherited Members
Static Public Attributes inherited from Node
static const int	INVALID_TAG = -1
	Default tag used for all the nodes.
Protected Member Functions inherited from Node
void	childrenAlloc ()
	lazy allocs
void	insertChild (Node *child, int z)
	helper that reorder a child
void	detachChild (Node *child, ssize_t index, bool cleanup)
	Removes a child, call child->onExit(), do cleanup, remove it from children array.
Vec2	convertToScreenSpace (const Vec2 &nodePoint) const
	Convert axmol coordinates to UI windows coordinate.
Protected Attributes inherited from Node
float	_rotationX
	rotation on the X-axis
float	_rotationY
	rotation on the Y-axis
float	_rotationZ_X
	rotation angle on Z-axis, component X
float	_rotationZ_Y
	rotation angle on Z-axis, component Y
rhi::VertexLayout *	_vertexLayout = nullptr
	rotation using quaternion, if _rotationZ_X == _rotationZ_Y, _rotationQuat = RotationZ_X * RotationY * RotationX, else _rotationQuat = RotationY * RotationX
float	_scaleX
	scaling factor on x-axis
float	_scaleY
	scaling factor on y-axis
float	_scaleZ
	scaling factor on z-axis
Vec2	_position
	position of the node
float	_positionZ
	OpenGL real Z position.
float	_skewX
	skew angle on x-axis
float	_skewY
	skew angle on y-axis
Vec2	_anchorPointInPoints
	anchor point in points
Vec2	_anchorPoint
	anchor point normalized (NOT in points)
Vec2	_contentSize
	untransformed size of the node
Mat4	_modelViewTransform
	ModelView transform of the Node.
Mat4	_transform
	transform
Mat4	_inverse
	inverse transform
Mat4 *	_additionalTransform
	two transforms needed by additional transforms
float	_globalZOrder
	Global order used to sort the node.
Vector< Node * >	_children
	array of children nodes
NodeIndexerMap_t *	_childrenIndexer
	The children indexer for fast find child.
Node *	_parent
	weak reference to parent node
int	_tag
	a tag. Can be any number you assigned just to identify this node
std::string	_name
	a string label, an user defined string to identify this node
uint64_t	_hashOfName
	hash value of _name, used for speed in getChildByName
void *	_userData
	A user assigned void pointer, Can be point to any cpp object.
Object *	_userObject
	A user assigned Object.
Scheduler *	_scheduler
	scheduler used to schedule timers and updates
ActionManager *	_actionManager
	a pointer to ActionManager singleton, which is used to handle all the actions
EventDispatcher *	_eventDispatcher
	event dispatcher used to dispatch all kinds of events
bool	_reorderChildDirty
	children order dirty flag
bool	_running
	is running
bool	_visible
	is this node visible
bool	_ignoreAnchorPointForPosition
	true if the Anchor Vec2 will be (0,0) when you position the Node, false otherwise. Used by Layer and Scene.
bool	_isTransitionFinished
	flag to indicate whether the transition was finished
bool	_contentSizeDirty
	whether or not the contentSize is dirty
bool	_transformDirty
	transform dirty flag
bool	_inverseDirty
	inverse transform dirty flag
bool	_additionalTransformDirty
	transform dirty ?
bool	_transformUpdated
	Whether or not the Transform object was updated since the last frame.
ComponentContainer *	_componentContainer
	Dictionary of components.

Detailed Description

Base class for all ui widgets.

This class inherent from ProtectedNode and LayoutParameterProtocol. If you want to implements your own ui widget, you should subclass it.

Member Enumeration Documentation

◆ TextureResType

enum class TextureResType

strong

Texture resource type.

LOCAL: It means the texture is loaded from image.
PLIST: It means the texture is loaded from texture atlas.

Member Function Documentation

◆ setEnabled()

virtual void setEnabled ( bool enabled )

virtual

Sets whether the widget is enabled.

true if the widget is enabled, widget may be touched , false if the widget is disabled, widget cannot be touched.

Note: If you want to change the widget's appearance to disabled state, you should also call setBright(false).

The default value is true, a widget is default to enable touch.

Parameters

enabled Set to true to enable touch, false otherwise.

Reimplemented in InputField.

◆ isEnabled()

bool isEnabled ( ) const

Determines if the widget is enabled or not.

Returns: true if the widget is enabled, false if the widget is disabled.

◆ setBright()

void setBright ( bool bright )

Sets whether the widget is bright.

The default value is true, a widget is default to bright

Parameters

bright true if the widget is bright, false if the widget is dark.

◆ isBright()

bool isBright ( ) const

Determines if the widget is bright.

Returns: true if the widget is bright, false if the widget is dark.

◆ setPointerEnabled()

virtual void setPointerEnabled ( bool enabled )

virtual

Sets whether the widget is touch enabled.

The default value is false, a widget is default to touch disabled.

Parameters

enabled True if the widget is touch enabled, false if the widget is touch disabled.

◆ setBrightStyle()

void setBrightStyle ( BrightStyle style )

To set the bright style of widget.

See also: BrightStyle

Parameters

style BrightStyle::NORMAL means the widget is in normal state, BrightStyle::HIGHLIGHT means the widget is in highlight state.

◆ getBrightStyle()

BrightStyle getBrightStyle ( ) const

inline

Get the bright style of widget.

Returns

◆ isPointerEnabled()

bool isPointerEnabled ( ) const

Determines if the widget is pointer enabled.

Returns: true if the widget is pointer enabled, false if the widget is pointer disabled.

◆ isHighlighted()

bool isHighlighted ( ) const

Determines if the widget is highlighted.

Returns: true if the widget is highlighted, false if the widget is not highlighted.

◆ setHighlighted()

void setHighlighted ( bool highlight )

Sets whether the widget is highlighted.

The default value is false, a widget is default to not highlighted

Parameters

highlight true if the widget is highlighted, false if the widget is not highlighted.

◆ getLeftBoundary()

float getLeftBoundary ( ) const

Gets the left boundary position of this widget in parent's coordination system.

Returns: The left boundary position of this widget.

◆ getBottomBoundary()

float getBottomBoundary ( ) const

Gets the bottom boundary position of this widget in parent's coordination system.

Returns: The bottom boundary position of this widget.

◆ getRightBoundary()

float getRightBoundary ( ) const

Gets the right boundary position of this widget in parent's coordination system.

Returns: The right boundary position of this widget.

◆ getTopBoundary()

float getTopBoundary ( ) const

Gets the top boundary position of this widget in parent's coordination system.

Returns: The top boundary position of this widget.

◆ visit()

void visit	(	const ax::SceneRenderState &	state,
		const Mat4 &	parentTransform,
		uint32_t	parentFlags )

overridevirtual

Visits this node's children and draw them recursively.

Parameters

state	A scene render traversal state.
parentTransform	A transform matrix.
parentFlags	Renderer flag.

Reimplemented from ProtectedNode.

◆ addPointerEventListener()

void addPointerEventListener ( const PointerEventHandler & handler )

inline

Set a callback to pointer event listener.

Parameters

callback The callback in PointerEventHandler.

◆ addClickEventListener()

void addClickEventListener ( const ClickEventHandler & handler )

inline

Set a click event handler to the widget.

Parameters

callback The handler in ClickEventHandler.

◆ addCCSEventListener()

virtual void addCCSEventListener ( const WidgetEventCallback & callback )

virtual

Set a custom event callback for Cocos Studio compatibility.

Parameters

callback The callback in WidgetEventCallback. @lua NA

◆ setPosition()

void setPosition ( const Vec2 & pos )

overridevirtual

Changes the position (x,y) of the widget in OpenGL coordinates.

Usually we use p(x,y) to compose a Vec2 object. The original point (0,0) is at the left-bottom corner of screen.

Parameters

pos	The position (x,y) of the widget in OpenGL coordinates

Reimplemented from Node.

◆ setPositionNormalized()

void setPositionNormalized ( const Vec2 & position )

overridevirtual

Sets the position (x,y) using values between 0 and 1.

Parameters

position The normalized position (x,y) of the node, using value between 0 and 1.

Reimplemented from Node.

◆ setPositionPercent()

void setPositionPercent ( const Vec2 & percent )

Set the percent(x,y) of the widget in OpenGL coordinates.

Parameters

percent The percent (x,y) of the widget in OpenGL coordinates

◆ getPositionPercent()

const Vec2 & getPositionPercent ( )

Gets the percent (x,y) of the widget in OpenGL coordinates.

See also: setPosition(const Vec2&)

Returns: The percent (x,y) of the widget in OpenGL coordinates

◆ setPositionType()

void setPositionType ( PositionType type )

Changes the position type of the widget.

See also: PositionType

Parameters

type	the position type of widget

◆ getPositionType()

PositionType getPositionType ( ) const

Gets the position type of the widget.

See also: PositionType

Returns: type the position type of widget

◆ setFlippedX()

virtual void setFlippedX ( bool flippedX )

virtual

Sets whether the widget should be flipped horizontally or not.

Parameters

flippedX true if the widget should be flipped horizontally, false otherwise.

◆ isFlippedX()

virtual bool isFlippedX ( ) const

inlinevirtual

Returns the flag which indicates whether the widget is flipped horizontally or not.

It not only flips the texture of the widget, but also the texture of the widget's children. Also, flipping relies on widget's anchor point. Internally, it just use setScaleX(-1) to flip the widget.

Returns: true if the widget is flipped horizontally, false otherwise.

◆ setFlippedY()

virtual void setFlippedY ( bool flippedY )

virtual

Sets whether the widget should be flipped vertically or not.

Parameters

flippedY true if the widget should be flipped vertically, false otherwise.

◆ isFlippedY()

virtual bool isFlippedY ( ) const

inlinevirtual

Return the flag which indicates whether the widget is flipped vertically or not.

It not only flips the texture of the widget, but also the texture of the widget's children. Also, flipping relies on widget's anchor point. Internally, it just use setScaleY(-1) to flip the widget.

Returns: true if the widget is flipped vertically, false otherwise.

◆ setScaleX()

void setScaleX ( float scaleX )

overridevirtual

Sets the scale (x) of the node.

It is a scaling factor that multiplies the width of the node and its children.

Parameters

scaleX The scale factor on X axis.

Warning: The physics body doesn't support this.

Reimplemented from Node.

◆ setScaleY()

void setScaleY ( float scaleY )

overridevirtual

Sets the scale (y) of the node.

It is a scaling factor that multiplies the height of the node and its children.

Parameters

scaleY The scale factor on Y axis.

Warning: The physics body doesn't support this.

Reimplemented from Node.

◆ setScale() [1/2]

void setScale ( float scale )

overridevirtual

Sets the scale (x,y,z) of the node.

It is a scaling factor that multiplies the width, height and depth of the node and its children.

Parameters

scale The scale factor for both X and Y axis.

Warning: The physics body doesn't support this.

Reimplemented from Node.

◆ setScale() [2/2]

void setScale	(	float	scaleX,
		float	scaleY )

overridevirtual

Sets the scale (x,y) of the node.

It is a scaling factor that multiplies the width and height of the node and its children.

Parameters

scaleX	The scale factor on X axis.
scaleY	The scale factor on Y axis.

Warning: The physics body doesn't support this.

Reimplemented from Node.

◆ getScaleX()

float getScaleX ( ) const

overridevirtual

Returns the scale factor on X axis of this node.

See also: setScaleX(float)

Returns: The scale factor on X axis.

Reimplemented from Node.

◆ getScaleY()

float getScaleY ( ) const

overridevirtual

Returns the scale factor on Y axis of this node.

See also: setScaleY(float)

Returns: The scale factor on Y axis.

Reimplemented from Node.

◆ getScale()

float getScale ( ) const

overridevirtual

Gets the scale factor of the node, when X and Y have the same scale factor.

Warning: Assert when _scaleX != _scaleY

See also: setScale(float)

Returns: The scale factor of the node.

Reimplemented from Node.

◆ isClippingParentContainsPoint()

bool isClippingParentContainsPoint ( PointerEvent * event )

Checks a point if in parent's area.

Parameters

pt	A point in Vec2.

Returns: true if the point is in parent's area, false otherwise.

◆ getTouchBeganPosition()

const Vec2 & getTouchBeganPosition ( ) const

Gets the touch began point of widget when widget is selected.

Returns: the touch began point.

◆ setContentSize()

void setContentSize ( const Vec2 & contentSize )

overridevirtual

Changes the size that is widget's size.

Parameters

contentSize A content size in Vec2.

Reimplemented from Node.

◆ setSizePercent()

virtual void setSizePercent ( const Vec2 & percent )

virtual

Changes the percent that is widget's percent size.

Parameters

percent that is widget's percent size

◆ setSizeType()

void setSizeType ( SizeType type )

Changes the size type of widget.

See also: SizeType

Parameters

type	that is widget's size type

◆ getSizeType()

SizeType getSizeType ( ) const

Gets the size type of widget.

See also: SizeType

◆ getCustomSize()

const Vec2 & getCustomSize ( ) const

Get the user defined widget size.

Returns: User defined size.

◆ getLayoutSize()

virtual const Vec2 & getLayoutSize ( )

inlinevirtual

Get the content size of widget.

Warning: This API exists mainly for keeping back compatibility.

Returns

◆ getSizePercent()

const Vec2 & getSizePercent ( )

Get size percent of widget.

Returns: Percent size.

◆ setLayoutParameter()

void setLayoutParameter ( LayoutParameter * parameter )

Sets a LayoutParameter to widget.

See also: LayoutParameter

Parameters

parameter LayoutParameter pointer

◆ getLayoutParameter()

LayoutParameter * getLayoutParameter ( ) const

overridevirtual

Gets LayoutParameter of widget.

See also: LayoutParameter

Returns: LayoutParameter

Implements LayoutParameterProtocol.

◆ getRenderNode()

virtual Node * getRenderNode ( )

virtual

Gets the internal render node of widget.

For example, a button's render node is its texture sprite.

Returns: Node pointer.

Reimplemented in AbstractCheckButton, Button, ImageView, InputField, LoadingBar, Slider, Text, TextAtlas, and TextBMFont.

◆ getPreferredSize()

Vec2 getPreferredSize ( ) const

inline

Gets the preferred size of the internal render node.

This is equivalent to getRenderNode()->getContentSize().

Returns: The render node's content size.

◆ getDescription()

std::string getDescription ( ) const

overridevirtual

Returns the string representation of widget class name.

Returns: get the class description.

Reimplemented from Node.

◆ clone()

Widget * clone ( )

Create a new widget copy of the original one.

Returns: A cloned widget copy of original.

◆ updateSizeAndPosition()

void updateSizeAndPosition ( )

Update all children's contents size and position recursively.

See also: updateSizeAndPosition(const Vec2&)

◆ setActionTag()

void setActionTag ( int tag )

Set the tag of action.

Parameters

tag	A integer tag value.

◆ getActionTag()

int getActionTag ( ) const

Get the action tag.

Returns: Action tag.

◆ setPropagatePointerEvents()

void setPropagatePointerEvents ( bool isPropagate )

Allow widget touch events to propagate to its parents.

Set false will disable propagation

Parameters

isPropagate True to allow propagation, false otherwise.

Since: v3.3

◆ isPropagatePointerEvents()

bool isPropagatePointerEvents ( ) const

Return whether the widget is propagate touch events to its parents or not.

Returns: whether touch event propagation is allowed or not.

Since: v3.3

◆ isFocused()

bool isFocused ( ) const

Query whether widget is focused or not.

Returns: whether the widget is focused or not

◆ setFocused()

void setFocused ( bool focus )

Toggle widget focus status.

Parameters

focus pass true to let the widget get focus or pass false to let the widget lose focus

◆ isFocusEnabled()

bool isFocusEnabled ( ) const

Query widget's focus enable state.

Returns: true represent the widget could accept focus, false represent the widget couldn't accept focus

◆ setFocusEnabled()

void setFocusEnabled ( bool enable )

Allow widget to accept focus.

Parameters

enable pass true/false to enable/disable the focus ability of a widget

◆ findNextFocusedWidget()

virtual Widget * findNextFocusedWidget	(	FocusDirection	direction,
		Widget *	current )

virtual

When a widget is in a layout, you could call this method to get the next focused widget within a specified direction.

If the widget is not in a layout, it will return itself

Parameters

direction	the direction to look for the next focused widget in a layout
current	the current focused widget

Returns: the next focused widget in a layout

Reimplemented in LayoutGroup, and ScrollView.

◆ getCurrentFocusedWidget()

Widget * getCurrentFocusedWidget ( )

static

Return a current focused widget in your UI scene.

No matter what widget object you call this method on , it will return you the exact one focused widget.

◆ setAutoSize()

virtual void setAutoSize ( bool enable )

virtual

Toggle auto size mode.

When enabled, the widget will automatically adapt its size to its content (virtual renderer).

Parameters

enable True to enable auto size, false to use custom size.

Reimplemented in Button, ImageView, LoadingBar, RichText, and Slider.

◆ isAutoSize()

bool isAutoSize ( ) const

inline

Query whether auto size mode is enabled.

Returns: true if auto size is enabled, false otherwise.

◆ setCallbackName()

void setCallbackName ( std::string_view callbackName )

inline

Set callback name.

Parameters

callbackName A string representation of callback name.

◆ getCallbackName()

std::string_view getCallbackName ( ) const

inline

Query callback name.

Returns: The callback name.

◆ setCallbackType()

void setCallbackType ( std::string_view callbackType )

inline

Set callback type.

Parameters

callbackType A string representation of callback type.

◆ getCallbackType()

std::string_view getCallbackType ( ) const

inline

Query callback type.

Returns: Callback type string.

◆ setLayoutComponentEnabled()

void setLayoutComponentEnabled ( bool enable )

Toggle layout component enable.

Parameters

enable Layout Component of a widget

◆ isLayoutComponentEnabled()

bool isLayoutComponentEnabled ( ) const

Query whether layout component is enabled or not.

Returns: true represent the widget use Layout Component, false represent the widget couldn't use Layout Component.

◆ onFocusChange()

void onFocusChange	(	Widget *	widgetLostFocus,
		Widget *	widgetGetFocus )

This method is called when a focus change event happens.

Parameters

widgetLostFocus	The widget which lose its focus
widgetGetFocus	The widget which get its focus

◆ dispatchFocusEvent()

void dispatchFocusEvent	(	Widget *	widgetLoseFocus,
		Widget *	widgetGetFocus )

Dispatch a FocusEvent through a EventDispatcher.

Parameters

widgetLoseFocus	The widget which lose its focus
widgetGetFocus	he widget which get its focus

◆ setScaleZ()

virtual void setScaleZ ( float scaleZ )

virtual

Changes the scale factor on Z axis of this node.

The Default value is 1.0 if you haven't changed it before.

Parameters

scaleZ The scale factor on Z axis.

Warning: The physics body doesn't support this.

Reimplemented from Node.

◆ getScaleZ()

virtual float getScaleZ ( ) const

virtual

Returns the scale factor on Z axis of this node.

See also: setScaleZ(float)

Returns: The scale factor on Z axis.

Reimplemented from Node.

Member Data Documentation

◆ onFocusChanged

std::function<void(Widget*, Widget*)> onFocusChanged

When a widget lose/get focus, this method will be called.

Be Caution when you provide your own version, you must call widget->setFocused(true/false) to change the focus state of the current focused widget;

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

Widget.h

Public Types

Public Member Functions

Static Public Member Functions

Public Attributes

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

◆ TextureResType

Member Function Documentation

◆ setEnabled()

◆ isEnabled()

◆ setBright()

◆ isBright()

◆ setPointerEnabled()

◆ setBrightStyle()

◆ getBrightStyle()

◆ isPointerEnabled()

◆ isHighlighted()

◆ setHighlighted()

◆ getLeftBoundary()

◆ getBottomBoundary()

◆ getRightBoundary()

◆ getTopBoundary()

◆ visit()

◆ addPointerEventListener()

◆ addClickEventListener()

◆ addCCSEventListener()

◆ setPosition()

◆ setPositionNormalized()

◆ setPositionPercent()

◆ getPositionPercent()

◆ setPositionType()

◆ getPositionType()

◆ setFlippedX()

◆ isFlippedX()

◆ setFlippedY()

◆ isFlippedY()

◆ setScaleX()

◆ setScaleY()

◆ setScale() [1/2]

◆ setScale() [2/2]

◆ getScaleX()

◆ getScaleY()

◆ getScale()

◆ isClippingParentContainsPoint()

◆ getTouchBeganPosition()

◆ setContentSize()

◆ setSizePercent()

◆ setSizeType()

◆ getSizeType()

◆ getCustomSize()

◆ getLayoutSize()

◆ getSizePercent()

◆ setLayoutParameter()

◆ getLayoutParameter()

◆ getRenderNode()

◆ getPreferredSize()

◆ getDescription()

◆ clone()

◆ updateSizeAndPosition()

◆ setActionTag()

◆ getActionTag()

◆ setPropagatePointerEvents()

◆ isPropagatePointerEvents()

◆ isFocused()

◆ setFocused()

◆ isFocusEnabled()

◆ setFocusEnabled()

◆ findNextFocusedWidget()

◆ getCurrentFocusedWidget()

◆ setAutoSize()

◆ isAutoSize()

◆ setCallbackName()

◆ getCallbackName()

◆ setCallbackType()

◆ getCallbackType()

◆ setLayoutComponentEnabled()

◆ isLayoutComponentEnabled()

◆ onFocusChange()

◆ dispatchFocusEvent()