src/jexer/TWidget.java

   1 /*
   2  * Jexer - Java Text User Interface
   3  *
   4  * The MIT License (MIT)
   5  *
   6  * Copyright (C) 2017 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.io.IOException;
  32 import java.util.List;
  33 import java.util.ArrayList;
  34
  35 import jexer.bits.ColorTheme;
  36 import jexer.event.TCommandEvent;
  37 import jexer.event.TInputEvent;
  38 import jexer.event.TKeypressEvent;
  39 import jexer.event.TMenuEvent;
  40 import jexer.event.TMouseEvent;
  41 import jexer.event.TResizeEvent;
  42 import jexer.io.Screen;
  43 import jexer.menu.TMenu;
  44 import static jexer.TKeypress.*;
  45
  46 /**
  47  * TWidget is the base class of all objects that can be drawn on screen or
  48  * handle user input events.
  49  */
  50 public abstract class TWidget implements Comparable<TWidget> {
  51
  52     // ------------------------------------------------------------------------
  53     // Common widget attributes -----------------------------------------------
  54     // ------------------------------------------------------------------------
  55
  56     /**
  57      * Every widget has a parent widget that it may be "contained" in.  For
  58      * example, a TWindow might contain several TTextFields, or a TComboBox
  59      * may contain a TScrollBar.
  60      */
  61     private TWidget parent = null;
  62
  63     /**
  64      * Get parent widget.
  65      *
  66      * @return parent widget
  67      */
  68     public final TWidget getParent() {
  69         return parent;
  70     }
  71
  72     /**
  73      * Child widgets that this widget contains.
  74      */
  75     private List<TWidget> children;
  76
  77     /**
  78      * Get the list of child widgets that this widget contains.
  79      *
  80      * @return the list of child widgets
  81      */
  82     public List<TWidget> getChildren() {
  83         return children;
  84     }
  85
  86     /**
  87      * The currently active child widget that will receive keypress events.
  88      */
  89     private TWidget activeChild = null;
  90
  91     /**
  92      * If true, this widget will receive events.
  93      */
  94     private boolean active = false;
  95
  96     /**
  97      * Get active flag.
  98      *
  99      * @return if true, this widget will receive events
 100      */
 101     public final boolean isActive() {
 102         return active;
 103     }
 104
 105     /**
 106      * Set active flag.
 107      *
 108      * @param active if true, this widget will receive events
 109      */
 110     public final void setActive(final boolean active) {
 111         this.active = active;
 112     }
 113
 114     /**
 115      * The window that this widget draws to.
 116      */
 117     private TWindow window = null;
 118
 119     /**
 120      * Get the window this widget is on.
 121      *
 122      * @return the window
 123      */
 124     public final TWindow getWindow() {
 125         return window;
 126     }
 127
 128     /**
 129      * Absolute X position of the top-left corner.
 130      */
 131     private int x = 0;
 132
 133     /**
 134      * Get X position.
 135      *
 136      * @return absolute X position of the top-left corner
 137      */
 138     public final int getX() {
 139         return x;
 140     }
 141
 142     /**
 143      * Set X position.
 144      *
 145      * @param x absolute X position of the top-left corner
 146      */
 147     public final void setX(final int x) {
 148         this.x = x;
 149     }
 150
 151     /**
 152      * Absolute Y position of the top-left corner.
 153      */
 154     private int y = 0;
 155
 156     /**
 157      * Get Y position.
 158      *
 159      * @return absolute Y position of the top-left corner
 160      */
 161     public final int getY() {
 162         return y;
 163     }
 164
 165     /**
 166      * Set Y position.
 167      *
 168      * @param y absolute Y position of the top-left corner
 169      */
 170     public final void setY(final int y) {
 171         this.y = y;
 172     }
 173
 174     /**
 175      * Width.
 176      */
 177     private int width = 0;
 178
 179     /**
 180      * Get the width.
 181      *
 182      * @return widget width
 183      */
 184     public final int getWidth() {
 185         return this.width;
 186     }
 187
 188     /**
 189      * Change the width.
 190      *
 191      * @param width new widget width
 192      */
 193     public final void setWidth(final int width) {
 194         this.width = width;
 195     }
 196
 197     /**
 198      * Height.
 199      */
 200     private int height = 0;
 201
 202     /**
 203      * Get the height.
 204      *
 205      * @return widget height
 206      */
 207     public final int getHeight() {
 208         return this.height;
 209     }
 210
 211     /**
 212      * Change the height.
 213      *
 214      * @param height new widget height
 215      */
 216     public final void setHeight(final int height) {
 217         this.height = height;
 218     }
 219
 220     /**
 221      * My tab order inside a window or containing widget.
 222      */
 223     private int tabOrder = 0;
 224
 225     /**
 226      * If true, this widget can be tabbed to or receive events.
 227      */
 228     private boolean enabled = true;
 229
 230     /**
 231      * Get enabled flag.
 232      *
 233      * @return if true, this widget can be tabbed to or receive events
 234      */
 235     public final boolean isEnabled() {
 236         return enabled;
 237     }
 238
 239     /**
 240      * Set enabled flag.
 241      *
 242      * @param enabled if true, this widget can be tabbed to or receive events
 243      */
 244     public final void setEnabled(final boolean enabled) {
 245         this.enabled = enabled;
 246         if (!enabled) {
 247             active = false;
 248             // See if there are any active siblings to switch to
 249             boolean foundSibling = false;
 250             if (parent != null) {
 251                 for (TWidget w: parent.children) {
 252                     if ((w.enabled)
 253                         && !(this instanceof THScroller)
 254                         && !(this instanceof TVScroller)
 255                     ) {
 256                         parent.activate(w);
 257                         foundSibling = true;
 258                         break;
 259                     }
 260                 }
 261                 if (!foundSibling) {
 262                     parent.activeChild = null;
 263                 }
 264             }
 265         }
 266     }
 267
 268     /**
 269      * If true, this widget has a cursor.
 270      */
 271     private boolean cursorVisible = false;
 272
 273     /**
 274      * Set visible cursor flag.
 275      *
 276      * @param cursorVisible if true, this widget has a cursor
 277      */
 278     public final void setCursorVisible(final boolean cursorVisible) {
 279         this.cursorVisible = cursorVisible;
 280     }
 281
 282     /**
 283      * See if this widget has a visible cursor.
 284      *
 285      * @return if true, this widget has a visible cursor
 286      */
 287     public final boolean isCursorVisible() {
 288         return cursorVisible;
 289     }
 290
 291     /**
 292      * Cursor column position in relative coordinates.
 293      */
 294     private int cursorX = 0;
 295
 296     /**
 297      * Get cursor X value.
 298      *
 299      * @return cursor column position in relative coordinates
 300      */
 301     public final int getCursorX() {
 302         return cursorX;
 303     }
 304
 305     /**
 306      * Set cursor X value.
 307      *
 308      * @param cursorX column position in relative coordinates
 309      */
 310     public final void setCursorX(final int cursorX) {
 311         this.cursorX = cursorX;
 312     }
 313
 314     /**
 315      * Cursor row position in relative coordinates.
 316      */
 317     private int cursorY = 0;
 318
 319     /**
 320      * Get cursor Y value.
 321      *
 322      * @return cursor row position in relative coordinates
 323      */
 324     public final int getCursorY() {
 325         return cursorY;
 326     }
 327
 328     /**
 329      * Set cursor Y value.
 330      *
 331      * @param cursorY row position in relative coordinates
 332      */
 333     public final void setCursorY(final int cursorY) {
 334         this.cursorY = cursorY;
 335     }
 336
 337     // ------------------------------------------------------------------------
 338     // TApplication integration -----------------------------------------------
 339     // ------------------------------------------------------------------------
 340
 341     /**
 342      * Get this TWidget's parent TApplication.
 343      *
 344      * @return the parent TApplication
 345      */
 346     public TApplication getApplication() {
 347         return window.getApplication();
 348     }
 349
 350     /**
 351      * Get the Screen.
 352      *
 353      * @return the Screen
 354      */
 355     public Screen getScreen() {
 356         return window.getScreen();
 357     }
 358
 359     /**
 360      * Comparison operator.  For various subclasses it sorts on:
 361      * <ul>
 362      * <li>tabOrder for TWidgets</li>
 363      * <li>z for TWindows</li>
 364      * <li>text for TTreeItems</li>
 365      * </ul>
 366      *
 367      * @param that another TWidget, TWindow, or TTreeItem instance
 368      * @return difference between this.tabOrder and that.tabOrder, or
 369      * difference between this.z and that.z, or String.compareTo(text)
 370      */
 371     public final int compareTo(final TWidget that) {
 372         if ((this instanceof TWindow)
 373             && (that instanceof TWindow)
 374         ) {
 375             return (((TWindow) this).getZ() - ((TWindow) that).getZ());
 376         }
 377         if ((this instanceof TTreeItem)
 378             && (that instanceof TTreeItem)
 379         ) {
 380             return (((TTreeItem) this).getText().compareTo(
 381                 ((TTreeItem) that).getText()));
 382         }
 383         return (this.tabOrder - that.tabOrder);
 384     }
 385
 386     /**
 387      * See if this widget should render with the active color.
 388      *
 389      * @return true if this widget is active and all of its parents are
 390      * active.
 391      */
 392     public final boolean isAbsoluteActive() {
 393         if (parent == this) {
 394             return active;
 395         }
 396         return (active && parent.isAbsoluteActive());
 397     }
 398
 399     /**
 400      * Returns the cursor X position.
 401      *
 402      * @return absolute screen column number for the cursor's X position
 403      */
 404     public final int getCursorAbsoluteX() {
 405         assert (cursorVisible);
 406         return getAbsoluteX() + cursorX;
 407     }
 408
 409     /**
 410      * Returns the cursor Y position.
 411      *
 412      * @return absolute screen row number for the cursor's Y position
 413      */
 414     public final int getCursorAbsoluteY() {
 415         assert (cursorVisible);
 416         return getAbsoluteY() + cursorY;
 417     }
 418
 419     /**
 420      * Compute my absolute X position as the sum of my X plus all my parent's
 421      * X's.
 422      *
 423      * @return absolute screen column number for my X position
 424      */
 425     public final int getAbsoluteX() {
 426         assert (parent != null);
 427         if (parent == this) {
 428             return x;
 429         }
 430         if ((parent instanceof TWindow) && !(parent instanceof TMenu)) {
 431             // Widgets on a TWindow have (0,0) as their top-left, but this is
 432             // actually the TWindow's (1,1).
 433             return parent.getAbsoluteX() + x + 1;
 434         }
 435         return parent.getAbsoluteX() + x;
 436     }
 437
 438     /**
 439      * Compute my absolute Y position as the sum of my Y plus all my parent's
 440      * Y's.
 441      *
 442      * @return absolute screen row number for my Y position
 443      */
 444     public final int getAbsoluteY() {
 445         assert (parent != null);
 446         if (parent == this) {
 447             return y;
 448         }
 449         if ((parent instanceof TWindow) && !(parent instanceof TMenu)) {
 450             // Widgets on a TWindow have (0,0) as their top-left, but this is
 451             // actually the TWindow's (1,1).
 452             return parent.getAbsoluteY() + y + 1;
 453         }
 454         return parent.getAbsoluteY() + y;
 455     }
 456
 457     /**
 458      * Get the global color theme.
 459      *
 460      * @return the ColorTheme
 461      */
 462     public final ColorTheme getTheme() {
 463         return window.getApplication().getTheme();
 464     }
 465
 466     /**
 467      * Draw my specific widget.  When called, the screen rectangle I draw
 468      * into is already setup (offset and clipping).
 469      */
 470     public void draw() {
 471         // Default widget draws nothing.
 472     }
 473
 474     /**
 475      * Called by parent to render to TWindow.
 476      */
 477     public final void drawChildren() {
 478         // Set my clipping rectangle
 479         assert (window != null);
 480         assert (getScreen() != null);
 481         Screen screen = getScreen();
 482
 483         // Special case: TStatusBar is drawn by TApplication, not anything
 484         // else.
 485         if (this instanceof TStatusBar) {
 486             return;
 487         }
 488
 489         screen.setClipRight(width);
 490         screen.setClipBottom(height);
 491
 492         int absoluteRightEdge = window.getAbsoluteX() + window.getWidth();
 493         int absoluteBottomEdge = window.getAbsoluteY() + window.getHeight();
 494         if (!(this instanceof TWindow) && !(this instanceof TVScroller)) {
 495             absoluteRightEdge -= 1;
 496         }
 497         if (!(this instanceof TWindow) && !(this instanceof THScroller)) {
 498             absoluteBottomEdge -= 1;
 499         }
 500         int myRightEdge = getAbsoluteX() + width;
 501         int myBottomEdge = getAbsoluteY() + height;
 502         if (getAbsoluteX() > absoluteRightEdge) {
 503             // I am offscreen
 504             screen.setClipRight(0);
 505         } else if (myRightEdge > absoluteRightEdge) {
 506             screen.setClipRight(screen.getClipRight()
 507                 - (myRightEdge - absoluteRightEdge));
 508         }
 509         if (getAbsoluteY() > absoluteBottomEdge) {
 510             // I am offscreen
 511             screen.setClipBottom(0);
 512         } else if (myBottomEdge > absoluteBottomEdge) {
 513             screen.setClipBottom(screen.getClipBottom()
 514                 - (myBottomEdge - absoluteBottomEdge));
 515         }
 516
 517         // Set my offset
 518         screen.setOffsetX(getAbsoluteX());
 519         screen.setOffsetY(getAbsoluteY());
 520
 521         // Draw me
 522         draw();
 523
 524         // Continue down the chain
 525         for (TWidget widget: children) {
 526             widget.drawChildren();
 527         }
 528     }
 529
 530     // ------------------------------------------------------------------------
 531     // Constructors -----------------------------------------------------------
 532     // ------------------------------------------------------------------------
 533
 534     /**
 535      * Default constructor for subclasses.
 536      */
 537     protected TWidget() {
 538         children = new ArrayList<TWidget>();
 539     }
 540
 541     /**
 542      * Protected constructor.
 543      *
 544      * @param parent parent widget
 545      */
 546     protected TWidget(final TWidget parent) {
 547         this(parent, true);
 548     }
 549
 550     /**
 551      * Protected constructor.
 552      *
 553      * @param parent parent widget
 554      * @param x column relative to parent
 555      * @param y row relative to parent
 556      * @param width width of widget
 557      * @param height height of widget
 558      */
 559     protected TWidget(final TWidget parent, final int x, final int y,
 560         final int width, final int height) {
 561
 562         this(parent, true, x, y, width, height);
 563     }
 564
 565     /**
 566      * Protected constructor used by subclasses that are disabled by default.
 567      *
 568      * @param parent parent widget
 569      * @param enabled if true assume enabled
 570      */
 571     protected TWidget(final TWidget parent, final boolean enabled) {
 572         this.enabled = enabled;
 573         this.parent = parent;
 574         this.window = parent.window;
 575         children = new ArrayList<TWidget>();
 576         parent.addChild(this);
 577     }
 578
 579     /**
 580      * Protected constructor used by subclasses that are disabled by default.
 581      *
 582      * @param parent parent widget
 583      * @param enabled if true assume enabled
 584      * @param x column relative to parent
 585      * @param y row relative to parent
 586      * @param width width of widget
 587      * @param height height of widget
 588      */
 589     protected TWidget(final TWidget parent, final boolean enabled,
 590         final int x, final int y, final int width, final int height) {
 591
 592         this.enabled = enabled;
 593         this.parent = parent;
 594         this.window = parent.window;
 595         children = new ArrayList<TWidget>();
 596         parent.addChild(this);
 597
 598         this.x = x;
 599         this.y = y;
 600         this.width = width;
 601         this.height = height;
 602     }
 603
 604     /**
 605      * Backdoor access for TWindow's constructor.  ONLY TWindow USES THIS.
 606      *
 607      * @param window the top-level window
 608      * @param x column relative to parent
 609      * @param y row relative to parent
 610      * @param width width of window
 611      * @param height height of window
 612      */
 613     protected final void setupForTWindow(final TWindow window,
 614         final int x, final int y, final int width, final int height) {
 615
 616         this.parent = window;
 617         this.window = window;
 618         this.x      = x;
 619         this.y      = y;
 620         this.width  = width;
 621         this.height = height;
 622     }
 623
 624     // ------------------------------------------------------------------------
 625     // General behavior -------------------------------------------------------
 626     // ------------------------------------------------------------------------
 627
 628     /**
 629      * Add a child widget to my list of children.  We set its tabOrder to 0
 630      * and increment the tabOrder of all other children.
 631      *
 632      * @param child TWidget to add
 633      */
 634     private void addChild(final TWidget child) {
 635         children.add(child);
 636
 637         if ((child.enabled)
 638             && !(child instanceof THScroller)
 639             && !(child instanceof TVScroller)
 640         ) {
 641             for (TWidget widget: children) {
 642                 widget.active = false;
 643             }
 644             child.active = true;
 645             activeChild = child;
 646         }
 647         for (int i = 0; i < children.size(); i++) {
 648             children.get(i).tabOrder = i;
 649         }
 650     }
 651
 652     /**
 653      * Switch the active child.
 654      *
 655      * @param child TWidget to activate
 656      */
 657     public final void activate(final TWidget child) {
 658         assert (child.enabled);
 659         if ((child instanceof THScroller)
 660             || (child instanceof TVScroller)
 661         ) {
 662             return;
 663         }
 664
 665         if (child != activeChild) {
 666             if (activeChild != null) {
 667                 activeChild.active = false;
 668             }
 669             child.active = true;
 670             activeChild = child;
 671         }
 672     }
 673
 674     /**
 675      * Switch the active child.
 676      *
 677      * @param tabOrder tabOrder of the child to activate.  If that child
 678      * isn't enabled, then the next enabled child will be activated.
 679      */
 680     public final void activate(final int tabOrder) {
 681         if (activeChild == null) {
 682             return;
 683         }
 684         TWidget child = null;
 685         for (TWidget widget: children) {
 686             if ((widget.enabled)
 687                 && !(widget instanceof THScroller)
 688                 && !(widget instanceof TVScroller)
 689                 && (widget.tabOrder >= tabOrder)
 690             ) {
 691                 child = widget;
 692                 break;
 693             }
 694         }
 695         if ((child != null) && (child != activeChild)) {
 696             activeChild.active = false;
 697             assert (child.enabled);
 698             child.active = true;
 699             activeChild = child;
 700         }
 701     }
 702
 703     /**
 704      * Switch the active widget with the next in the tab order.
 705      *
 706      * @param forward if true, then switch to the next enabled widget in the
 707      * list, otherwise switch to the previous enabled widget in the list
 708      */
 709     public final void switchWidget(final boolean forward) {
 710
 711         // Only switch if there are multiple enabled widgets
 712         if ((children.size() < 2) || (activeChild == null)) {
 713             return;
 714         }
 715
 716         int tabOrder = activeChild.tabOrder;
 717         do {
 718             if (forward) {
 719                 tabOrder++;
 720             } else {
 721                 tabOrder--;
 722             }
 723             if (tabOrder < 0) {
 724
 725                 // If at the end, pass the switch to my parent.
 726                 if ((!forward) && (parent != this)) {
 727                     parent.switchWidget(forward);
 728                     return;
 729                 }
 730
 731                 tabOrder = children.size() - 1;
 732             } else if (tabOrder == children.size()) {
 733                 // If at the end, pass the switch to my parent.
 734                 if ((forward) && (parent != this)) {
 735                     parent.switchWidget(forward);
 736                     return;
 737                 }
 738
 739                 tabOrder = 0;
 740             }
 741             if (activeChild.tabOrder == tabOrder) {
 742                 // We wrapped around
 743                 break;
 744             }
 745         } while ((!children.get(tabOrder).enabled)
 746             && !(children.get(tabOrder) instanceof THScroller)
 747             && !(children.get(tabOrder) instanceof TVScroller));
 748
 749         assert (children.get(tabOrder).enabled);
 750
 751         activeChild.active = false;
 752         children.get(tabOrder).active = true;
 753         activeChild = children.get(tabOrder);
 754     }
 755
 756     /**
 757      * Returns my active widget.
 758      *
 759      * @return widget that is active, or this if no children
 760      */
 761     public TWidget getActiveChild() {
 762         if ((this instanceof THScroller)
 763             || (this instanceof TVScroller)
 764         ) {
 765             return parent;
 766         }
 767
 768         for (TWidget widget: children) {
 769             if (widget.active) {
 770                 return widget.getActiveChild();
 771             }
 772         }
 773         // No active children, return me
 774         return this;
 775     }
 776
 777     // ------------------------------------------------------------------------
 778     // Event handlers ---------------------------------------------------------
 779     // ------------------------------------------------------------------------
 780
 781     /**
 782      * Check if a mouse press/release event coordinate is contained in this
 783      * widget.
 784      *
 785      * @param mouse a mouse-based event
 786      * @return whether or not a mouse click would be sent to this widget
 787      */
 788     public final boolean mouseWouldHit(final TMouseEvent mouse) {
 789
 790         if (!enabled) {
 791             return false;
 792         }
 793
 794         if ((mouse.getAbsoluteX() >= getAbsoluteX())
 795             && (mouse.getAbsoluteX() <  getAbsoluteX() + width)
 796             && (mouse.getAbsoluteY() >= getAbsoluteY())
 797             && (mouse.getAbsoluteY() <  getAbsoluteY() + height)
 798         ) {
 799             return true;
 800         }
 801         return false;
 802     }
 803
 804     /**
 805      * Method that subclasses can override to handle keystrokes.
 806      *
 807      * @param keypress keystroke event
 808      */
 809     public void onKeypress(final TKeypressEvent keypress) {
 810
 811         if ((children.size() == 0)
 812             || (this instanceof TTreeView)
 813             || (this instanceof TText)
 814         ) {
 815
 816             // Defaults:
 817             //   tab / shift-tab - switch to next/previous widget
 818             //   right-arrow or down-arrow: same as tab
 819             //   left-arrow or up-arrow: same as shift-tab
 820             if ((keypress.equals(kbTab))
 821                 || (keypress.equals(kbRight))
 822                 || (keypress.equals(kbDown))
 823             ) {
 824                 parent.switchWidget(true);
 825                 return;
 826             } else if ((keypress.equals(kbShiftTab))
 827                 || (keypress.equals(kbBackTab))
 828                 || (keypress.equals(kbLeft))
 829                 || (keypress.equals(kbUp))
 830             ) {
 831                 parent.switchWidget(false);
 832                 return;
 833             }
 834         }
 835
 836         // If I have any buttons on me AND this is an Alt-key that matches
 837         // its mnemonic, send it an Enter keystroke
 838         for (TWidget widget: children) {
 839             if (widget instanceof TButton) {
 840                 TButton button = (TButton) widget;
 841                 if (button.isEnabled()
 842                     && !keypress.getKey().isFnKey()
 843                     && keypress.getKey().isAlt()
 844                     && !keypress.getKey().isCtrl()
 845                     && (Character.toLowerCase(button.getMnemonic().getShortcut())
 846                         == Character.toLowerCase(keypress.getKey().getChar()))
 847                 ) {
 848
 849                     widget.handleEvent(new TKeypressEvent(kbEnter));
 850                     return;
 851                 }
 852             }
 853         }
 854
 855         // Dispatch the keypress to an active widget
 856         for (TWidget widget: children) {
 857             if (widget.active) {
 858                 widget.handleEvent(keypress);
 859                 return;
 860             }
 861         }
 862     }
 863
 864     /**
 865      * Method that subclasses can override to handle mouse button presses.
 866      *
 867      * @param mouse mouse button event
 868      */
 869     public void onMouseDown(final TMouseEvent mouse) {
 870         // Default: do nothing, pass to children instead
 871         for (TWidget widget: children) {
 872             if (widget.mouseWouldHit(mouse)) {
 873                 // Dispatch to this child, also activate it
 874                 activate(widget);
 875
 876                 // Set x and y relative to the child's coordinates
 877                 mouse.setX(mouse.getAbsoluteX() - widget.getAbsoluteX());
 878                 mouse.setY(mouse.getAbsoluteY() - widget.getAbsoluteY());
 879                 widget.handleEvent(mouse);
 880                 return;
 881             }
 882         }
 883     }
 884
 885     /**
 886      * Method that subclasses can override to handle mouse button releases.
 887      *
 888      * @param mouse mouse button event
 889      */
 890     public void onMouseUp(final TMouseEvent mouse) {
 891         // Default: do nothing, pass to children instead
 892         for (TWidget widget: children) {
 893             if (widget.mouseWouldHit(mouse)) {
 894                 // Dispatch to this child, also activate it
 895                 activate(widget);
 896
 897                 // Set x and y relative to the child's coordinates
 898                 mouse.setX(mouse.getAbsoluteX() - widget.getAbsoluteX());
 899                 mouse.setY(mouse.getAbsoluteY() - widget.getAbsoluteY());
 900                 widget.handleEvent(mouse);
 901                 return;
 902             }
 903         }
 904     }
 905
 906     /**
 907      * Method that subclasses can override to handle mouse movements.
 908      *
 909      * @param mouse mouse motion event
 910      */
 911     public void onMouseMotion(final TMouseEvent mouse) {
 912         // Default: do nothing, pass it on to ALL of my children.  This way
 913         // the children can see the mouse "leaving" their area.
 914         for (TWidget widget: children) {
 915             // Set x and y relative to the child's coordinates
 916             mouse.setX(mouse.getAbsoluteX() - widget.getAbsoluteX());
 917             mouse.setY(mouse.getAbsoluteY() - widget.getAbsoluteY());
 918             widget.handleEvent(mouse);
 919         }
 920     }
 921
 922     /**
 923      * Method that subclasses can override to handle window/screen resize
 924      * events.
 925      *
 926      * @param resize resize event
 927      */
 928     public void onResize(final TResizeEvent resize) {
 929         // Default: do nothing, pass to children instead
 930         for (TWidget widget: children) {
 931             widget.onResize(resize);
 932         }
 933     }
 934
 935     /**
 936      * Method that subclasses can override to handle posted command events.
 937      *
 938      * @param command command event
 939      */
 940     public void onCommand(final TCommandEvent command) {
 941         // Default: do nothing, pass to children instead
 942         for (TWidget widget: children) {
 943             widget.onCommand(command);
 944         }
 945     }
 946
 947     /**
 948      * Method that subclasses can override to handle menu or posted menu
 949      * events.
 950      *
 951      * @param menu menu event
 952      */
 953     public void onMenu(final TMenuEvent menu) {
 954         // Default: do nothing, pass to children instead
 955         for (TWidget widget: children) {
 956             widget.onMenu(menu);
 957         }
 958     }
 959
 960     /**
 961      * Method that subclasses can override to do processing when the UI is
 962      * idle.
 963      */
 964     public void onIdle() {
 965         // Default: do nothing, pass to children instead
 966         for (TWidget widget: children) {
 967             widget.onIdle();
 968         }
 969     }
 970
 971     /**
 972      * Consume event.  Subclasses that want to intercept all events in one go
 973      * can override this method.
 974      *
 975      * @param event keyboard, mouse, resize, command, or menu event
 976      */
 977     public void handleEvent(final TInputEvent event) {
 978         // System.err.printf("TWidget (%s) event: %s\n", this.getClass().getName(),
 979         //     event);
 980
 981         if (!enabled) {
 982             // Discard event
 983             // System.err.println("   -- discard --");
 984             return;
 985         }
 986
 987         if (event instanceof TKeypressEvent) {
 988             onKeypress((TKeypressEvent) event);
 989         } else if (event instanceof TMouseEvent) {
 990
 991             TMouseEvent mouse = (TMouseEvent) event;
 992
 993             switch (mouse.getType()) {
 994
 995             case MOUSE_DOWN:
 996                 onMouseDown(mouse);
 997                 break;
 998
 999             case MOUSE_UP:
1000                 onMouseUp(mouse);
1001                 break;
1002
1003             case MOUSE_MOTION:
1004                 onMouseMotion(mouse);
1005                 break;
1006
1007             default:
1008                 throw new IllegalArgumentException("Invalid mouse event type: "
1009                     + mouse.getType());
1010             }
1011         } else if (event instanceof TResizeEvent) {
1012             onResize((TResizeEvent) event);
1013         } else if (event instanceof TCommandEvent) {
1014             onCommand((TCommandEvent) event);
1015         } else if (event instanceof TMenuEvent) {
1016             onMenu((TMenuEvent) event);
1017         }
1018
1019         // Do nothing else
1020         return;
1021     }
1022
1023     // ------------------------------------------------------------------------
1024     // Other TWidget constructors ---------------------------------------------
1025     // ------------------------------------------------------------------------
1026
1027     /**
1028      * Convenience function to add a label to this container/window.
1029      *
1030      * @param text label
1031      * @param x column relative to parent
1032      * @param y row relative to parent
1033      * @return the new label
1034      */
1035     public final TLabel addLabel(final String text, final int x, final int y) {
1036         return addLabel(text, x, y, "tlabel");
1037     }
1038
1039     /**
1040      * Convenience function to add a label to this container/window.
1041      *
1042      * @param text label
1043      * @param x column relative to parent
1044      * @param y row relative to parent
1045      * @param colorKey ColorTheme key color to use for foreground text.
1046      * Default is "tlabel"
1047      * @return the new label
1048      */
1049     public final TLabel addLabel(final String text, final int x, final int y,
1050         final String colorKey) {
1051
1052         return new TLabel(this, text, x, y, colorKey);
1053     }
1054
1055     /**
1056      * Convenience function to add a button to this container/window.
1057      *
1058      * @param text label on the button
1059      * @param x column relative to parent
1060      * @param y row relative to parent
1061      * @param action to call when button is pressed
1062      * @return the new button
1063      */
1064     public final TButton addButton(final String text, final int x, final int y,
1065         final TAction action) {
1066
1067         return new TButton(this, text, x, y, action);
1068     }
1069
1070     /**
1071      * Convenience function to add a checkbox to this container/window.
1072      *
1073      * @param x column relative to parent
1074      * @param y row relative to parent
1075      * @param label label to display next to (right of) the checkbox
1076      * @param checked initial check state
1077      * @return the new checkbox
1078      */
1079     public final TCheckbox addCheckbox(final int x, final int y,
1080         final String label, final boolean checked) {
1081
1082         return new TCheckbox(this, x, y, label, checked);
1083     }
1084
1085     /**
1086      * Convenience function to add a progress bar to this container/window.
1087      *
1088      * @param x column relative to parent
1089      * @param y row relative to parent
1090      * @param width width of progress bar
1091      * @param value initial value of percent complete
1092      * @return the new progress bar
1093      */
1094     public final TProgressBar addProgressBar(final int x, final int y,
1095         final int width, final int value) {
1096
1097         return new TProgressBar(this, x, y, width, value);
1098     }
1099
1100     /**
1101      * Convenience function to add a radio button group to this
1102      * container/window.
1103      *
1104      * @param x column relative to parent
1105      * @param y row relative to parent
1106      * @param label label to display on the group box
1107      * @return the new radio button group
1108      */
1109     public final TRadioGroup addRadioGroup(final int x, final int y,
1110         final String label) {
1111
1112         return new TRadioGroup(this, x, y, label);
1113     }
1114
1115     /**
1116      * Convenience function to add a text field to this container/window.
1117      *
1118      * @param x column relative to parent
1119      * @param y row relative to parent
1120      * @param width visible text width
1121      * @param fixed if true, the text cannot exceed the display width
1122      * @return the new text field
1123      */
1124     public final TField addField(final int x, final int y,
1125         final int width, final boolean fixed) {
1126
1127         return new TField(this, x, y, width, fixed);
1128     }
1129
1130     /**
1131      * Convenience function to add a text field to this container/window.
1132      *
1133      * @param x column relative to parent
1134      * @param y row relative to parent
1135      * @param width visible text width
1136      * @param fixed if true, the text cannot exceed the display width
1137      * @param text initial text, default is empty string
1138      * @return the new text field
1139      */
1140     public final TField addField(final int x, final int y,
1141         final int width, final boolean fixed, final String text) {
1142
1143         return new TField(this, x, y, width, fixed, text);
1144     }
1145
1146     /**
1147      * Convenience function to add a text field to this container/window.
1148      *
1149      * @param x column relative to parent
1150      * @param y row relative to parent
1151      * @param width visible text width
1152      * @param fixed if true, the text cannot exceed the display width
1153      * @param text initial text, default is empty string
1154      * @param enterAction function to call when enter key is pressed
1155      * @param updateAction function to call when the text is updated
1156      * @return the new text field
1157      */
1158     public final TField addField(final int x, final int y,
1159         final int width, final boolean fixed, final String text,
1160         final TAction enterAction, final TAction updateAction) {
1161
1162         return new TField(this, x, y, width, fixed, text, enterAction,
1163             updateAction);
1164     }
1165
1166     /**
1167      * Convenience function to add a scrollable text box to this
1168      * container/window.
1169      *
1170      * @param text text on the screen
1171      * @param x column relative to parent
1172      * @param y row relative to parent
1173      * @param width width of text area
1174      * @param height height of text area
1175      * @param colorKey ColorTheme key color to use for foreground text
1176      * @return the new text box
1177      */
1178     public final TText addText(final String text, final int x,
1179         final int y, final int width, final int height, final String colorKey) {
1180
1181         return new TText(this, text, x, y, width, height, colorKey);
1182     }
1183
1184     /**
1185      * Convenience function to add a scrollable text box to this
1186      * container/window.
1187      *
1188      * @param text text on the screen
1189      * @param x column relative to parent
1190      * @param y row relative to parent
1191      * @param width width of text area
1192      * @param height height of text area
1193      * @return the new text box
1194      */
1195     public final TText addText(final String text, final int x, final int y,
1196         final int width, final int height) {
1197
1198         return new TText(this, text, x, y, width, height, "ttext");
1199     }
1200
1201     /**
1202      * Convenience function to spawn a message box.
1203      *
1204      * @param title window title, will be centered along the top border
1205      * @param caption message to display.  Use embedded newlines to get a
1206      * multi-line box.
1207      * @return the new message box
1208      */
1209     public final TMessageBox messageBox(final String title,
1210         final String caption) {
1211
1212         return getApplication().messageBox(title, caption, TMessageBox.Type.OK);
1213     }
1214
1215     /**
1216      * Convenience function to spawn a message box.
1217      *
1218      * @param title window title, will be centered along the top border
1219      * @param caption message to display.  Use embedded newlines to get a
1220      * multi-line box.
1221      * @param type one of the TMessageBox.Type constants.  Default is
1222      * Type.OK.
1223      * @return the new message box
1224      */
1225     public final TMessageBox messageBox(final String title,
1226         final String caption, final TMessageBox.Type type) {
1227
1228         return getApplication().messageBox(title, caption, type);
1229     }
1230
1231     /**
1232      * Convenience function to spawn an input box.
1233      *
1234      * @param title window title, will be centered along the top border
1235      * @param caption message to display.  Use embedded newlines to get a
1236      * multi-line box.
1237      * @return the new input box
1238      */
1239     public final TInputBox inputBox(final String title, final String caption) {
1240
1241         return getApplication().inputBox(title, caption);
1242     }
1243
1244     /**
1245      * Convenience function to spawn an input box.
1246      *
1247      * @param title window title, will be centered along the top border
1248      * @param caption message to display.  Use embedded newlines to get a
1249      * multi-line box.
1250      * @param text initial text to seed the field with
1251      * @return the new input box
1252      */
1253     public final TInputBox inputBox(final String title, final String caption,
1254         final String text) {
1255
1256         return getApplication().inputBox(title, caption, text);
1257     }
1258
1259     /**
1260      * Convenience function to add a password text field to this
1261      * container/window.
1262      *
1263      * @param x column relative to parent
1264      * @param y row relative to parent
1265      * @param width visible text width
1266      * @param fixed if true, the text cannot exceed the display width
1267      * @return the new text field
1268      */
1269     public final TPasswordField addPasswordField(final int x, final int y,
1270         final int width, final boolean fixed) {
1271
1272         return new TPasswordField(this, x, y, width, fixed);
1273     }
1274
1275     /**
1276      * Convenience function to add a password text field to this
1277      * container/window.
1278      *
1279      * @param x column relative to parent
1280      * @param y row relative to parent
1281      * @param width visible text width
1282      * @param fixed if true, the text cannot exceed the display width
1283      * @param text initial text, default is empty string
1284      * @return the new text field
1285      */
1286     public final TPasswordField addPasswordField(final int x, final int y,
1287         final int width, final boolean fixed, final String text) {
1288
1289         return new TPasswordField(this, x, y, width, fixed, text);
1290     }
1291
1292     /**
1293      * Convenience function to add a password text field to this
1294      * container/window.
1295      *
1296      * @param x column relative to parent
1297      * @param y row relative to parent
1298      * @param width visible text width
1299      * @param fixed if true, the text cannot exceed the display width
1300      * @param text initial text, default is empty string
1301      * @param enterAction function to call when enter key is pressed
1302      * @param updateAction function to call when the text is updated
1303      * @return the new text field
1304      */
1305     public final TPasswordField addPasswordField(final int x, final int y,
1306         final int width, final boolean fixed, final String text,
1307         final TAction enterAction, final TAction updateAction) {
1308
1309         return new TPasswordField(this, x, y, width, fixed, text, enterAction,
1310             updateAction);
1311     }
1312
1313     /**
1314      * Convenience function to add a tree view to this container/window.
1315      *
1316      * @param x column relative to parent
1317      * @param y row relative to parent
1318      * @param width width of tree view
1319      * @param height height of tree view
1320      * @return the new tree view
1321      */
1322     public final TTreeView addTreeView(final int x, final int y,
1323         final int width, final int height) {
1324
1325         return new TTreeView(this, x, y, width, height);
1326     }
1327
1328     /**
1329      * Convenience function to add a tree view to this container/window.
1330      *
1331      * @param x column relative to parent
1332      * @param y row relative to parent
1333      * @param width width of tree view
1334      * @param height height of tree view
1335      * @param action action to perform when an item is selected
1336      * @return the new tree view
1337      */
1338     public final TTreeView addTreeView(final int x, final int y,
1339         final int width, final int height, final TAction action) {
1340
1341         return new TTreeView(this, x, y, width, height, action);
1342     }
1343
1344     /**
1345      * Convenience function to spawn a file open box.
1346      *
1347      * @param path path of selected file
1348      * @return the result of the new file open box
1349      * @throws IOException if a java.io operation throws
1350      */
1351     public final String fileOpenBox(final String path) throws IOException {
1352         return getApplication().fileOpenBox(path);
1353     }
1354
1355     /**
1356      * Convenience function to spawn a file open box.
1357      *
1358      * @param path path of selected file
1359      * @param type one of the Type constants
1360      * @return the result of the new file open box
1361      * @throws IOException if a java.io operation throws
1362      */
1363     public final String fileOpenBox(final String path,
1364         final TFileOpenBox.Type type) throws IOException {
1365
1366         return getApplication().fileOpenBox(path, type);
1367     }
1368     /**
1369      * Convenience function to add a directory list to this container/window.
1370      *
1371      * @param path directory path, must be a directory
1372      * @param x column relative to parent
1373      * @param y row relative to parent
1374      * @param width width of text area
1375      * @param height height of text area
1376      * @return the new directory list
1377      */
1378     public final TDirectoryList addDirectoryList(final String path, final int x,
1379         final int y, final int width, final int height) {
1380
1381         return new TDirectoryList(this, path, x, y, width, height, null);
1382     }
1383
1384     /**
1385      * Convenience function to add a directory list to this container/window.
1386      *
1387      * @param path directory path, must be a directory
1388      * @param x column relative to parent
1389      * @param y row relative to parent
1390      * @param width width of text area
1391      * @param height height of text area
1392      * @param action action to perform when an item is selected
1393      * @return the new directory list
1394      */
1395     public final TDirectoryList addDirectoryList(final String path, final int x,
1396         final int y, final int width, final int height, final TAction action) {
1397
1398         return new TDirectoryList(this, path, x, y, width, height, action);
1399     }
1400
1401     /**
1402      * Convenience function to add a directory list to this container/window.
1403      *
1404      * @param strings list of strings to show
1405      * @param x column relative to parent
1406      * @param y row relative to parent
1407      * @param width width of text area
1408      * @param height height of text area
1409      * @return the new directory list
1410      */
1411     public final TList addList(final List<String> strings, final int x,
1412         final int y, final int width, final int height) {
1413
1414         return new TList(this, strings, x, y, width, height, null);
1415     }
1416
1417     /**
1418      * Convenience function to add a directory list to this container/window.
1419      *
1420      * @param strings list of strings to show
1421      * @param x column relative to parent
1422      * @param y row relative to parent
1423      * @param width width of text area
1424      * @param height height of text area
1425      * @param enterAction action to perform when an item is selected
1426      * @return the new directory list
1427      */
1428     public final TList addList(final List<String> strings, final int x,
1429         final int y, final int width, final int height,
1430         final TAction enterAction) {
1431
1432         return new TList(this, strings, x, y, width, height, enterAction);
1433     }
1434
1435     /**
1436      * Convenience function to add a directory list to this container/window.
1437      *
1438      * @param strings list of strings to show
1439      * @param x column relative to parent
1440      * @param y row relative to parent
1441      * @param width width of text area
1442      * @param height height of text area
1443      * @param enterAction action to perform when an item is selected
1444      * @param moveAction action to perform when the user navigates to a new
1445      * item with arrow/page keys
1446      * @return the new directory list
1447      */
1448     public final TList addList(final List<String> strings, final int x,
1449         final int y, final int width, final int height,
1450         final TAction enterAction, final TAction moveAction) {
1451
1452         return new TList(this, strings, x, y, width, height, enterAction,
1453             moveAction);
1454     }
1455
1456 }