Structure¶

KeyEquivalent¶

Key equivalents consist of a letter, punctuation, or function key that can be combined with an optional set of modifier keys to specify a keyboard shortcut.¶

Declaration¶

struct KeyEquivalent

Overview¶

Key equivalents are used to establish keyboard shortcuts to app functionality. Any key can be used as a key equivalent as long as pressing it produces a single character value. Key equivalents are typically initialized using a single-character string literal, with constants for unprintable or hard-to-type values.

The modifier keys necessary to type a key equivalent are factored in to the resulting keyboard shortcut. That is, a key equivalent whose raw value is the capitalized string "A" corresponds with the keyboard shortcut Command-Shift-A. The exact mapping may depend on the keyboard layout—for example, a key equivalent whith the character value "}" produces a shortcut equivalent to Command-Shift-] on ANSI keyboards, but would produce a different shortcut for keyboard layouts where punctuation characters are in different locations.

Use this structure with the keyboardShortcut(_:modifiers:) view modifier to add keyboard shortcuts to a view.

Key equivalents are also used in constructing KeyboardShortcut objects, which are used extensively in Commands.

struct ShortcutEnabledView: View {
    @State var bananas = ""

    let key = KeyEquivalent("p") //Try changing this

    var body: some View {
        VStack {
            Text(bananas)
            Button("Click or press command+P to print 🍌") {
                bananas += "🍌"
            }
            .keyboardShortcut(key, modifiers: [.command])
        }
        .frame(maxWidth: .infinity, maxHeight: .infinity)
    }
}

A view on macOs containing a state variable bananas initialized as an empty string and the KeyEquivalent "p" followed by a VStack with a text view calling bananas, a button reading "Click or press command+P to print 🍌", and a keyboard shortcut with command as the modifier; the gif shows that when the button is clicked or command and the p key are pressed, "🍌" is appended to the bananas string, as reflected in its display on teh screen.

Availability¶

iOS 14.0+

macOS 11.0+

Topics¶

Initializer¶

init(_:) Creates a new key equivalent from the given character value.

init(extendedGraphemeClusterLiteral:) Creates an instance initialized to the given value.

Type Alias¶

ExtendedGraphemeClusterLiteralType A type that represents an extended grapheme cluster literal.

UnicodeScalarLiteralType A type that represents a Unicode scalar literal.

Instance Property¶

character The character value that the key equivalent represents.

Type Property¶

clear Clear (U+F739) key equivalent

delete Delete (U+0008) key equivalent

deleteForward Delete Forward (U+F728) key equivalent

downArrow Down Arrow (U+F701) key equivalent

end End (U+F72B)

escape Escape (U+001B) key equivalent

home Home (U+F729) key equivalent

leftArrow Left Arrow (U+F702) key equivalent.

pageDown Page Down (U+F72D) key equivalent

pageUp Page Up (U+F72C) key equivalent

return Return (U+000D) key equivalent

rightArrow Right Arrow (U+F703) key equivalent

space Space (U+0020) key equivalent

tab Tab (U+0009) key equivalent

upArrow Up Arrow (U+F700) key equivalent.