Skip to content

Commit b5c8a4c

Browse files
wolfconwolfcon
committed
Add NSMenuItem and NSButton shortcut manuals
1 parent ad323af commit b5c8a4c

3 files changed

+217
-0
lines changed

‎README.md

+1
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,7 @@
2323
- [Let App Support Files](iOS_LetAppSupportFiles.md)
2424
- [Get Rid of CocoaPods](CocoaPods_Deintegrate.md)
2525
- [Auto Push to CocoaPod Trunk](CocoaPod_AutoPush.md)
26+
- [Shortcut of NSMenuItem and NSButton](macOS_Shortcut4MenuItem+Button.md)
2627

2728
### LocalStorage
2829

‎iOS_LetAppSupportFiles.md

+22
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
---
2+
title: Let App Support Files
3+
---
4+
5+
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
6+
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
7+
**Table of Content**
8+
9+
- [Let App Support Files](#let-app-support-files)
10+
- [Add some config in `info.plist`](#add-some-config-in-infoplist)
11+
12+
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
13+
14+
15+
# Let App Support Files
16+
17+
## Add some config in `info.plist`
18+
19+
- UIFileSharingEnabled
20+
- LSSupportsOpeningDocumentsInPlace
21+
22+
Now your app can support `Files.app`

‎macOS_Shortcut4MenuItem+Button.md

+194
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,194 @@
1+
---
2+
title: Shortcut of NSMenuItem and NSButton
3+
---
4+
5+
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
6+
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
7+
**Table of Content**
8+
9+
- [Shortcut of NSMenuItem and NSButton](#shortcut-of-nsmenuitem-and-nsbutton)
10+
- [1. Composition of Key Equivalent](#1-composition-of-key-equivalent)
11+
- [2. Changing xib object property](#2-changing-xib-object-property)
12+
- [3. Programmatic Way](#3-programmatic-way)
13+
- [3.1 Normal Key](#31-normal-key)
14+
- [3.2 Symbol Key](#32-symbol-key)
15+
- [4. Dynamic Menu Items](#4-dynamic-menu-items)
16+
- [5. Some Design Guideline](#5-some-design-guideline)
17+
- [6. Other Weird Facts](#6-other-weird-facts)
18+
- [7. Reference](#7-reference)
19+
- [8. Demo Project](#8-demo-project)
20+
21+
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
22+
23+
# Shortcut of NSMenuItem and NSButton
24+
25+
Shortcut key, or hot key, is called `Key Equivalent` in Mac development. To use it, just press corresponding key combination, it will trigger predefined application function.
26+
27+
Among NSControl’s subclass, NSMenuItem and NSButton supports key equivalent, which can be implemented in programmatic way or by changing xib object property.
28+
29+
## 1. Composition of Key Equivalent
30+
31+
Normally, key equivalent is composite of two parts: some modifier keys and one basic key.
32+
33+
There are 4 possible modifier keys:
34+
35+
| Symbol | Name |
36+
| :----- | :---------------------- |
37+
| ⌘ | Command |
38+
| ⌃ | Control |
39+
| ⇧ | Shift |
40+
| ⌥ | Option, alias Alternate |
41+
42+
Normal key, includes alphabet, number, punctuation, symbol key, etc.
43+
44+
Key Equivalent may have no modifier key. This is very common in high-efficiency professional application, for example, in Photoshop, moving layer’s shortcut key is `V`.
45+
46+
For symbol key, it refers to key like `⎋` (escape), `↑` (up arrow). On Mac laptop, `⌦` (delete), `⇞` (page up), `⇟` (page down), `↖` (home), `↘` (end) does not have dedicated physical keys. But there are substitutes to accomplish same function:
47+
48+
| Key | Substitute |
49+
| :-------- | :--------- |
50+
| Delete | Fn + ⌫ |
51+
| Page Up | Fn + ↑ |
52+
| Page Down | Fn + ↓ |
53+
| Home | Fn + ← |
54+
| End | Fn + → |
55+
56+
## 2. Changing xib object property
57+
58+
In **Attributes** panel of NSMenuItem/NSButton, **Key Equivalent**input field, is used to set shortcut. For example, a character, E, will be displayed capitalized.
59+
60+
If shortcut includes `⇧` key, the input field will show an Alternates button, to let you choose displaying style between, like `⌘+` and `⇧⌘=`.
61+
62+
![img](https://user-images.githubusercontent.com/55504/37417474-5cafc540-27eb-11e8-830a-58ddb9c7defb.gif)
63+
64+
## 3. Programmatic Way
65+
66+
### 3.1 Normal Key
67+
68+
Following code sets menuItem’s shortcut as `E`.
69+
70+
```
71+
[menuItem setKeyEquivalentModifierMask:!NSEventModifierFlagCommand];
72+
[menuItem setKeyEquivalent:@"e"];
73+
```
74+
75+
Following code sets menuItem’s shortcut as `⌘E`.
76+
77+
```
78+
[menuItem setKeyEquivalent:@"e"];
79+
```
80+
81+
Following code sets menuItem’s shortcut as `⇧⌘E`.
82+
83+
```
84+
[menuItem setKeyEquivalent:@"E"];
85+
```
86+
87+
### 3.2 Symbol Key
88+
89+
First of all, you need to know corresponding Unicode value.
90+
91+
| Symbol | Name | Unicode |
92+
| :----- | :-------- | :------ |
93+
| ⌫ | Backspace | 0x0008 |
94+
| ⇥ | Tab | 0x0009 |
95+
| ↩ | Return | 0x000d |
96+
| ⎋ | Escape | 0x001b |
97+
| ← | Left | 0x001c |
98+
| → | Right | 0x001d |
99+
| ↑ | Up | 0x001e |
100+
| ↓ | Down | 0x001f |
101+
| ␣ | Space | 0x0020 |
102+
| ⌦ | Delete | 0x007f |
103+
| ↖ | Home | 0x2196 |
104+
| ↘ | End | 0x2198 |
105+
| ⇞ | Page Up | 0x21de |
106+
| ⇟ | Page Down | 0x21df |
107+
108+
**Note:** `NSBackspaceCharacter`, `NSTabCharacter`, `NSCarriageReturnCharacter` are defined in *NSText.h*, others are not. All of them (except 4 arrow keys) can be found [here](https://unicode-table.com/en). Arrow keys do not use 0x2190, 0x2191, 0x2192, 0x2193, I don’t know the reason.
109+
110+
Following code sets menuItem’s shortcut as `⌘↩`.
111+
112+
```
113+
NSString *s = [NSString stringWithFormat:@"%c", NSCarriageReturnCharacter];
114+
[menuItem setKeyEquivalent:s];
115+
```
116+
117+
Following code sets menuItem’s shortcut as `⌘↑`.
118+
119+
```
120+
NSString *s = [NSString stringWithFormat:@"%C", 0x001e];
121+
[menuItem setKeyEquivalent:s];
122+
```
123+
124+
**Attention:** the format specifiers are different, the latter **MUST** use `%C`.
125+
126+
One more thing, the shortcuts displayed by menu items are different than the symbols on xib canvas and those printed on some keyboards.
127+
128+
| In xib | Running application |
129+
| :----------------------------------------------------------- | :----------------------------------------------------------- |
130+
| ![img](https://user-images.githubusercontent.com/55504/37520582-9bb5dd4c-2958-11e8-9c6e-0e442beca151.png) | ![img](https://user-images.githubusercontent.com/55504/37520583-9bf7487c-2958-11e8-8363-1e3990fe26bc.png) |
131+
132+
Some keyboard models:
133+
134+
[![img](https://user-images.githubusercontent.com/55504/37498987-5c8c51ca-28fc-11e8-880e-5389466e76ee.jpg)](https://user-images.githubusercontent.com/55504/37498987-5c8c51ca-28fc-11e8-880e-5389466e76ee.jpg)
135+
136+
Apple - Magic Keyboard with Numeric Keypad
137+
138+
[![img](https://user-images.githubusercontent.com/55504/37498988-5cd81308-28fc-11e8-9423-a70fe8c2aa5f.jpg)](https://user-images.githubusercontent.com/55504/37498988-5cd81308-28fc-11e8-9423-a70fe8c2aa5f.jpg)
139+
140+
Belkin - YourType Bluetooth Wireless Keypad
141+
142+
## 4. Dynamic Menu Items
143+
144+
Option key has an alias, Alternate key, it is called so when holding it, the menu item will appear in a different way.
145+
146+
In Apple’s *Human Interface Guidelines*, this menu item is called [Dynamic Menu Items](https://developer.apple.com/macos/human-interface-guidelines/menus/menu-anatomy/), and invisible by default.
147+
148+
For instance, click MacOS desktop’s left top `` menu item, then hold option key, you will see, “About This Mac” changes to “System Information…” and its triggered action changes too.
149+
150+
![img](https://user-images.githubusercontent.com/55504/37418708-cde64e8a-27ed-11e8-884a-022c6a51fe6d.gif)
151+
152+
In xib, to implement this:
153+
154+
1. Add 2 NSMenuItem, they **MUST** be adjacent, no other menu item between them.
155+
2. Set valid shortcut for them, and the second’s shortcut **MUST**be the first’s shortcut, plus `⌥` key.
156+
3. Check **Alternate** property for the second NSMenuItem.
157+
158+
Now, run the app and it will works as above `` menu item example.
159+
160+
![img](https://user-images.githubusercontent.com/55504/37417755-03bbaffc-27ec-11e8-8cad-b9445ae05777.gif)
161+
162+
Besides, in step 2, if you switch shortcuts of these two menu items, the default visible will be the second one instead, while they’re still **alternate**.
163+
164+
![img](https://user-images.githubusercontent.com/55504/37417756-040844fc-27ec-11e8-9539-ff3e068b7c15.gif)
165+
166+
## 5. Some Design Guideline
167+
168+
1. Do **NOT** add shortcut for contextual menu. [Link](https://developer.apple.com/macos/human-interface-guidelines/menus/contextual-menus/)
169+
2. Do **NOT** conflict with system shortcuts or other popular shortcuts, like `⇧⌘Q` (log out account), `⌘C` (copy), etc.
170+
3. Only add shortcut for frequently used action, to relieve user’s learning and remembering burden. For example, about, is a rarely-used action, it does not need a shortcut.
171+
172+
## 6. Other Weird Facts
173+
174+
1. `⌃⇧1` and `⇧1` can not exist together, or the former triggers the latter’s action.
175+
2. `⌃⌥⇧1` and `⇧1` can not exist together, or the former triggers the latter’s action.
176+
3. `⌃⌥⇧1` and `⌃⇧1` can not exist together, or the former triggers the latter’s action.
177+
4. `⌃⇧A`, its log info shows incorrectly for **⌃A**, both in code and xib. What’s more, In code, if `keyEquivalent` is a capitalized alphabet and `keyEquivalentModifierMask` does not include `NSEventModifierFlagShift`, system will add `⇧` automatically in the shortcut UI.
178+
5. In xib, set a menu item or button’s Key Equivalent with `⇧`, `⌘`, `=`, and choose alternates as `⌘+`, then `⌘=` and `⇧⌘=` can both trigger its action.
179+
6. When setting `keyEquivalentModifierMask` for NSButton, it can not include `NSEventModifierFlagControl`, or shortcut will not work.
180+
181+
## 7. Reference
182+
183+
1. [*Human Interface Guidelines*](https://developer.apple.com/macos/human-interface-guidelines/menus/menu-anatomy/)
184+
2. [*Application Menu and Pop-up List Programming Topics*](https://developer.apple.com/library/content/documentation/Cocoa/Conceptual/MenuList/Articles/SettingMenuKeyEquiv.html#//apple_ref/doc/uid/20000264-BBCDCAIG)
185+
3. https://stackoverflow.com/a/6230866/353927
186+
4. [Unicode character table](https://unicode-table.com/en)
187+
188+
## 8. Demo Project
189+
190+
[Here](https://github.com/cool8jay/KeyEquivelant) is demo project.
191+
192+
193+
194+
> Repost from https://cool8jay.github.io/shortcut-nemenuitem-nsbutton/

0 commit comments

Comments
 (0)