src/jexer/TList.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 java.util.ArrayList;
  32 import java.util.List;
  33
  34 import jexer.bits.CellAttributes;
  35 import jexer.bits.StringUtils;
  36 import jexer.event.TKeypressEvent;
  37 import jexer.event.TMouseEvent;
  38 import static jexer.TKeypress.*;
  39
  40 /**
  41  * TList shows a list of strings, and lets the user select one.
  42  */
  43 public class TList extends TScrollableWidget {
  44
  45     // ------------------------------------------------------------------------
  46     // Variables --------------------------------------------------------------
  47     // ------------------------------------------------------------------------
  48
  49     /**
  50      * The list of strings to display.
  51      */
  52     private List<String> strings;
  53
  54     /**
  55      * Selected string.
  56      */
  57     private int selectedString = -1;
  58
  59     /**
  60      * Maximum width of a single line.
  61      */
  62     private int maxLineWidth;
  63
  64     /**
  65      * The action to perform when the user selects an item (double-clicks or
  66      * enter).
  67      */
  68     protected TAction enterAction = null;
  69
  70     /**
  71      * The action to perform when the user selects an item (single-click).
  72      */
  73     protected TAction singleClickAction = null;
  74
  75     /**
  76      * The action to perform when the user navigates with keyboard.
  77      */
  78     protected TAction moveAction = null;
  79
  80     // ------------------------------------------------------------------------
  81     // Constructors -----------------------------------------------------------
  82     // ------------------------------------------------------------------------
  83
  84     /**
  85      * Public constructor.
  86      *
  87      * @param parent parent widget
  88      * @param strings list of strings to show
  89      * @param x column relative to parent
  90      * @param y row relative to parent
  91      * @param width width of text area
  92      * @param height height of text area
  93      */
  94     public TList(final TWidget parent, final List<String> strings, final int x,
  95         final int y, final int width, final int height) {
  96
  97         this(parent, strings, x, y, width, height, null, null, null);
  98     }
  99
 100     /**
 101      * Public constructor.
 102      *
 103      * @param parent parent widget
 104      * @param strings list of strings to show.  This is allowed to be null
 105      * and set later with setList() or by subclasses.
 106      * @param x column relative to parent
 107      * @param y row relative to parent
 108      * @param width width of text area
 109      * @param height height of text area
 110      * @param enterAction action to perform when an item is selected
 111      */
 112     public TList(final TWidget parent, final List<String> strings, final int x,
 113         final int y, final int width, final int height,
 114         final TAction enterAction) {
 115
 116         this(parent, strings, x, y, width, height, enterAction, null, null);
 117     }
 118
 119     /**
 120      * Public constructor.
 121      *
 122      * @param parent parent widget
 123      * @param strings list of strings to show.  This is allowed to be null
 124      * and set later with setList() or by subclasses.
 125      * @param x column relative to parent
 126      * @param y row relative to parent
 127      * @param width width of text area
 128      * @param height height of text area
 129      * @param enterAction action to perform when an item is selected
 130      * @param moveAction action to perform when the user navigates to a new
 131      * item with arrow/page keys
 132      */
 133     public TList(final TWidget parent, final List<String> strings, final int x,
 134         final int y, final int width, final int height,
 135         final TAction enterAction, final TAction moveAction) {
 136
 137         this(parent, strings, x, y, width, height, enterAction, moveAction,
 138             null);
 139     }
 140
 141     /**
 142      * Public constructor.
 143      *
 144      * @param parent parent widget
 145      * @param strings list of strings to show.  This is allowed to be null
 146      * and set later with setList() or by subclasses.
 147      * @param x column relative to parent
 148      * @param y row relative to parent
 149      * @param width width of text area
 150      * @param height height of text area
 151      * @param enterAction action to perform when an item is selected
 152      * @param moveAction action to perform when the user navigates to a new
 153      * item with arrow/page keys
 154      * @param singleClickAction action to perform when the user clicks on an
 155      * item
 156      */
 157     public TList(final TWidget parent, final List<String> strings, final int x,
 158         final int y, final int width, final int height,
 159         final TAction enterAction, final TAction moveAction,
 160         final TAction singleClickAction) {
 161
 162         super(parent, x, y, width, height);
 163         this.enterAction = enterAction;
 164         this.moveAction = moveAction;
 165         this.singleClickAction = singleClickAction;
 166         this.strings = new ArrayList<String>();
 167         if (strings != null) {
 168             this.strings.addAll(strings);
 169         }
 170
 171         hScroller = new THScroller(this, 0, getHeight() - 1, getWidth() - 1);
 172         vScroller = new TVScroller(this, getWidth() - 1, 0, getHeight() - 1);
 173         reflowData();
 174     }
 175
 176     // ------------------------------------------------------------------------
 177     // Event handlers ---------------------------------------------------------
 178     // ------------------------------------------------------------------------
 179
 180     /**
 181      * Handle mouse press events.
 182      *
 183      * @param mouse mouse button press event
 184      */
 185     @Override
 186     public void onMouseDown(final TMouseEvent mouse) {
 187         if (mouse.isMouseWheelUp()) {
 188             verticalDecrement();
 189             return;
 190         }
 191         if (mouse.isMouseWheelDown()) {
 192             verticalIncrement();
 193             return;
 194         }
 195
 196         if ((mouse.getX() < getWidth() - 1)
 197             && (mouse.getY() < getHeight() - 1)
 198         ) {
 199             if (getVerticalValue() + mouse.getY() < strings.size()) {
 200                 selectedString = getVerticalValue() + mouse.getY();
 201                 dispatchSingleClick();
 202             }
 203             return;
 204         }
 205
 206         // Pass to children
 207         super.onMouseDown(mouse);
 208     }
 209
 210     /**
 211      * Handle mouse double click.
 212      *
 213      * @param mouse mouse double click event
 214      */
 215     @Override
 216     public void onMouseDoubleClick(final TMouseEvent mouse) {
 217         if ((mouse.getX() < getWidth() - 1)
 218             && (mouse.getY() < getHeight() - 1)
 219         ) {
 220             if (getVerticalValue() + mouse.getY() < strings.size()) {
 221                 selectedString = getVerticalValue() + mouse.getY();
 222                 dispatchEnter();
 223             }
 224             return;
 225         }
 226
 227         // Pass to children
 228         super.onMouseDoubleClick(mouse);
 229     }
 230
 231     /**
 232      * Handle keystrokes.
 233      *
 234      * @param keypress keystroke event
 235      */
 236     @Override
 237     public void onKeypress(final TKeypressEvent keypress) {
 238         if (keypress.equals(kbLeft)) {
 239             horizontalDecrement();
 240         } else if (keypress.equals(kbRight)) {
 241             horizontalIncrement();
 242         } else if (keypress.equals(kbUp)) {
 243             if (strings.size() > 0) {
 244                 if (selectedString >= 0) {
 245                     if (selectedString > 0) {
 246                         if (selectedString - getVerticalValue() == 0) {
 247                             verticalDecrement();
 248                         }
 249                         selectedString--;
 250                     }
 251                 } else {
 252                     selectedString = strings.size() - 1;
 253                 }
 254             }
 255             if (selectedString >= 0) {
 256                 dispatchMove();
 257             }
 258         } else if (keypress.equals(kbDown)) {
 259             if (strings.size() > 0) {
 260                 if (selectedString >= 0) {
 261                     if (selectedString < strings.size() - 1) {
 262                         selectedString++;
 263                         if (selectedString - getVerticalValue() == getHeight() - 1) {
 264                             verticalIncrement();
 265                         }
 266                     }
 267                 } else {
 268                     selectedString = 0;
 269                 }
 270             }
 271             if (selectedString >= 0) {
 272                 dispatchMove();
 273             }
 274         } else if (keypress.equals(kbPgUp)) {
 275             bigVerticalDecrement();
 276             if (selectedString >= 0) {
 277                 selectedString -= getHeight() - 1;
 278                 if (selectedString < 0) {
 279                     selectedString = 0;
 280                 }
 281             }
 282             if (selectedString >= 0) {
 283                 dispatchMove();
 284             }
 285         } else if (keypress.equals(kbPgDn)) {
 286             bigVerticalIncrement();
 287             if (selectedString >= 0) {
 288                 selectedString += getHeight() - 1;
 289                 if (selectedString > strings.size() - 1) {
 290                     selectedString = strings.size() - 1;
 291                 }
 292             }
 293             if (selectedString >= 0) {
 294                 dispatchMove();
 295             }
 296         } else if (keypress.equals(kbHome)) {
 297             toTop();
 298             if (strings.size() > 0) {
 299                 selectedString = 0;
 300             }
 301             if (selectedString >= 0) {
 302                 dispatchMove();
 303             }
 304         } else if (keypress.equals(kbEnd)) {
 305             toBottom();
 306             if (strings.size() > 0) {
 307                 selectedString = strings.size() - 1;
 308             }
 309             if (selectedString >= 0) {
 310                 dispatchMove();
 311             }
 312         } else if (keypress.equals(kbTab)) {
 313             getParent().switchWidget(true);
 314         } else if (keypress.equals(kbShiftTab) || keypress.equals(kbBackTab)) {
 315             getParent().switchWidget(false);
 316         } else if (keypress.equals(kbEnter)) {
 317             if (selectedString >= 0) {
 318                 dispatchEnter();
 319             }
 320         } else {
 321             // Pass other keys (tab etc.) on
 322             super.onKeypress(keypress);
 323         }
 324     }
 325
 326     // ------------------------------------------------------------------------
 327     // TScrollableWidget ------------------------------------------------------
 328     // ------------------------------------------------------------------------
 329
 330     /**
 331      * Override TWidget's width: we need to set child widget widths.
 332      *
 333      * @param width new widget width
 334      */
 335     @Override
 336     public void setWidth(final int width) {
 337         super.setWidth(width);
 338         hScroller.setWidth(getWidth() - 1);
 339         vScroller.setX(getWidth() - 1);
 340     }
 341
 342     /**
 343      * Override TWidget's height: we need to set child widget heights.
 344      * time.
 345      *
 346      * @param height new widget height
 347      */
 348     @Override
 349     public void setHeight(final int height) {
 350         super.setHeight(height);
 351         hScroller.setY(getHeight() - 1);
 352         vScroller.setHeight(getHeight() - 1);
 353     }
 354
 355     /**
 356      * Resize for a new width/height.
 357      */
 358     @Override
 359     public void reflowData() {
 360
 361         // Reset the lines
 362         selectedString = -1;
 363         maxLineWidth = 0;
 364
 365         for (int i = 0; i < strings.size(); i++) {
 366             String line = strings.get(i);
 367             int lineLength = StringUtils.width(line);
 368             if (lineLength > maxLineWidth) {
 369                 maxLineWidth = lineLength;
 370             }
 371         }
 372
 373         setBottomValue(strings.size() - getHeight() + 1);
 374         if (getBottomValue() < 0) {
 375             setBottomValue(0);
 376         }
 377
 378         setRightValue(maxLineWidth - getWidth() + 1);
 379         if (getRightValue() < 0) {
 380             setRightValue(0);
 381         }
 382     }
 383
 384     /**
 385      * Draw the list.
 386      */
 387     @Override
 388     public void draw() {
 389         CellAttributes color = null;
 390         int begin = getVerticalValue();
 391         int topY = 0;
 392         for (int i = begin; i < strings.size(); i++) {
 393             String line = strings.get(i);
 394             if (getHorizontalValue() < line.length()) {
 395                 line = line.substring(getHorizontalValue());
 396             } else {
 397                 line = "";
 398             }
 399             if (i == selectedString) {
 400                 if (isAbsoluteActive()) {
 401                     color = getTheme().getColor("tlist.selected");
 402                 } else {
 403                     color = getTheme().getColor("tlist.selected.inactive");
 404                 }
 405             } else if (isAbsoluteActive()) {
 406                 color = getTheme().getColor("tlist");
 407             } else {
 408                 color = getTheme().getColor("tlist.inactive");
 409             }
 410             String formatString = "%-" + Integer.toString(getWidth() - 1) + "s";
 411             putStringXY(0, topY, String.format(formatString, line), color);
 412             topY++;
 413             if (topY >= getHeight() - 1) {
 414                 break;
 415             }
 416         }
 417
 418         if (isAbsoluteActive()) {
 419             color = getTheme().getColor("tlist");
 420         } else {
 421             color = getTheme().getColor("tlist.inactive");
 422         }
 423
 424         // Pad the rest with blank lines
 425         for (int i = topY; i < getHeight() - 1; i++) {
 426             hLineXY(0, i, getWidth() - 1, ' ', color);
 427         }
 428     }
 429
 430     // ------------------------------------------------------------------------
 431     // TList ------------------------------------------------------------------
 432     // ------------------------------------------------------------------------
 433
 434     /**
 435      * Get the selection index.
 436      *
 437      * @return -1 if nothing is selected, otherwise the index into the list
 438      */
 439     public final int getSelectedIndex() {
 440         return selectedString;
 441     }
 442
 443     /**
 444      * Set the selected string index.
 445      *
 446      * @param index -1 to unselect, otherwise the index into the list
 447      */
 448     public final void setSelectedIndex(final int index) {
 449         selectedString = index;
 450     }
 451
 452     /**
 453      * Get a selectable string by index.
 454      *
 455      * @param idx index into list
 456      * @return the string at idx in the list
 457      */
 458     public final String getListItem(final int idx) {
 459         return strings.get(idx);
 460     }
 461
 462     /**
 463      * Get the selected string.
 464      *
 465      * @return the selected string, or null of nothing is selected yet
 466      */
 467     public final String getSelected() {
 468         if ((selectedString >= 0) && (selectedString <= strings.size() - 1)) {
 469             return strings.get(selectedString);
 470         }
 471         return null;
 472     }
 473
 474     /**
 475      * Get the maximum selection index value.
 476      *
 477      * @return -1 if the list is empty
 478      */
 479     public final int getMaxSelectedIndex() {
 480         return strings.size() - 1;
 481     }
 482
 483     /**
 484      * Get a copy of the list of strings to display.
 485      *
 486      * @return the list of strings
 487      */
 488     public final List<String> getList() {
 489         return new ArrayList<String>(strings);
 490     }
 491
 492     /**
 493      * Set the new list of strings to display.
 494      *
 495      * @param list new list of strings
 496      */
 497     public final void setList(final List<String> list) {
 498         strings.clear();
 499         strings.addAll(list);
 500         reflowData();
 501     }
 502
 503     /**
 504      * Perform user selection action.
 505      */
 506     public void dispatchEnter() {
 507         assert (selectedString >= 0);
 508         assert (selectedString < strings.size());
 509         if (enterAction != null) {
 510             enterAction.DO(this);
 511         }
 512     }
 513
 514     /**
 515      * Perform list movement action.
 516      */
 517     public void dispatchMove() {
 518         assert (selectedString >= 0);
 519         assert (selectedString < strings.size());
 520         if (moveAction != null) {
 521             moveAction.DO(this);
 522         }
 523     }
 524
 525     /**
 526      * Perform single-click action.
 527      */
 528     public void dispatchSingleClick() {
 529         assert (selectedString >= 0);
 530         assert (selectedString < strings.size());
 531         if (singleClickAction != null) {
 532             singleClickAction.DO(this);
 533         }
 534     }
 535
 536 }