001// License: GPL. For details, see LICENSE file. 002package org.openstreetmap.josm.tools; 003 004import static org.openstreetmap.josm.tools.I18n.tr; 005 006import java.awt.event.KeyEvent; 007import java.util.ArrayList; 008import java.util.Arrays; 009import java.util.Comparator; 010import java.util.HashMap; 011import java.util.List; 012import java.util.Map; 013import java.util.Optional; 014import java.util.concurrent.CopyOnWriteArrayList; 015import java.util.function.Predicate; 016import java.util.stream.Collectors; 017 018import javax.swing.AbstractAction; 019import javax.swing.AbstractButton; 020import javax.swing.JMenu; 021import javax.swing.KeyStroke; 022import javax.swing.text.JTextComponent; 023 024import org.openstreetmap.josm.Main; 025import org.openstreetmap.josm.spi.preferences.Config; 026 027/** 028 * Global shortcut class. 029 * 030 * Note: This class represents a single shortcut, contains the factory to obtain 031 * shortcut objects from, manages shortcuts and shortcut collisions, and 032 * finally manages loading and saving shortcuts to/from the preferences. 033 * 034 * Action authors: You only need the {@link #registerShortcut} factory. Ignore everything else. 035 * 036 * All: Use only public methods that are also marked to be used. The others are 037 * public so the shortcut preferences can use them. 038 * @since 1084 039 */ 040public final class Shortcut { 041 /** the unique ID of the shortcut */ 042 private final String shortText; 043 /** a human readable description that will be shown in the preferences */ 044 private String longText; 045 /** the key, the caller requested */ 046 private final int requestedKey; 047 /** the group, the caller requested */ 048 private final int requestedGroup; 049 /** the key that actually is used */ 050 private int assignedKey; 051 /** the modifiers that are used */ 052 private int assignedModifier; 053 /** true if it got assigned what was requested. 054 * (Note: modifiers will be ignored in favour of group when loading it from the preferences then.) */ 055 private boolean assignedDefault; 056 /** true if the user changed this shortcut */ 057 private boolean assignedUser; 058 /** true if the user cannot change this shortcut (Note: it also will not be saved into the preferences) */ 059 private boolean automatic; 060 /** true if the user requested this shortcut to be set to its default value 061 * (will happen on next restart, as this shortcut will not be saved to the preferences) */ 062 private boolean reset; 063 064 // simple constructor 065 private Shortcut(String shortText, String longText, int requestedKey, int requestedGroup, int assignedKey, int assignedModifier, 066 boolean assignedDefault, boolean assignedUser) { 067 this.shortText = shortText; 068 this.longText = longText; 069 this.requestedKey = requestedKey; 070 this.requestedGroup = requestedGroup; 071 this.assignedKey = assignedKey; 072 this.assignedModifier = assignedModifier; 073 this.assignedDefault = assignedDefault; 074 this.assignedUser = assignedUser; 075 this.automatic = false; 076 this.reset = false; 077 } 078 079 public String getShortText() { 080 return shortText; 081 } 082 083 public String getLongText() { 084 return longText; 085 } 086 087 // a shortcut will be renamed when it is handed out again, because the original name may be a dummy 088 private void setLongText(String longText) { 089 this.longText = longText; 090 } 091 092 public int getAssignedKey() { 093 return assignedKey; 094 } 095 096 public int getAssignedModifier() { 097 return assignedModifier; 098 } 099 100 public boolean isAssignedDefault() { 101 return assignedDefault; 102 } 103 104 public boolean isAssignedUser() { 105 return assignedUser; 106 } 107 108 public boolean isAutomatic() { 109 return automatic; 110 } 111 112 public boolean isChangeable() { 113 return !automatic && !"core:none".equals(shortText); 114 } 115 116 private boolean isReset() { 117 return reset; 118 } 119 120 /** 121 * FOR PREF PANE ONLY 122 */ 123 public void setAutomatic() { 124 automatic = true; 125 } 126 127 /** 128 * FOR PREF PANE ONLY.<p> 129 * Sets the modifiers that are used. 130 * @param assignedModifier assigned modifier 131 */ 132 public void setAssignedModifier(int assignedModifier) { 133 this.assignedModifier = assignedModifier; 134 } 135 136 /** 137 * FOR PREF PANE ONLY.<p> 138 * Sets the key that actually is used. 139 * @param assignedKey assigned key 140 */ 141 public void setAssignedKey(int assignedKey) { 142 this.assignedKey = assignedKey; 143 } 144 145 /** 146 * FOR PREF PANE ONLY.<p> 147 * Sets whether the user has changed this shortcut. 148 * @param assignedUser {@code true} if the user has changed this shortcut 149 */ 150 public void setAssignedUser(boolean assignedUser) { 151 this.reset = (this.assignedUser || reset) && !assignedUser; 152 if (assignedUser) { 153 assignedDefault = false; 154 } else if (reset) { 155 assignedKey = requestedKey; 156 assignedModifier = findModifier(requestedGroup, null); 157 } 158 this.assignedUser = assignedUser; 159 } 160 161 /** 162 * Use this to register the shortcut with Swing 163 * @return the key stroke 164 */ 165 public KeyStroke getKeyStroke() { 166 if (assignedModifier != -1) 167 return KeyStroke.getKeyStroke(assignedKey, assignedModifier); 168 return null; 169 } 170 171 // create a shortcut object from an string as saved in the preferences 172 private Shortcut(String prefString) { 173 List<String> s = new ArrayList<>(Config.getPref().getList(prefString)); 174 this.shortText = prefString.substring(15); 175 this.longText = s.get(0); 176 this.requestedKey = Integer.parseInt(s.get(1)); 177 this.requestedGroup = Integer.parseInt(s.get(2)); 178 this.assignedKey = Integer.parseInt(s.get(3)); 179 this.assignedModifier = Integer.parseInt(s.get(4)); 180 this.assignedDefault = Boolean.parseBoolean(s.get(5)); 181 this.assignedUser = Boolean.parseBoolean(s.get(6)); 182 } 183 184 private void saveDefault() { 185 Config.getPref().getList("shortcut.entry."+shortText, Arrays.asList(longText, 186 String.valueOf(requestedKey), String.valueOf(requestedGroup), String.valueOf(requestedKey), 187 String.valueOf(getGroupModifier(requestedGroup)), String.valueOf(true), String.valueOf(false))); 188 } 189 190 // get a string that can be put into the preferences 191 private boolean save() { 192 if (isAutomatic() || isReset() || !isAssignedUser()) { 193 return Config.getPref().putList("shortcut.entry."+shortText, null); 194 } else { 195 return Config.getPref().putList("shortcut.entry."+shortText, Arrays.asList(longText, 196 String.valueOf(requestedKey), String.valueOf(requestedGroup), String.valueOf(assignedKey), 197 String.valueOf(assignedModifier), String.valueOf(assignedDefault), String.valueOf(assignedUser))); 198 } 199 } 200 201 private boolean isSame(int isKey, int isModifier) { 202 // an unassigned shortcut is different from any other shortcut 203 return isKey == assignedKey && isModifier == assignedModifier && assignedModifier != getGroupModifier(NONE); 204 } 205 206 public boolean isEvent(KeyEvent e) { 207 KeyStroke ks = getKeyStroke(); 208 return ks != null && ks.equals(KeyStroke.getKeyStroke(e.getKeyCode(), e.getModifiersEx())); 209 } 210 211 /** 212 * use this to set a menu's mnemonic 213 * @param menu menu 214 */ 215 public void setMnemonic(JMenu menu) { 216 if (assignedModifier == getGroupModifier(MNEMONIC) && getKeyStroke() != null && KeyEvent.getKeyText(assignedKey).length() == 1) { 217 menu.setMnemonic(KeyEvent.getKeyText(assignedKey).charAt(0)); //getKeyStroke().getKeyChar() seems not to work here 218 } 219 } 220 221 /** 222 * use this to set a buttons's mnemonic 223 * @param button button 224 */ 225 public void setMnemonic(AbstractButton button) { 226 if (assignedModifier == getGroupModifier(MNEMONIC) && getKeyStroke() != null && KeyEvent.getKeyText(assignedKey).length() == 1) { 227 button.setMnemonic(KeyEvent.getKeyText(assignedKey).charAt(0)); //getKeyStroke().getKeyChar() seems not to work here 228 } 229 } 230 231 /** 232 * Sets the mnemonic key on a text component. 233 * @param component component 234 */ 235 public void setFocusAccelerator(JTextComponent component) { 236 if (assignedModifier == getGroupModifier(MNEMONIC) && getKeyStroke() != null && KeyEvent.getKeyText(assignedKey).length() == 1) { 237 component.setFocusAccelerator(KeyEvent.getKeyText(assignedKey).charAt(0)); 238 } 239 } 240 241 /** 242 * use this to set a actions's accelerator 243 * @param action action 244 */ 245 public void setAccelerator(AbstractAction action) { 246 if (getKeyStroke() != null) { 247 action.putValue(AbstractAction.ACCELERATOR_KEY, getKeyStroke()); 248 } 249 } 250 251 /** 252 * Returns a human readable text for the shortcut. 253 * @return a human readable text for the shortcut 254 */ 255 public String getKeyText() { 256 return getKeyText(getKeyStroke()); 257 } 258 259 /** 260 * Returns a human readable text for the key stroke. 261 * @param keyStroke key stroke to convert to human readable text 262 * @return a human readable text for the key stroke 263 * @since 12520 264 */ 265 public static String getKeyText(KeyStroke keyStroke) { 266 if (keyStroke == null) return ""; 267 String modifText = KeyEvent.getModifiersExText(keyStroke.getModifiers()); 268 if ("".equals(modifText)) return KeyEvent.getKeyText(keyStroke.getKeyCode()); 269 return modifText + '+' + KeyEvent.getKeyText(keyStroke.getKeyCode()); 270 } 271 272 @Override 273 public String toString() { 274 return getKeyText(); 275 } 276 277 /////////////////////////////// 278 // everything's static below // 279 /////////////////////////////// 280 281 // here we store our shortcuts 282 private static ShortcutCollection shortcuts = new ShortcutCollection(); 283 284 private static class ShortcutCollection extends CopyOnWriteArrayList<Shortcut> { 285 @Override 286 public boolean add(Shortcut shortcut) { 287 // expensive consistency check only in debug mode 288 if (Logging.isDebugEnabled() 289 && stream().map(Shortcut::getShortText).anyMatch(shortcut.getShortText()::equals)) { 290 Logging.warn(new AssertionError(shortcut.getShortText() + " already added")); 291 } 292 return super.add(shortcut); 293 } 294 295 void replace(Shortcut newShortcut) { 296 final Optional<Shortcut> existing = findShortcutByKeyOrShortText(-1, NONE, newShortcut.shortText); 297 if (existing.isPresent()) { 298 replaceAll(sc -> existing.get() == sc ? newShortcut : sc); 299 } else { 300 add(newShortcut); 301 } 302 } 303 } 304 305 // and here our modifier groups 306 private static Map<Integer, Integer> groups = new HashMap<>(); 307 308 // check if something collides with an existing shortcut 309 310 /** 311 * Returns the registered shortcut fot the key and modifier 312 * @param requestedKey the requested key 313 * @param modifier the modifier 314 * @return an {@link Optional} registered shortcut, never {@code null} 315 */ 316 public static Optional<Shortcut> findShortcut(int requestedKey, int modifier) { 317 return findShortcutByKeyOrShortText(requestedKey, modifier, null); 318 } 319 320 private static Optional<Shortcut> findShortcutByKeyOrShortText(int requestedKey, int modifier, String shortText) { 321 final Predicate<Shortcut> sameKey = sc -> modifier != getGroupModifier(NONE) && sc.isSame(requestedKey, modifier); 322 final Predicate<Shortcut> sameShortText = sc -> sc.getShortText().equals(shortText); 323 return shortcuts.stream() 324 .filter(sameKey.or(sameShortText)) 325 .sorted(Comparator.comparingInt(sc -> sameShortText.test(sc) ? 0 : 1)) 326 .findAny(); 327 } 328 329 /** 330 * Returns a list of all shortcuts. 331 * @return a list of all shortcuts 332 */ 333 public static List<Shortcut> listAll() { 334 return shortcuts.stream() 335 .filter(c -> !"core:none".equals(c.shortText)) 336 .collect(Collectors.toList()); 337 } 338 339 /** None group: used with KeyEvent.CHAR_UNDEFINED if no shortcut is defined */ 340 public static final int NONE = 5000; 341 public static final int MNEMONIC = 5001; 342 /** Reserved group: for system shortcuts only */ 343 public static final int RESERVED = 5002; 344 /** Direct group: no modifier */ 345 public static final int DIRECT = 5003; 346 /** Alt group */ 347 public static final int ALT = 5004; 348 /** Shift group */ 349 public static final int SHIFT = 5005; 350 /** Command group. Matches CTRL modifier on Windows/Linux but META modifier on OS X */ 351 public static final int CTRL = 5006; 352 /** Alt-Shift group */ 353 public static final int ALT_SHIFT = 5007; 354 /** Alt-Command group. Matches ALT-CTRL modifier on Windows/Linux but ALT-META modifier on OS X */ 355 public static final int ALT_CTRL = 5008; 356 /** Command-Shift group. Matches CTRL-SHIFT modifier on Windows/Linux but META-SHIFT modifier on OS X */ 357 public static final int CTRL_SHIFT = 5009; 358 /** Alt-Command-Shift group. Matches ALT-CTRL-SHIFT modifier on Windows/Linux but ALT-META-SHIFT modifier on OS X */ 359 public static final int ALT_CTRL_SHIFT = 5010; 360 361 /* for reassignment */ 362 private static int[] mods = {ALT_CTRL, ALT_SHIFT, CTRL_SHIFT, ALT_CTRL_SHIFT}; 363 private static int[] keys = {KeyEvent.VK_F1, KeyEvent.VK_F2, KeyEvent.VK_F3, KeyEvent.VK_F4, 364 KeyEvent.VK_F5, KeyEvent.VK_F6, KeyEvent.VK_F7, KeyEvent.VK_F8, 365 KeyEvent.VK_F9, KeyEvent.VK_F10, KeyEvent.VK_F11, KeyEvent.VK_F12}; 366 367 // bootstrap 368 private static boolean initdone; 369 private static void doInit() { 370 if (initdone) return; 371 initdone = true; 372 int commandDownMask = Main.platform.getMenuShortcutKeyMaskEx(); 373 groups.put(NONE, -1); 374 groups.put(MNEMONIC, KeyEvent.ALT_DOWN_MASK); 375 groups.put(DIRECT, 0); 376 groups.put(ALT, KeyEvent.ALT_DOWN_MASK); 377 groups.put(SHIFT, KeyEvent.SHIFT_DOWN_MASK); 378 groups.put(CTRL, commandDownMask); 379 groups.put(ALT_SHIFT, KeyEvent.ALT_DOWN_MASK | KeyEvent.SHIFT_DOWN_MASK); 380 groups.put(ALT_CTRL, KeyEvent.ALT_DOWN_MASK | commandDownMask); 381 groups.put(CTRL_SHIFT, commandDownMask | KeyEvent.SHIFT_DOWN_MASK); 382 groups.put(ALT_CTRL_SHIFT, KeyEvent.ALT_DOWN_MASK | commandDownMask | KeyEvent.SHIFT_DOWN_MASK); 383 384 // (1) System reserved shortcuts 385 Main.platform.initSystemShortcuts(); 386 // (2) User defined shortcuts 387 Main.pref.getAllPrefixCollectionKeys("shortcut.entry.").stream() 388 .map(Shortcut::new) 389 .filter(sc -> !findShortcut(sc.getAssignedKey(), sc.getAssignedModifier()).isPresent()) 390 .sorted(Comparator.comparing(sc -> sc.isAssignedUser() ? 1 : sc.isAssignedDefault() ? 2 : 3)) 391 .forEachOrdered(shortcuts::replace); 392 } 393 394 private static int getGroupModifier(int group) { 395 return Optional.ofNullable(groups.get(group)).orElse(-1); 396 } 397 398 private static int findModifier(int group, Integer modifier) { 399 if (modifier == null) { 400 modifier = getGroupModifier(group); 401 if (modifier == null) { // garbage in, no shortcut out 402 modifier = getGroupModifier(NONE); 403 } 404 } 405 return modifier; 406 } 407 408 // shutdown handling 409 public static boolean savePrefs() { 410 return shortcuts.stream() 411 .map(Shortcut::save) 412 .reduce(Boolean.FALSE, Boolean::logicalOr); // has changed 413 } 414 415 /** 416 * FOR PLATFORMHOOK USE ONLY. 417 * <p> 418 * This registers a system shortcut. See PlatformHook for details. 419 * @param shortText an ID. re-use a {@code "system:*"} ID if possible, else use something unique. 420 * @param longText this will be displayed in the shortcut preferences dialog. Better 421 * use something the user will recognize... 422 * @param key the key. Use a {@link KeyEvent KeyEvent.VK_*} constant here. 423 * @param modifier the modifier. Use a {@link KeyEvent KeyEvent.*_MASK} constant here. 424 * @return the system shortcut 425 */ 426 public static Shortcut registerSystemShortcut(String shortText, String longText, int key, int modifier) { 427 final Optional<Shortcut> existing = findShortcutByKeyOrShortText(key, modifier, shortText); 428 if (existing.isPresent() && shortText.equals(existing.get().getShortText())) { 429 return existing.get(); 430 } else if (existing.isPresent()) { 431 // this always is a logic error in the hook 432 Logging.error("CONFLICT WITH SYSTEM KEY " + shortText + ": " + existing.get()); 433 return null; 434 } 435 final Shortcut shortcut = new Shortcut(shortText, longText, key, RESERVED, key, modifier, true, false); 436 shortcuts.add(shortcut); 437 return shortcut; 438 } 439 440 /** 441 * Register a shortcut. 442 * 443 * Here you get your shortcuts from. The parameters are: 444 * 445 * @param shortText an ID. re-use a {@code "system:*"} ID if possible, else use something unique. 446 * {@code "menu:*"} is reserved for menu mnemonics, {@code "core:*"} is reserved for 447 * actions that are part of JOSM's core. Use something like 448 * {@code <pluginname>+":"+<actionname>}. 449 * @param longText this will be displayed in the shortcut preferences dialog. Better 450 * use something the user will recognize... 451 * @param requestedKey the key you'd prefer. Use a {@link KeyEvent KeyEvent.VK_*} constant here. 452 * @param requestedGroup the group this shortcut fits best. This will determine the 453 * modifiers your shortcut will get assigned. Use the constants defined above. 454 * @return the shortcut 455 */ 456 public static Shortcut registerShortcut(String shortText, String longText, int requestedKey, int requestedGroup) { 457 return registerShortcut(shortText, longText, requestedKey, requestedGroup, null); 458 } 459 460 // and now the workhorse. same parameters as above, just one more 461 private static Shortcut registerShortcut(String shortText, String longText, int requestedKey, int requestedGroup, Integer modifier) { 462 doInit(); 463 Integer defaultModifier = findModifier(requestedGroup, modifier); 464 final Optional<Shortcut> existing = findShortcutByKeyOrShortText(requestedKey, defaultModifier, shortText); 465 if (existing.isPresent() && shortText.equals(existing.get().getShortText())) { 466 // a re-register? maybe a sc already read from the preferences? 467 final Shortcut sc = existing.get(); 468 sc.setLongText(longText); // or set by the platformHook, in this case the original longText doesn't match the real action 469 sc.saveDefault(); 470 return sc; 471 } else if (existing.isPresent()) { 472 final Shortcut conflict = existing.get(); 473 if (Main.isPlatformOsx()) { 474 // Try to reassign Meta to Ctrl 475 int newmodifier = findNewOsxModifier(requestedGroup); 476 if (!findShortcut(requestedKey, newmodifier).isPresent()) { 477 Logging.info("Reassigning OSX shortcut '" + shortText + "' from Meta to Ctrl because of conflict with " + conflict); 478 return reassignShortcut(shortText, longText, requestedKey, conflict, requestedGroup, requestedKey, newmodifier); 479 } 480 } 481 for (int m : mods) { 482 for (int k : keys) { 483 int newmodifier = getGroupModifier(m); 484 if (!findShortcut(k, newmodifier).isPresent()) { 485 Logging.info("Reassigning shortcut '" + shortText + "' from " + modifier + " to " + newmodifier + 486 " because of conflict with " + conflict); 487 return reassignShortcut(shortText, longText, requestedKey, conflict, m, k, newmodifier); 488 } 489 } 490 } 491 } else { 492 Shortcut newsc = new Shortcut(shortText, longText, requestedKey, requestedGroup, requestedKey, defaultModifier, true, false); 493 newsc.saveDefault(); 494 shortcuts.add(newsc); 495 return newsc; 496 } 497 498 return null; 499 } 500 501 private static int findNewOsxModifier(int requestedGroup) { 502 switch (requestedGroup) { 503 case CTRL: return KeyEvent.CTRL_DOWN_MASK; 504 case ALT_CTRL: return KeyEvent.ALT_DOWN_MASK | KeyEvent.CTRL_DOWN_MASK; 505 case CTRL_SHIFT: return KeyEvent.CTRL_DOWN_MASK | KeyEvent.SHIFT_DOWN_MASK; 506 case ALT_CTRL_SHIFT: return KeyEvent.ALT_DOWN_MASK | KeyEvent.CTRL_DOWN_MASK | KeyEvent.SHIFT_DOWN_MASK; 507 default: return 0; 508 } 509 } 510 511 private static Shortcut reassignShortcut(String shortText, String longText, int requestedKey, Shortcut conflict, 512 int m, int k, int newmodifier) { 513 Shortcut newsc = new Shortcut(shortText, longText, requestedKey, m, k, newmodifier, false, false); 514 Logging.info(tr("Silent shortcut conflict: ''{0}'' moved by ''{1}'' to ''{2}''.", 515 shortText, conflict.getShortText(), newsc.getKeyText())); 516 newsc.saveDefault(); 517 shortcuts.add(newsc); 518 return newsc; 519 } 520 521 /** 522 * Replies the platform specific key stroke for the 'Copy' command, i.e. 523 * 'Ctrl-C' on windows or 'Meta-C' on a Mac. null, if the platform specific 524 * copy command isn't known. 525 * 526 * @return the platform specific key stroke for the 'Copy' command 527 */ 528 public static KeyStroke getCopyKeyStroke() { 529 return getKeyStrokeForShortKey("system:copy"); 530 } 531 532 /** 533 * Replies the platform specific key stroke for the 'Paste' command, i.e. 534 * 'Ctrl-V' on windows or 'Meta-V' on a Mac. null, if the platform specific 535 * paste command isn't known. 536 * 537 * @return the platform specific key stroke for the 'Paste' command 538 */ 539 public static KeyStroke getPasteKeyStroke() { 540 return getKeyStrokeForShortKey("system:paste"); 541 } 542 543 /** 544 * Replies the platform specific key stroke for the 'Cut' command, i.e. 545 * 'Ctrl-X' on windows or 'Meta-X' on a Mac. null, if the platform specific 546 * 'Cut' command isn't known. 547 * 548 * @return the platform specific key stroke for the 'Cut' command 549 */ 550 public static KeyStroke getCutKeyStroke() { 551 return getKeyStrokeForShortKey("system:cut"); 552 } 553 554 private static KeyStroke getKeyStrokeForShortKey(String shortKey) { 555 return shortcuts.stream() 556 .filter(sc -> shortKey.equals(sc.getShortText())) 557 .findAny() 558 .map(Shortcut::getKeyStroke) 559 .orElse(null); 560 } 561}