de.matthiasmann.twl
Class GUI

java.lang.Object
  extended by de.matthiasmann.twl.Widget
      extended by de.matthiasmann.twl.GUI

public final class GUI
extends Widget

Root of a UI tree. Handles timing, mouse and keyboard events, popups, tooltips etc.


Nested Class Summary
static interface GUI.AsyncCompletionListener<V>
          A completion listener for async jobs.
static interface GUI.MouseIdleListener
           
 
Nested classes/interfaces inherited from class de.matthiasmann.twl.Widget
Widget.OffscreenMouseAdjustments, Widget.RenderOffscreen
 
Field Summary
 
Fields inherited from class de.matthiasmann.twl.Widget
STATE_DISABLED, STATE_HAS_FOCUSED_CHILD, STATE_HAS_OPEN_POPUPS, STATE_KEYBOARD_FOCUS
 
Constructor Summary
GUI(Renderer renderer)
          Constructs a new GUI manager with the given renderer and a default root pane.
GUI(Widget rootPane, Renderer renderer)
          Constructs a new GUI manager with the given renderer, root pane and a input source obtained from the renderer.
GUI(Widget rootPane, Renderer renderer, Input input)
          Constructs a new GUI manager with the given renderer, input source and root pane
 
Method Summary
 void adjustSize()
          Does nothing
 void applyTheme(ThemeManager themeManager)
          Applies the specified theme to this UI tree.
 void clearKeyboardState()
          Clears current keyboard modifiers.
 void clearMouseState()
          Clears current mouse button & drag state.
 MouseSensitiveRectangle createMouseSenitiveRectangle()
           
 Timer createTimer()
          Creates a new UI timer.
 void draw()
          Renders all visible widgets.
 int getCurrentDeltaTime()
          Returns the delta time to the previous frame in milliseconds.
 long getCurrentTime()
          Returns the current UI time in milliseconds.
 Input getInput()
           
 GUI.MouseIdleListener getMouseIdleListener()
           
 int getMouseIdleTime()
           
 Renderer getRenderer()
           
 Widget getRootPane()
           
 int getTooltipDelay()
           
 int getTooltipOffsetX()
           
 int getTooltipOffsetY()
           
 int getTooltipReappearDelay()
           
 void handleInput()
          Polls input by calling Input.pollInput(de.matthiasmann.twl.GUI) if an input source was specified, otherwise it does nothing.
 boolean handleKey(int keyCode, char keyChar, boolean pressed)
          A key was pressed or released.
 void handleKeyRepeat()
          Must be called after calling handleKey().
 boolean handleMouse(int mouseX, int mouseY, int button, boolean pressed)
          Mouse has moved / button was pressed or released.
 boolean handleMouseWheel(int wheelDelta)
          Mouse wheel has been turned.
 void handleTooltips()
          Must be called after calling handleMouse or handleMouseWheel.
 void insertChild(Widget child, int index)
          Throws UnsupportedOperationException
<V> java.util.concurrent.Future<V>
invokeAsync(java.util.concurrent.Callable<V> job, GUI.AsyncCompletionListener<V> listener)
          Performs a job async in the background.
<V> java.util.concurrent.Future<V>
invokeAsync(java.lang.Runnable job, GUI.AsyncCompletionListener<V> listener)
          Performs a job async in the background.
 void invokeLater(java.lang.Runnable runnable)
          Queues a Runnable to be executed in the GUI main loop.
 void invokeRunables()
          Invokes all queued Runnable objects.
protected  void layout()
          Called when the layoutInvalid flag is set.
 void removeAllChildren()
          Throws UnsupportedOperationException
 Widget removeChild(int index)
          Throws UnsupportedOperationException
 boolean requestKeyboardFocus()
          Requests that the keyboard focus is transfered to this widget.
