CCControl Class Reference

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

Overview

CCControl is the abstract base class of the Cocos2D GUI components. It handles touch/mouse events. Its subclasses use child nodes to draw themselves in the node hierarchy.

You should not instantiate CCControl directly. Instead use one of its sub-classes:

If you need to create a new GUI control you should make it a subclass of CCControl.

Note: If you are subclassing CCControl you should #import "CCControlSubclass.h" in your subclass as it includes methods that are not publicly exposed.

Controlling Content Size

  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

See Also

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

See Also

Declared In

CCControl.h

Setting and Getting Control Attributes

  state

Sets or retrieves the current state of the control.

@property (nonatomic, assign) CCControlState state

Discussion

Note: This property is a bitmask. It’s easier to use the enabled, highlighted and selected properties to indirectly set or read this property.

See Also

Declared In

CCControl.h

  enabled

Determines if the control is currently enabled.

@property (nonatomic, assign) BOOL enabled

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

  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

  continuous

True if the control continously should generate events when it’s value is changed. E.g. this can be used by slider controls to run the block/selector whenever the slider is moved.

@property (nonatomic, assign) BOOL continuous

Declared In

CCControl.h

Accessing Control State

  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

  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

Receiving Action Callbacks

  block

A block that handles action callbacks sent by the control. The block runs when the control subclass is activated (ie slider moved, button tapped).

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

Discussion

The block must have the following signature: void (^)(id sender) where sender is the sending CCControl subclass. For example:

control.block = ^(id sender) {
    NSLog(@"control activated by: %@", sender);
};

See Also

Declared In

CCControl.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.

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

Parameters

target

The target object to which the message should be sent.
selector

Selector in target object receiving the message.

Discussion

The selector must have the following signature: -(void) theSelector:(id)sender where sender is the sending CCControl subclass. It is therefore legal to implement the selector more specifically as, for instance:

-(void) onSliderDragged:(CCSlider*)slider
{
    NSLog(@"sender: %@", slider);
}

Provided that this selector was assigned to a CCSlider instance.

See Also

Declared In

CCControl.h

Implemented_by_Subclasses Methods

– triggerAction

Can be implemented 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

– stateChanged

Can be implemented 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

– needsLayout

  • Can be implemented 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

– layout

  • Can be implemented 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

– setValue:forKey:state:

Can be implemented 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 CocosBuilder. 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.

See Also

Declared In

CCControlSubclass.h

– valueForKey:state:

Can be implemented 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

– touchEntered:withEvent:

Can be implemented 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:(CCTouch *)touch withEvent:(CCTouchEvent *)event

Parameters

touch

Touch that entered the component.
event

Event associated with the touch.

Declared In

CCControlSubclass.h

– touchExited:withEvent:

Can be implemented by sub-classes. Called when a touch exits the component.

- (void)touchExited:(CCTouch *)touch withEvent:(CCTouchEvent *)event

Parameters

touch

Touch that exited the component
event

Event associated with the touch.

Declared In

CCControlSubclass.h

– touchUpInside:withEvent:

Can be implemented 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:(CCTouch *)touch withEvent:(CCTouchEvent *)event

Parameters

touch

Touch that is released inside the component.
event

Event associated with the touch.

Declared In

CCControlSubclass.h

– touchUpOutside:withEvent:

Can be implemented 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:(CCTouch *)touch withEvent:(CCTouchEvent *)event

Parameters

touch

Touch that is release outside of the component.
event

Event associated with the touch.

Declared In

CCControlSubclass.h

– mouseDownEntered:

Can be implemented 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.

See Also

Declared In

CCControlSubclass.h

– mouseDownExited:

Can be implemented by sub-classes. Called when a mouse down exits the component.

- (void)mouseDownExited:(NSEvent *)event

Parameters

event

Event associated with the mouse down.

See Also

Declared In

CCControlSubclass.h

– mouseUpInside:

Can be implemented 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.

See Also

Declared In

CCControlSubclass.h

– mouseUpOutside:

Can be implemented 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.

See Also

Declared In

CCControlSubclass.h