Fix UTF8 bug, create first executable JAR file
[jvcard.git] / src / com / googlecode / lanterna / gui2 / Interactable.java
... / ...
CommitLineData
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 */
19package com.googlecode.lanterna.gui2;
20
21import com.googlecode.lanterna.TerminalPosition;
22import 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 */
32public 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}