protected  boolean requestKeyboardFocus(Widget child)
          A child requests keyboard focus.
 boolean requestToolTip(Widget widget, int x, int y, java.lang.Object content, Alignment alignment)
           
 void resyncTimerAfterPause()
          When calls to updateTime where stopped then this method should be called before calling updateTime again to prevent a large delta jump.
 void setCursor()
          Sets the cursor from the widget under the mouse
 void setMouseIdleListener(GUI.MouseIdleListener mouseIdleListener)
           
 void setMouseIdleTime(int mouseIdleTime)
           
 boolean setPosition(int x, int y)
          Throws UnsupportedOperationException
 void setRootPane(Widget rootPane)
           
 void setSize()
          Sets the size of the GUI based on the OpenGL viewport.
 void setTooltipDelay(int tooltipDelay)
          Sets the delay in MS before the tooltip is shown
 void setTooltipOffset(int tooltipOffsetX, int tooltipOffsetY)
          Sets the offset from the mouse position to display the tooltip
 void setTooltipReappearDelay(int tooltipReappearDelay)
          Sets the time window in which a new tooltip is shown after the last tooltip was closed before waiting for the tooltip delay.
 void setTooltipWindowRenderOffscreen(Widget.RenderOffscreen renderOffscreen)
          Sets set offscreen rendering delegate on the tooltip window.
 void setTooltipWindowTheme(java.lang.String theme)
          Changes the theme name of the tooltip window and applies and calls Widget.reapplyTheme()
 void update()
          Polls inputs, updates layout and renders the GUI by calls the following method: setSize() updateTime() handleInput() handleKeyRepeat() handleTooltips() updateTimers() invokeRunables() validateLayout() draw() setCursor() This is the easiest method to use this GUI.
 void updateTime()
          Updates the current time returned by getCurrentTime by calling Renderer.getTimeMillis() and computes the delta time since the last update.
 void updateTimers()
          Updates all active timers with the delta time computed by updateTime.
 void validateLayout()
          Calls layout() if the layout is marked invalid.
 
Methods inherited from class de.matthiasmann.twl.Widget
add, addActionMapping, addPropertyChangeListener, addPropertyChangeListener, afterAddToGUI, allChildrenRemoved, applyTheme, applyThemeBackground, applyThemeBorder, applyThemeInputMap, applyThemeMaxSize, applyThemeMinSize, applyThemeMouseCursor, applyThemeOffscreenExtra, applyThemeOverlay, applyThemeTooltip, beforeRemoveFromGUI, borderChanged, canAcceptKeyboardFocus, childAdded, childInvalidateLayout, childRemoved, childVisibilityChanged, computeSize, destroy, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, focusFirstChild, focusLastChild, focusNextChild, focusPrevChild, getActionMap, getAnimationState, getBackground, getBorderBottom, getBorderHorizontal, getBorderLeft, getBorderRight, getBorderTop, getBorderVertical, getBottom, getChild, getChildAt, getChildIndex, getGUI, getHeight, getInnerBottom, getInnerHeight, getInnerRight, getInnerWidth, getInnerX, getInnerY, getInputMap, getKeyboardFocusOrder, getMaxHeight, getMaxWidth, getMinHeight, getMinWidth, getMouseCursor, getMouseCursor, getNumChildren, getOffscreenExtraBottom, getOffscreenExtraLeft, getOffscreenExtraRight, getOffscreenExtraTop, getOrCreateActionMap, getOverlay, getParent, getPreferredHeight, getPreferredInnerHeight, getPreferredInnerWidth, getPreferredWidth, getRenderOffscreen, getRight, getRootWidget, getTheme, getThemePath, getThemeTooltipContent, getTintAnimator, getTooltipContent, getTooltipContentAt, getWidgetAt, getWidth, getX, getY, giveupKeyboardFocus, handleEvent, handleKeyStrokeAction, hasKeyboardFocus, hasOpenPopups, hasSharedAnimationState, invalidateLayout, invalidateLayoutLocally, isAbsoluteTheme, isClip, isDepthFocusTraversal, isEnabled, isFocusKeyEnabled, isInside, isLocallyEnabled, isMouseInside, isVisible, keyboardFocusChildChanged, keyboardFocusGained, keyboardFocusGained, keyboardFocusLost, layoutChildFullInnerArea, layoutChildrenFullInnerArea, moveChild, paint, paintBackground, paintChild, paintChildren, paintDragOverlay, paintOverlay, paintWidget, positionChanged, reapplyTheme, removeChild, removePropertyChangeListener, removePropertyChangeListener, resetTooltip, setActionMap, setBackground, setBorderSize, setBorderSize, setBorderSize, setBorderSize, setCanAcceptKeyboardFocus, setClip, setDepthFocusTraversal, setEnabled, setFocusKeyEnabled, setInnerSize, setInputMap, setMaxSize, setMinSize, setMouseCursor, setOffscreenExtra, setOffscreenExtra, setOverlay, setRenderOffscreen, setSize, setTheme, setTintAnimator, setTooltipContent, setVisible, sizeChanged, updateTintAnimation, updateTooltip, widgetDisabled
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

