de.matthiasmann.twl
Class ScrollPane

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

public class ScrollPane
extends Widget

A scroll pane to scroll another widget if it requires more space then available.

It requires the following child themes:

ThemeDescription
hscrollbarThe horizontal scrollbar
vscrollbarThe vertical scrollbar
dragButtonThe drag button in the bottom right corner. Only needed when hasDragButton is true.

For the remaining theme parameters look at applyThemeScrollPane(de.matthiasmann.twl.ThemeInfo)


Nested Class Summary
static interface ScrollPane.AutoScrollable
          Custom auto scroll area checking.
static interface ScrollPane.CustomPageSize
          Custom page sizes for page scrolling and scroll bar thumb sizing.
static class ScrollPane.Fixed
          Controls which axis of the scroll pane should be fixed
static interface ScrollPane.Scrollable
          Indicates that the content handles scrolling itself.
 
Nested classes/interfaces inherited from class de.matthiasmann.twl.Widget
Widget.OffscreenMouseAdjustments, Widget.RenderOffscreen
 
Field Summary
static AnimationState.StateKey STATE_AUTO_SCROLL_DOWN
           
static AnimationState.StateKey STATE_AUTO_SCROLL_UP
           
static AnimationState.StateKey STATE_DOWNARROW_ARMED
           
static AnimationState.StateKey STATE_HORIZONTAL_SCROLLBAR_VISIBLE
           
static AnimationState.StateKey STATE_RIGHTARROW_ARMED
           
static AnimationState.StateKey STATE_VERTICAL_SCROLLBAR_VISIBLE
           
 
Fields inherited from class de.matthiasmann.twl.Widget
STATE_DISABLED, STATE_HAS_FOCUSED_CHILD, STATE_HAS_OPEN_POPUPS, STATE_KEYBOARD_FOCUS
 
Constructor Summary
ScrollPane()
           
ScrollPane(Widget content)
           
 
Method Summary
protected  void applyTheme(ThemeInfo themeInfo)
          Apply the given theme.
protected  void applyThemeScrollPane(ThemeInfo themeInfo)
          The following theme parameters are required by the scroll pane: Parameter nameTypeDescription autoScrollAreaintegerThe size of the auto scroll area autoScrollSpeedintegerThe speed in pixels to scroll every 50 ms hasDragButtonbooleanIf the dragButton should be shown or not scrollbarsAlwaysVisiblebooleanShow scrollbars always (true) or only when needed (false)
The following optional parameters can be used to change the appearance of the scroll pane: Parameter nameTypeDescription hscrollbarOffsetDimensionMoves the horizontal scrollbar but does not change the available area for the scroll content. vscrollbarOffsetDimensionMoves the vertical scrollbar but does not change the available area for the scroll content. contentScrollbarSpacingDimensionAn optional spacing between the scrollbar and the content area.
 boolean checkAutoScroll(Event evt)
          Checks for an auto scroll event.
protected  void childInvalidateLayout(Widget child)
          Called when the layout of a child has been invalidated.
 DraggableButton.DragListener createDragListener()
          Creates a DragListener which can be used to drag the content of this ScrollPane around.
protected  int getAutoScrollDirection(Event evt)
           
static ScrollPane getContainingScrollPane(Widget widget)
          Returns the ScrollPane instance which has the specified widget as content.
 Widget getContent()
           
 int getContentAreaHeight()
           
 int getContentAreaWidth()
           
 ScrollPane.Fixed getFixed()
           
 Scrollbar getHorizontalScrollbar()
          Returns the horizontal scrollbar widget, be very careful with changes to it.
 int getMaxScrollPosX()
           
 int getMaxScrollPosY()
           
 int getMinHeight()
          Returns the minimum height of the widget.
 int getMinWidth()
          Returns the minimum width of the widget.
 int getPreferredInnerHeight()
          Computes the preferred inner height (the size of the widget without the border) The default implementation uses the current position of the children.
 int getPreferredInnerWidth()
          Computes the preferred inner width (the size of the widget without the border) The default implementation uses the current position of the children.
 int getScrollPositionX()
           
 int getScrollPositionY()
           
 Scrollbar getVerticalScrollbar()
          Returns the vertical scrollbar widget, be very careful with changes to it.
protected  boolean handleEvent(Event evt)
          Called when an event occurred that this widget could be interested in.
 void insertChild(Widget child, int index)
          Inserts a new child into this widget.
 boolean isExpandContentSize()
           
protected  void layout()
          Called when the layoutInvalid flag is set.
protected  void paint(GUI gui)
          Paints this widget and it's children.
