1 /* 2 * Copyright (c) 1996, 2009, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 package java.awt; 26 27 import java.awt.event.KeyEvent; 28 29 /** 30 * The {@code MenuShortcut} class represents a keyboard accelerator 31 * for a MenuItem. 32 * <p> 33 * Menu shortcuts are created using virtual keycodes, not characters. 34 * For example, a menu shortcut for Ctrl-a (assuming that Control is 35 * the accelerator key) would be created with code like the following: 36 * <p> 37 * {@code MenuShortcut ms = new MenuShortcut(KeyEvent.VK_A, false);} 38 * <p> or alternatively 39 * <p> 40 * {@code MenuShortcut ms = new MenuShortcut(KeyEvent.getExtendedKeyCodeForChar('A'), false);} 41 * <p> 42 * Menu shortcuts may also be constructed for a wider set of keycodes 43 * using the {@code java.awt.event.KeyEvent.getExtendedKeyCodeForChar} call. 44 * For example, a menu shortcut for "Ctrl+cyrillic ef" is created by 45 * <p> 46 * <code>MenuShortcut ms = new MenuShortcut(KeyEvent.getExtendedKeyCodeForChar('\u0444'), false);</code> 47 * <p> 48 * Note that shortcuts created with a keycode or an extended keycode defined as a constant in {@code KeyEvent} 49 * work regardless of the current keyboard layout. However, a shortcut made of 50 * an extended keycode not listed in {@code KeyEvent} 51 * only work if the current keyboard layout produces a corresponding letter. 52 * <p> 53 * The accelerator key is platform-dependent and may be obtained 54 * via {@link Toolkit#getMenuShortcutKeyMask}. 55 * 56 * @author Thomas Ball 57 * @since 1.1 58 */ 59 public class MenuShortcut implements java.io.Serializable 60 { 61 /** 62 * The virtual keycode for the menu shortcut. 63 * This is the keycode with which the menu shortcut will be created. 64 * Note that it is a virtual keycode, not a character, 65 * e.g. KeyEvent.VK_A, not 'a'. 66 * Note: in 1.1.x you must use setActionCommand() on a menu item 67 * in order for its shortcut to work, otherwise it will fire a null 68 * action command. 69 * 70 * @serial 71 * @see #getKey() 72 * @see #usesShiftModifier() 73 * @see java.awt.event.KeyEvent 74 * @since 1.1 75 */ 76 int key; 77 78 /** 79 * Indicates whether the shift key was pressed. 80 * If true, the shift key was pressed. 81 * If false, the shift key was not pressed 82 * 83 * @serial 84 * @see #usesShiftModifier() 85 * @since 1.1 86 */ 87 boolean usesShift; 88 89 /* 90 * JDK 1.1 serialVersionUID 91 */ 92 private static final long serialVersionUID = 143448358473180225L; 93 94 /** 95 * Constructs a new MenuShortcut for the specified virtual keycode. 96 * @param key the raw keycode for this MenuShortcut, as would be returned 97 * in the keyCode field of a {@link java.awt.event.KeyEvent KeyEvent} if 98 * this key were pressed. 99 * @see java.awt.event.KeyEvent 100 **/ 101 public MenuShortcut(int key) { 102 this(key, false); 103 } 104 105 /** 106 * Constructs a new MenuShortcut for the specified virtual keycode. 107 * @param key the raw keycode for this MenuShortcut, as would be returned 108 * in the keyCode field of a {@link java.awt.event.KeyEvent KeyEvent} if 109 * this key were pressed. 110 * @param useShiftModifier indicates whether this MenuShortcut is invoked 111 * with the SHIFT key down. 112 * @see java.awt.event.KeyEvent 113 **/ 114 public MenuShortcut(int key, boolean useShiftModifier) { 115 this.key = key; 116 this.usesShift = useShiftModifier; 117 } 118 119 /** 120 * Returns the raw keycode of this MenuShortcut. 121 * @return the raw keycode of this MenuShortcut. 122 * @see java.awt.event.KeyEvent 123 * @since 1.1 124 */ 125 public int getKey() { 126 return key; 127 } 128 129 /** 130 * Returns whether this MenuShortcut must be invoked using the SHIFT key. 131 * @return {@code true} if this MenuShortcut must be invoked using the 132 * SHIFT key, {@code false} otherwise. 133 * @since 1.1 134 */ 135 public boolean usesShiftModifier() { 136 return usesShift; 137 } 138 139 /** 140 * Returns whether this MenuShortcut is the same as another: 141 * equality is defined to mean that both MenuShortcuts use the same key 142 * and both either use or don't use the SHIFT key. 143 * @param s the MenuShortcut to compare with this. 144 * @return {@code true} if this MenuShortcut is the same as another, 145 * {@code false} otherwise. 146 * @since 1.1 147 */ 148 public boolean equals(MenuShortcut s) { 149 return (s != null && (s.getKey() == key) && 150 (s.usesShiftModifier() == usesShift)); 151 } 152 153 /** 154 * Returns whether this MenuShortcut is the same as another: 155 * equality is defined to mean that both MenuShortcuts use the same key 156 * and both either use or don't use the SHIFT key. 157 * @param obj the Object to compare with this. 158 * @return {@code true} if this MenuShortcut is the same as another, 159 * {@code false} otherwise. 160 * @since 1.2 161 */ 162 public boolean equals(Object obj) { 163 if (obj instanceof MenuShortcut) { 164 return equals( (MenuShortcut) obj ); 165 } 166 return false; 167 } 168 169 /** 170 * Returns the hashcode for this MenuShortcut. 171 * @return the hashcode for this MenuShortcut. 172 * @since 1.2 173 */ 174 public int hashCode() { 175 return (usesShift) ? (~key) : key; 176 } 177 178 /** 179 * Returns an internationalized description of the MenuShortcut. 180 * @return a string representation of this MenuShortcut. 181 * @since 1.1 182 */ 183 @SuppressWarnings("deprecation") 184 public String toString() { 185 int modifiers = 0; 186 if (!GraphicsEnvironment.isHeadless()) { 187 modifiers = Toolkit.getDefaultToolkit().getMenuShortcutKeyMask(); 188 } 189 if (usesShiftModifier()) { 190 modifiers |= Event.SHIFT_MASK; 191 } 192 return KeyEvent.getKeyModifiersText(modifiers) + "+" + 193 KeyEvent.getKeyText(key); 194 } 195 196 /** 197 * Returns the parameter string representing the state of this 198 * MenuShortcut. This string is useful for debugging. 199 * @return the parameter string of this MenuShortcut. 200 * @since 1.1 201 */ 202 protected String paramString() { 203 String str = "key=" + key; 204 if (usesShiftModifier()) { 205 str += ",usesShiftModifier"; 206 } 207 return str; 208 } 209 }