GUI

public GUI(Renderer renderer)
Constructs a new GUI manager with the given renderer and a default root pane. This default root pane has no theme (eg "") and can't receive keyboard focus.

Parameters:
renderer - the renderer
See Also:
GUI(de.matthiasmann.twl.Widget, de.matthiasmann.twl.renderer.Renderer)

GUI

public GUI(Widget rootPane,
           Renderer renderer)
Constructs a new GUI manager with the given renderer, root pane and a input source obtained from the renderer.

Parameters:
rootPane - the root pane
renderer - the renderer
See Also:
Renderer.getInput()

GUI

public GUI(Widget rootPane,
           Renderer renderer,
           Input input)
Constructs a new GUI manager with the given renderer, input source and root pane

Parameters:
rootPane - the root pane
renderer - the renderer
input - the input source, can be null.
Method Detail

applyTheme

public void applyTheme(ThemeManager themeManager)
Applies the specified theme to this UI tree. If a widget in the tree has an empty theme name then it is omitted from this process but it children are still processed.

Parameters:
themeManager - the theme manager that should be used
Throws:
java.lang.NullPointerException - if themeManager is null
See Also:
Widget.setTheme(java.lang.String)

getRootPane

public Widget getRootPane()

setRootPane

public void setRootPane(Widget rootPane)

getRenderer

public Renderer getRenderer()

getInput

public Input getInput()

createMouseSenitiveRectangle

public MouseSensitiveRectangle createMouseSenitiveRectangle()

createTimer

public Timer createTimer()
Creates a new UI timer.

Returns:
new Timer(this)

getCurrentTime

public long getCurrentTime()
Returns the current UI time in milliseconds. This time is updated via updateTime()

Returns:
the current UI time in milliseconds.

getCurrentDeltaTime

public int getCurrentDeltaTime()
Returns the delta time to the previous frame in milliseconds. This time is updated via updateTime()

Returns:
the delta time

invokeLater

public void invokeLater(java.lang.Runnable runnable)
Queues a Runnable to be executed in the GUI main loop. This method is thread safe.

Parameters:
runnable - the Runnable to execute
See Also:
Widget.getGUI()

invokeAsync

public <V> java.util.concurrent.Future<V> invokeAsync(java.util.concurrent.Callable<V> job,
                                                      GUI.AsyncCompletionListener<V> listener)
Performs a job async in the background. After the job has completed (normally or by throwing an exception) the completion listener is executed via invokeLater(java.lang.Runnable) If the job is canceled before it is started then the listener is not executed. This method is thread safe.

Type Parameters:
V - the result type of the job
Parameters:
job - the job to execute
listener - the listener which will be called once the job is finished
Returns:
a Future representing pending completion of the job
See Also:
Widget.getGUI()

invokeAsync

public <V> java.util.concurrent.Future<V> invokeAsync(java.lang.Runnable job,
                                                      GUI.AsyncCompletionListener<V> listener)
Performs a job async in the background. After the job has completed (normally or by throwing an exception) the completion listener is executed via invokeLater(java.lang.Runnable) If the job is canceled before it is started then the listener is not executed. This method is thread safe.

Type Parameters:
V - the result type of the listener. The job always returns null.
Parameters:
job - the job to execute
listener - the listener which will be called once the job is finished
Returns:
a Future representing pending completion of the job
See Also:
Widget.getGUI()

requestToolTip

public boolean requestToolTip(Widget widget,
                              int x,
                              int y,
                              java.lang.Object content,
                              Alignment alignment)

getMouseIdleListener

public GUI.MouseIdleListener getMouseIdleListener()

setMouseIdleListener

public void setMouseIdleListener(GUI.MouseIdleListener mouseIdleListener)

getMouseIdleTime

public int getMouseIdleTime()

