Inherits from CCNode : CCResponder : NSObject
Declared in CCControl.h

Overview

CCControl is the abstract base class of the Cocos2d components that handles touches or mouse events. You cannot instantiate it directly, instead use one of its sub-classes, such as CCButton. If you need to create a new sort of component you should make a sub-class of this class.

The control class handles events and its sub-classes will use child nodes to draw itself in the node heirarchy.

Important: If you are sub-classing CCControl you will need to include the CCControlSubclass.h file as it includes methods that are otherwise not exposed.

Tasks

Controlling Content Size

Setting and Getting Control Attributes

Receiving Action Callbacks

Subclass Methods

Properties

block

A block that handles action callbacks sent by the control. Use either the block property or the setTarget:selector: method to receive actions from controls.

@property (nonatomic, copy) void ( ^ ) ( id sender ) block

Declared In

CCControl.h

continuous

True if the control continously should generate events when it’s value is changed. E.g. this can be used by slider controls.

@property (nonatomic, assign) BOOL continuous

Declared In

CCControl.h

enabled

Determines if the control is currently enabled.

@property (nonatomic, assign) BOOL enabled

Declared In

CCControl.h

highlighted

Determines if the control is currently highlighted. E.g. this corresponds to the down state of a button

@property (nonatomic, assign) BOOL highlighted

Declared In

CCControl.h

maxSize

The maximum size that the component will layout to, the component will not be larger than this size and will instead shrink its content if needed.

@property (nonatomic, assign) CGSize maxSize

Declared In

CCControl.h

maxSizeType

The content size type that the preferredSize is using. Please refer to the CCNode documentation on how to use content size types.

@property (nonatomic, assign) CCSizeType maxSizeType

Declared In

CCControl.h

preferredSize

The preferred (and minimum) size that the component will attempt to layout to. If its contents are larger it may have a larger size.

@property (nonatomic, assign) CGSize preferredSize

Declared In

CCControl.h

preferredSizeType

The content size type that the preferredSize is using. Please refer to the CCNode documentation on how to use content size types.

@property (nonatomic, assign) CCSizeType preferredSizeType

Declared In

CCControl.h

selected

Determines if the control is currently selected. E.g. this is used by toggle buttons to handle the on state.

@property (nonatomic, assign) BOOL selected

Declared In

CCControl.h

state

Sets or retrieves the current state of the control. It’s often easier to use the enabled, highlighted and selected properties to indirectly set or read this property. This property is stored as a bit-mask.

@property (nonatomic, assign) CCControlState state

Declared In

CCControl.h

touchInside

True if the control currently has a touch or a mouse event within its bounds.

@property (nonatomic, readonly) BOOL touchInside

Declared In

CCControl.h

tracking

True if the control is currently tracking touches or mouse events. That is, if the user has touched down in the component but not lifted his finger (the actual touch may be outside the component).

@property (nonatomic, readonly) BOOL tracking

Declared In

CCControl.h

Instance Methods

layout

Used by sub classes. Override this method to do any layout needed by the component. This can include setting positions or sizes of child labels or sprites as well as the compontents contentSize.

- (void)layout

Declared In

CCControlSubclass.h

mouseDownEntered:

Used by sub-classes. Called when a mouse down enters the component. By default this happes if the mouse down is within the control, if the claimsUserEvents property is set to false this will also happen if the mouse down starts outside of the control.

- (void)mouseDownEntered:(NSEvent *)event

Parameters

event

Event associated with the mouse down.

Declared In

CCControlSubclass.h

mouseDownExited:

Used by sub-classes. Called when a mouse down exits the component.

- (void)mouseDownExited:(NSEvent *)event

Parameters

event

Event associated with the mouse down.

Declared In

CCControlSubclass.h

mouseUpInside:

Used by sub-classes. Called when a mouse down that started inside the component is ended inside the component. E.g. for CCButton, this triggers the buttons callback action.

- (void)mouseUpInside:(NSEvent *)event

Parameters

event

Event associated with the mouse up.

Declared In

CCControlSubclass.h

mouseUpOutside:

Used by sub-classes. Called when a mouse down that started inside the component is ended outside the component. E.g. for CCButton, this doesn’t trigger any callback action.

- (void)mouseUpOutside:(NSEvent *)event

Parameters

event

Event associated with the mouse up.

Declared In

CCControlSubclass.h

needsLayout

Used by sub-classes. This method should be called whenever the control needs to update its layout. It will force a call to the layout method at the beginning of the next draw cycle.

- (void)needsLayout

Declared In

CCControlSubclass.h

setTarget:selector:

Sets a target and selector that should be called when an action is triggered by the control. Actions are generated when buttons are clicked, sliders are dragged etc. You can also set the action callback using the block property.

- (void)setTarget:(id)target selector:(SEL)selector

Parameters

target

The target object.

selector

Selector to call on the target object.

Declared In

CCControl.h

setValue:forKey:state:

Used by sub-classes. Override this method if you are using custom properties and need to set them by name using the setValue:forKey method. This is needed for integration with editors such as SpriteBuilder. When overriding this method, make sure to call its super method if you cannot handle the key.

- (void)setValue:(id)value forKey:(NSString *)key state:(CCControlState)state

Parameters

value

The value to set.

key

The key to set the value for.

state

The state to set the value for.

Declared In

CCControlSubclass.h

stateChanged

Used by sub-classes. This method is called every time the control’s state changes, it’s default behavior is to call the needsLayout method.

- (void)stateChanged

Declared In

CCControlSubclass.h

touchEntered:withEvent:

Used by sub-classes. Called when a touch enters the component. By default this happes if the touch down is within the control, if the claimsUserEvents property is set to false this will also happen if the touch starts outside of the control.

- (void)touchEntered:(UITouch *)touch withEvent:(UIEvent *)event

Parameters

touch

Touch that entered the component.

event

Event associated with the touch.

Declared In

CCControlSubclass.h

touchExited:withEvent:

Used by sub-classes. Called when a touch exits the component.

- (void)touchExited:(UITouch *)touch withEvent:(UIEvent *)event

Parameters

touch

Touch that exited the component

event

Event associated with the touch.

Declared In

CCControlSubclass.h

touchUpInside:withEvent:

Used by sub-classes. Called when a touch that started inside the component is ended inside the component. E.g. for CCButton, this triggers the buttons callback action.

- (void)touchUpInside:(UITouch *)touch withEvent:(UIEvent *)event

Parameters

touch

Touch that is released inside the component.

event

Event associated with the touch.

Declared In

CCControlSubclass.h

touchUpOutside:withEvent:

Used by sub-classes. Called when a touch that started inside the component is ended outside the component. E.g. for CCButton, this doesn’t trigger any callback action.

- (void)touchUpOutside:(UITouch *)touch withEvent:(UIEvent *)event

Parameters

touch

Touch that is release outside of the component.

event

Event associated with the touch.

Declared In

CCControlSubclass.h

triggerAction

Used by sub-classes. This method is called to trigger an action callback. E.g. CCButton calls this method when the button is tapped.

- (void)triggerAction

Declared In

CCControlSubclass.h

valueForKey:state:

Used by sub-classes. Override this method to return values of custom properties that are set by state.

- (id)valueForKey:(NSString *)key state:(CCControlState)state

Parameters

key

The key to retrieve the value for.

state

The state to retrieve the value for.

Return Value

The value for the specified key and value or NULL if no such value exist.

See Also

Declared In

CCControlSubclass.h