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                 if (position < codePointLength(text)) {
 223                     screenPosition -= StringUtils.width(text.codePointBefore(position));
 224                     position -= Character.charCount(text.codePointBefore(position));
 225                 } else {
 226                     screenPosition--;
 227                     position--;
 228                 }
 229             }
 230             if (fixed == false) {
 231                 if ((screenPosition == windowStart) && (windowStart > 0)) {
 232                     windowStart -= StringUtils.width(text.codePointAt(
 233                         screenToTextPosition(windowStart)));
 234                 }
 235             }
 236             normalizeWindowStart();
 237             return;
 238         }
 239
 240         if (keypress.equals(kbRight)) {
 241             if (position < codePointLength(text)) {
 242                 screenPosition += StringUtils.width(text.codePointAt(position));
 243                 position += Character.charCount(text.codePointAt(position));
 244                 if (fixed == true) {
 245                     if (screenPosition == getWidth()) {
 246                         screenPosition--;
 247                         position -= Character.charCount(text.codePointAt(position));
 248                     }
 249                 } else {
 250                     if ((screenPosition - windowStart) >= getWidth()) {
 251                         windowStart += StringUtils.width(text.codePointAt(
 252                             screenToTextPosition(windowStart)));
 253                     }
 254                 }
 255             }
 256             return;
 257         }
 258
 259         if (keypress.equals(kbEnter)) {
 260             dispatch(true);
 261             return;
 262         }
 263
 264         if (keypress.equals(kbIns)) {
 265             insertMode = !insertMode;
 266             return;
 267         }
 268         if (keypress.equals(kbHome)) {
 269             home();
 270             return;
 271         }
 272
 273         if (keypress.equals(kbEnd)) {
 274             end();
 275             return;
 276         }
 277
 278         if (keypress.equals(kbDel)) {
 279             if ((codePointLength(text) > 0) && (position < codePointLength(text))) {
 280                 text = text.substring(0, position)
 281                         + text.substring(position + 1);
 282                 screenPosition = StringUtils.width(text.substring(0, position));
 283             }
 284             dispatch(false);
 285             return;
 286         }
 287
 288         if (keypress.equals(kbBackspace) || keypress.equals(kbBackspaceDel)) {
 289             if (position > 0) {
 290                 position -= Character.charCount(text.codePointBefore(position));
 291                 text = text.substring(0, position)
 292                         + text.substring(position + 1);
 293                 screenPosition = StringUtils.width(text.substring(0, position));
 294             }
 295             if (fixed == false) {
 296                 if ((screenPosition >= windowStart)
 297                     && (windowStart > 0)
 298                 ) {
 299                     windowStart -= StringUtils.width(text.codePointAt(
 300                         screenToTextPosition(windowStart)));
 301                 }
 302             }
 303             dispatch(false);
 304             normalizeWindowStart();
 305             return;
 306         }
 307
 308         if (!keypress.getKey().isFnKey()
 309             && !keypress.getKey().isAlt()
 310             && !keypress.getKey().isCtrl()
 311         ) {
 312             // Plain old keystroke, process it
 313             if ((position == codePointLength(text))
 314                 && (StringUtils.width(text) < getWidth())) {
 315
 316                 // Append case
 317                 appendChar(keypress.getKey().getChar());
 318             } else if ((position < codePointLength(text))
 319                 && (StringUtils.width(text) < getWidth())) {
 320
 321                 // Overwrite or insert a character
 322                 if (insertMode == false) {
 323                     // Replace character
 324                     text = text.substring(0, position)
 325                             + codePointString(keypress.getKey().getChar())
 326                             + text.substring(position + 1);
 327                     screenPosition += StringUtils.width(text.codePointAt(position));
 328                     position += Character.charCount(keypress.getKey().getChar());
 329                 } else {
 330                     // Insert character
 331                     insertChar(keypress.getKey().getChar());
 332                 }
 333             } else if ((position < codePointLength(text))
 334                 && (StringUtils.width(text) >= getWidth())) {
 335
 336                 // Multiple cases here
 337                 if ((fixed == true) && (insertMode == true)) {
 338                     // Buffer is full, do nothing
 339                 } else if ((fixed == true) && (insertMode == false)) {
 340                     // Overwrite the last character, maybe move position
 341                     text = text.substring(0, position)
 342                             + codePointString(keypress.getKey().getChar())
 343                             + text.substring(position + 1);
 344                     if (screenPosition < getWidth() - 1) {
 345                         screenPosition += StringUtils.width(text.codePointAt(position));
 346                         position += Character.charCount(keypress.getKey().getChar());
 347                     }
 348                 } else if ((fixed == false) && (insertMode == false)) {
 349                     // Overwrite the last character, definitely move position
 350                     text = text.substring(0, position)
 351                             + codePointString(keypress.getKey().getChar())
 352                             + text.substring(position + 1);
 353                     screenPosition += StringUtils.width(text.codePointAt(position));
 354                     position += Character.charCount(keypress.getKey().getChar());
 355                 } else {
 356                     if (position == codePointLength(text)) {
 357                         // Append this character
 358                         appendChar(keypress.getKey().getChar());
 359                     } else {
 360                         // Insert this character
 361                         insertChar(keypress.getKey().getChar());
 362                     }
 363                 }
 364             } else {
 365                 assert (!fixed);
 366
 367                 // Append this character
 368                 appendChar(keypress.getKey().getChar());
 369             }
 370             dispatch(false);
 371             return;
 372         }
 373
 374         // Pass to parent for the things we don't care about.
 375         super.onKeypress(keypress);
 376     }
 377
 378     // ------------------------------------------------------------------------
 379     // TWidget ----------------------------------------------------------------
 380     // ------------------------------------------------------------------------
 381
 382     /**
 383      * Draw the text field.
 384      */
 385     @Override
 386     public void draw() {
 387         CellAttributes fieldColor;
 388
 389         if (isAbsoluteActive()) {
 390             fieldColor = getTheme().getColor(activeColorKey);
 391         } else {
 392             fieldColor = getTheme().getColor(inactiveColorKey);
 393         }
 394
 395         int end = windowStart + getWidth();
 396         if (end > StringUtils.width(text)) {
 397             end = StringUtils.width(text);
 398         }
 399         hLineXY(0, 0, getWidth(), backgroundChar, fieldColor);
 400         putStringXY(0, 0, text.substring(screenToTextPosition(windowStart),
 401                 screenToTextPosition(end)), fieldColor);
 402
 403         // Fix the cursor, it will be rendered by TApplication.drawAll().
 404         updateCursor();
 405     }
 406
 407     // ------------------------------------------------------------------------
 408     // TField -----------------------------------------------------------------
 409     // ------------------------------------------------------------------------
 410
 411     /**
 412      * Convert a char (codepoint) to a string.
 413      *
 414      * @param ch the char
 415      * @return the string
 416      */
 417     private String codePointString(final int ch) {
 418         StringBuilder sb = new StringBuilder(1);
 419         sb.append(Character.toChars(ch));
 420         return sb.toString();
 421     }
 422
 423     /**
 424      * Get the number of codepoints in a string.
 425      *
 426      * @param str the string
 427      * @return the number of codepoints
 428      */
 429     private int codePointLength(final String str) {
 430         return str.codePointCount(0, str.length());
 431     }
 432
 433     /**
 434      * Get field background character.
 435      *
 436      * @return background character
 437      */
 438     public final int getBackgroundChar() {
 439         return backgroundChar;
 440     }
 441
 442     /**
 443      * Set field background character.
 444      *
 445      * @param backgroundChar the background character
 446      */
 447     public void setBackgroundChar(final int backgroundChar) {
 448         this.backgroundChar = backgroundChar;
 449     }
 450
 451     /**
 452      * Get field text.
 453      *
 454      * @return field text
 455      */
 456     public final String getText() {
 457         return text;
 458     }
 459
 460     /**
 461      * Set field text.
 462      *
 463      * @param text the new field text
 464      */
 465     public void setText(final String text) {
 466         assert (text != null);
 467         this.text = text;
 468         position = 0;
 469         windowStart = 0;
 470     }
 471
 472     /**
 473      * Dispatch to the action function.
 474      *
 475      * @param enter if true, the user pressed Enter, else this was an update
 476      * to the text.
 477      */
 478     protected void dispatch(final boolean enter) {
 479         if (enter) {
 480             if (enterAction != null) {
 481                 enterAction.DO();
 482             }
 483         } else {
 484             if (updateAction != null) {
 485                 updateAction.DO();
 486             }
 487         }
 488     }
 489
 490     /**
 491      * Determine string position from screen position.
 492      *
 493      * @param screenPosition the position on screen
 494      * @return the equivalent position in text
 495      */
 496     protected int screenToTextPosition(final int screenPosition) {
 497         if (screenPosition == 0) {
 498             return 0;
 499         }
 500
 501         int n = 0;
 502         for (int i = 0; i < codePointLength(text); i++) {
 503             n += StringUtils.width(text.codePointAt(i));
 504             if (n >= screenPosition) {
 505                 return i + 1;
 506             }
 507         }
 508         // screenPosition exceeds the available text length.
 509         throw new IndexOutOfBoundsException("screenPosition " + screenPosition +
 510             " exceeds available text length " + codePointLength(text));
 511     }
 512
 513     /**
 514      * Update the visible cursor position to match the location of position
 515      * and windowStart.
 516      */
 517     protected void updateCursor() {
 518         if ((screenPosition > getWidth()) && fixed) {
 519             setCursorX(getWidth());
 520         } else if ((screenPosition - windowStart >= getWidth()) && !fixed) {
 521             setCursorX(getWidth() - 1);
 522         } else {
 523             setCursorX(screenPosition - windowStart);
 524         }
 525     }
 526
 527     /**
 528      * Normalize windowStart such that most of the field data if visible.
 529      */
 530     protected void normalizeWindowStart() {
 531         if (fixed) {
 532             // windowStart had better be zero, there is nothing to do here.
 533             assert (windowStart == 0);
 534             return;
 535         }
 536         windowStart = screenPosition - (getWidth() - 1);
 537         if (windowStart < 0) {
 538             windowStart = 0;
 539         }
 540
 541         updateCursor();
 542     }
 543
 544     /**
 545      * Append char to the end of the field.
 546      *
 547      * @param ch char to append
 548      */
 549     protected void appendChar(final int ch) {
 550         // Append the LAST character
 551         text += codePointString(ch);
 552         position += Character.charCount(ch);
 553         screenPosition += StringUtils.width(ch);
 554
 555         assert (position == codePointLength(text));
 556
 557         if (fixed) {
 558             if (screenPosition >= getWidth()) {
 559                 position -= Character.charCount(ch);
 560                 screenPosition -= StringUtils.width(ch);
 561             }
 562         } else {
 563             if ((screenPosition - windowStart) >= getWidth()) {
 564                 windowStart++;
 565             }
 566         }
 567     }
 568
 569     /**
 570      * Insert char somewhere in the middle of the field.
 571      *
 572      * @param ch char to append
 573      */
 574     protected void insertChar(final int ch) {
 575         text = text.substring(0, position) + codePointString(ch)
 576                 + text.substring(position);
 577         position += Character.charCount(ch);
 578         screenPosition += StringUtils.width(ch);
 579         if ((screenPosition - windowStart) == getWidth()) {
 580             assert (!fixed);
 581             windowStart++;
 582         }
 583     }
 584
 585     /**
 586      * Position the cursor at the first column.  The field may adjust the
 587      * window start to show as much of the field as possible.
 588      */
 589     public void home() {
 590         position = 0;
 591         screenPosition = 0;
 592         windowStart = 0;
 593     }
 594
 595     /**
 596      * Set the editing position to the last filled character.  The field may
 597      * adjust the window start to show as much of the field as possible.
 598      */
 599     public void end() {
 600         position = codePointLength(text);
 601         screenPosition = StringUtils.width(text);
 602         if (fixed == true) {
 603             if (screenPosition >= getWidth()) {
 604                 position = codePointLength(text) - 1;
 605                 screenPosition = StringUtils.width(text) - 1;
 606              }
 607         } else {
 608             windowStart = StringUtils.width(text) - getWidth() + 1;
 609             if (windowStart < 0) {
 610                 windowStart = 0;
 611             }
 612         }
 613     }
 614
 615     /**
 616      * Set the editing position.  The field may adjust the window start to
 617      * show as much of the field as possible.
 618      *
 619      * @param position the new position
 620      * @throws IndexOutOfBoundsException if position is outside the range of
 621      * the available text
 622      */
 623     public void setPosition(final int position) {
 624         if ((position < 0) || (position >= codePointLength(text))) {
 625             throw new IndexOutOfBoundsException("Max length is " +
 626                 codePointLength(text) + ", requested position " + position);
 627         }
 628         this.position = position;
 629         normalizeWindowStart();
 630     }
 631
 632     /**
 633      * Set the active color key.
 634      *
 635      * @param activeColorKey ColorTheme key color to use when this field is
 636      * active
 637      */
 638     public void setActiveColorKey(final String activeColorKey) {
 639         this.activeColorKey = activeColorKey;
 640     }
 641
 642     /**
 643      * Set the inactive color key.
 644      *
 645      * @param inactiveColorKey ColorTheme key color to use when this field is
 646      * inactive
 647      */
 648     public void setInactiveColorKey(final String inactiveColorKey) {
 649         this.inactiveColorKey = inactiveColorKey;
 650     }
 651
 652     /**
 653      * Set the action to perform when the user presses enter.
 654      *
 655      * @param action the action to perform when the user presses enter
 656      */
 657     public void setEnterAction(final TAction action) {
 658         enterAction = action;
 659     }
 660
 661     /**
 662      * Set the action to perform when the field is updated.
 663      *
 664      * @param action the action to perform when the field is updated
 665      */
 666     public void setUpdateAction(final TAction action) {
 667         updateAction = action;
 668     }
 669
 670 }