Commit | Line | Data |
---|---|---|
a3b510ab NR |
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->right, up->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->left, down->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 | } |