code cleanup / jdoc
[nikiroo-utils.git] / src / jexer / backend / Screen.java
1 /*
2 * Jexer - Java Text User Interface
3 *
4 * The MIT License (MIT)
5 *
6 * Copyright (C) 2019 Kevin Lamonte
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 */
29 package jexer.backend;
30
31 import jexer.bits.Cell;
32 import jexer.bits.CellAttributes;
33 import jexer.bits.Clipboard;
34
35 /**
36 * Drawing operations API.
37 */
38 public interface Screen {
39
40 /**
41 * Set drawing offset for x.
42 *
43 * @param offsetX new drawing offset
44 */
45 public void setOffsetX(final int offsetX);
46
47 /**
48 * Set drawing offset for y.
49 *
50 * @param offsetY new drawing offset
51 */
52 public void setOffsetY(final int offsetY);
53
54 /**
55 * Get right drawing clipping boundary.
56 *
57 * @return drawing boundary
58 */
59 public int getClipRight();
60
61 /**
62 * Set right drawing clipping boundary.
63 *
64 * @param clipRight new boundary
65 */
66 public void setClipRight(final int clipRight);
67
68 /**
69 * Get bottom drawing clipping boundary.
70 *
71 * @return drawing boundary
72 */
73 public int getClipBottom();
74
75 /**
76 * Set bottom drawing clipping boundary.
77 *
78 * @param clipBottom new boundary
79 */
80 public void setClipBottom(final int clipBottom);
81
82 /**
83 * Get left drawing clipping boundary.
84 *
85 * @return drawing boundary
86 */
87 public int getClipLeft();
88
89 /**
90 * Set left drawing clipping boundary.
91 *
92 * @param clipLeft new boundary
93 */
94 public void setClipLeft(final int clipLeft);
95
96 /**
97 * Get top drawing clipping boundary.
98 *
99 * @return drawing boundary
100 */
101 public int getClipTop();
102
103 /**
104 * Set top drawing clipping boundary.
105 *
106 * @param clipTop new boundary
107 */
108 public void setClipTop(final int clipTop);
109
110 /**
111 * Get dirty flag.
112 *
113 * @return if true, the logical screen is not in sync with the physical
114 * screen
115 */
116 public boolean isDirty();
117
118 /**
119 * Get the attributes at one location.
120 *
121 * @param x column coordinate. 0 is the left-most column.
122 * @param y row coordinate. 0 is the top-most row.
123 * @return attributes at (x, y)
124 */
125 public CellAttributes getAttrXY(final int x, final int y);
126
127 /**
128 * Get the cell at one location.
129 *
130 * @param x column coordinate. 0 is the left-most column.
131 * @param y row coordinate. 0 is the top-most row.
132 * @return the character + attributes
133 */
134 public Cell getCharXY(final int x, final int y);
135
136 /**
137 * Set the attributes at one location.
138 *
139 * @param x column coordinate. 0 is the left-most column.
140 * @param y row coordinate. 0 is the top-most row.
141 * @param attr attributes to use (bold, foreColor, backColor)
142 */
143 public void putAttrXY(final int x, final int y,
144 final CellAttributes attr);
145
146 /**
147 * Set the attributes at one location.
148 *
149 * @param x column coordinate. 0 is the left-most column.
150 * @param y row coordinate. 0 is the top-most row.
151 * @param attr attributes to use (bold, foreColor, backColor)
152 * @param clip if true, honor clipping/offset
153 */
154 public void putAttrXY(final int x, final int y,
155 final CellAttributes attr, final boolean clip);
156
157 /**
158 * Fill the entire screen with one character with attributes.
159 *
160 * @param ch character to draw
161 * @param attr attributes to use (bold, foreColor, backColor)
162 */
163 public void putAll(final int ch, final CellAttributes attr);
164
165 /**
166 * Render one character with attributes.
167 *
168 * @param x column coordinate. 0 is the left-most column.
169 * @param y row coordinate. 0 is the top-most row.
170 * @param ch character + attributes to draw
171 */
172 public void putCharXY(final int x, final int y, final Cell ch);
173
174 /**
175 * Render one character with attributes.
176 *
177 * @param x column coordinate. 0 is the left-most column.
178 * @param y row coordinate. 0 is the top-most row.
179 * @param ch character to draw
180 * @param attr attributes to use (bold, foreColor, backColor)
181 */
182 public void putCharXY(final int x, final int y, final int ch,
183 final CellAttributes attr);
184
185 /**
186 * Render one character without changing the underlying attributes.
187 *
188 * @param x column coordinate. 0 is the left-most column.
189 * @param y row coordinate. 0 is the top-most row.
190 * @param ch character to draw
191 */
192 public void putCharXY(final int x, final int y, final int ch);
193
194 /**
195 * Render a string. Does not wrap if the string exceeds the line.
196 *
197 * @param x column coordinate. 0 is the left-most column.
198 * @param y row coordinate. 0 is the top-most row.
199 * @param str string to draw
200 * @param attr attributes to use (bold, foreColor, backColor)
201 */
202 public void putStringXY(final int x, final int y, final String str,
203 final CellAttributes attr);
204
205 /**
206 * Render a string without changing the underlying attribute. Does not
207 * wrap if the string exceeds the line.
208 *
209 * @param x column coordinate. 0 is the left-most column.
210 * @param y row coordinate. 0 is the top-most row.
211 * @param str string to draw
212 */
213 public void putStringXY(final int x, final int y, final String str);
214
215 /**
216 * Draw a vertical line from (x, y) to (x, y + n).
217 *
218 * @param x column coordinate. 0 is the left-most column.
219 * @param y row coordinate. 0 is the top-most row.
220 * @param n number of characters to draw
221 * @param ch character to draw
222 * @param attr attributes to use (bold, foreColor, backColor)
223 */
224 public void vLineXY(final int x, final int y, final int n,
225 final int ch, final CellAttributes attr);
226
227 /**
228 * Draw a horizontal line from (x, y) to (x + n, y).
229 *
230 * @param x column coordinate. 0 is the left-most column.
231 * @param y row coordinate. 0 is the top-most row.
232 * @param n number of characters to draw
233 * @param ch character to draw
234 * @param attr attributes to use (bold, foreColor, backColor)
235 */
236 public void hLineXY(final int x, final int y, final int n,
237 final int ch, final CellAttributes attr);
238
239 /**
240 * Change the width. Everything on-screen will be destroyed and must be
241 * redrawn.
242 *
243 * @param width new screen width
244 */
245 public void setWidth(final int width);
246
247 /**
248 * Change the height. Everything on-screen will be destroyed and must be
249 * redrawn.
250 *
251 * @param height new screen height
252 */
253 public void setHeight(final int height);
254
255 /**
256 * Change the width and height. Everything on-screen will be destroyed
257 * and must be redrawn.
258 *
259 * @param width new screen width
260 * @param height new screen height
261 */
262 public void setDimensions(final int width, final int height);
263
264 /**
265 * Get the height.
266 *
267 * @return current screen height
268 */
269 public int getHeight();
270
271 /**
272 * Get the width.
273 *
274 * @return current screen width
275 */
276 public int getWidth();
277
278 /**
279 * Reset screen to not-bold, white-on-black. Also flushes the offset and
280 * clip variables.
281 */
282 public void reset();
283
284 /**
285 * Flush the offset and clip variables.
286 */
287 public void resetClipping();
288
289 /**
290 * Clear the logical screen.
291 */
292 public void clear();
293
294 /**
295 * Draw a box with a border and empty background.
296 *
297 * @param left left column of box. 0 is the left-most row.
298 * @param top top row of the box. 0 is the top-most row.
299 * @param right right column of box
300 * @param bottom bottom row of the box
301 * @param border attributes to use for the border
302 * @param background attributes to use for the background
303 */
304 public void drawBox(final int left, final int top,
305 final int right, final int bottom,
306 final CellAttributes border, final CellAttributes background);
307
308 /**
309 * Draw a box with a border and empty background.
310 *
311 * @param left left column of box. 0 is the left-most row.
312 * @param top top row of the box. 0 is the top-most row.
313 * @param right right column of box
314 * @param bottom bottom row of the box
315 * @param border attributes to use for the border
316 * @param background attributes to use for the background
317 * @param borderType if 1, draw a single-line border; if 2, draw a
318 * double-line border; if 3, draw double-line top/bottom edges and
319 * single-line left/right edges (like Qmodem)
320 * @param shadow if true, draw a "shadow" on the box
321 */
322 public void drawBox(final int left, final int top,
323 final int right, final int bottom,
324 final CellAttributes border, final CellAttributes background,
325 final int borderType, final boolean shadow);
326
327 /**
328 * Draw a box shadow.
329 *
330 * @param left left column of box. 0 is the left-most row.
331 * @param top top row of the box. 0 is the top-most row.
332 * @param right right column of box
333 * @param bottom bottom row of the box
334 */
335 public void drawBoxShadow(final int left, final int top,
336 final int right, final int bottom);
337
338 /**
339 * Clear the physical screen.
340 */
341 public void clearPhysical();
342
343 /**
344 * Unset every image cell on one row of the physical screen, forcing
345 * images on that row to be redrawn.
346 *
347 * @param y row coordinate. 0 is the top-most row.
348 */
349 public void unsetImageRow(final int y);
350
351 /**
352 * Classes must provide an implementation to push the logical screen to
353 * the physical device.
354 */
355 public void flushPhysical();
356
357 /**
358 * Put the cursor at (x,y).
359 *
360 * @param visible if true, the cursor should be visible
361 * @param x column coordinate to put the cursor on
362 * @param y row coordinate to put the cursor on
363 */
364 public void putCursor(final boolean visible, final int x, final int y);
365
366 /**
367 * Hide the cursor.
368 */
369 public void hideCursor();
370
371 /**
372 * Get the cursor visibility.
373 *
374 * @return true if the cursor is visible
375 */
376 public boolean isCursorVisible();
377
378 /**
379 * Get the cursor X position.
380 *
381 * @return the cursor x column position
382 */
383 public int getCursorX();
384
385 /**
386 * Get the cursor Y position.
387 *
388 * @return the cursor y row position
389 */
390 public int getCursorY();
391
392 /**
393 * Set the window title.
394 *
395 * @param title the new title
396 */
397 public void setTitle(final String title);
398
399 /**
400 * Get the width of a character cell in pixels.
401 *
402 * @return the width in pixels of a character cell
403 */
404 public int getTextWidth();
405
406 /**
407 * Get the height of a character cell in pixels.
408 *
409 * @return the height in pixels of a character cell
410 */
411 public int getTextHeight();
412
413 /**
414 * Invert the cell color at a position, including both halves of a
415 * double-width cell.
416 *
417 * @param x column position
418 * @param y row position
419 */
420 public void invertCell(final int x, final int y);
421
422 /**
423 * Invert the cell color at a position.
424 *
425 * @param x column position
426 * @param y row position
427 * @param onlyThisCell if true, only invert this cell, otherwise invert
428 * both halves of a double-width cell if necessary
429 */
430 public void invertCell(final int x, final int y,
431 final boolean onlyThisCell);
432
433 /**
434 * Set a selection area on the screen.
435 *
436 * @param x0 the starting X position of the selection
437 * @param y0 the starting Y position of the selection
438 * @param x1 the ending X position of the selection
439 * @param y1 the ending Y position of the selection
440 * @param rectangle if true, this is a rectangle select
441 */
442 public void setSelection(final int x0, final int y0,
443 final int x1, final int y1, final boolean rectangle);
444
445 /**
446 * Copy the screen selection area to the clipboard.
447 *
448 * @param clipboard the clipboard to use
449 * @param x0 the starting X position of the selection
450 * @param y0 the starting Y position of the selection
451 * @param x1 the ending X position of the selection
452 * @param y1 the ending Y position of the selection
453 * @param rectangle if true, this is a rectangle select
454 */
455 public void copySelection(final Clipboard clipboard,
456 final int x0, final int y0, final int x1, final int y1,
457 final boolean rectangle);
458
459 }