Class ccui.Widget

Class Summary
Constructor Attributes Constructor Name and Description
 
ccui.Widget()
The base class for ccui controls and layout

Method Summary

Class Detail

ccui.Widget()
The base class for ccui controls and layout

Field Detail

{Number} actionTag
- The action tag of the widget
{Boolean} bright
- Indicate whether the widget is bright
<static> <constant> ccui.Widget.BRIGHT_STYLE_HIGH_LIGHT
Light bright style of ccui.Widget.
<static> <constant> ccui.Widget.BRIGHT_STYLE_NONE
None bright style of ccui.Widget.
<static> <constant> ccui.Widget.BRIGHT_STYLE_NORMAL
Normal bright style of ccui.Widget.
<static> <constant> ccui.Widget.DOWN
The down of Focus direction for ccui.Widget
{Boolean} enabled
- Indicate whether the widget is enabled
{Boolean} focused
- Indicate whether the widget is focused
{Number} heightPercent
- Height in percentage of parent height
<static> <constant> ccui.Widget.LEFT
The left of Focus direction for ccui.Widget
<static> <constant> ccui.Widget.LOCAL_TEXTURE
The image file texture type of ccui.Widget loads.
{String} name
- The name of the 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;

onNextFocusedWidget
use this function to manually specify the next focused widget regards to each direction
<static> <constant> ccui.Widget.PLIST_TEXTURE
The sprite frame texture type of ccui.Widget loads.
<static> <constant> ccui.Widget.POSITION_ABSOLUTE
The absolute of ccui.Widget's position type.
<static> <constant> ccui.Widget.POSITION_PERCENT
The percent of ccui.Widget's position type.
<static> <constant> ccui.Widget.RIGHT
The right of Focus direction for ccui.Widget
<static> <constant> ccui.Widget.SIZE_ABSOLUTE
The absolute of ccui.Widget's size type.
<static> <constant> ccui.Widget.SIZE_PERCENT
The percent of ccui.Widget's size type.
- The size type of the widget
<static> <constant> ccui.Widget.TOUCH_BEGAN
The touch began type of ccui.Widget's touch event
<static> <constant> ccui.Widget.TOUCH_CANCELED
The touch canceled type of ccui.Widget's touch event
<static> <constant> ccui.Widget.TOUCH_ENDED
The touch end type of ccui.Widget's touch event
<static> <constant> ccui.Widget.TOUCH_MOVED
The touch moved type of ccui.Widget's touch event
{Boolean} touchEnabled
- Indicate whether touch events are enabled
<static> <constant> ccui.Widget.TYPE_CONTAINER
The type code of Container for ccui controls.
<static> <constant> ccui.Widget.TYPE_WIDGET
The type code of Widget for ccui controls.
<static> <constant> ccui.Widget.UP
The up of Focus direction for ccui.Widget
{Boolean} updateEnabled
- Indicate whether the update function is scheduled
{ccui.Widget} widgetParent
- <@readonly> The direct parent when it's a widget also, otherwise equals null
- <@readonly> The type of the widget
{Number} widthPercent
- Width in percentage of parent width
{Number} xPercent
- Position x in percentage of width
{Number} yPercent
- Position y in percentage of height