protected  void paintWidget(GUI gui)
          Called by Widget.paint(de.matthiasmann.twl.GUI) after painting the background and before painting all children.
 void removeAllChildren()
          Removes all children of this widget.
 Widget removeChild(int index)
          Removes the specified child from this widget.
 void scrollToAreaX(int start, int size, int extra)
          Tries to make the specified horizontal area completely visible.
 void scrollToAreaY(int start, int size, int extra)
          Tries to make the specified vertical area completely visible.
 void setContent(Widget content)
          Sets the widget which should be scrolled.
 void setExpandContentSize(boolean expandContentSize)
          Control if the content size.
 void setFixed(ScrollPane.Fixed fixed)
          Controls if this scroll pane has a fixed axis which will not show a scrollbar.
 void setScrollPositionX(int pos)
           
 void setScrollPositionY(int pos)
           
 void stopAutoScroll()
          Stops an activate auto scroll.
 void updateScrollbarSizes()
          Forces a layout of the scroll pane content to update the ranges of the scroll bars.
 void validateLayout()
          Calls layout() if the layout is marked invalid.
 
Methods inherited from class de.matthiasmann.twl.Widget
add, addActionMapping, addPropertyChangeListener, addPropertyChangeListener, adjustSize, afterAddToGUI, allChildrenRemoved, applyThemeBackground, applyThemeBorder, applyThemeInputMap, applyThemeMaxSize, applyThemeMinSize, applyThemeMouseCursor, applyThemeOffscreenExtra, applyThemeOverlay, applyThemeTooltip, beforeRemoveFromGUI, borderChanged, canAcceptKeyboardFocus, childAdded, 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, getMouseCursor, getMouseCursor, getNumChildren, getOffscreenExtraBottom, getOffscreenExtraLeft, getOffscreenExtraRight, getOffscreenExtraTop, getOrCreateActionMap, getOverlay, getParent, getPreferredHeight, getPreferredWidth, getRenderOffscreen, getRight, getRootWidget, getTheme, getThemePath, getThemeTooltipContent, getTintAnimator, getTooltipContent, getTooltipContentAt, getWidgetAt, getWidth, getX, getY, giveupKeyboardFocus, handleKeyStrokeAction, hasKeyboardFocus, hasOpenPopups, hasSharedAnimationState, invalidateLayout, invalidateLayoutLocally, isAbsoluteTheme, isClip, isDepthFocusTraversal, isEnabled, isFocusKeyEnabled, isInside, isLocallyEnabled, isMouseInside, isVisible, keyboardFocusChildChanged, keyboardFocusGained, keyboardFocusGained, keyboardFocusLost, layoutChildFullInnerArea, layoutChildrenFullInnerArea, moveChild, paintBackground, paintChild, paintChildren, paintDragOverlay, paintOverlay, positionChanged, reapplyTheme, removeChild, removePropertyChangeListener, removePropertyChangeListener, requestKeyboardFocus, requestKeyboardFocus, resetTooltip, setActionMap, setBackground, setBorderSize, setBorderSize, setBorderSize, setBorderSize, setCanAcceptKeyboardFocus, setClip, setDepthFocusTraversal, setEnabled, setFocusKeyEnabled, setInnerSize, setInputMap, setMaxSize, setMinSize, setMouseCursor, setOffscreenExtra, setOffscreenExtra, setOverlay, setPosition, 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
 

Field Detail

STATE_DOWNARROW_ARMED

public static final AnimationState.StateKey STATE_DOWNARROW_ARMED

STATE_RIGHTARROW_ARMED

public static final AnimationState.StateKey STATE_RIGHTARROW_ARMED

STATE_HORIZONTAL_SCROLLBAR_VISIBLE

public static final AnimationState.StateKey STATE_HORIZONTAL_SCROLLBAR_VISIBLE

STATE_VERTICAL_SCROLLBAR_VISIBLE

public static final AnimationState.StateKey STATE_VERTICAL_SCROLLBAR_VISIBLE

STATE_AUTO_SCROLL_UP

public static final AnimationState.StateKey STATE_AUTO_SCROLL_UP

STATE_AUTO_SCROLL_DOWN

public static final AnimationState.StateKey STATE_AUTO_SCROLL_DOWN
Constructor Detail

ScrollPane

public ScrollPane()

ScrollPane

public ScrollPane(Widget content)
Method Detail

getFixed

public ScrollPane.Fixed getFixed()

setFixed

public void setFixed(ScrollPane.Fixed fixed)
Controls if this scroll pane has a fixed axis which will not show a scrollbar. Default is ScrollPane.Fixed.NONE

Parameters:
fixed - the fixed axis.

getContent

public Widget getContent()

setContent

public void setContent(Widget content)
Sets the widget which should be scrolled.