setMouseIdleTime

public void setMouseIdleTime(int mouseIdleTime)

getTooltipDelay

public int getTooltipDelay()

setTooltipDelay

public void setTooltipDelay(int tooltipDelay)
Sets the delay in MS before the tooltip is shown

Parameters:
tooltipDelay - the delay in MS, must be >= 1.

getTooltipReappearDelay

public int getTooltipReappearDelay()

setTooltipReappearDelay

public void setTooltipReappearDelay(int tooltipReappearDelay)
Sets the time window in which a new tooltip is shown after the last tooltip was closed before waiting for the tooltip delay.

Parameters:
tooltipReappearDelay - the delay in MS - set to 0 to disable

getTooltipOffsetX

public int getTooltipOffsetX()

getTooltipOffsetY

public int getTooltipOffsetY()

setTooltipOffset

public void setTooltipOffset(int tooltipOffsetX,
                             int tooltipOffsetY)
Sets the offset from the mouse position to display the tooltip

Parameters:
tooltipOffsetX - the X offset
tooltipOffsetY - the Y offset

setTooltipWindowRenderOffscreen

public void setTooltipWindowRenderOffscreen(Widget.RenderOffscreen renderOffscreen)
Sets set offscreen rendering delegate on the tooltip window. Can be null to disable offscreen rendering.

Parameters:
renderOffscreen - the offscreen rendering delegate.
See Also:
Widget.setRenderOffscreen(de.matthiasmann.twl.Widget.RenderOffscreen)

setTooltipWindowTheme

public void setTooltipWindowTheme(java.lang.String theme)
Changes the theme name of the tooltip window and applies and calls Widget.reapplyTheme()

Parameters:
theme - the new theme path element
See Also:
Widget.setTheme(java.lang.String)

setPosition

public boolean setPosition(int x,
                           int y)
Throws UnsupportedOperationException

Overrides:
setPosition in class Widget
Parameters:
x - The new x position, can be negative
y - The new y position, can be negative
Returns:
true if the position was changed, false if new position == old position
Throws:
java.lang.UnsupportedOperationException - always
See Also:
Widget.layout()

insertChild

public void insertChild(Widget child,
                        int index)
Throws UnsupportedOperationException

Overrides:
insertChild in class Widget
Parameters:
child - the child that should be inserted
index - the index where it should be inserted
Throws:
java.lang.UnsupportedOperationException - always

removeAllChildren

public void removeAllChildren()
Throws UnsupportedOperationException

Overrides:
removeAllChildren in class Widget
Throws:
java.lang.UnsupportedOperationException - always
See Also:
Widget.allChildrenRemoved()

removeChild

public Widget removeChild(int index)
Throws UnsupportedOperationException

Overrides:
removeChild in class Widget
Parameters:
index - the index of the child
Returns:
the removed widget
Throws:
java.lang.UnsupportedOperationException - always
See Also:
Widget.invalidateLayout()

adjustSize

public void adjustSize()
Does nothing

Overrides:
adjustSize in class Widget

layout

protected void layout()
Description copied from class: Widget
Called when the layoutInvalid flag is set. The default implementation does nothing.

Overrides:
layout in class Widget

validateLayout

public void validateLayout()
Description copied from class: Widget
Calls layout() if the layout is marked invalid.

Overrides:
validateLayout in class Widget
See Also:
Widget.invalidateLayout(), Widget.layout()

setSize

public void setSize()
Sets the size of the GUI based on the OpenGL viewport.


update

public void update()
Polls inputs, updates layout and renders the GUI by calls the following method:
  1. setSize()
  2. updateTime()
  3. handleInput()
  4. handleKeyRepeat()
  5. handleTooltips()
  6. updateTimers()
  7. invokeRunables()
  8. validateLayout()
  9. draw()
  10. setCursor()
This is the easiest method to use this GUI.

When not using this method care must be taken to invoke the methods in the right order. See the javadoc of the individual methods for details.


resyncTimerAfterPause

public void resyncTimerAfterPause()
When calls to updateTime where stopped then this method should be called before calling updateTime again to prevent a large delta jump. This allows the UI timer to be suspended.


updateTime

public void updateTime()
Updates the current time returned by getCurrentTime by calling Renderer.getTimeMillis() and computes the delta time since the last update.