Method Detail

  • addCCSEventListener(callback)
    Set a event handler to the widget in order to use cocostudio editor and framework
    Parameters:
    {function} callback
    Since:
    v3.3
  • addNode(node, zOrder, tag)
    Adds a node for widget (this function is deleted in -x)
    Parameters:
    {cc.Node} node
    {Number} zOrder
    {Number} tag
    Deprecated:
    since v3.0, please use addChild instead.
  • addTouchEventListener(selector, target)
    Sets the touch event target/selector of the ccui.Widget
    Parameters:
    {Function} selector
    {Object} target
  • checkChildInfo(handleState, sender, touchPoint)
    Calls the checkChildInfo of widget's parent, its subclass will override it.
    Parameters:
    {number} handleState
    {ccui.Widget} sender
    {cc.Point} touchPoint
  • {Boolean} clippingParentAreaContainPoint(pt)
    Checks a point if in parent's area.
    Parameters:
    {cc.Point} pt
    Deprecated:
    since v3.0, please use isClippingParentContainsPoint instead.
    Returns:
    {Boolean}
  • {ccui.Widget} clone()
    Clones a new widget.
    Returns:
    {ccui.Widget}
  • <static> {ccui.Widget} ccui.Widget.create()
    allocates and initializes a UIWidget.
    Returns:
    {ccui.Widget}
  • ctor()
    Constructor function, override it to extend the construction behavior, remember to call "this._super()" in the extended "ctor" function.
  • didNotSelectSelf()
    A call back function when widget lost of focus.
  • dispatchFocusEvent(widgetLostFocus, widgetGetFocus)
    Dispatch a EventFocus through a EventDispatcher
    Parameters:
    {ccui.Widget} widgetLostFocus
    {ccui.Widget} widgetGetFocus
  • <static> ccui.Widget.enableDpadNavigation(enable)
    call this method with parameter true to enable the Android Dpad focus navigation feature
    Parameters:
    {Boolean} enable
    set true to enable dpad focus navigation, otherwise disable dpad focus navigation
  • findNextFocusedWidget(direction, current)

    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
  • {number} getBottomBoundary()
    Gets the bottom boundary position of this widget.
    Returns:
    {number}
  • {number} getBottomInParent()
    Gets the bottom boundary position of this widget.
    Deprecated:
    since v3.0, please use getBottomBoundary instead.
    Returns:
    {number}
  • {String|Null} getCallbackName()
    Gets callback name of widget
    Since:
    v3.3
    Returns:
    {String|Null}
  • {String|null} getCallbackType()
    Gets callback type of widget
    Since:
    v3.3
    Returns:
    {String|null}
  • <static> {null|ccui.Widget} ccui.Widget.getCurrentFocusedWidget()
    Gets the focused widget of current stage.
    Returns:
    {null|ccui.Widget}
  • getCurrentFocusedWidget()
    no matter what widget object you call this method on , it will return you the exact one focused widget
  • {cc.Size} getCustomSize()
    Get custom size of ccui.Widget
    Returns:
    {cc.Size}
  • {string} getDescription()
    Returns the "class name" of widget.
    Returns:
    {string}
  • {ccui.LayoutParameter} getLayoutParameter(type)
    Gets layout parameter
    Parameters:
    {ccui.LayoutParameter.NONE|ccui.LayoutParameter.LINEAR|ccui.LayoutParameter.RELATIVE} type
    Returns:
    {ccui.LayoutParameter}
  • {cc.Size} getLayoutSize()
    Gets layout size of ccui.Widget.
    Returns:
    {cc.Size}
  • {number} getLeftBoundary()
    Gets the left boundary position of this widget.
    Returns:
    {number}
  • {number} getLeftInParent()
    Gets the left boundary position of this widget.
    Deprecated:
    since v3.0, please use getLeftBoundary instead.
    Returns:
    {number}
  • {cc.Node} getNodeByTag(tag)
    Gets node by tag
    Parameters:
    {Number} tag
    Deprecated:
    since v3.0, please use getChildByTag instead.
    Returns:
    {cc.Node}
  • {Array} getNodes()
    Returns all children.
    Deprecated:
    since v3.0, please use getChildren instead.
    Returns:
    {Array}
  • {cc.Point} getPositionPercent()
    Gets the percent (x,y) of the widget
    Returns:
    {cc.Point} The percent (x,y) of the widget in OpenGL coordinates
  • {Number} getPositionType()
    Gets the position type of the widget
    Returns:
    {Number} the position type of widget
  • {number} getRightBoundary()
    Gets the right boundary position of this widget.
    Returns:
    {number}
  • {number} getRightInParent()
    Gets the right boundary position of this widget.
    Deprecated:
    since v3.0, please use getRightBoundary instead.
    Returns:
    {number}
  • {cc.Size} getSize()
    Returns size of widget
    Deprecated:
    since v3.0, please use getContentSize instead.
    Returns:
    {cc.Size}
  • {cc.Point} getSizePercent()
    Returns size percent of ccui.Widget
    Returns:
    {cc.Point}
  • Gets the size type of widget.
    Returns:
    {ccui.Widget.SIZE_ABSOLUTE|ccui.Widget.SIZE_PERCENT} that is widget's size type
  • {number} getTopBoundary()
    Gets the top boundary position of this widget.
    Returns:
    {number}
  • {number} getTopInParent()
    Gets the top boundary position of this widget.
    Deprecated:
    since v3.0, please use getTopBoundary instead.
    Returns:
    {number}
  • {cc.Point} getTouchBeganPosition()
    Gets the position of touch began event.
    Returns:
    {cc.Point}
  • {cc.Point} getTouchEndPos()
    Gets the touch end point of widget when widget is selected.
    Deprecated:
    since v3.0, please use getTouchEndPosition instead.
    Returns:
    {cc.Point} the touch end point.
  • {cc.Point} getTouchEndPosition()
    Gets the position of touch end event
    Returns:
    {cc.Point}
  • {cc.Point} getTouchMovePos()
    Gets the touch move point of widget when widget is selected.
    Deprecated:
    since v3.0, please use getTouchMovePosition instead.
    Returns:
    {cc.Point} the touch move point.
  • {cc.Point} getTouchMovePosition()
    Gets the position of touch moved event
    Returns:
    {cc.Point}
  • {cc.Point} getTouchStartPos()
    Gets the touch began point of widget when widget is selected.
    Deprecated:
    since v3.0, please use getTouchBeganPosition instead.
    Returns:
    {cc.Point} the touch began point.
  • {ccui.Widget} getVirtualRenderer()
    Gets the Virtual Renderer of widget.
    Returns:
    {ccui.Widget}
  • getVirtualRendererSize()
    Gets the content size of widget. Content size is widget's texture size.
  • {ccui.Widget|null} getWidgetParent()
    The direct parent when it's a widget also, otherwise equals null
    Returns:
    {ccui.Widget|null}
  • get widget type
    Returns:
    {ccui.Widget.TYPE_WIDGET|ccui.Widget.TYPE_CONTAINER}
  • {cc.Point} getWorldPosition()
    Gets world position of ccui.Widget.
    Returns:
    {cc.Point} world position of ccui.Widget.
  • {boolean} hitTest(pt)
    Checks a point if is in widget's space
    Parameters:
    {cc.Point} pt
    Returns:
    {boolean} true if the point is in widget's space, false otherwise.
  • ignoreContentAdaptWithSize(ignore)
    Ignore the widget size
    Parameters:
    {Boolean} ignore
    true that widget will ignore it's size, use texture size, false otherwise. Default value is true.
  • {boolean} init()
    initializes state of widget. please do not call this function by yourself, you should pass the parameters to constructor to initialize it
