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
  34 /**
  35  * Drawing operations API.
  36  */
  37 public 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
 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
 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
 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
 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
 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
 391     /**
 392      * Set the window title.
 393      *
 394      * @param title the new title
 395      */
 396     public void setTitle(final String title);
 397
 398     /**
 399      * Get the width of a character cell in pixels.
 400      *
 401      * @return the width in pixels of a character cell
 402      */
 403     public int getTextWidth();
 404
 405     /**
 406      * Get the height of a character cell in pixels.
 407      *
 408      * @return the height in pixels of a character cell
 409      */
 410     public int getTextHeight();
 411
 412 }