src/jexer/TField.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;
  30
  31 import jexer.bits.CellAttributes;
  32 import jexer.bits.GraphicsChars;
  33 import jexer.bits.StringUtils;
  34 import jexer.event.TCommandEvent;
  35 import jexer.event.TKeypressEvent;
  36 import jexer.event.TMouseEvent;
  37 import static jexer.TCommand.*;
  38 import static jexer.TKeypress.*;
  39
  40 /**
  41  * TField implements an editable text field.
  42  */
  43 public class TField extends TWidget implements EditMenuUser {
  44
  45     // ------------------------------------------------------------------------
  46     // Variables --------------------------------------------------------------
  47     // ------------------------------------------------------------------------
  48
  49     /**
  50      * Background character for unfilled-in text.
  51      */
  52     protected int backgroundChar = GraphicsChars.HATCH;
  53
  54     /**
  55      * Field text.
  56      */
  57     protected String text = "";
  58
  59     /**
  60      * If true, only allow enough characters that will fit in the width.  If
  61      * false, allow the field to scroll to the right.
  62      */
  63     protected boolean fixed = false;
  64
  65     /**
  66      * Current editing position within text.
  67      */
  68     protected int position = 0;
  69
  70     /**
  71      * Current editing position screen column number.
  72      */
  73     protected int screenPosition = 0;
  74
  75     /**
  76      * Beginning of visible portion.
  77      */
  78     protected int windowStart = 0;
  79
  80     /**
  81      * If true, new characters are inserted at position.
  82      */
  83     protected boolean insertMode = true;
  84
  85     /**
  86      * Remember mouse state.
  87      */
  88     protected TMouseEvent mouse;
  89
  90     /**
  91      * The action to perform when the user presses enter.
  92      */
  93     protected TAction enterAction;
  94
  95     /**
  96      * The action to perform when the text is updated.
  97      */
  98     protected TAction updateAction;
  99
 100     /**
 101      * The color to use when this field is active.
 102      */
 103     private String activeColorKey = "tfield.active";
 104
 105     /**
 106      * The color to use when this field is not active.
 107      */
 108     private String inactiveColorKey = "tfield.inactive";
 109
 110     // ------------------------------------------------------------------------
 111     // Constructors -----------------------------------------------------------
 112     // ------------------------------------------------------------------------
 113
 114     /**
 115      * Public constructor.
 116      *
 117      * @param parent parent widget
 118      * @param x column relative to parent
 119      * @param y row relative to parent
 120      * @param width visible text width
 121      * @param fixed if true, the text cannot exceed the display width
 122      */
 123     public TField(final TWidget parent, final int x, final int y,
 124         final int width, final boolean fixed) {
 125
 126         this(parent, x, y, width, fixed, "", null, null);
 127     }
 128
 129     /**
 130      * Public constructor.
 131      *
 132      * @param parent parent widget
 133      * @param x column relative to parent
 134      * @param y row relative to parent
 135      * @param width visible text width
 136      * @param fixed if true, the text cannot exceed the display width
 137      * @param text initial text, default is empty string
 138      */
 139     public TField(final TWidget parent, final int x, final int y,
 140         final int width, final boolean fixed, final String text) {
 141
 142         this(parent, x, y, width, fixed, text, null, null);
 143     }
 144
 145     /**
 146      * Public constructor.
 147      *
 148      * @param parent parent widget
 149      * @param x column relative to parent
 150      * @param y row relative to parent
 151      * @param width visible text width
 152      * @param fixed if true, the text cannot exceed the display width
 153      * @param text initial text, default is empty string
 154      * @param enterAction function to call when enter key is pressed
 155      * @param updateAction function to call when the text is updated
 156      */
 157     public TField(final TWidget parent, final int x, final int y,
 158         final int width, final boolean fixed, final String text,
 159         final TAction enterAction, final TAction updateAction) {
 160
 161         // Set parent and window
 162         super(parent, x, y, width, 1);
 163
 164         setCursorVisible(true);
 165         this.fixed = fixed;
 166         this.text = text;
 167         this.enterAction = enterAction;
 168         this.updateAction = updateAction;
 169     }
 170
 171     // ------------------------------------------------------------------------
 172     // Event handlers ---------------------------------------------------------
 173     // ------------------------------------------------------------------------
 174
 175     /**
 176      * Returns true if the mouse is currently on the field.
 177      *
 178      * @return if true the mouse is currently on the field
 179      */
 180     protected boolean mouseOnField() {
 181         int rightEdge = getWidth() - 1;
 182         if ((mouse != null)
 183             && (mouse.getY() == 0)
 184             && (mouse.getX() >= 0)
 185             && (mouse.getX() <= rightEdge)
 186         ) {
 187             return true;
 188         }
 189         return false;
 190     }
 191
 192     /**
 193      * Handle mouse button presses.
 194      *
 195      * @param mouse mouse button event
 196      */
 197     @Override
 198     public void onMouseDown(final TMouseEvent mouse) {
 199         this.mouse = mouse;
 200
 201         if ((mouseOnField()) && (mouse.isMouse1())) {
 202             // Move cursor
 203             int deltaX = mouse.getX() - getCursorX();
 204             screenPosition += deltaX;
 205             if (screenPosition > StringUtils.width(text)) {
 206                 screenPosition = StringUtils.width(text);
 207             }
 208             position = screenToTextPosition(screenPosition);
 209             updateCursor();
 210             return;
 211         }
 212     }
 213
 214     /**
 215      * Handle keystrokes.
 216      *
 217      * @param keypress keystroke event
 218      */
 219     @Override
 220     public void onKeypress(final TKeypressEvent keypress) {
 221
 222         if (keypress.equals(kbLeft)) {
 223             if (position > 0) {
 224                 screenPosition -= StringUtils.width(text.codePointBefore(position));
 225                 position -= Character.charCount(text.codePointBefore(position));
 226             }
 227             if (fixed == false) {
 228                 if ((screenPosition == windowStart) && (windowStart > 0)) {
 229                     windowStart -= StringUtils.width(text.codePointAt(
 230                         screenToTextPosition(windowStart)));
 231                 }
 232             }
 233             normalizeWindowStart();
 234             return;
 235         }
 236
 237         if (keypress.equals(kbRight)) {
 238             if (position < text.length()) {
 239                 int lastPosition = position;
 240                 screenPosition += StringUtils.width(text.codePointAt(position));
 241                 position += Character.charCount(text.codePointAt(position));
 242                 if (fixed == true) {
 243                     if (screenPosition == getWidth()) {
 244                         screenPosition--;
 245                         position -= Character.charCount(text.codePointAt(lastPosition));
 246                     }
 247                 } else {
 248                     while ((screenPosition - windowStart +
 249                             StringUtils.width(text.codePointAt(text.length() - 1)))
 250                         > getWidth()
 251                     ) {
 252                         windowStart += StringUtils.width(text.codePointAt(
 253                             screenToTextPosition(windowStart)));
 254                     }
 255                 }
 256             }
 257             assert (position <= text.length());
 258             return;
 259         }
 260
 261         if (keypress.equals(kbEnter)) {
 262             dispatch(true);
 263             return;
 264         }
 265
 266         if (keypress.equals(kbIns)) {
 267             insertMode = !insertMode;
 268             return;
 269         }
 270         if (keypress.equals(kbHome)) {
 271             home();
 272             return;
 273         }
 274
 275         if (keypress.equals(kbEnd)) {
 276             end();
 277             return;
 278         }
 279
 280         if (keypress.equals(kbDel)) {
 281             if ((text.length() > 0) && (position < text.length())) {
 282                 text = text.substring(0, position)
 283                         + text.substring(position + 1);
 284                 screenPosition = StringUtils.width(text.substring(0, position));
 285             }
 286             dispatch(false);
 287             return;
 288         }
 289
 290         if (keypress.equals(kbBackspace) || keypress.equals(kbBackspaceDel)) {
 291             if (position > 0) {
 292                 position -= Character.charCount(text.codePointBefore(position));
 293                 text = text.substring(0, position)
 294                         + text.substring(position + 1);
 295                 screenPosition = StringUtils.width(text.substring(0, position));
 296             }
 297             if (fixed == false) {
 298                 if ((screenPosition >= windowStart)
 299                     && (windowStart > 0)
 300                 ) {
 301                     windowStart -= StringUtils.width(text.codePointAt(
 302                         screenToTextPosition(windowStart)));
 303                 }
 304             }
 305             dispatch(false);
 306             normalizeWindowStart();
 307             return;
 308         }
 309
 310         if (!keypress.getKey().isFnKey()
 311             && !keypress.getKey().isAlt()
 312             && !keypress.getKey().isCtrl()
 313         ) {
 314             // Plain old keystroke, process it
 315             if ((position == text.length())
 316                 && (StringUtils.width(text) < getWidth())) {
 317
 318                 // Append case
 319                 appendChar(keypress.getKey().getChar());
 320             } else if ((position < text.length())
 321                 && (StringUtils.width(text) < getWidth())) {
 322
 323                 // Overwrite or insert a character
 324                 if (insertMode == false) {
 325                     // Replace character
 326                     text = text.substring(0, position)
 327                             + codePointString(keypress.getKey().getChar())
 328                             + text.substring(position + 1);
 329                     screenPosition += StringUtils.width(text.codePointAt(position));
 330                     position += Character.charCount(keypress.getKey().getChar());
 331                 } else {
 332                     // Insert character
 333                     insertChar(keypress.getKey().getChar());
 334                 }
 335             } else if ((position < text.length())
 336                 && (StringUtils.width(text) >= getWidth())) {
 337
 338                 // Multiple cases here
 339                 if ((fixed == true) && (insertMode == true)) {
 340                     // Buffer is full, do nothing
 341                 } else if ((fixed == true) && (insertMode == false)) {
 342                     // Overwrite the last character, maybe move position
 343                     text = text.substring(0, position)
 344                             + codePointString(keypress.getKey().getChar())
 345                             + text.substring(position + 1);
 346                     if (screenPosition < getWidth() - 1) {
 347                         screenPosition += StringUtils.width(text.codePointAt(position));
 348                         position += Character.charCount(keypress.getKey().getChar());
 349                     }
 350                 } else if ((fixed == false) && (insertMode == false)) {
 351                     // Overwrite the last character, definitely move position
 352                     text = text.substring(0, position)
 353                             + codePointString(keypress.getKey().getChar())
 354                             + text.substring(position + 1);
 355                     screenPosition += StringUtils.width(text.codePointAt(position));
 356                     position += Character.charCount(keypress.getKey().getChar());
 357                 } else {
 358                     if (position == text.length()) {
 359                         // Append this character
 360                         appendChar(keypress.getKey().getChar());
 361                     } else {
 362                         // Insert this character
 363                         insertChar(keypress.getKey().getChar());
 364                     }
 365                 }
 366             } else {
 367                 assert (!fixed);
 368
 369                 // Append this character
 370                 appendChar(keypress.getKey().getChar());
 371             }
 372             dispatch(false);
 373             return;
 374         }
 375
 376         // Pass to parent for the things we don't care about.
 377         super.onKeypress(keypress);
 378     }
 379
 380     /**
 381      * Handle posted command events.
 382      *
 383      * @param command command event
 384      */
 385     @Override
 386     public void onCommand(final TCommandEvent command) {
 387         if (command.equals(cmCut)) {
 388             // Copy text to clipboard, and then remove it.
 389             getClipboard().copyText(text);
 390             setText("");
 391             return;
 392         }
 393
 394         if (command.equals(cmCopy)) {
 395             // Copy text to clipboard.
 396             getClipboard().copyText(text);
 397             return;
 398         }
 399
 400         if (command.equals(cmPaste)) {
 401             // Paste text from clipboard.
 402             String newText = getClipboard().pasteText();
 403             if (newText != null) {
 404                 setText(newText);
 405             }
 406             return;
 407         }
 408
 409         if (command.equals(cmClear)) {
 410             // Remove text.
 411             setText("");
 412             return;
 413         }
 414
 415     }
 416
 417     // ------------------------------------------------------------------------
 418     // TWidget ----------------------------------------------------------------
 419     // ------------------------------------------------------------------------
 420
 421     /**
 422      * Override TWidget's height: we can only set height at construction
 423      * time.
 424      *
 425      * @param height new widget height (ignored)
 426      */
 427     @Override
 428     public void setHeight(final int height) {
 429         // Do nothing
 430     }
 431
 432     /**
 433      * Draw the text field.
 434      */
 435     @Override
 436     public void draw() {
 437         CellAttributes fieldColor;
 438
 439         if (isAbsoluteActive()) {
 440             fieldColor = getTheme().getColor(activeColorKey);
 441         } else {
 442             fieldColor = getTheme().getColor(inactiveColorKey);
 443         }
 444
 445         int end = windowStart + getWidth();
 446         if (end > StringUtils.width(text)) {
 447             end = StringUtils.width(text);
 448         }
 449         hLineXY(0, 0, getWidth(), backgroundChar, fieldColor);
 450         putStringXY(0, 0, text.substring(screenToTextPosition(windowStart),
 451                 screenToTextPosition(end)), fieldColor);
 452
 453         // Fix the cursor, it will be rendered by TApplication.drawAll().
 454         updateCursor();
 455     }
 456
 457     // ------------------------------------------------------------------------
 458     // TField -----------------------------------------------------------------
 459     // ------------------------------------------------------------------------
 460
 461     /**
 462      * Convert a char (codepoint) to a string.
 463      *
 464      * @param ch the char
 465      * @return the string
 466      */
 467     private String codePointString(final int ch) {
 468         StringBuilder sb = new StringBuilder(1);
 469         sb.append(Character.toChars(ch));
 470         assert (Character.charCount(ch) == sb.length());
 471         return sb.toString();
 472     }
 473
 474     /**
 475      * Get field background character.
 476      *
 477      * @return background character
 478      */
 479     public final int getBackgroundChar() {
 480         return backgroundChar;
 481     }
 482
 483     /**
 484      * Set field background character.
 485      *
 486      * @param backgroundChar the background character
 487      */
 488     public void setBackgroundChar(final int backgroundChar) {
 489         this.backgroundChar = backgroundChar;
 490     }
 491
 492     /**
 493      * Get field text.
 494      *
 495      * @return field text
 496      */
 497     public final String getText() {
 498         return text;
 499     }
 500
 501     /**
 502      * Set field text.
 503      *
 504      * @param text the new field text
 505      */
 506     public void setText(final String text) {
 507         assert (text != null);
 508         this.text = text;
 509         position = 0;
 510         screenPosition = 0;
 511         windowStart = 0;
 512         if ((fixed == true) && (this.text.length() > getWidth())) {
 513             this.text = this.text.substring(0, getWidth());
 514         }
 515     }
 516
 517     /**
 518      * Dispatch to the action function.
 519      *
 520      * @param enter if true, the user pressed Enter, else this was an update
 521      * to the text.
 522      */
 523     protected void dispatch(final boolean enter) {
 524         if (enter) {
 525             if (enterAction != null) {
 526                 enterAction.DO(this);
 527             }
 528         } else {
 529             if (updateAction != null) {
 530                 updateAction.DO(this);
 531             }
 532         }
 533     }
 534
 535     /**
 536      * Determine string position from screen position.
 537      *
 538      * @param screenPosition the position on screen
 539      * @return the equivalent position in text
 540      */
 541     protected int screenToTextPosition(final int screenPosition) {
 542         if (screenPosition == 0) {
 543             return 0;
 544         }
 545
 546         int n = 0;
 547         for (int i = 0; i < text.length(); i++) {
 548             n += StringUtils.width(text.codePointAt(i));
 549             if (n >= screenPosition) {
 550                 return i + 1;
 551             }
 552         }
 553         // screenPosition exceeds the available text length.
 554         throw new IndexOutOfBoundsException("screenPosition " + screenPosition +
 555             " exceeds available text length " + text.length());
 556     }
 557
 558     /**
 559      * Update the visible cursor position to match the location of position
 560      * and windowStart.
 561      */
 562     protected void updateCursor() {
 563         if ((screenPosition > getWidth()) && fixed) {
 564             setCursorX(getWidth());
 565         } else if ((screenPosition - windowStart >= getWidth()) && !fixed) {
 566             setCursorX(getWidth() - 1);
 567         } else {
 568             setCursorX(screenPosition - windowStart);
 569         }
 570     }
 571
 572     /**
 573      * Normalize windowStart such that most of the field data if visible.
 574      */
 575     protected void normalizeWindowStart() {
 576         if (fixed) {
 577             // windowStart had better be zero, there is nothing to do here.
 578             assert (windowStart == 0);
 579             return;
 580         }
 581         windowStart = screenPosition - (getWidth() - 1);
 582         if (windowStart < 0) {
 583             windowStart = 0;
 584         }
 585
 586         updateCursor();
 587     }
 588
 589     /**
 590      * Append char to the end of the field.
 591      *
 592      * @param ch char to append
 593      */
 594     protected void appendChar(final int ch) {
 595         // Append the LAST character
 596         text += codePointString(ch);
 597         position += Character.charCount(ch);
 598         screenPosition += StringUtils.width(ch);
 599
 600         assert (position == text.length());
 601
 602         if (fixed) {
 603             if (screenPosition >= getWidth()) {
 604                 position -= Character.charCount(ch);
 605                 screenPosition -= StringUtils.width(ch);
 606             }
 607         } else {
 608             if ((screenPosition - windowStart) >= getWidth()) {
 609                 windowStart++;
 610             }
 611         }
 612     }
 613
 614     /**
 615      * Insert char somewhere in the middle of the field.
 616      *
 617      * @param ch char to append
 618      */
 619     protected void insertChar(final int ch) {
 620         text = text.substring(0, position) + codePointString(ch)
 621                 + text.substring(position);
 622         position += Character.charCount(ch);
 623         screenPosition += StringUtils.width(ch);
 624         if ((screenPosition - windowStart) == getWidth()) {
 625             assert (!fixed);
 626             windowStart++;
 627         }
 628     }
 629
 630     /**
 631      * Position the cursor at the first column.  The field may adjust the
 632      * window start to show as much of the field as possible.
 633      */
 634     public void home() {
 635         position = 0;
 636         screenPosition = 0;
 637         windowStart = 0;
 638     }
 639
 640     /**
 641      * Set the editing position to the last filled character.  The field may
 642      * adjust the window start to show as much of the field as possible.
 643      */
 644     public void end() {
 645         position = text.length();
 646         screenPosition = StringUtils.width(text);
 647         if (fixed == true) {
 648             if (screenPosition >= getWidth()) {
 649                 position -= Character.charCount(text.codePointBefore(position));
 650                 screenPosition = StringUtils.width(text) - 1;
 651              }
 652         } else {
 653             windowStart = StringUtils.width(text) - getWidth() + 1;
 654             if (windowStart < 0) {
 655                 windowStart = 0;
 656             }
 657         }
 658     }
 659
 660     /**
 661      * Set the editing position.  The field may adjust the window start to
 662      * show as much of the field as possible.
 663      *
 664      * @param position the new position
 665      * @throws IndexOutOfBoundsException if position is outside the range of
 666      * the available text
 667      */
 668     public void setPosition(final int position) {
 669         if ((position < 0) || (position >= text.length())) {
 670             throw new IndexOutOfBoundsException("Max length is " +
 671                 text.length() + ", requested position " + position);
 672         }
 673         this.position = position;
 674         normalizeWindowStart();
 675     }
 676
 677     /**
 678      * Set the active color key.
 679      *
 680      * @param activeColorKey ColorTheme key color to use when this field is
 681      * active
 682      */
 683     public void setActiveColorKey(final String activeColorKey) {
 684         this.activeColorKey = activeColorKey;
 685     }
 686
 687     /**
 688      * Set the inactive color key.
 689      *
 690      * @param inactiveColorKey ColorTheme key color to use when this field is
 691      * inactive
 692      */
 693     public void setInactiveColorKey(final String inactiveColorKey) {
 694         this.inactiveColorKey = inactiveColorKey;
 695     }
 696
 697     /**
 698      * Set the action to perform when the user presses enter.
 699      *
 700      * @param action the action to perform when the user presses enter
 701      */
 702     public void setEnterAction(final TAction action) {
 703         enterAction = action;
 704     }
 705
 706     /**
 707      * Set the action to perform when the field is updated.
 708      *
 709      * @param action the action to perform when the field is updated
 710      */
 711     public void setUpdateAction(final TAction action) {
 712         updateAction = action;
 713     }
 714
 715     // ------------------------------------------------------------------------
 716     // EditMenuUser -----------------------------------------------------------
 717     // ------------------------------------------------------------------------
 718
 719     /**
 720      * Check if the cut menu item should be enabled.
 721      *
 722      * @return true if the cut menu item should be enabled
 723      */
 724     public boolean isEditMenuCut() {
 725         return true;
 726     }
 727
 728     /**
 729      * Check if the copy menu item should be enabled.
 730      *
 731      * @return true if the copy menu item should be enabled
 732      */
 733     public boolean isEditMenuCopy() {
 734         return true;
 735     }
 736
 737     /**
 738      * Check if the paste menu item should be enabled.
 739      *
 740      * @return true if the paste menu item should be enabled
 741      */
 742     public boolean isEditMenuPaste() {
 743         return true;
 744     }
 745
 746     /**
 747      * Check if the clear menu item should be enabled.
 748      *
 749      * @return true if the clear menu item should be enabled
 750      */
 751     public boolean isEditMenuClear() {
 752         return true;
 753     }
 754
 755 }