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.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 | } |