[jvcard.git] / src / com / googlecode / lanterna / gui2 / Component.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.TerminalSize;

/**
 * This is the main interface defining a component in Lanterna, although you will probably not implement this directly
 * but rather extend the {@code AbstractComponent} or another one of the sub-classes instead to avoid implementing most
 * of the methods in this interface.
 * @author Martin
 */
public interface Component extends TextGUIElement {
    /**
     * Returns the top-left corner of this component, measured from its parent.
     * @return Position of this component
     */
    TerminalPosition getPosition();

    /**
     * This method will be called by the layout manager when it has decided where the component is to be located. If you
     * call this method yourself, prepare for unexpected results.
     * @param position Top-left position of the component, relative to its parent
     * @return Itself
     */
    Component setPosition(TerminalPosition position);

    /**
     * Returns how large this component is. If the layout manager has not yet laid this component out, it will return
     * an empty size (0x0)
     * @return How large this component is
     */
    TerminalSize getSize();

    /**
     * This method will be called by the layout manager when it has decided how large the component will be. If you call
     * this method yourself, prepare for unexpected results.
     * @param size Current size of the component
     * @return Itself
     */
    Component setSize(TerminalSize size);

    /**
     * Returns the ideal size this component would like to have, in order to draw itself properly. There are no
     * guarantees the GUI system will decide to give it this size though.
     * @return Size we would like to be
     */
    TerminalSize getPreferredSize();


    /**
     * Overrides the components preferred size calculation and makes the {@code getPreferredSize()} always return the
     * value passed in here. If you call this will {@code null}, it will re-enable the preferred size calculation again.
     * Please note that using this method on components that are not designed to work with arbitrary sizes make have
     * unexpected behaviour.
     * @param explicitPreferredSize Preferred size we want to use for this component
     * @return Itself
     */
    Component setPreferredSize(TerminalSize explicitPreferredSize);

    /**
     * Sets optional layout data associated with this component. This meaning of this data is up to the layout manager
     * to figure out, see each layout manager for examples of how to use it.
     * @param data Layout data associated with this component
     * @return Itself
     */
    Component setLayoutData(LayoutData data);

    /**
     * Returns the layout data associated with this component. This data will optionally be used by the layout manager,
     * see the documentation for each layout manager for more details on valid values and their meaning.
     * @return This component's layout data
     */
    LayoutData getLayoutData();
    
    /**
     * Returns the container which is holding this container, or {@code null} if it's not assigned to anything.
     * @return Parent container or null
     */
    Container getParent();

    /**
     * Returns {@code true} if the supplied Container is either the direct or indirect Parent of this component.
     * @param parent Container to test if it's the parent or grand-parent of this component
     * @return {@code true} if the container is either the direct or indirect parent of this component, otherwise {@code false}
     */
    boolean hasParent(Container parent);
    
    /**
     * Returns the TextGUI that this component is currently part of. If the component hasn't been added to any container
     * or in any other way placed into a GUI system, this method will return null.
     * @return The TextGUI that this component belongs to, or null if none
     */
    TextGUI getTextGUI();
    
    /**
     * Returns true if this component is inside of the specified Container. It might be a direct child or not, this 
     * method makes no difference. If {@code getParent()} is not the same instance as {@code container}, but if this 
     * method returns true, you can be sure that this component is not a direct child.
     * @param container Container to test if this component is inside
     * @return True if this component is contained in some way within the {@code container}
     */
    boolean isInside(Container container);

    /**
     * Returns the renderer used to draw this component and measure its preferred size. You probably won't need to call
     * this method unless you know exactly which ComponentRenderer implementation is used and you need to customize it.
     * @return Renderer this component is using
     */
    ComponentRenderer<? extends Component> getRenderer();

    /**
     * Marks the component as invalid and requiring to be re-drawn at next opportunity. Container components should take
     * this as a hint to layout the child components again.
     */
    void invalidate();
    
    /**
     * Takes a border object and moves this component inside it and then returns it again. This makes it easy to quickly
     * wrap a component on creation, like this:
     * <pre>
     * container.addComponent(new Button("Test").withBorder(Borders.singleLine()));
     * </pre>
     * @param border
     * @return 
     */
    Border withBorder(Border border);
    
