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