Pull demo into jar
[nikiroo-utils.git] / src / jexer / io / Screen.java
1 /**
2 * Jexer - Java Text User Interface
3 *
4 * License: LGPLv3 or later
5 *
6 * This module is licensed under the GNU Lesser General Public License
7 * Version 3. Please see the file "COPYING" in this directory for more
8 * information about the GNU Lesser General Public License Version 3.
9 *
10 * Copyright (C) 2015 Kevin Lamonte
11 *
12 * This program is free software; you can redistribute it and/or
13 * modify it under the terms of the GNU Lesser General Public License
14 * as published by the Free Software Foundation; either version 3 of
15 * the License, or (at your option) any later version.
16 *
17 * This program is distributed in the hope that it will be useful, but
18 * WITHOUT ANY WARRANTY; without even the implied warranty of
19 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
20 * General Public License for more details.
21 *
22 * You should have received a copy of the GNU Lesser General Public
23 * License along with this program; if not, see
24 * http://www.gnu.org/licenses/, or write to the Free Software
25 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
26 * 02110-1301 USA
27 *
28 * @author Kevin Lamonte [kevin.lamonte@gmail.com]
29 * @version 1
30 */
31 package jexer.io;
32
33 import jexer.bits.Cell;
34 import jexer.bits.CellAttributes;
35 import jexer.bits.GraphicsChars;
36
37 /**
38 * This class represents a text-based screen. Drawing operations write to a
39 * logical screen.
40 */
41 public abstract class Screen {
42
43 /**
44 * Width of the visible window.
45 */
46 protected int width;
47
48 /**
49 * Height of the visible window.
50 */
51 protected int height;
52
53 /**
54 * Drawing offset for x.
55 */
56 private int offsetX;
57
58 /**
59 * Set drawing offset for x.
60 *
61 * @param offsetX new drawing offset
62 */
63 public final void setOffsetX(final int offsetX) {
64 this.offsetX = offsetX;
65 }
66
67 /**
68 * Drawing offset for y.
69 */
70 private int offsetY;
71
72 /**
73 * Set drawing offset for y.
74 *
75 * @param offsetY new drawing offset
76 */
77 public final void setOffsetY(final int offsetY) {
78 this.offsetY = offsetY;
79 }
80
81 /**
82 * Ignore anything drawn right of clipRight.
83 */
84 private int clipRight;
85
86 /**
87 * Get right drawing clipping boundary.
88 *
89 * @return drawing boundary
90 */
91 public final int getClipRight() {
92 return clipRight;
93 }
94
95 /**
96 * Set right drawing clipping boundary.
97 *
98 * @param clipRight new boundary
99 */
100 public final void setClipRight(final int clipRight) {
101 this.clipRight = clipRight;
102 }
103
104 /**
105 * Ignore anything drawn below clipBottom.
106 */
107 private int clipBottom;
108
109 /**
110 * Get bottom drawing clipping boundary.
111 *
112 * @return drawing boundary
113 */
114 public final int getClipBottom() {
115 return clipBottom;
116 }
117
118 /**
119 * Set bottom drawing clipping boundary.
120 *
121 * @param clipBottom new boundary
122 */
123 public final void setClipBottom(final int clipBottom) {
124 this.clipBottom = clipBottom;
125 }
126
127 /**
128 * Ignore anything drawn left of clipLeft.
129 */
130 private int clipLeft;
131
132 /**
133 * Get left drawing clipping boundary.
134 *
135 * @return drawing boundary
136 */
137 public final int getClipLeft() {
138 return clipLeft;
139 }
140
141 /**
142 * Set left drawing clipping boundary.
143 *
144 * @param clipLeft new boundary
145 */
146 public final void setClipLeft(final int clipLeft) {
147 this.clipLeft = clipLeft;
148 }
149
150 /**
151 * Ignore anything drawn above clipTop.
152 */
153 private int clipTop;
154
155 /**
156 * Get top drawing clipping boundary.
157 *
158 * @return drawing boundary
159 */
160 public final int getClipTop() {
161 return clipTop;
162 }
163
164 /**
165 * Set top drawing clipping boundary.
166 *
167 * @param clipTop new boundary
168 */
169 public final void setClipTop(final int clipTop) {
170 this.clipTop = clipTop;
171 }
172
173 /**
174 * The physical screen last sent out on flush().
175 */
176 protected Cell [][] physical;
177
178 /**
179 * The logical screen being rendered to.
180 */
181 protected Cell [][] logical;
182
183 /**
184 * When true, logical != physical.
185 */
186 protected boolean dirty;
187
188 /**
189 * Set if the user explicitly wants to redraw everything starting with a
190 * ECMATerminal.clearAll().
191 */
192 protected boolean reallyCleared;
193
194 /**
195 * If true, the cursor is visible and should be placed onscreen at
196 * (cursorX, cursorY) during a call to flushPhysical().
197 */
198 protected boolean cursorVisible;
199
200 /**
201 * Cursor X position if visible.
202 */
203 protected int cursorX;
204
205 /**
206 * Cursor Y position if visible.
207 */
208 protected int cursorY;
209
210 /**
211 * Get the attributes at one location.
212 *
213 * @param x column coordinate. 0 is the left-most column.
214 * @param y row coordinate. 0 is the top-most row.
215 * @return attributes at (x, y)
216 */
217 public final CellAttributes getAttrXY(final int x, final int y) {
218 CellAttributes attr = new CellAttributes();
219 attr.setTo(logical[x][y]);
220 return attr;
221 }
222
223 /**
224 * Set the attributes at one location.
225 *
226 * @param x column coordinate. 0 is the left-most column.
227 * @param y row coordinate. 0 is the top-most row.
228 * @param attr attributes to use (bold, foreColor, backColor)
229 */
230 public final void putAttrXY(final int x, final int y,
231 final CellAttributes attr) {
232
233 putAttrXY(x, y, attr, true);
234 }
235
236 /**
237 * Set the attributes at one location.
238 *
239 * @param x column coordinate. 0 is the left-most column.
240 * @param y row coordinate. 0 is the top-most row.
241 * @param attr attributes to use (bold, foreColor, backColor)
242 * @param clip if true, honor clipping/offset
243 */
244 public final void putAttrXY(final int x, final int y,
245 final CellAttributes attr, final boolean clip) {
246
247 int X = x;
248 int Y = y;
249
250 if (clip) {
251 if ((x < clipLeft)
252 || (x >= clipRight)
253 || (y < clipTop)
254 || (y >= clipBottom)
255 ) {
256 return;
257 }
258 X += offsetX;
259 Y += offsetY;
260 }
261
262 if ((X >= 0) && (X < width) && (Y >= 0) && (Y < height)) {
263 dirty = true;
264 logical[X][Y].setForeColor(attr.getForeColor());
265 logical[X][Y].setBackColor(attr.getBackColor());
266 logical[X][Y].setBold(attr.getBold());
267 logical[X][Y].setBlink(attr.getBlink());
268 logical[X][Y].setReverse(attr.getReverse());
269 logical[X][Y].setUnderline(attr.getUnderline());
270 logical[X][Y].setProtect(attr.getProtect());
271 }
272 }
273
274 /**
275 * Fill the entire screen with one character with attributes.
276 *
277 * @param ch character to draw
278 * @param attr attributes to use (bold, foreColor, backColor)
279 */
280 public final void putAll(final char ch, final CellAttributes attr) {
281 for (int x = 0; x < width; x++) {
282 for (int y = 0; y < height; y++) {
283 putCharXY(x, y, ch, attr);
284 }
285 }
286 }
287
288 /**
289 * Render one character with attributes.
290 *
291 * @param x column coordinate. 0 is the left-most column.
292 * @param y row coordinate. 0 is the top-most row.
293 * @param ch character + attributes to draw
294 */
295 public final void putCharXY(final int x, final int y, final Cell ch) {
296 putCharXY(x, y, ch.getChar(), ch);
297 }
298
299 /**
300 * Render one character with attributes.
301 *
302 * @param x column coordinate. 0 is the left-most column.
303 * @param y row coordinate. 0 is the top-most row.
304 * @param ch character to draw
305 * @param attr attributes to use (bold, foreColor, backColor)
306 */
307 public final void putCharXY(final int x, final int y, final char ch,
308 final CellAttributes attr) {
309
310 if ((x < clipLeft)
311 || (x >= clipRight)
312 || (y < clipTop)
313 || (y >= clipBottom)
314 ) {
315 return;
316 }
317
318 int X = x + offsetX;
319 int Y = y + offsetY;
320
321 // System.err.printf("putCharXY: %d, %d, %c\n", X, Y, ch);
322
323 if ((X >= 0) && (X < width) && (Y >= 0) && (Y < height)) {
324 dirty = true;
325
326 // Do not put control characters on the display
327 assert (ch >= 0x20);
328 assert (ch != 0x7F);
329
330 logical[X][Y].setChar(ch);
331 logical[X][Y].setForeColor(attr.getForeColor());
332 logical[X][Y].setBackColor(attr.getBackColor());
333 logical[X][Y].setBold(attr.getBold());
334 logical[X][Y].setBlink(attr.getBlink());
335 logical[X][Y].setReverse(attr.getReverse());
336 logical[X][Y].setUnderline(attr.getUnderline());
337 logical[X][Y].setProtect(attr.getProtect());
338 }
339 }
340
341 /**
342 * Render one character without changing the underlying attributes.
343 *
344 * @param x column coordinate. 0 is the left-most column.
345 * @param y row coordinate. 0 is the top-most row.
346 * @param ch character to draw
347 */
348 public final void putCharXY(final int x, final int y, final char ch) {
349 if ((x < clipLeft)
350 || (x >= clipRight)
351 || (y < clipTop)
352 || (y >= clipBottom)
353 ) {
354 return;
355 }
356
357 int X = x + offsetX;
358 int Y = y + offsetY;
359
360 // System.err.printf("putCharXY: %d, %d, %c\n", X, Y, ch);
361
362 if ((X >= 0) && (X < width) && (Y >= 0) && (Y < height)) {
363 dirty = true;
364 logical[X][Y].setChar(ch);
365 }
366 }
367
368 /**
369 * Render a string. Does not wrap if the string exceeds the line.
370 *
371 * @param x column coordinate. 0 is the left-most column.
372 * @param y row coordinate. 0 is the top-most row.
373 * @param str string to draw
374 * @param attr attributes to use (bold, foreColor, backColor)
375 */
376 public final void putStrXY(final int x, final int y, final String str,
377 final CellAttributes attr) {
378
379 int i = x;
380 for (int j = 0; j < str.length(); j++) {
381 char ch = str.charAt(j);
382 putCharXY(i, y, ch, attr);
383 i++;
384 if (i == width) {
385 break;
386 }
387 }
388 }
389
390 /**
391 * Render a string without changing the underlying attribute. Does not
392 * wrap if the string exceeds the line.
393 *
394 * @param x column coordinate. 0 is the left-most column.
395 * @param y row coordinate. 0 is the top-most row.
396 * @param str string to draw
397 */
398 public final void putStrXY(final int x, final int y, final String str) {
399 int i = x;
400 for (int j = 0; j < str.length(); j++) {
401 char ch = str.charAt(j);
402 putCharXY(i, y, ch);
403 i++;
404 if (i == width) {
405 break;
406 }
407 }
408 }
409
410 /**
411 * Draw a vertical line from (x, y) to (x, y + n).
412 *
413 * @param x column coordinate. 0 is the left-most column.
414 * @param y row coordinate. 0 is the top-most row.
415 * @param n number of characters to draw
416 * @param ch character to draw
417 * @param attr attributes to use (bold, foreColor, backColor)
418 */
419 public final void vLineXY(final int x, final int y, final int n,
420 final char ch, final CellAttributes attr) {
421
422 for (int i = y; i < y + n; i++) {
423 putCharXY(x, i, ch, attr);
424 }
425 }
426
427 /**
428 * Draw a horizontal line from (x, y) to (x + n, y).
429 *
430 * @param x column coordinate. 0 is the left-most column.
431 * @param y row coordinate. 0 is the top-most row.
432 * @param n number of characters to draw
433 * @param ch character to draw
434 * @param attr attributes to use (bold, foreColor, backColor)
435 */
436 public final void hLineXY(final int x, final int y, final int n,
437 final char ch, final CellAttributes attr) {
438
439 for (int i = x; i < x + n; i++) {
440 putCharXY(i, y, ch, attr);
441 }
442 }
443
444 /**
445 * Reallocate screen buffers.
446 *
447 * @param width new width
448 * @param height new height
449 */
450 private void reallocate(final int width, final int height) {
451 if (logical != null) {
452 for (int row = 0; row < this.height; row++) {
453 for (int col = 0; col < this.width; col++) {
454 logical[col][row] = null;
455 }
456 }
457 logical = null;
458 }
459 logical = new Cell[width][height];
460 if (physical != null) {
461 for (int row = 0; row < this.height; row++) {
462 for (int col = 0; col < this.width; col++) {
463 physical[col][row] = null;
464 }
465 }
466 physical = null;
467 }
468 physical = new Cell[width][height];
469
470 for (int row = 0; row < height; row++) {
471 for (int col = 0; col < width; col++) {
472 physical[col][row] = new Cell();
473 logical[col][row] = new Cell();
474 }
475 }
476
477 this.width = width;
478 this.height = height;
479
480 clipLeft = 0;
481 clipTop = 0;
482 clipRight = width;
483 clipBottom = height;
484
485 reallyCleared = true;
486 dirty = true;
487 }
488
489 /**
490 * Change the width. Everything on-screen will be destroyed and must be
491 * redrawn.
492 *
493 * @param width new screen width
494 */
495 public final void setWidth(final int width) {
496 reallocate(width, this.height);
497 }
498
499 /**
500 * Change the height. Everything on-screen will be destroyed and must be
501 * redrawn.
502 *
503 * @param height new screen height
504 */
505 public final void setHeight(final int height) {
506 reallocate(this.width, height);
507 }
508
509 /**
510 * Change the width and height. Everything on-screen will be destroyed
511 * and must be redrawn.
512 *
513 * @param width new screen width
514 * @param height new screen height
515 */
516 public final void setDimensions(final int width, final int height) {
517 reallocate(width, height);
518 }
519
520 /**
521 * Get the height.
522 *
523 * @return current screen height
524 */
525 public final int getHeight() {
526 return this.height;
527 }
528
529 /**
530 * Get the width.
531 *
532 * @return current screen width
533 */
534 public final int getWidth() {
535 return this.width;
536 }
537
538 /**
539 * Public constructor. Sets everything to not-bold, white-on-black.
540 */
541 protected Screen() {
542 offsetX = 0;
543 offsetY = 0;
544 width = 80;
545 height = 24;
546 logical = null;
547 physical = null;
548 reallocate(width, height);
549 }
550
551 /**
552 * Reset screen to not-bold, white-on-black. Also flushes the offset and
553 * clip variables.
554 */
555 public final void reset() {
556 dirty = true;
557 for (int row = 0; row < height; row++) {
558 for (int col = 0; col < width; col++) {
559 logical[col][row].reset();
560 }
561 }
562 resetClipping();
563 }
564
565 /**
566 * Flush the offset and clip variables.
567 */
568 public final void resetClipping() {
569 offsetX = 0;
570 offsetY = 0;
571 clipLeft = 0;
572 clipTop = 0;
573 clipRight = width;
574 clipBottom = height;
575 }
576
577 /**
578 * Force the screen to be fully cleared and redrawn on the next flush().
579 */
580 public final void clear() {
581 reset();
582 }
583
584 /**
585 * Draw a box with a border and empty background.
586 *
587 * @param left left column of box. 0 is the left-most row.
588 * @param top top row of the box. 0 is the top-most row.
589 * @param right right column of box
590 * @param bottom bottom row of the box
591 * @param border attributes to use for the border
592 * @param background attributes to use for the background
593 */
594 public final void drawBox(final int left, final int top,
595 final int right, final int bottom,
596 final CellAttributes border, final CellAttributes background) {
597
598 drawBox(left, top, right, bottom, border, background, 1, false);
599 }
600
601 /**
602 * Draw a box with a border and empty background.
603 *
604 * @param left left column of box. 0 is the left-most row.
605 * @param top top row of the box. 0 is the top-most row.
606 * @param right right column of box
607 * @param bottom bottom row of the box
608 * @param border attributes to use for the border
609 * @param background attributes to use for the background
610 * @param borderType if 1, draw a single-line border; if 2, draw a
611 * double-line border; if 3, draw double-line top/bottom edges and
612 * single-line left/right edges (like Qmodem)
613 * @param shadow if true, draw a "shadow" on the box
614 */
615 public final void drawBox(final int left, final int top,
616 final int right, final int bottom,
617 final CellAttributes border, final CellAttributes background,
618 final int borderType, final boolean shadow) {
619
620 int boxTop = top;
621 int boxLeft = left;
622 int boxWidth = right - left;
623 int boxHeight = bottom - top;
624
625 char cTopLeft;
626 char cTopRight;
627 char cBottomLeft;
628 char cBottomRight;
629 char cHSide;
630 char cVSide;
631
632 switch (borderType) {
633 case 1:
634 cTopLeft = GraphicsChars.ULCORNER;
635 cTopRight = GraphicsChars.URCORNER;
636 cBottomLeft = GraphicsChars.LLCORNER;
637 cBottomRight = GraphicsChars.LRCORNER;
638 cHSide = GraphicsChars.SINGLE_BAR;
639 cVSide = GraphicsChars.WINDOW_SIDE;
640 break;
641
642 case 2:
643 cTopLeft = GraphicsChars.WINDOW_LEFT_TOP_DOUBLE;
644 cTopRight = GraphicsChars.WINDOW_RIGHT_TOP_DOUBLE;
645 cBottomLeft = GraphicsChars.WINDOW_LEFT_BOTTOM_DOUBLE;
646 cBottomRight = GraphicsChars.WINDOW_RIGHT_BOTTOM_DOUBLE;
647 cHSide = GraphicsChars.DOUBLE_BAR;
648 cVSide = GraphicsChars.WINDOW_SIDE_DOUBLE;
649 break;
650
651 case 3:
652 cTopLeft = GraphicsChars.WINDOW_LEFT_TOP;
653 cTopRight = GraphicsChars.WINDOW_RIGHT_TOP;
654 cBottomLeft = GraphicsChars.WINDOW_LEFT_BOTTOM;
655 cBottomRight = GraphicsChars.WINDOW_RIGHT_BOTTOM;
656 cHSide = GraphicsChars.WINDOW_TOP;
657 cVSide = GraphicsChars.WINDOW_SIDE;
658 break;
659 default:
660 throw new IllegalArgumentException("Invalid border type: "
661 + borderType);
662 }
663
664 // Place the corner characters
665 putCharXY(left, top, cTopLeft, border);
666 putCharXY(left + boxWidth - 1, top, cTopRight, border);
667 putCharXY(left, top + boxHeight - 1, cBottomLeft, border);
668 putCharXY(left + boxWidth - 1, top + boxHeight - 1, cBottomRight,
669 border);
670
671 // Draw the box lines
672 hLineXY(left + 1, top, boxWidth - 2, cHSide, border);
673 vLineXY(left, top + 1, boxHeight - 2, cVSide, border);
674 hLineXY(left + 1, top + boxHeight - 1, boxWidth - 2, cHSide, border);
675 vLineXY(left + boxWidth - 1, top + 1, boxHeight - 2, cVSide, border);
676
677 // Fill in the interior background
678 for (int i = 1; i < boxHeight - 1; i++) {
679 hLineXY(1 + left, i + top, boxWidth - 2, ' ', background);
680 }
681
682 if (shadow) {
683 // Draw a shadow
684 drawBoxShadow(left, top, right, bottom);
685 }
686 }
687
688 /**
689 * Draw a box shadow.
690 *
691 * @param left left column of box. 0 is the left-most row.
692 * @param top top row of the box. 0 is the top-most row.
693 * @param right right column of box
694 * @param bottom bottom row of the box
695 */
696 public final void drawBoxShadow(final int left, final int top,
697 final int right, final int bottom) {
698
699 int boxTop = top;
700 int boxLeft = left;
701 int boxWidth = right - left;
702 int boxHeight = bottom - top;
703 CellAttributes shadowAttr = new CellAttributes();
704
705 // Shadows do not honor clipping but they DO honor offset.
706 int oldClipRight = clipRight;
707 int oldClipBottom = clipBottom;
708 /*
709 clipRight = boxWidth + 2;
710 clipBottom = boxHeight + 1;
711 */
712 clipRight = width;
713 clipBottom = height;
714
715 for (int i = 0; i < boxHeight; i++) {
716 putAttrXY(boxLeft + boxWidth, boxTop + 1 + i, shadowAttr);
717 putAttrXY(boxLeft + boxWidth + 1, boxTop + 1 + i, shadowAttr);
718 }
719 for (int i = 0; i < boxWidth; i++) {
720 putAttrXY(boxLeft + 2 + i, boxTop + boxHeight, shadowAttr);
721 }
722 clipRight = oldClipRight;
723 clipBottom = oldClipBottom;
724 }
725
726 /**
727 * Subclasses must provide an implementation to push the logical screen
728 * to the physical device.
729 */
730 abstract public void flushPhysical();
731
732 /**
733 * Put the cursor at (x,y).
734 *
735 * @param visible if true, the cursor should be visible
736 * @param x column coordinate to put the cursor on
737 * @param y row coordinate to put the cursor on
738 */
739 public final void putCursor(final boolean visible,
740 final int x, final int y) {
741
742 cursorVisible = visible;
743 cursorX = x;
744 cursorY = y;
745 }
746
747 /**
748 * Hide the cursor.
749 */
750 public final void hideCursor() {
751 cursorVisible = false;
752 }
753 }