    /**
     * Translates a position local to the container to the base pane's coordinate space. For a window-based GUI, this 
     * be a coordinate in the window's coordinate space. If the component belongs to no base pane, it will return
     * {@code null}.
     * @param position Position to translate (relative to the container's top-left corner)
     * @return Position in base pane space, or {@code null} if the component is an orphan
     */
    TerminalPosition toBasePane(TerminalPosition position);

    /**
     * Translates a position local to the container to global coordinate space. This should be the absolute coordinate
     * in the terminal screen, taking no windows or containers into account. If the component belongs to no base pane,
     * it will return {@code null}.
     * @param position Position to translate (relative to the container's top-left corner)
     * @return Position in global (or absolute) coordinates, or {@code null} if the component is an orphan
     */
    TerminalPosition toGlobal(TerminalPosition position);

    /**
     * Returns the BasePane that this container belongs to. In a window-based GUI system, this will be a Window.
     * @return The base pane this component is placed on, or {@code null} if none
     */
    BasePane getBasePane();

    /**
     * Same as calling {@code panel.addComponent(thisComponent)}
     * @param panel Panel to add this component to
     * @return Itself
     */
    Component addTo(Panel panel);
    
    /**
     * Called by the GUI system when you add a component to a container; DO NOT CALL THIS YOURSELF! 
     * @param container Container that this component was just added to
     */
    void onAdded(Container container);
    
