iOS Developer Library

Developer

UIKit Framework Reference UIKeyCommand Class Reference

Options
Deployment Target:

On This Page
Language:

UIKeyCommand

The UIKeyCommand class specifies a key presses performed on a hardware keyboard and the resulting action that should take place. Hardware keyboards allow a user to hold down the Control, Option, Command, or other modifier key and press a key in combination to initiate commands such as cut, copy, or paste. You can use instances of this class to define custom command sequences that your app recognizes and then provide an appropriate response.

To use this class, you create instances and associate them with your app’s responder objects. Each responder has a keyCommands property that you can redefine and use to return the key command objects that responder supports. Key command sequences are generated only for devices with an attached hardware keyboard.

The system always has the first opportunity to handle key commands. Key commands that map to known system events (such as cut, copy and paste) are automatically routed to the appropriate responder methods. For other key commands, UIKit looks for an object in the responder chain with a key command object that matches the pressed keys. If it finds such an object, it then walks the responder chain looking for the first object that implements the corresponding action method and calls the first one it finds.

  • Creates and returns a new key command object that matches the specified input and has a title.

    Declaration

    Swift

    init(input input: String, modifierFlags modifierFlags: UIKeyModifierFlags, action action: Selector, discoverabilityTitle discoverabilityTitle: String)

    Objective-C

    + (UIKeyCommand *)keyCommandWithInput:(NSString *)input modifierFlags:(UIKeyModifierFlags)modifierFlags action:(SEL)action discoverabilityTitle:(NSString *)discoverabilityTitle

    Parameters

    input

    The keys that must be pressed by the user. The string must contain one or more characters corresponding to the keys that were pressed. For a list of special characters that do not have a textual representation, see Input Strings for Special Keys.

    modifierFlags

    The bit mask of modifier keys that must be pressed. You can use this parameter to specify which modifier keys (Command, Option, and so on) must also be pressed by the user. You may specify more than one modifier key. For a list of possible values, see UIKeyModifierFlags.

    action

    The action method to execute on the responder object.

    discoverabilityTitle

    A string that can be displayed to the user to explain the purpose of the key command.

    Return Value

    The initialized key command object.

    Discussion

    After creating a key command object, you can add it to a view controller using the addKeyCommand: method of the view controller. You can also override any responder class and return the key command directly from the responder’s keyCommands property.

    Availability

    Available in iOS 9.0 and later.

  • Creates and returns a new key command object that matches the specified input.

    Declaration

    Swift

    init(input input: String, modifierFlags modifierFlags: UIKeyModifierFlags, action action: Selector)

    Objective-C

    + (UIKeyCommand *)keyCommandWithInput:(NSString *)input modifierFlags:(UIKeyModifierFlags)modifierFlags action:(SEL)action

    Parameters

    input

    The keys that must be pressed by the user. The string must contain one or more characters corresponding to the keys that were pressed. For a list of special characters that do not have a textual representation, see Input Strings for Special Keys.

    modifierFlags

    The bit mask of modifier keys that must be pressed. You can use this parameter to specify which modifier keys (Command, Option, and so on) must also be pressed by the user. You may specify more than one modifier key. For a list of possible values, see UIKeyModifierFlags.

    action

    The action method to execute on the responder object.

    Return Value

    The initialized key command object.

    Discussion

    After creating a key command object, you can add it to a view controller using the addKeyCommand: method of the view controller. You can also override any responder class and return the key command directly from the responder’s keyCommands property.

    Availability

    Available in iOS 7.0 and later.

  • The string of characters corresponding to the keys that must be pressed to match this key command. (read-only)

    Declaration

    Swift

    var input: String { get }

    Objective-C

    @property(nonatomic, readonly) NSString *input

    Availability

    Available in iOS 7.0 and later.

  • The bit mask of modifier flags that must be pressed to match this key command. (read-only)

    Declaration

    Swift

    var modifierFlags: UIKeyModifierFlags { get }

    Objective-C

    @property(nonatomic, readonly) UIKeyModifierFlags modifierFlags

    Availability

    Available in iOS 7.0 and later.

  • The title to display to the user.

    Declaration

    Swift

    var discoverabilityTitle: String?

    Objective-C

    @property(nonatomic, copy) NSString *discoverabilityTitle

    Discussion

    Use this property to explain the behavior of the key command. When this title string is present, UIKit displays information about the key command in appropriate places, such as the discoverability HUD in iOS 9 and later. If the value of this property is nil, UIKit does not display it to the user but still performs the key command at appropriate times.

    Availability

    Available in iOS 9.0 and later.

  • These constants indicate which modifier keys are pressed.

    Declaration

    Swift

    struct UIKeyModifierFlags : OptionSetType { init(rawValue rawValue: Int) static var AlphaShift: UIKeyModifierFlags { get } static var Shift: UIKeyModifierFlags { get } static var Control: UIKeyModifierFlags { get } static var Alternate: UIKeyModifierFlags { get } static var Command: UIKeyModifierFlags { get } static var NumericPad: UIKeyModifierFlags { get } }

    Objective-C

    typedef { UIKeyModifierAlphaShift = 1 << 16, UIKeyModifierShift = 1 << 17, UIKeyModifierControl = 1 << 18, UIKeyModifierAlternate = 1 << 19, UIKeyModifierCommand = 1 << 20, UIKeyModifierNumericPad = 1 << 21, } UIKeyModifierFlags;

    Constants

    • alphaShift

      UIKeyModifierAlphaShift

      The Caps Lock key is currently engaged.

      Available in iOS 7.0 and later.

    • shift

      UIKeyModifierShift

      The Shift key is pressed.

      Available in iOS 7.0 and later.

    • control

      UIKeyModifierControl

      The Control key is pressed.

      Available in iOS 7.0 and later.

    • alternate

      UIKeyModifierAlternate

      The Option key is pressed.

      Available in iOS 7.0 and later.

    • command

      UIKeyModifierCommand

      The Command key is pressed.

      Available in iOS 7.0 and later.

    • numericPad

      UIKeyModifierNumericPad

      The key is located on the numeric keypad.

      Available in iOS 7.0 and later.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 7.0 and later.

  • These constants represent the text input strings that correspond to special non visible keys.

    Declaration

    Swift

    let UIKeyInputUpArrow: String let UIKeyInputDownArrow: String let UIKeyInputLeftArrow: String let UIKeyInputRightArrow: String let UIKeyInputEscape: String

    Objective-C

    NSString *const UIKeyInputUpArrow; NSString *const UIKeyInputDownArrow; NSString *const UIKeyInputLeftArrow; NSString *const UIKeyInputRightArrow; NSString *const UIKeyInputEscape;

    Constants

    • UIKeyInputUpArrow

      UIKeyInputUpArrow

      The string representing the up arrow key.

      Available in iOS 7.0 and later.

    • UIKeyInputDownArrow

      UIKeyInputDownArrow

      The string representing the down arrow key.

      Available in iOS 7.0 and later.

    • UIKeyInputLeftArrow

      UIKeyInputLeftArrow

      The string representing the left arrow key.

      Available in iOS 7.0 and later.

    • UIKeyInputRightArrow

      UIKeyInputRightArrow

      The string representing the right arrow key.

      Available in iOS 7.0 and later.

    • UIKeyInputEscape

      UIKeyInputEscape

      The string representing the Escape key.

      Available in iOS 7.0 and later.