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 }