    /**
     * Called by the GUI system when you remove a component from a container; DO NOT CALL THIS YOURSELF! 
     * @param container Container that this component was just removed from
     */
    void onRemoved(Container container);
}
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.TerminalSize;
	23
	24	/**
	25	* This is the main interface defining a component in Lanterna, although you will probably not implement this directly
	26	* but rather extend the {@code AbstractComponent} or another one of the sub-classes instead to avoid implementing most
	27	* of the methods in this interface.
	28	* @author Martin
	29	*/
	30	public interface Component extends TextGUIElement {
	31	/**
	32	* Returns the top-left corner of this component, measured from its parent.
	33	* @return Position of this component
	34	*/
	35	TerminalPosition getPosition();
	36
	37	/**
	38	* This method will be called by the layout manager when it has decided where the component is to be located. If you
	39	* call this method yourself, prepare for unexpected results.
	40	* @param position Top-left position of the component, relative to its parent
	41	* @return Itself
	42	*/
	43	Component setPosition(TerminalPosition position);
	44
	45	/**
	46	* Returns how large this component is. If the layout manager has not yet laid this component out, it will return
	47	* an empty size (0x0)
	48	* @return How large this component is
	49	*/
	50	TerminalSize getSize();
	51
	52	/**
	53	* This method will be called by the layout manager when it has decided how large the component will be. If you call
	54	* this method yourself, prepare for unexpected results.
	55	* @param size Current size of the component
	56	* @return Itself
	57	*/
	58	Component setSize(TerminalSize size);
	59
	60	/**
	61	* Returns the ideal size this component would like to have, in order to draw itself properly. There are no
	62	* guarantees the GUI system will decide to give it this size though.
	63	* @return Size we would like to be
	64	*/
	65	TerminalSize getPreferredSize();
	66
	67
	68	/**
	69	* Overrides the components preferred size calculation and makes the {@code getPreferredSize()} always return the
	70	* value passed in here. If you call this will {@code null}, it will re-enable the preferred size calculation again.
	71	* Please note that using this method on components that are not designed to work with arbitrary sizes make have
	72	* unexpected behaviour.
	73	* @param explicitPreferredSize Preferred size we want to use for this component
	74	* @return Itself
	75	*/
	76	Component setPreferredSize(TerminalSize explicitPreferredSize);
	77
	78	/**
	79	* Sets optional layout data associated with this component. This meaning of this data is up to the layout manager
	80	* to figure out, see each layout manager for examples of how to use it.
	81	* @param data Layout data associated with this component
	82	* @return Itself
	83	*/
	84	Component setLayoutData(LayoutData data);
	85
	86	/**
	87	* Returns the layout data associated with this component. This data will optionally be used by the layout manager,
	88	* see the documentation for each layout manager for more details on valid values and their meaning.
	89	* @return This component's layout data
	90	*/
	91	LayoutData getLayoutData();
	92
	93	/**
	94	* Returns the container which is holding this container, or {@code null} if it's not assigned to anything.
	95	* @return Parent container or null
	96	*/
	97	Container getParent();
	98
	99	/**
	100	* Returns {@code true} if the supplied Container is either the direct or indirect Parent of this component.
	101	* @param parent Container to test if it's the parent or grand-parent of this component
	102	* @return {@code true} if the container is either the direct or indirect parent of this component, otherwise {@code false}
	103	*/
	104	boolean hasParent(Container parent);
	105
	106	/**
	107	* Returns the TextGUI that this component is currently part of. If the component hasn't been added to any container
	108	* or in any other way placed into a GUI system, this method will return null.
	109	* @return The TextGUI that this component belongs to, or null if none
	110	*/
	111	TextGUI getTextGUI();
	112
	113	/**
	114	* Returns true if this component is inside of the specified Container. It might be a direct child or not, this
	115	* method makes no difference. If {@code getParent()} is not the same instance as {@code container}, but if this
	116	* method returns true, you can be sure that this component is not a direct child.
	117	* @param container Container to test if this component is inside
	118	* @return True if this component is contained in some way within the {@code container}
	119	*/
	120	boolean isInside(Container container);
	121
	122	/**
	123	* Returns the renderer used to draw this component and measure its preferred size. You probably won't need to call
	124	* this method unless you know exactly which ComponentRenderer implementation is used and you need to customize it.
	125	* @return Renderer this component is using
	126	*/
	127	ComponentRenderer<? extends Component> getRenderer();
	128
	129	/**
	130	* Marks the component as invalid and requiring to be re-drawn at next opportunity. Container components should take
	131	* this as a hint to layout the child components again.
	132	*/
	133	void invalidate();
	134
	135	/**
	136	* Takes a border object and moves this component inside it and then returns it again. This makes it easy to quickly
	137	* wrap a component on creation, like this:
	138	* <pre>
	139	* container.addComponent(new Button("Test").withBorder(Borders.singleLine()));
	140	* </pre>
	141	* @param border
	142	* @return
	143	*/
	144	Border withBorder(Border border);
	145
	146	/**
	147	* Translates a position local to the container to the base pane's coordinate space. For a window-based GUI, this
	148	* be a coordinate in the window's coordinate space. If the component belongs to no base pane, it will return
	149	* {@code null}.
	150	* @param position Position to translate (relative to the container's top-left corner)
	151	* @return Position in base pane space, or {@code null} if the component is an orphan
	152	*/
	153	TerminalPosition toBasePane(TerminalPosition position);
	154
	155	/**
	156	* Translates a position local to the container to global coordinate space. This should be the absolute coordinate
	157	* in the terminal screen, taking no windows or containers into account. If the component belongs to no base pane,
	158	* it will return {@code null}.
	159	* @param position Position to translate (relative to the container's top-left corner)
	160	* @return Position in global (or absolute) coordinates, or {@code null} if the component is an orphan
	161	*/
	162	TerminalPosition toGlobal(TerminalPosition position);
	163
	164	/**
	165	* Returns the BasePane that this container belongs to. In a window-based GUI system, this will be a Window.
	166	* @return The base pane this component is placed on, or {@code null} if none
	167	*/
	168	BasePane getBasePane();
	169
	170	/**
	171	* Same as calling {@code panel.addComponent(thisComponent)}
	172	* @param panel Panel to add this component to
	173	* @return Itself
	174	*/
	175	Component addTo(Panel panel);
	176
	177	/**
	178	* Called by the GUI system when you add a component to a container; DO NOT CALL THIS YOURSELF!
	179	* @param container Container that this component was just added to
	180	*/
	181	void onAdded(Container container);
	182
	183	/**
	184	* Called by the GUI system when you remove a component from a container; DO NOT CALL THIS YOURSELF!
	185	* @param container Container that this component was just removed from
	186	*/
	187	void onRemoved(Container container);
	188	}