1 /*
   2  * Copyright (c) 1997, 2011, 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 javax.swing.text;
  26 
  27 import javax.swing.Action;
  28 import javax.swing.KeyStroke;
  29 
  30 /**
  31  * A collection of bindings of KeyStrokes to actions.  The
  32  * bindings are basically name-value pairs that potentially
  33  * resolve in a hierarchy.
  34  *
  35  * @author  Timothy Prinzing
  36  */
  37 public interface Keymap {
  38 
  39     /**
  40      * Fetches the name of the set of key-bindings.
  41      *
  42      * @return the name
  43      */
  44     public String getName();
  45 
  46     /**
  47      * Fetches the default action to fire if a
  48      * key is typed (i.e. a KEY_TYPED KeyEvent is received)
  49      * and there is no binding for it.  Typically this
  50      * would be some action that inserts text so that
  51      * the keymap doesn't require an action for each
  52      * possible key.
  53      *
  54      * @return the default action
  55      */
  56     public Action getDefaultAction();
  57 
  58     /**
  59      * Set the default action to fire if a key is typed.
  60      *
  61      * @param a the action
  62      */
  63     public void setDefaultAction(Action a);
  64 
  65     /**
  66      * Fetches the action appropriate for the given symbolic
  67      * event sequence.  This is used by JTextController to
  68      * determine how to interpret key sequences.  If the
  69      * binding is not resolved locally, an attempt is made
  70      * to resolve through the parent keymap, if one is set.
  71      *
  72      * @param key the key sequence
  73      * @return  the action associated with the key
  74      *  sequence if one is defined, otherwise <code>null</code>
  75      */
  76     public Action getAction(KeyStroke key);
  77 
  78     /**
  79      * Fetches all of the keystrokes in this map that
  80      * are bound to some action.
  81      *
  82      * @return the list of keystrokes
  83      */
  84     public KeyStroke[] getBoundKeyStrokes();
  85 
  86     /**
  87      * Fetches all of the actions defined in this keymap.
  88      *
  89      * @return the list of actions
  90      */
  91     public Action[] getBoundActions();
  92 
  93     /**
  94      * Fetches the keystrokes that will result in
  95      * the given action.
  96      *
  97      * @param a the action
  98      * @return the list of keystrokes
  99      */
 100     public KeyStroke[] getKeyStrokesForAction(Action a);
 101 
 102     /**
 103      * Determines if the given key sequence is locally defined.
 104      *
 105      * @param key the key sequence
 106      * @return true if the key sequence is locally defined else false
 107      */
 108     public boolean isLocallyDefined(KeyStroke key);
 109 
 110     /**
 111      * Adds a binding to the keymap.
 112      *
 113      * @param key the key sequence
 114      * @param a the action
 115      */
 116     public void addActionForKeyStroke(KeyStroke key, Action a);
 117 
 118     /**
 119      * Removes a binding from the keymap.
 120      *
 121      * @param keys the key sequence
 122      */
 123     public void removeKeyStrokeBinding(KeyStroke keys);
 124 
 125     /**
 126      * Removes all bindings from the keymap.
 127      */
 128     public void removeBindings();
 129 
 130     /**
 131      * Fetches the parent keymap used to resolve key-bindings.
 132      *
 133      * @return the keymap
 134      */
 135     public Keymap getResolveParent();
 136 
 137     /**
 138      * Sets the parent keymap, which will be used to
 139      * resolve key-bindings.
 140      * The behavior is unspecified if a {@code Keymap} has itself
 141      * as one of its resolve parents.
 142      *
 143      * @param parent the parent keymap
 144      */
 145     public void setResolveParent(Keymap parent);
 146 
 147 }