.
    Returns:
    {boolean}
  • interceptTouchEvent(eventType, sender, touch)
    Sends the touch event to widget's parent, its subclass will override it, e.g. ccui.ScrollView, ccui.PageView
    Parameters:
    {Number} eventType
    {ccui.Widget} sender
    {cc.Touch} touch
  • {boolean} isBright()
    Determines if the widget is bright
    Returns:
    {boolean} true if the widget is bright, false if the widget is dark.
  • {Boolean} isClippingParentContainsPoint(pt)
    returns whether clipping parent widget contains point.
    Parameters:
    {cc.Point} pt
    location point
    Returns:
    {Boolean}
  • {boolean} isEnabled()
    Determines if the widget is enabled
    Returns:
    {boolean}
  • {Boolean} isFlippedX()

    Returns the flag which indicates whether the widget is flipped horizontally or not.
    It only flips the texture of the widget, and not the texture of the widget's children.
    Also, flipping the texture doesn't alter the anchorPoint.
    If you want to flip the anchorPoint too, and/or to flip the children too use:
    widget.setScaleX(sprite.getScaleX() * -1);

    Returns:
    {Boolean} true if the widget is flipped horizontally, false otherwise.
  • {Boolean} isFlippedY()

    Return the flag which indicates whether the widget is flipped vertically or not.
    It only flips the texture of the widget, and not the texture of the widget's children.
    Also, flipping the texture doesn't alter the anchorPoint.
    If you want to flip the anchorPoint too, and/or to flip the children too use:
    widget.setScaleY(widget.getScaleY() * -1);

    Returns:
    {Boolean} true if the widget is flipped vertically, false otherwise.
  • {boolean} isFocused()
    Determines if the widget is on focused
    Returns:
    {boolean} whether the widget is focused or not
  • {boolean} isFocusEnabled()
    returns whether the widget could accept focus.
    Returns:
    {boolean} true represent the widget could accept focus, false represent the widget couldn't accept focus
  • {boolean} isHighlighted()
    Determines if the widget is highlighted
    Returns:
    {boolean} true if the widget is highlighted, false if the widget is not highlighted .
  • {boolean} isIgnoreContentAdaptWithSize()
    Gets whether ignore the content size (custom size)
    Returns:
    {boolean} true that widget will ignore it's size, use texture size, false otherwise.
  • {Boolean} isLayoutComponentEnabled()
    Returns whether enable layout component of a widget
    Returns:
    {Boolean} true represent the widget use Layout Component, false represent the widget couldn't use Layout Component.
  • {boolean} isPropagateTouchEvents()
    Return whether the widget is propagate touch events to its parents or not
    Since:
    v3.2
    Returns:
    {boolean}
  • {boolean} isSwallowTouches()
    Return whether the widget is swallowing touch or not
    Since:
    v3.2
    Returns:
    {boolean}
  • {boolean} isTouchEnabled()
    Returns whether or not touch is enabled.
    Returns:
    {boolean} true if the widget is touch enabled, false if the widget is touch disabled.
  • {boolean} isUnifySizeEnabled()
    Since:
    v3.2
    Returns:
    {boolean} true represent the widget use Unify Size, false represent the widget couldn't use Unify Size
  • onEnter()
    Calls updateSizeAndPosition and its parent's onEnter
  • onExit()
    Calls unscheduleUpdate and its parent's onExit
  • onFocusChange(widgetLostFocus, widgetGetFocus)
    This method is called when a focus change event happens
    Parameters:
    {ccui.Widget} widgetLostFocus
    {ccui.Widget} widgetGetFocus
  • {boolean} onTouchBegan(touch, event)

    The callback of touch began event.
    If the bounding box of ccui.Widget contains the touch point, it will do the following things:
    1. sets highlight state,
    2. sends event to parent widget by interceptTouchEvent
    3. calls the callback of touch began event.
    4. returns true,
    otherwise returns false directly.

    Parameters:
    {cc.Touch} touch
    {cc.Event} event
    Returns:
    {boolean}
  • onTouchCancelled(touchPoint)
    A call back function called when widget is selected, and on touch canceled.
    Parameters:
    {cc.Point} touchPoint
  • onTouchEnded(touch, event)

    The callback of touch end event It sends event to parent widget by interceptTouchEvent, calls the callback of touch end event (highlight= true) or touch canceled event (highlight= false). sets the highlight state to false ,

    Parameters:
    touch
    event
  • onTouchLongClicked(touchPoint)
    A call back function called when widget is selected, and on touch long clicked.
    Parameters:
    {cc.Point} touchPoint
  • onTouchMoved(touch, event)

    The callback of touch moved event.
    It sets the highlight state by touch, sends event to parent widget by interceptTouchEvent and calls the callback of touch moved event.

    Parameters:
    {cc.Touch} touch
    {cc.Event} event
  • removeAllNodes()
    Removes all node
    Deprecated:
    since v3.0, please use removeAllChildren instead.
  • removeNode(node, cleanup)
    Removes a node from ccui.Widget
    Parameters:
    {cc.Node} node
    {Boolean} cleanup
    Deprecated:
    since v3.0, please use removeChild instead.
  • removeNodeByTag(tag, cleanup)
    Removes node by tag
    Parameters:
    {Number} tag
    {Boolean} cleanup Optional
    Deprecated:
    since v3.0, please use removeChildByTag instead.
  • requestFocus()
    when a widget calls this method, it will get focus immediately.
  • setBright(bright)
    Sets whether the widget is bright. The default value is true, a widget is default to bright
    Parameters:
    {Boolean} bright
    true if the widget is bright, false if the widget is dark.
  • setBrightStyle(style)
    To set the bright style of ccui.Widget.
    Parameters:
    {Number} style
    BRIGHT_NORMAL the widget is normal state, BRIGHT_HIGHLIGHT the widget is height light state.
  • setCallbackName(callbackName)
    Sets callback name to widget.
    Parameters:
    {String} callbackName
    Since:
    v3.3
  • setCallbackType(callbackType)
    Sets callback type to widget
    Parameters:
    {String} callbackType
    Since:
    v3.3
  • setContentSize(contentSize, height)
    Sets _customSize of ccui.Widget, if ignoreSize is true, the content size is its renderer's contentSize, otherwise the content size is parameter. and updates size percent by parent content size. At last, updates its children's size and position.
    Parameters:
    {cc.Size|Number} contentSize
    content size or width of content size
    {Number} height Optional
  • setEnabled(enabled)

    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.
    The default value is true, a widget is default to enabled

    Parameters:
    {Boolean} enabled
  • setFlippedX(flipX)
    Sets whether the widget should be flipped horizontally or not.
    Parameters:
    {Boolean} flipX
    true if the widget should be flipped horizontally, false otherwise.
  • setFlippedY(flipY)
    Sets whether the widget should be flipped vertically or not.
    Parameters:
    {Boolean} flipY
    true if the widget should be flipped vertically, false otherwise.
  • setFocused(focus)
    Sets whether the widget is on focused The default value is false, a widget is default to not on focused
    Parameters:
    {boolean} focus
    pass true to let the widget get focus or pass false to let the widget lose focus
  • setFocusEnabled(enable)
    sets whether the widget could accept focus.
    Parameters:
    {Boolean} enable
    true represent the widget could accept focus, false represent the widget couldn't accept focus
  • setHighlighted(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.
  • setLayoutComponentEnabled(enable)
    Whether enable layout component of a widget
    Parameters:
    {Boolean} enable
    enable layout Component of a widget
    Since:
    v3.3
  • setLayoutParameter(parameter)
    Gets LayoutParameter of widget.
    Parameters:
    {ccui.LayoutParameter} parameter
  • setPosition(pos, posY)
    Changes the position (x,y) of the widget . The original point (0,0) is at the left-bottom corner of screen.
    Parameters:
    {cc.Point|Number} pos
    {Number} posY Optional
  • setPositionPercent(percent)
    Changes the position (x,y) of the widget
    Parameters:
    {cc.Point} percent
  • setPositionType(type)
    Changes the position type of the widget
    Parameters:
    {Number} type
    the position type of widget
  • setPropagateTouchEvents(isPropagate)
    Allow widget touch events to propagate to its parents. Set false will disable propagation
    Parameters:
    {Boolean} isPropagate
    Since:
    v3.2
  • setSize(size)
    Changes the size that is widget's size
    Parameters:
    {cc.Size} size
    that is widget's size
    Deprecated:
    since v3.0, please use setContentSize instead.
  • setSizePercent(percent)
    Changes the percent that is widget's percent size
    Parameters:
    {cc.Point} percent
    that is widget's percent size, width and height value from 0 to 1.
  • setSizeType(type)
    TEXTURE_RES_TYPE Changes the size type of widget.
    Parameters:
    {ccui.Widget.SIZE_ABSOLUTE|ccui.Widget.SIZE_PERCENT} type
    that is widget's size type
  • setSwallowTouches(swallow)
    Specify widget to swallow touches or not
    Parameters:
    {Boolean} swallow
    Since:
    v3.2
  • setTouchEnabled(enable)
    Sets whether the widget is touch enabled. The default value is false, a widget is default to touch disabled
    Parameters:
    {Boolean} enable
    true if the widget is touch enabled, false if the widget is touch disabled.
  • setUnifySizeEnabled(enable)
    Parameters:
    {Boolean} enable
    enable Unify Size of a widget
    Since:
    v3.2
  • updateSizeAndPosition(parentSize)
    updates its size by size type and its position by position type.
    Parameters:
    {cc.Size} parentSize Optional
    parent size