Fix comment
[fanfix.git] / src / jexer / backend / Screen.java
CommitLineData
42873e30
KL
1/*
2 * Jexer - Java Text User Interface
3 *
4 * The MIT License (MIT)
5 *
a69ed767 6 * Copyright (C) 2019 Kevin Lamonte
42873e30
KL
7 *
8 * Permission is hereby granted, free of charge, to any person obtaining a
9 * copy of this software and associated documentation files (the "Software"),
10 * to deal in the Software without restriction, including without limitation
11 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
12 * and/or sell copies of the Software, and to permit persons to whom the
13 * Software is furnished to do so, subject to the following conditions:
14 *
15 * The above copyright notice and this permission notice shall be included in
16 * all copies or substantial portions of the Software.
17 *
18 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
19 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
20 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
21 * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
22 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
23 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
24 * DEALINGS IN THE SOFTWARE.
25 *
26 * @author Kevin Lamonte [kevin.lamonte@gmail.com]
27 * @version 1
28 */
29package jexer.backend;
30
31import jexer.bits.Cell;
32import jexer.bits.CellAttributes;
33
34/**
35 * Drawing operations API.
36 */
37public interface Screen {
38
39 /**
40 * Set drawing offset for x.
41 *
42 * @param offsetX new drawing offset
43 */
44 public void setOffsetX(final int offsetX);
45
46 /**
47 * Set drawing offset for y.
48 *
49 * @param offsetY new drawing offset
50 */
51 public void setOffsetY(final int offsetY);
52
53 /**
54 * Get right drawing clipping boundary.
55 *
56 * @return drawing boundary
57 */
58 public int getClipRight();
59
60 /**
61 * Set right drawing clipping boundary.
62 *
63 * @param clipRight new boundary
64 */
65 public void setClipRight(final int clipRight);
66
67 /**
68 * Get bottom drawing clipping boundary.
69 *
70 * @return drawing boundary
71 */
72 public int getClipBottom();
73
74 /**
75 * Set bottom drawing clipping boundary.
76 *
77 * @param clipBottom new boundary
78 */
79 public void setClipBottom(final int clipBottom);
80
81 /**
82 * Get left drawing clipping boundary.
83 *
84 * @return drawing boundary
85 */
86 public int getClipLeft();
87
88 /**
89 * Set left drawing clipping boundary.
90 *
91 * @param clipLeft new boundary
92 */
93 public void setClipLeft(final int clipLeft);
94
95 /**
96 * Get top drawing clipping boundary.
97 *
98 * @return drawing boundary
99 */
100 public int getClipTop();
101
102 /**
103 * Set top drawing clipping boundary.
104 *
105 * @param clipTop new boundary
106 */
107 public void setClipTop(final int clipTop);
108
109 /**
110 * Get dirty flag.
111 *
112 * @return if true, the logical screen is not in sync with the physical
113 * screen
114 */
115 public boolean isDirty();
116
117 /**
118 * Get the attributes at one location.
119 *
120 * @param x column coordinate. 0 is the left-most column.
121 * @param y row coordinate. 0 is the top-most row.
122 * @return attributes at (x, y)
123 */
124 public CellAttributes getAttrXY(final int x, final int y);
125
3e074355
KL
126 /**
127 * Get the cell at one location.
128 *
129 * @param x column coordinate. 0 is the left-most column.
130 * @param y row coordinate. 0 is the top-most row.
131 * @return the character + attributes
132 */
133 public Cell getCharXY(final int x, final int y);
134
42873e30
KL
135 /**
136 * Set the attributes at one location.
137 *
138 * @param x column coordinate. 0 is the left-most column.
139 * @param y row coordinate. 0 is the top-most row.
140 * @param attr attributes to use (bold, foreColor, backColor)
141 */
142 public void putAttrXY(final int x, final int y,
143 final CellAttributes attr);
144
145 /**
146 * Set the attributes at one location.
147 *
148 * @param x column coordinate. 0 is the left-most column.
149 * @param y row coordinate. 0 is the top-most row.
150 * @param attr attributes to use (bold, foreColor, backColor)
151 * @param clip if true, honor clipping/offset
152 */
153 public void putAttrXY(final int x, final int y,
154 final CellAttributes attr, final boolean clip);
155
156 /**
157 * Fill the entire screen with one character with attributes.
158 *
159 * @param ch character to draw
160 * @param attr attributes to use (bold, foreColor, backColor)
161 */
162 public void putAll(final char ch, final CellAttributes attr);
163
164 /**
165 * Render one character with attributes.
166 *
167 * @param x column coordinate. 0 is the left-most column.
168 * @param y row coordinate. 0 is the top-most row.
169 * @param ch character + attributes to draw
170 */
171 public void putCharXY(final int x, final int y, final Cell ch);
172
173 /**
174 * Render one character with attributes.
175 *
176 * @param x column coordinate. 0 is the left-most column.
177 * @param y row coordinate. 0 is the top-most row.
178 * @param ch character to draw
179 * @param attr attributes to use (bold, foreColor, backColor)
180 */
181 public void putCharXY(final int x, final int y, final char ch,
182 final CellAttributes attr);
183
184 /**
185 * Render one character without changing the underlying attributes.
186 *
187 * @param x column coordinate. 0 is the left-most column.
188 * @param y row coordinate. 0 is the top-most row.
189 * @param ch character to draw
190 */
191 public void putCharXY(final int x, final int y, final char ch);
192
193 /**
194 * Render a string. Does not wrap if the string exceeds the line.
195 *
196 * @param x column coordinate. 0 is the left-most column.
197 * @param y row coordinate. 0 is the top-most row.
198 * @param str string to draw
199 * @param attr attributes to use (bold, foreColor, backColor)
200 */
201 public void putStringXY(final int x, final int y, final String str,
202 final CellAttributes attr);
203
204 /**
205 * Render a string without changing the underlying attribute. Does not
206 * wrap if the string exceeds the line.
207 *
208 * @param x column coordinate. 0 is the left-most column.
209 * @param y row coordinate. 0 is the top-most row.
210 * @param str string to draw
211 */
212 public void putStringXY(final int x, final int y, final String str);
213
214 /**
215 * Draw a vertical line from (x, y) to (x, y + n).
216 *
217 * @param x column coordinate. 0 is the left-most column.
218 * @param y row coordinate. 0 is the top-most row.
219 * @param n number of characters to draw
220 * @param ch character to draw
221 * @param attr attributes to use (bold, foreColor, backColor)
222 */
223 public void vLineXY(final int x, final int y, final int n,
224 final char ch, final CellAttributes attr);
225
226 /**
227 * Draw a horizontal line from (x, y) to (x + n, y).
228 *
229 * @param x column coordinate. 0 is the left-most column.
230 * @param y row coordinate. 0 is the top-most row.
231 * @param n number of characters to draw
232 * @param ch character to draw
233 * @param attr attributes to use (bold, foreColor, backColor)
234 */
235 public void hLineXY(final int x, final int y, final int n,
236 final char ch, final CellAttributes attr);
237
238 /**
239 * Change the width. Everything on-screen will be destroyed and must be
240 * redrawn.
241 *
242 * @param width new screen width
243 */
244 public void setWidth(final int width);
245
246 /**
247 * Change the height. Everything on-screen will be destroyed and must be
248 * redrawn.
249 *
250 * @param height new screen height
251 */
252 public void setHeight(final int height);
253
254 /**
255 * Change the width and height. Everything on-screen will be destroyed
256 * and must be redrawn.
257 *
258 * @param width new screen width
259 * @param height new screen height
260 */
261 public void setDimensions(final int width, final int height);
262
263 /**
264 * Get the height.
265 *
266 * @return current screen height
267 */
268 public int getHeight();
269
270 /**
271 * Get the width.
272 *
273 * @return current screen width
274 */
275 public int getWidth();
276
277 /**
278 * Reset screen to not-bold, white-on-black. Also flushes the offset and
279 * clip variables.
280 */
281 public void reset();
282
283 /**
284 * Flush the offset and clip variables.
285 */
286 public void resetClipping();
287
288 /**
289 * Clear the logical screen.
290 */
291 public void clear();
292
293 /**
294 * Draw a box with a border and empty background.
295 *
296 * @param left left column of box. 0 is the left-most row.
297 * @param top top row of the box. 0 is the top-most row.
298 * @param right right column of box
299 * @param bottom bottom row of the box
300 * @param border attributes to use for the border
301 * @param background attributes to use for the background
302 */
303 public void drawBox(final int left, final int top,
304 final int right, final int bottom,
305 final CellAttributes border, final CellAttributes background);
306
307 /**
308 * Draw a box with a border and empty background.
309 *
310 * @param left left column of box. 0 is the left-most row.
311 * @param top top row of the box. 0 is the top-most row.
312 * @param right right column of box
313 * @param bottom bottom row of the box
314 * @param border attributes to use for the border
315 * @param background attributes to use for the background
316 * @param borderType if 1, draw a single-line border; if 2, draw a
317 * double-line border; if 3, draw double-line top/bottom edges and
318 * single-line left/right edges (like Qmodem)
319 * @param shadow if true, draw a "shadow" on the box
320 */
321 public void drawBox(final int left, final int top,
322 final int right, final int bottom,
323 final CellAttributes border, final CellAttributes background,
324 final int borderType, final boolean shadow);
325
326 /**
327 * Draw a box shadow.
328 *
329 * @param left left column of box. 0 is the left-most row.
330 * @param top top row of the box. 0 is the top-most row.
331 * @param right right column of box
332 * @param bottom bottom row of the box
333 */
334 public void drawBoxShadow(final int left, final int top,
335 final int right, final int bottom);
336
a69ed767
KL
337 /**
338 * Clear the physical screen.
339 */
340 public void clearPhysical();
341
342 /**
343 * Unset every image cell on one row of the physical screen, forcing
344 * images on that row to be redrawn.
345 *
346 * @param y row coordinate. 0 is the top-most row.
347 */
348 public void unsetImageRow(final int y);
349
42873e30
KL
350 /**
351 * Classes must provide an implementation to push the logical screen to
352 * the physical device.
353 */
354 public void flushPhysical();
355
356 /**
357 * Put the cursor at (x,y).
358 *
359 * @param visible if true, the cursor should be visible
360 * @param x column coordinate to put the cursor on
361 * @param y row coordinate to put the cursor on
362 */
363 public void putCursor(final boolean visible, final int x, final int y);
364
365 /**
366 * Hide the cursor.
367 */
368 public void hideCursor();
369
3e074355
KL
370 /**
371 * Get the cursor visibility.
372 *
373 * @return true if the cursor is visible
374 */
375 public boolean isCursorVisible();
376
377 /**
378 * Get the cursor X position.
379 *
380 * @return the cursor x column position
381 */
382 public int getCursorX();
383
384 /**
385 * Get the cursor Y position.
386 *
387 * @return the cursor y row position
388 */
389 public int getCursorY();
390
42873e30
KL
391 /**
392 * Set the window title.
393 *
394 * @param title the new title
395 */
396 public void setTitle(final String title);
397
398}