001 /* InputMap.java --
002 Copyright (C) 2002, 2004, 2006, Free Software Foundation, Inc.
003
004 This file is part of GNU Classpath.
005
006 GNU Classpath is free software; you can redistribute it and/or modify
007 it under the terms of the GNU General Public License as published by
008 the Free Software Foundation; either version 2, or (at your option)
009 any later version.
010
011 GNU Classpath is distributed in the hope that it will be useful, but
012 WITHOUT ANY WARRANTY; without even the implied warranty of
013 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014 General Public License for more details.
015
016 You should have received a copy of the GNU General Public License
017 along with GNU Classpath; see the file COPYING. If not, write to the
018 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
019 02110-1301 USA.
020
021 Linking this library statically or dynamically with other modules is
022 making a combined work based on this library. Thus, the terms and
023 conditions of the GNU General Public License cover the whole
024 combination.
025
026 As a special exception, the copyright holders of this library give you
027 permission to link this library with independent modules to produce an
028 executable, regardless of the license terms of these independent
029 modules, and to copy and distribute the resulting executable under
030 terms of your choice, provided that you also meet, for each linked
031 independent module, the terms and conditions of the license of that
032 module. An independent module is a module which is not derived from
033 or based on this library. If you modify this library, you may extend
034 this exception to your version of the library, but you are not
035 obligated to do so. If you do not wish to do so, delete this
036 exception statement from your version. */
037
038 package javax.swing;
039
040 import java.io.Serializable;
041 import java.util.Arrays;
042 import java.util.HashMap;
043 import java.util.HashSet;
044 import java.util.Map;
045 import java.util.Set;
046
047 /**
048 * Maps {@link KeyStroke}s to arbitrary objects, usually Strings. This
049 * is used in combination with {@link ActionMap}s.
050 *
051 * If a component receives an input event, this is looked up in
052 * the component's <code>InputMap</code>. The result is an object which
053 * serves as a key to the component's <code>ActionMap</code>. Finally
054 * the <code>Action</code> that is stored is executed.
055 *
056 * @author Andrew Selkirk
057 * @author Michael Koch
058 *
059 * @since 1.3
060 */
061 public class InputMap
062 implements Serializable
063 {
064 private static final long serialVersionUID = -5429059542008604257L;
065
066 /**
067 * Storage for the KeyStroke --> Object mappings.
068 */
069 private Map inputMap;
070
071 /**
072 * An optional parent map.
073 */
074 private InputMap parent;
075
076 /**
077 * Creates a new <code>InputMap</code> instance. This default instance
078 * contains no mappings and has no parent.
079 */
080 public InputMap()
081 {
082 // nothing to do
083 }
084
085 /**
086 * Returns the binding for the specified keystroke, if there is one.
087 *
088 * @param keystroke the key of the entry (<code>null</code> is ignored).
089 *
090 * @return The binding associated with the specified keystroke (or
091 * <code>null</code>).
092 */
093 public Object get(KeyStroke keystroke)
094 {
095 Object result = null;
096 if (inputMap != null)
097 result = inputMap.get(keystroke);
098
099 if (result == null && parent != null)
100 result = parent.get(keystroke);
101 return result;
102 }
103
104 /**
105 * Puts a new entry into the <code>InputMap</code>. If
106 * <code>actionMapKey</code> is <code>null</code> any existing entry will be
107 * removed.
108 *
109 * @param keystroke the keystroke for the entry (<code>null</code> is
110 * ignored).
111 * @param actionMapKey the action (<code>null</code> permitted).
112 */
113 public void put(KeyStroke keystroke, Object actionMapKey)
114 {
115 if (keystroke == null)
116 return;
117 if (inputMap == null)
118 inputMap = new HashMap();
119 if (actionMapKey == null)
120 inputMap.remove(keystroke);
121 else
122 inputMap.put(keystroke, actionMapKey);
123 }
124
125 /**
126 * Removes an entry from this <code>InputMap</code>. Note that this will
127 * not remove any entry from the parent map, if there is one.
128 *
129 * @param keystroke the key of the entry to remove (<code>null</code> is
130 * ignored).
131 */
132 public void remove(KeyStroke keystroke)
133 {
134 if (inputMap != null)
135 inputMap.remove(keystroke);
136 }
137
138 /**
139 * Returns the parent of this <code>InputMap</code>. The default value
140 * is <code>null</code>.
141 *
142 * @return The parent map (possibly <code>null</code>).
143 *
144 * @see #setParent(InputMap)
145 */
146 public InputMap getParent()
147 {
148 return parent;
149 }
150
151 /**
152 * Sets a parent for this <code>InputMap</code>. If a parent is specified,
153 * the {@link #get(KeyStroke)} method will look in the parent if it cannot
154 * find an entry in this map.
155 *
156 * @param parentMap the new parent (<code>null</code> permitted).
157 *
158 * @see #getParent()
159 */
160 public void setParent(InputMap parentMap)
161 {
162 parent = parentMap;
163 }
164
165 /**
166 * Returns the number of entries in this <code>InputMap</code>. This count
167 * does not include any entries from the parent map, if there is one.
168 *
169 * @return The number of entries.
170 */
171 public int size()
172 {
173 int result = 0;
174 if (inputMap != null)
175 result = inputMap.size();
176 return result;
177 }
178
179 /**
180 * Clears the entries from this <code>InputMap</code>. The parent map, if
181 * there is one, is not cleared.
182 */
183 public void clear()
184 {
185 if (inputMap != null)
186 inputMap.clear();
187 }
188
189 /**
190 * Returns all keys of entries in this <code>InputMap</code>. This does not
191 * include keys defined in the parent, if there is one (use the
192 * {@link #allKeys()} method for that case).
193 * <br><br>
194 * Following the behaviour of the reference implementation, this method will
195 * return <code>null</code> when no entries have been added to the map,
196 * and a zero length array if entries have been added but subsequently
197 * removed (or cleared) from the map.
198 *
199 * @return An array of keys (may be <code>null</code> or have zero length).
200 */
201 public KeyStroke[] keys()
202 {
203 if (inputMap != null)
204 {
205 KeyStroke[] array = new KeyStroke[size()];
206 return (KeyStroke[]) inputMap.keySet().toArray(array);
207 }
208 return null;
209 }
210
211 /**
212 * Returns all keys of entries in this <code>InputMap</code> and all its
213 * parents.
214 *
215 * @return An array of keys (may be <code>null</code> or have zero length).
216 */
217 public KeyStroke[] allKeys()
218 {
219 Set set = new HashSet();
220
221 if (parent != null)
222 {
223 Object[] parentKeys = parent.allKeys();
224 if (parentKeys != null)
225 set.addAll(Arrays.asList(parentKeys));
226 }
227 if (inputMap != null)
228 set.addAll(inputMap.keySet());
229 if (set.size() == 0)
230 return null;
231 KeyStroke[] array = new KeyStroke[set.size()];
232 return (KeyStroke[]) set.toArray(array);
233 }
234
235 }