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