This must be called exactly once per frame and befiore processing input events or calling updateTimers(). See update() for the sequence in which the methods of this class should be called.

See Also:
getCurrentTime(), #getTimeMillis()

updateTimers

public void updateTimers()
Updates all active timers with the delta time computed by updateTime.

This method must be called exactly once after a call to updateTime.

See Also:
updateTime()

invokeRunables

public void invokeRunables()
Invokes all queued Runnable objects.

See Also:
invokeLater(java.lang.Runnable)

draw

public void draw()
Renders all visible widgets. Calls startRendering before and endRendering after rendering all widgets.

See Also:
Renderer.startRendering(), Renderer.endRendering()

setCursor

public void setCursor()
Sets the cursor from the widget under the mouse

If the widget is disabled or did not define a cursor then it's parent widget is tried. If no cursor was found the default OS cursor will be displayed.

See Also:
Renderer.setCursor(de.matthiasmann.twl.renderer.MouseCursor), Widget.getMouseCursor(de.matthiasmann.twl.Event)

handleInput

public void handleInput()
Polls input by calling Input.pollInput(de.matthiasmann.twl.GUI) if an input source was specified, otherwise it does nothing.

If pollInput returned false then clearKeyboardState() and clearMouseState() are called.

If you don't want to use polled input you can easily use a push model for handling input. Just call the following methods:

These metods (including this one) needs to be called after updateTime()


handleMouse

public final boolean handleMouse(int mouseX,
                                 int mouseY,
                                 int button,
                                 boolean pressed)
Mouse has moved / button was pressed or released.

Parameters:
mouseX - the new mouse X coordinate
mouseY - the new mouse Y coordinate
button - the button that has been pressed/released or -1 if no button changed
pressed - true if the button was pressed. Ignored if button is -1.
Returns:
true if the event was handled by a widget

clearMouseState

public void clearMouseState()
Clears current mouse button & drag state. Should be called when the Display is minimized or when mouse events are handled outside of TWL.


handleMouseWheel

public final boolean handleMouseWheel(int wheelDelta)
Mouse wheel has been turned. Must be called after handleMouse.

Parameters:
wheelDelta - the normalized wheel delta
Returns:
true if the event was handled by a widget

handleKey

public final boolean handleKey(int keyCode,
                               char keyChar,
                               boolean pressed)
A key was pressed or released. Keyboard events depend on the constants of LWJGL's Keybaord class. Repeated key presses should be handled by handleKeyRepeat and not this method so that the repeated flag is set correctly for the generated events.

Parameters:
keyCode - the key code for this key or Keyboard.KEY_NONE
keyChar - the unicode character resulting from this event or Keyboard.CHAR_NONE
pressed - true if the key was pressed and false if it was released
Returns:
true if the event was handled by a widget

clearKeyboardState

public final void clearKeyboardState()
Clears current keyboard modifiers. Should be called when the Display is minimized or when keyboard events are handled outside of TWL.


handleKeyRepeat

public final void handleKeyRepeat()
Must be called after calling handleKey(). This method checks the time since the last key event and causes a repeated key press event to be generated.

See Also:
handleKey(int, char, boolean)

handleTooltips

public final void handleTooltips()
Must be called after calling handleMouse or handleMouseWheel. This method displays a tooltip if the widget under mouse has a tooltip message and the mouse has not moved for a certain amount of time.

See Also:
handleMouse(int, int, int, boolean), handleMouseWheel(int)

requestKeyboardFocus

public boolean requestKeyboardFocus()
Description copied from class: Widget
Requests that the keyboard focus is transfered to this widget.

Use with care - users don't expect focus changes while working with the UI

Focus transfer only works when the widget is added to the GUI tree. See Widget.getGUI().

Overrides:
requestKeyboardFocus in class Widget
Returns:
true if keyboard focus was transfered to this widget.

requestKeyboardFocus

protected boolean requestKeyboardFocus(Widget child)
Description copied from class: Widget
A child requests keyboard focus. Default implementation will grant keyboard focus and request itself keyboard focus.

Overrides:
requestKeyboardFocus in class Widget
Parameters:
child - The child that wants keyboard focus
Returns:
true if the child received the focus.