The following interfaces change the behavior of the scroll pane when they are implemented by the content:

Parameters:
content - the new scroll pane content

isExpandContentSize

public boolean isExpandContentSize()

setExpandContentSize

public void setExpandContentSize(boolean expandContentSize)
Control if the content size. If set to true then the content size will be the larger of it's preferred size and the size of the content area. If set to false then the content size will be it's preferred area. Default is false

Parameters:
expandContentSize - true if the content should always cover the content area

updateScrollbarSizes

public void updateScrollbarSizes()
Forces a layout of the scroll pane content to update the ranges of the scroll bars. This method should be called after changes to the content which might affect it's size and before computing a new scroll position.

See Also:
scrollToAreaX(int, int, int), scrollToAreaY(int, int, int)

getScrollPositionX

public int getScrollPositionX()

getMaxScrollPosX

public int getMaxScrollPosX()

setScrollPositionX

public void setScrollPositionX(int pos)

scrollToAreaX

public void scrollToAreaX(int start,
                          int size,
                          int extra)
Tries to make the specified horizontal area completely visible. If it is larger then the horizontal page size then it scrolls to the start of the area.

Parameters:
start - the position of the area
size - size of the area
extra - the extra space which should be visible around the area
See Also:
Scrollbar.scrollToArea(int, int, int)

getScrollPositionY

public int getScrollPositionY()

getMaxScrollPosY

public int getMaxScrollPosY()

setScrollPositionY

public void setScrollPositionY(int pos)

scrollToAreaY

public void scrollToAreaY(int start,
                          int size,
                          int extra)
Tries to make the specified vertical area completely visible. If it is larger then the vertical page size then it scrolls to the start of the area.

Parameters:
start - the position of the area
size - size of the area
extra - the extra space which should be visible around the area
See Also:
Scrollbar.scrollToArea(int, int, int)

getContentAreaWidth

public int getContentAreaWidth()

getContentAreaHeight

public int getContentAreaHeight()

getHorizontalScrollbar

public Scrollbar getHorizontalScrollbar()
Returns the horizontal scrollbar widget, be very careful with changes to it.

Returns:
the horizontal scrollbar

getVerticalScrollbar

public Scrollbar getVerticalScrollbar()
Returns the vertical scrollbar widget, be very careful with changes to it.

Returns:
the vertical scrollbar

createDragListener

public DraggableButton.DragListener createDragListener()
Creates a DragListener which can be used to drag the content of this ScrollPane around.

Returns:
a DragListener to scroll this this ScrollPane.

checkAutoScroll

public boolean checkAutoScroll(Event evt)
Checks for an auto scroll event. This should be called when a drag & drop operation is in progress and the drop target is inside a scroll pane.

Parameters:
evt - the mouse event which should be checked.
Returns:
true if auto scrolling is started/active.
See Also:
stopAutoScroll()

stopAutoScroll

public void stopAutoScroll()
Stops an activate auto scroll. This must be called when the drag & drop operation is finished.

See Also:
checkAutoScroll(de.matthiasmann.twl.Event)

getContainingScrollPane

public static ScrollPane getContainingScrollPane(Widget widget)
Returns the ScrollPane instance which has the specified widget as content.

Parameters:
widget - the widget to retrieve the containing ScrollPane for.
Returns:
the ScrollPane or null if that widget is not directly in a ScrollPane.
See Also:
setContent(de.matthiasmann.twl.Widget)

getMinWidth

public int getMinWidth()
Description copied from class: Widget
Returns the minimum width of the widget. Layout manager will allocate atleast the minimum width to a widget even when the container is not big enough. The default implementation will not return values smaller then the current border width.

Overrides:
getMinWidth in class Widget
Returns:
the minimum width of the widget

getMinHeight

public int getMinHeight()
Description copied from class: Widget
Returns the minimum height of the widget. Layout manager will allocate atleast the minimum height to a widget even when the container is not big enough. The default implementation will not return values smaller then the current border width.

Overrides:
getMinHeight in class Widget
Returns:
the minimum height of the widget

getPreferredInnerWidth

public int getPreferredInnerWidth()
Description copied from class: Widget
Computes the preferred inner width (the size of the widget without the border) The default implementation uses the current position of the children. It is highly recommended to override this method as the default implementation lead to unstable layouts. The default behavior might change in the future to provide a better default behavior.

Overrides:
getPreferredInnerWidth in class Widget
Returns:
the preferred inner width

getPreferredInnerHeight

public int getPreferredInnerHeight()
Description copied from class: Widget
Computes the preferred inner height (the size of the widget without the border) The default implementation uses the current position of the children. It is highly recommended to override this method as the default implementation lead to unstable layouts. The default behavior might change in the future to provide a better default behavior.

