Fix UTF8 bug, create first executable JAR file
[jvcard.git] / src / com / googlecode / lanterna / gui2 / Component.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.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 */
30public 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}