src/com/googlecode/lanterna/gui2/Interactable.java

   1 /*
   2  * This file is part of lanterna (http://code.google.com/p/lanterna/).
   3  *
   4  * lanterna is free software: you can redistribute it and/or modify
   5  * it under the terms of the GNU Lesser General Public License as published by
   6  * the Free Software Foundation, either version 3 of the License, or
   7  * (at your option) any later version.
   8  *
   9  * This program is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12  * GNU Lesser General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU Lesser General Public License
  15  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  16  *
  17  * Copyright (C) 2010-2015 Martin
  18  */
  19 package com.googlecode.lanterna.gui2;
  20
  21 import com.googlecode.lanterna.TerminalPosition;
  22 import com.googlecode.lanterna.input.KeyStroke;
  23
  24 /**
  25  * This interface marks a component as able to receive keyboard input from the user. Components that do not implement
  26  * this interface in some way will not be able to receive input focus. Normally if you create a new component, you'll
  27  * probably want to extend from {@code AbstractInteractableComponent} instead of implementing this one directly.
  28  *
  29  * @see AbstractInteractableComponent
  30  * @author Martin
  31  */
  32 public interface Interactable extends Component {
  33     /**
  34      * Returns, in local coordinates, where to put the cursor on the screen when this component has focus. If null, the
  35      * cursor should be hidden. If you component is 5x1 and you want to have the cursor in the middle (when in focus),
  36      * return [2,0]. The GUI system will convert the position to global coordinates.
  37      * @return Coordinates of where to place the cursor when this component has focus
  38      */
  39     TerminalPosition getCursorLocation();
  40
  41     /**
  42      * Accepts a KeyStroke as input and processes this as a user input. Depending on what the component does with this
  43      * key-stroke, there are several results passed back to the GUI system that will decide what to do next. If the
  44      * event was not handled or ignored, {@code Result.UNHANDLED} should be returned. This will tell the GUI system that
  45      * the key stroke was not understood by this component and may be dealt with in another way. If event was processed
  46      * properly, it should return {@code Result.HANDLED}, which will make the GUI system stop processing this particular
  47      * key-stroke. Furthermore, if the component understood the key-stroke and would like to move focus to a different
  48      * component, there are the {@code Result.MOVE_FOCUS_*} values. This method should be invoking the input filter, if
  49      * it is set, to see if the input should be processed or not.
  50      * @param keyStroke What input was entered by the user
  51      * @return Result of processing the key-stroke
  52      */
  53     Result handleInput(KeyStroke keyStroke);
  54
  55     /**
  56      * Moves focus in the {@code BasePane} to this component. If the component has not been added to a {@code BasePane}
  57      * (i.e. a {@code Window} most of the time), does nothing.
  58      * @return Itself
  59      */
  60     Interactable takeFocus();
  61
  62     /**
  63      * Method called when this component gained keyboard focus.
  64      * @param direction What direction did the focus come from
  65      * @param previouslyInFocus Which component had focus previously ({@code null} if none)
  66      */
  67     void onEnterFocus(FocusChangeDirection direction, Interactable previouslyInFocus);
  68
  69     /**
  70      * Method called when keyboard focus moves away from this component
  71      * @param direction What direction is focus going in
  72      * @param nextInFocus Which component is receiving focus next (or {@code null} if none)
  73      */
  74     void onLeaveFocus(FocusChangeDirection direction, Interactable nextInFocus);
  75
  76     /**
  77      * Returns {@code true} if this component currently has input focus in its root container.
  78      * @return {@code true} if the interactable has input focus, {@code false} otherwise
  79      */
  80     boolean isFocused();
  81
  82     /**
  83      * Assigns an input filter to the interactable component. This will intercept any user input and decide if the input
  84      * should be passed on to the component or not. {@code null} means there is no filter.
  85      * @param inputFilter Input filter to assign to the interactable
  86      * @return Itself
  87      */
  88     Interactable setInputFilter(InputFilter inputFilter);
  89
  90     /**
  91      * Returns the input filter currently assigned to the interactable component. This will intercept any user input and
  92      * decide if the input should be passed on to the component or not. {@code null} means there is no filter.
  93      * @return Input filter currently assigned to the interactable component
  94      */
  95     InputFilter getInputFilter();
  96
  97     /**
  98      * Enum to represent the various results coming out of the handleKeyStroke method
  99      */
 100     enum Result {
 101         /**
 102          * This component didn't handle the key-stroke, either because it was not recognized or because it chose to
 103          * ignore it.
 104          */
 105         UNHANDLED,
 106         /**
 107          * This component has handled the key-stroke and it should be considered consumed.
 108          */
 109         HANDLED,
 110         /**
 111          * This component has handled the key-stroke and requests the GUI system to switch focus to next component in
 112          * an ordered list of components. This should generally be returned if moving focus by using the tab key.
 113          */
 114         MOVE_FOCUS_NEXT,
 115         /**
 116          * This component has handled the key-stroke and requests the GUI system to switch focus to previous component
 117          * in an ordered list of components. This should generally be returned if moving focus by using the reverse tab
 118          * key.
 119          */
 120         MOVE_FOCUS_PREVIOUS,
 121         /**
 122          * This component has handled the key-stroke and requests the GUI system to switch focus to next component in
 123          * the general left direction. By convention in Lanterna, if there is no component to the left, it will move up
 124          * instead. This should generally be returned if moving focus by using the left array key.
 125          */
 126         MOVE_FOCUS_LEFT,
 127         /**
 128          * This component has handled the key-stroke and requests the GUI system to switch focus to next component in
 129          * the general right direction. By convention in Lanterna, if there is no component to the right, it will move
 130          * down instead. This should generally be returned if moving focus by using the right array key.
 131          */
 132         MOVE_FOCUS_RIGHT,
 133         /**
 134          * This component has handled the key-stroke and requests the GUI system to switch focus to next component in
 135          * the general up direction. By convention in Lanterna, if there is no component above, it will move left
 136          * instead. This should generally be returned if moving focus by using the up array key.
 137          */
 138         MOVE_FOCUS_UP,
 139         /**
 140          * This component has handled the key-stroke and requests the GUI system to switch focus to next component in
 141          * the general down direction. By convention in Lanterna, if there is no component below, it will move up
 142          * instead. This should generally be returned if moving focus by using the down array key.
 143          */
 144         MOVE_FOCUS_DOWN,
 145         ;
 146     }
 147
 148     /**
 149      * When focus has changed, which direction.
 150      */
 151     enum FocusChangeDirection {
 152         /**
 153          * The next interactable component, going down. This direction usually comes from the user pressing down array.
 154          */
 155         DOWN,
 156         /**
 157          * The next interactable component, going right. This direction usually comes from the user pressing right array.
 158          */
 159         RIGHT,
 160         /**
 161          * The next interactable component, going up. This direction usually comes from the user pressing up array.
 162          */
 163         UP,
 164         /**
 165          * The next interactable component, going left. This direction usually comes from the user pressing left array.
 166          */
 167         LEFT,
 168         /**
 169          * The next interactable component, in layout manager order (usually left-&gt;right, up-&gt;down). This direction
 170          * usually comes from the user pressing tab key.
 171          */
 172         NEXT,
 173         /**
 174          * The previous interactable component, reversed layout manager order (usually right-&gt;left, down-&gt;up). This
 175          * direction usually comes from the user pressing shift and tab key (reverse tab).
 176          */
 177         PREVIOUS,
 178         /**
 179          * Focus was changed by calling the {@code RootContainer.setFocusedInteractable(..)} method directly.
 180          */
 181         TELEPORT,
 182         /**
 183          * Focus has gone away and no component is now in focus
 184          */
 185         RESET,
 186         ;
 187     }
 188 }