# CCControl Class Reference

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

- `preferredSize` property
- `preferredSizeType` property
- `maxSize` property
- `maxSizeType` property

### Setting and Getting Control Attributes

- `state` property
- `enabled` property
- `selected` property
- `highlighted` property
- `continuous` property
- `tracking` property
- `touchInside` property

### Receiving Action Callbacks

- `block` property
- `– setTarget:selector:`

### Subclass Methods

- `– triggerAction`
- `– stateChanged`
- `– needsLayout`
- `– layout`
- `– setValue:forKey:state:`
- `– valueForKey:state:`
- `– touchEntered:withEvent:`
- `– touchExited:withEvent:`
- `– touchUpInside:withEvent:`
- `– touchUpOutside:withEvent:`
- `– mouseDownEntered:`
- `– mouseDownExited:`
- `– mouseUpInside:`
- `– mouseUpOutside:`

## 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

- `

  - setValue:forKey:state:

  `

#### Declared In

`CCControlSubclass.h`