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      * Resize for a new width/height.
 332      */
 333     @Override
 334     public void reflowData() {
 335
 336         // Reset the lines
 337         selectedString = -1;
 338         maxLineWidth = 0;
 339
 340         for (int i = 0; i < strings.size(); i++) {
 341             String line = strings.get(i);
 342             int lineLength = StringUtils.width(line);
 343             if (lineLength > maxLineWidth) {
 344                 maxLineWidth = lineLength;
 345             }
 346         }
 347
 348         setBottomValue(strings.size() - getHeight() + 1);
 349         if (getBottomValue() < 0) {
 350             setBottomValue(0);
 351         }
 352
 353         setRightValue(maxLineWidth - getWidth() + 1);
 354         if (getRightValue() < 0) {
 355             setRightValue(0);
 356         }
 357     }
 358
 359     /**
 360      * Draw the list.
 361      */
 362     @Override
 363     public void draw() {
 364         CellAttributes color = null;
 365         int begin = getVerticalValue();
 366         int topY = 0;
 367         for (int i = begin; i < strings.size(); i++) {
 368             String line = strings.get(i);
 369             if (getHorizontalValue() < line.length()) {
 370                 line = line.substring(getHorizontalValue());
 371             } else {
 372                 line = "";
 373             }
 374             if (i == selectedString) {
 375                 if (isAbsoluteActive()) {
 376                     color = getTheme().getColor("tlist.selected");
 377                 } else {
 378                     color = getTheme().getColor("tlist.selected.inactive");
 379                 }
 380             } else if (isAbsoluteActive()) {
 381                 color = getTheme().getColor("tlist");
 382             } else {
 383                 color = getTheme().getColor("tlist.inactive");
 384             }
 385             String formatString = "%-" + Integer.toString(getWidth() - 1) + "s";
 386             putStringXY(0, topY, String.format(formatString, line), color);
 387             topY++;
 388             if (topY >= getHeight() - 1) {
 389                 break;
 390             }
 391         }
 392
 393         if (isAbsoluteActive()) {
 394             color = getTheme().getColor("tlist");
 395         } else {
 396             color = getTheme().getColor("tlist.inactive");
 397         }
 398
 399         // Pad the rest with blank lines
 400         for (int i = topY; i < getHeight() - 1; i++) {
 401             hLineXY(0, i, getWidth() - 1, ' ', color);
 402         }
 403     }
 404
 405     // ------------------------------------------------------------------------
 406     // TList ------------------------------------------------------------------
 407     // ------------------------------------------------------------------------
 408
 409     /**
 410      * Get the selection index.
 411      *
 412      * @return -1 if nothing is selected, otherwise the index into the list
 413      */
 414     public final int getSelectedIndex() {
 415         return selectedString;
 416     }
 417
 418     /**
 419      * Set the selected string index.
 420      *
 421      * @param index -1 to unselect, otherwise the index into the list
 422      */
 423     public final void setSelectedIndex(final int index) {
 424         selectedString = index;
 425     }
 426
 427     /**
 428      * Get a selectable string by index.
 429      *
 430      * @param idx index into list
 431      * @return the string at idx in the list
 432      */
 433     public final String getListItem(final int idx) {
 434         return strings.get(idx);
 435     }
 436
 437     /**
 438      * Get the selected string.
 439      *
 440      * @return the selected string, or null of nothing is selected yet
 441      */
 442     public final String getSelected() {
 443         if ((selectedString >= 0) && (selectedString <= strings.size() - 1)) {
 444             return strings.get(selectedString);
 445         }
 446         return null;
 447     }
 448
 449     /**
 450      * Get the maximum selection index value.
 451      *
 452      * @return -1 if the list is empty
 453      */
 454     public final int getMaxSelectedIndex() {
 455         return strings.size() - 1;
 456     }
 457
 458     /**
 459      * Get a copy of the list of strings to display.
 460      *
 461      * @return the list of strings
 462      */
 463     public final List<String> getList() {
 464         return new ArrayList<String>(strings);
 465     }
 466
 467     /**
 468      * Set the new list of strings to display.
 469      *
 470      * @param list new list of strings
 471      */
 472     public final void setList(final List<String> list) {
 473         strings.clear();
 474         strings.addAll(list);
 475         reflowData();
 476     }
 477
 478     /**
 479      * Perform user selection action.
 480      */
 481     public void dispatchEnter() {
 482         assert (selectedString >= 0);
 483         assert (selectedString < strings.size());
 484         if (enterAction != null) {
 485             enterAction.DO();
 486         }
 487     }
 488
 489     /**
 490      * Perform list movement action.
 491      */
 492     public void dispatchMove() {
 493         assert (selectedString >= 0);
 494         assert (selectedString < strings.size());
 495         if (moveAction != null) {
 496             moveAction.DO();
 497         }
 498     }
 499
 500     /**
 501      * Perform single-click action.
 502      */
 503     public void dispatchSingleClick() {
 504         assert (selectedString >= 0);
 505         assert (selectedString < strings.size());
 506         if (singleClickAction != null) {
 507             singleClickAction.DO();
 508         }
 509     }
 510
 511 }