Overrides:
getPreferredInnerHeight in class Widget
Returns:
the preferred inner height

insertChild

public void insertChild(Widget child,
                        int index)
Description copied from class: Widget
Inserts a new child into this widget. The position of the child is treated as relative to this widget and adjusted. If a theme was applied to this widget then this theme is also applied to the new child.

Overrides:
insertChild in class Widget
Parameters:
child - the child that should be inserted
index - the index where it should be inserted

removeAllChildren

public void removeAllChildren()
Description copied from class: Widget
Removes all children of this widget. The position of the all removed children is changed to the relative position to this widget. Calls allChildrenRemoved after removing all children.

Overrides:
removeAllChildren in class Widget
See Also:
Widget.allChildrenRemoved()

removeChild

public Widget removeChild(int index)
Description copied from class: Widget
Removes the specified child from this widget. The position of the removed child is changed to the relative position to this widget. Calls invalidateLayout after removing the child.

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

applyTheme

protected void applyTheme(ThemeInfo themeInfo)
Description copied from class: Widget
Apply the given theme. This method also calls invalidateLayout()

Overrides:
applyTheme in class Widget
Parameters:
themeInfo - The theme info for this widget

applyThemeScrollPane

protected void applyThemeScrollPane(ThemeInfo themeInfo)
The following theme parameters are required by the scroll pane:
Parameter nameTypeDescription
autoScrollAreaintegerThe size of the auto scroll area
autoScrollSpeedintegerThe speed in pixels to scroll every 50 ms
hasDragButtonbooleanIf the dragButton should be shown or not
scrollbarsAlwaysVisiblebooleanShow scrollbars always (true) or only when needed (false)

The following optional parameters can be used to change the appearance of the scroll pane:
Parameter nameTypeDescription
hscrollbarOffsetDimensionMoves the horizontal scrollbar but does not change the available area for the scroll content.
vscrollbarOffsetDimensionMoves the vertical scrollbar but does not change the available area for the scroll content.
contentScrollbarSpacingDimensionAn optional spacing between the scrollbar and the content area. This is only applied when the corresponding scrollbar is visible. It should be >= 0.

Parameters:
themeInfo - the theme info

getAutoScrollDirection

protected int getAutoScrollDirection(Event evt)

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()

childInvalidateLayout

protected void childInvalidateLayout(Widget child)
Description copied from class: Widget
Called when the layout of a child has been invalidated. The default implementation calls invalidateLayout.

Overrides:
childInvalidateLayout in class Widget
Parameters:
child - the child which was invalidated
See Also:
Widget.invalidateLayout()

paintWidget

protected void paintWidget(GUI gui)
Description copied from class: Widget
Called by Widget.paint(de.matthiasmann.twl.GUI) after painting the background and before painting all children.

This should be overwritten instead of paint if normal themeable painting is desired by the subclass.

The default implementation does nothing.

Overrides:
paintWidget in class Widget
Parameters:
gui - the GUI object - it's the same as getGUI()

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

handleEvent

protected boolean handleEvent(Event evt)
Description copied from class: Widget
Called when an event occurred that this widget could be interested in.

The default implementation handles only keyboard events and delegates them to the child widget which has keyboard focus. If focusKey handling is enabled then this widget cycles the keyboard focus through it's children. If the key was not consumed by a child or focusKey and an inputMap is specified then the event is translated by the InputMap and handleKeyStrokeAction is called when a mapping was found.

If the widget wants to receive mouse events then it must return true for all mouse events except for MOUSE_WHEEL (which is optional) event. Otherwise the following mouse event are not send. Before mouse movement or button events are send a MOUSE_ENTERED event is send first.

Overrides:
handleEvent in class Widget
Parameters:
evt - The event - do not store this object - it may be reused
Returns:
true if the widget handled this event
See Also:
Widget.setFocusKeyEnabled(boolean), Widget.handleKeyStrokeAction(java.lang.String, de.matthiasmann.twl.Event), Widget.setInputMap(de.matthiasmann.twl.InputMap)

paint

protected void paint(GUI gui)
Description copied from class: Widget
Paints this widget and it's children.

A subclass should overwrite paintWidget() instead of this function.

The default implementation calls the following method in order:

  1. Widget.paintBackground(de.matthiasmann.twl.GUI)
  2. Widget.paintWidget(de.matthiasmann.twl.GUI)
  3. Widget.paintChildren(de.matthiasmann.twl.GUI)
  4. Widget.paintOverlay(de.matthiasmann.twl.GUI)

Overrides:
paint in class Widget
Parameters:
gui - the GUI object