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</code>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);</code> 38 * <p> or alternatively 39 * <p> 40 * <code>MenuShortcut ms = new MenuShortcut(KeyEvent.getExtendedKeyCodeForChar('A'), false);</code> 41 * <p> 42 * Menu shortcuts may also be constructed for a wider set of keycodes 43 * using the <code>java.awt.event.KeyEvent.getExtendedKeyCodeForChar</code> 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</code> 49 * work regardless of the current keyboard layout. However, a shortcut made of 50 * an extended keycode not listed in <code>KeyEvent</code> 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</code> if this MenuShortcut must be invoked using the 132 * SHIFT key, <code>false</code> 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</code> if this MenuShortcut is the same as another, 145 * <code>false</code> 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</code> if this MenuShortcut is the same as another, 159 * <code>false</code> 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 public String toString() { 184 int modifiers = 0; 185 if (!GraphicsEnvironment.isHeadless()) { 186 modifiers = Toolkit.getDefaultToolkit().getMenuShortcutKeyMask(); 187 } 188 if (usesShiftModifier()) { 189 modifiers |= Event.SHIFT_MASK; 190 } 191 return KeyEvent.getKeyModifiersText(modifiers) + "+" + 192 KeyEvent.getKeyText(key); 193 } 194 195 /** 196 * Returns the parameter string representing the state of this 197 * MenuShortcut. This string is useful for debugging. 198 * @return the parameter string of this MenuShortcut. 199 * @since 1.1 200 */ 201 protected String paramString() { 202 String str = "key=" + key; 203 if (usesShiftModifier()) { 204 str += ",usesShiftModifier"; 205 } 206 return str; 207 } 208 }