[jvcard.git] / src / com / googlecode / lanterna / gui2 / Interactable.java

/*
 * This file is part of lanterna (http://code.google.com/p/lanterna/).
 * 
 * lanterna is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 * 
 * Copyright (C) 2010-2015 Martin
 */
package com.googlecode.lanterna.gui2;

import com.googlecode.lanterna.TerminalPosition;
import com.googlecode.lanterna.input.KeyStroke;

/**
 * This interface marks a component as able to receive keyboard input from the user. Components that do not implement
 * this interface in some way will not be able to receive input focus. Normally if you create a new component, you'll
 * probably want to extend from {@code AbstractInteractableComponent} instead of implementing this one directly.
 *
 * @see AbstractInteractableComponent
 * @author Martin
 */
public interface Interactable extends Component {
    /**
     * Returns, in local coordinates, where to put the cursor on the screen when this component has focus. If null, the
     * cursor should be hidden. If you component is 5x1 and you want to have the cursor in the middle (when in focus),
     * return [2,0]. The GUI system will convert the position to global coordinates.
     * @return Coordinates of where to place the cursor when this component has focus
     */
    TerminalPosition getCursorLocation();

    /**
     * Accepts a KeyStroke as input and processes this as a user input. Depending on what the component does with this
     * key-stroke, there are several results passed back to the GUI system that will decide what to do next. If the
     * event was not handled or ignored, {@code Result.UNHANDLED} should be returned. This will tell the GUI system that
     * the key stroke was not understood by this component and may be dealt with in another way. If event was processed
     * properly, it should return {@code Result.HANDLED}, which will make the GUI system stop processing this particular
     * key-stroke. Furthermore, if the component understood the key-stroke and would like to move focus to a different
     * component, there are the {@code Result.MOVE_FOCUS_*} values. This method should be invoking the input filter, if
     * it is set, to see if the input should be processed or not.
     * @param keyStroke What input was entered by the user
     * @return Result of processing the key-stroke
     */
    Result handleInput(KeyStroke keyStroke);

    /**
     * Moves focus in the {@code BasePane} to this component. If the component has not been added to a {@code BasePane}
     * (i.e. a {@code Window} most of the time), does nothing.
     * @return Itself
     */
    Interactable takeFocus();

    /**
     * Method called when this component gained keyboard focus.
     * @param direction What direction did the focus come from
     * @param previouslyInFocus Which component had focus previously ({@code null} if none)
     */
    void onEnterFocus(FocusChangeDirection direction, Interactable previouslyInFocus);

    /**
     * Method called when keyboard focus moves away from this component
     * @param direction What direction is focus going in
     * @param nextInFocus Which component is receiving focus next (or {@code null} if none)
     */
    void onLeaveFocus(FocusChangeDirection direction, Interactable nextInFocus);

    /**
     * Returns {@code true} if this component currently has input focus in its root container.
     * @return {@code true} if the interactable has input focus, {@code false} otherwise
     */
    boolean isFocused();

    /**
     * Assigns an input filter to the interactable component. This will intercept any user input and decide if the input
     * should be passed on to the component or not. {@code null} means there is no filter.
     * @param inputFilter Input filter to assign to the interactable
     * @return Itself
     */
    Interactable setInputFilter(InputFilter inputFilter);

    /**
     * Returns the input filter currently assigned to the interactable component. This will intercept any user input and
     * decide if the input should be passed on to the component or not. {@code null} means there is no filter.
     * @return Input filter currently assigned to the interactable component
     */
    InputFilter getInputFilter();

    /**
     * Enum to represent the various results coming out of the handleKeyStroke method
     */
    enum Result {
        /**
         * This component didn't handle the key-stroke, either because it was not recognized or because it chose to
         * ignore it.
         */
        UNHANDLED,
        /**
         * This component has handled the key-stroke and it should be considered consumed.
         */
        HANDLED,
        /**
         * This component has handled the key-stroke and requests the GUI system to switch focus to next component in
         * an ordered list of components. This should generally be returned if moving focus by using the tab key.
         */
        MOVE_FOCUS_NEXT,
        /**
         * This component has handled the key-stroke and requests the GUI system to switch focus to previous component
         * in an ordered list of components. This should generally be returned if moving focus by using the reverse tab
         * key.
         */
        MOVE_FOCUS_PREVIOUS,
        /**
         * This component has handled the key-stroke and requests the GUI system to switch focus to next component in
         * the general left direction. By convention in Lanterna, if there is no component to the left, it will move up
         * instead. This should generally be returned if moving focus by using the left array key.
         */
        MOVE_FOCUS_LEFT,
        /**
         * This component has handled the key-stroke and requests the GUI system to switch focus to next component in
         * the general right direction. By convention in Lanterna, if there is no component to the right, it will move
         * down instead. This should generally be returned if moving focus by using the right array key.
         */
        MOVE_FOCUS_RIGHT,
        /**
         * This component has handled the key-stroke and requests the GUI system to switch focus to next component in
         * the general up direction. By convention in Lanterna, if there is no component above, it will move left
         * instead. This should generally be returned if moving focus by using the up array key.
         */
        MOVE_FOCUS_UP,
        /**
         * This component has handled the key-stroke and requests the GUI system to switch focus to next component in
         * the general down direction. By convention in Lanterna, if there is no component below, it will move up
         * instead. This should generally be returned if moving focus by using the down array key.
         */
        MOVE_FOCUS_DOWN,
        ;
    }

    /**
     * When focus has changed, which direction.
     */
    enum FocusChangeDirection {
        /**
         * The next interactable component, going down. This direction usually comes from the user pressing down array.
         */
        DOWN,
        /**
         * The next interactable component, going right. This direction usually comes from the user pressing right array.
         */
        RIGHT,
        /**
         * The next interactable component, going up. This direction usually comes from the user pressing up array.
         */
        UP,
        /**
         * The next interactable component, going left. This direction usually comes from the user pressing left array.
         */
        LEFT,
        /**
         * The next interactable component, in layout manager order (usually left-&gt;right, up-&gt;down). This direction
         * usually comes from the user pressing tab key.
         */
        NEXT,
        /**
         * The previous interactable component, reversed layout manager order (usually right-&gt;left, down-&gt;up). This
         * direction usually comes from the user pressing shift and tab key (reverse tab).
         */
        PREVIOUS,
        /**
         * Focus was changed by calling the {@code RootContainer.setFocusedInteractable(..)} method directly.
         */
        TELEPORT,
        /**
         * Focus has gone away and no component is now in focus
         */
        RESET,
        ;
    }
}
Commit	Line	Data
	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	}