GCController Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/GameController.framework
Availability
Available in iOS 7.0 and later.
Companion guide
Declared in
GCController.h

Overview

A GCController object represents a connected physical game controller. Controllers can be connected directly to the device or through a wireless connection.

Tasks

Discovering Controllers

Determining Which Profiles Are Supported by a Controller

Responding When a Controller Is Paused

Inspecting a Controller

Assigning a Player Index

Properties

attachedToDevice

A Boolean property that indicates whether the controller is closely integrated with the device. (read-only)

@property(readonly, getter=isAttachedToDevice) BOOL attachedToDevice
Discussion

If YES, then the controller is attached to the device or is quite close to it. If NO, then the controller is not guaranteed to be near the device. This property is provided to allow you to make informed decisions about what other user interface interactions with the device will make sense.

Availability
  • Available in iOS 7.0 and later.
Declared In
GCController.h

controllerPausedHandler

A block called when the controller’s pause button is pressed.

@property(copy) void (^controllerPausedHandler)(GCController *controller)
Discussion

All controllers have a button that allows the player to suspend the current gameplay. When pressed, the block associated with this property is called. Your game should toggle between pausing and resuming gameplay. When paused, your game must display a user interface that indicates that the game is paused. This interface should tell the player how to resume the game. The exact design of this user interface is up to you; typically it should match the style of the rest of your game.

If your game is paused for other reasons defined by your game, and is in a state where it can be resumed, pressing the pause button should resume gameplay. Which is to say that the pause button on the controller as well as other things that pause gameplay should all present a seamless interface to the player.

Availability
  • Available in iOS 7.0 and later.
Declared In
GCController.h

extendedGamepad

The extended gamepad profile. (read-only)

@property(retain, readonly) GCExtendedGamepad *extendedGamepad
Discussion

If the controller supports the extended gamepad profile, then this property holds a GCExtendedGamepad object. You use this object to access the input elements of the controller. If the controller does not support the extended gamepad profile, this property holds nil.

Availability
  • Available in iOS 7.0 and later.
Declared In
GCController.h

gamepad

The gamepad profile. (read-only)

@property(retain, readonly) GCGamepad *gamepad
Discussion

If the controller supports the gamepad profile, then this property holds a GCGamepad object. You use this object to access the input elements of the controller. If the controller does not support the gamepad profile, this property holds nil.

Availability
  • Available in iOS 7.0 and later.
Declared In
GCController.h

playerIndex

The player index assigned to the controller.

@property(nonatomic) NSInteger playerIndex
Discussion

The player index is a value that is persistently stored on the device for a particular controller. Once assigned, the device uses the same index for that controller whenever it is discovered. Your app can use this index to identify a particular controller in the future. The default value is GCControllerPlayerIndexUnset. An index value can be 0 or any positive integer value, but you should almost always use numbers between 0 and 3. When you choose a number in this range, a matching LED on the controller lights up.

Availability
  • Available in iOS 7.0 and later.
Declared In
GCController.h

vendorName

The name of the vendor that manufactured the controller. (read-only)

@property(readonly, copy) NSString *vendorName
Discussion

The value of this property may be nil and is not guaranteed to be unique.

Availability
  • Available in iOS 7.0 and later.
Declared In
GCController.h

Class Methods

controllers

The controllers connected to the device.

+ (NSArray *)controllers
Return Value

An array of GCController objects for all currently connected controllers.

Discussion

Whenever a controller is connected to or disconnected from the device, the array of controllers is updated and a notification is posted.

Availability
  • Available in iOS 7.0 and later.
Declared In
GCController.h

startWirelessControllerDiscoveryWithCompletionHandler:

Starts browsing for nearby controllers.

+ (void)startWirelessControllerDiscoveryWithCompletionHandler:(void (^)(void))completionHandler
Parameters
completionHandler

A block to be called when browsing ends.

Discussion

You should include a user interface in your game to allow the player to determine when controllers are discovered. When the user chooses to search for controllers, call this method. The device searches asynchronously for discoverable wireless controllers. Whenever a new controller is connected, a GCControllerDidConnectNotification notification is posted. When no more devices can be found or the discovery process times out, the completion handler is called.

If this method is called multiple times, only the block associated with the last invocation is called when discovery times out.

Availability
  • Available in iOS 7.0 and later.
Declared In
GCController.h

stopWirelessControllerDiscovery

Stops browsing for nearby controllers.

+ (void)stopWirelessControllerDiscovery
Discussion

This method may be called at any time. If a search for new wireless controllers in progress, that search ends and its completion handler is called.

Availability
  • Available in iOS 7.0 and later.
Declared In
GCController.h

Constants

Controller Player Indices

Predefined values for controller indices.

enum {
   GCControllerPlayerIndexUnset = -1,
};
Constants
GCControllerPlayerIndexUnset

The default index for a player on a controller. No lights are lit on the controller.

Available in iOS 7.0 and later.

Declared in GCController.h.

Notifications

GCControllerDidConnectNotification

Posted immediately after a new controller is connected to the device.

The notification object is the GCController object that represents the connected device.

Availability
Declared In
GCController.h

GCControllerDidDisconnectNotification

Posted immediately after a controller is disconnected from the device.

The notification object is the GCController object that represented the disconnected device.

Availability
Declared In
GCController.h