com.badlogic.gdx.scenes.scene2d.ui
Class ScrollPane

java.lang.Object
  com.badlogic.gdx.scenes.scene2d.Actor
      com.badlogic.gdx.scenes.scene2d.Group
          com.badlogic.gdx.scenes.scene2d.ui.WidgetGroup
              com.badlogic.gdx.scenes.scene2d.ui.ScrollPane

All Implemented Interfaces:

Cullable, Layout

public class ScrollPane
extends WidgetGroup

A group that scrolls a child widget using scrollbars and/or mouse or touch dragging.

The widget is sized to its preferred size. If the widget's preferred width or height is less than the size of this scroll pane, it is set to the size of this scroll pane. Scrollbars appear when the widget is larger than the scroll pane.

The scroll pane's preferred size is that of the child widget. At this size, the child widget will not need to scroll, so the scroll pane is typically sized by ignoring the preferred size in one or both directions.

Author:

mzechner, Nathan Sweet

Nested Class Summary

static class

ScrollPane.ScrollPaneStyle The style for a scroll pane, see ScrollPane.

Constructor Summary

ScrollPane(Actor widget)

ScrollPane(Actor widget, ScrollPane.ScrollPaneStyle style)

ScrollPane(Actor widget, Skin skin)

ScrollPane(Actor widget, Skin skin, String styleName)

Method Summary

void	act(float delta) Updates the actor based on time.
void	addActor(Actor actor) Deprecated. ScrollPane may have only a single child.
void	addActorAfter(Actor actorAfter, Actor actor) Deprecated. ScrollPane may have only a single child.
void	addActorAt(int index, Actor actor) Deprecated. ScrollPane may have only a single child.
void	addActorBefore(Actor actorBefore, Actor actor) Deprecated. ScrollPane may have only a single child.
void	cancel() If currently scrolling by tracking a touch down, stop scrolling.
void	draw(Batch batch, float parentAlpha) If this method is overridden, the super method or WidgetGroup.validate() should be called to ensure the widget group is laid out.
void	fling(float flingTime, float velocityX, float velocityY) Generate fling gesture.
float	getMaxX() Returns the maximum scroll value in the x direction.
float	getMaxY() Returns the maximum scroll value in the y direction.
float	getMinHeight()
float	getMinWidth()
float	getPrefHeight()
float	getPrefWidth()
float	getScrollBarHeight()
float	getScrollBarWidth()
float	getScrollHeight() Returns the height of the scrolled viewport.
float	getScrollPercentX()
float	getScrollPercentY()
float	getScrollWidth() Returns the width of the scrolled viewport.
float	getScrollX() Returns the x scroll position in pixels.
float	getScrollY() Returns the y scroll position in pixels.
ScrollPane.ScrollPaneStyle	getStyle() Returns the scroll pane's style.
boolean	getVariableSizeKnobs()
float	getVelocityX() Gets the flick scroll y velocity.
float	getVelocityY() Gets the flick scroll y velocity.
float	getVisualScrollX()
float	getVisualScrollY()
Actor	getWidget() Returns the actor embedded in this scroll pane, or null.
Actor	hit(float x, float y, boolean touchable) Returns the deepest actor that contains the specified point and is touchable and visible, or null if no actor was hit.
boolean	isDragging()
boolean	isFlinging()
boolean	isForceScrollX()
boolean	isForceScrollY()
boolean	isPanning()
boolean	isScrollX()
boolean	isScrollY()
void	layout() Computes and caches any information needed for drawing and, if this actor has children, positions and sizes each child, calls Layout.invalidate() any each child whose width or height has changed, and calls Layout.validate() on each child.
boolean	removeActor(Actor actor) Removes an actor from this group.
void	scrollTo(float x, float y, float width, float height) Sets the scroll offset so the specified rectangle is fully in view, if possible.
void	scrollToCenter(float x, float y, float width, float height) Sets the scroll offset so the specified rectangle is fully in view and centered vertically in the scroll pane, if possible.
void	setCancelTouchFocus(boolean cancelTouchFocus) When true (default), the Stage.cancelTouchFocus() touch focus} is cancelled when flick scrolling begins.
void	setClamp(boolean clamp) For flick scroll, prevents scrolling out of the widget's bounds.
void	setFadeScrollBars(boolean fadeScrollBars) When true the scroll bars fade out after some time of not being used.
void	setFlickScroll(boolean flickScroll)
void	setFlingTime(float flingTime) For flick scroll, sets the amount of time in seconds that a fling will continue to scroll.
void	setForceScroll(boolean x, boolean y) Forces enabling scrollbars (for non-flick scroll) and overscrolling (for flick scroll) in a direction, even if the contents do not exceed the bounds in that direction.
void	setOverscroll(boolean overscrollX, boolean overscrollY) For flick scroll, if true the widget can be scrolled slightly past its bounds and will animate back to its bounds when scrolling is stopped.
void	setScrollBarPositions(boolean bottom, boolean right) Set the position of the vertical and horizontal scroll bars (if they exist).
void	setScrollbarsOnTop(boolean scrollbarsOnTop) When false (the default), the widget is clipped so it is not drawn under the scrollbars.
void	setScrollingDisabled(boolean x, boolean y) Disables scrolling in a direction.
void	setScrollPercentX(float percentX)
void	setScrollPercentY(float percentY)
void	setScrollX(float pixels)
void	setScrollY(float pixels)
void	setSmoothScrolling(boolean smoothScrolling)
void	setStyle(ScrollPane.ScrollPaneStyle style)
void	setupFadeScrollBars(float fadeAlphaSeconds, float fadeDelaySeconds)
void	setupOverscroll(float distance, float speedMin, float speedMax) For flick scroll, sets the overscroll distance in pixels and the speed it returns to the widget's bounds in seconds.
void	setVariableSizeKnobs(boolean variableSizeKnobs) If true, the scroll knobs are sized based on getMaxX() or getMaxY().
void	setVelocityX(float velocityX)
void	setVelocityY(float velocityY)
void	setWidget(Actor widget) Sets the Actor embedded in this scroll pane.
void	updateVisualScroll() Sets the visual scroll amount equal to the scroll amount.

Methods inherited from class com.badlogic.gdx.scenes.scene2d.ui.WidgetGroup

getMaxHeight, getMaxWidth, invalidate, invalidateHierarchy, needsLayout, pack, setFillParent, setLayoutEnabled, validate

Methods inherited from class com.badlogic.gdx.scenes.scene2d.Group

clear, clearChildren, findActor, getChildren, hasChildren, isTransform, localToDescendantCoordinates, print, setCullingArea, setTransform, swapActor, swapActor

Methods inherited from class com.badlogic.gdx.scenes.scene2d.Actor

addAction, addCaptureListener, addListener, clearActions, clearListeners, clipBegin, clipBegin, clipEnd, fire, getActions, getCaptureListeners, getColor, getHeight, getListeners, getName, getOriginX, getOriginY, getParent, getRight, getRotation, getScaleX, getScaleY, getStage, getTop, getTouchable, getUserObject, getWidth, getX, getY, getZIndex, hasParent, isAscendantOf, isDescendantOf, isTouchable, isVisible, localToAscendantCoordinates, localToParentCoordinates, localToStageCoordinates, moveBy, notify, parentToLocalCoordinates, remove, removeAction, removeCaptureListener, removeListener, rotateBy, scaleBy, scaleBy, screenToLocalCoordinates, setBounds, setColor, setColor, setHeight, setName, setOrigin, setOriginX, setOriginY, setPosition, setRotation, setScale, setScale, setScaleX, setScaleY, setSize, setTouchable, setUserObject, setVisible, setWidth, setX, setY, setZIndex, sizeBy, sizeBy, stageToLocalCoordinates, toBack, toFront, toString

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

ScrollPane

public ScrollPane(Actor widget)

Parameters:

widget - May be null.

ScrollPane

public ScrollPane(Actor widget,
                  Skin skin)

Parameters:

widget - May be null.

ScrollPane

public ScrollPane(Actor widget,
                  Skin skin,
                  String styleName)

Parameters:

widget - May be null.

ScrollPane

public ScrollPane(Actor widget,
                  ScrollPane.ScrollPaneStyle style)

Parameters:

widget - May be null.

Method Detail

cancel

public void cancel()

If currently scrolling by tracking a touch down, stop scrolling.

setStyle

public void setStyle(ScrollPane.ScrollPaneStyle style)

getStyle

public ScrollPane.ScrollPaneStyle getStyle()

Returns the scroll pane's style. Modifying the returned style may not have an effect until setStyle(ScrollPaneStyle) is called.

act

public void act(float delta)

Description copied from class: Actor

Updates the actor based on time. Typically this is called each frame by Stage.act(float).

The default implementation calls Action.act(float) on each action and removes actions that are complete.

Overrides:

act in class Group

Parameters:

delta - Time in seconds since the last frame.

layout

public void layout()

Description copied from interface: Layout

Computes and caches any information needed for drawing and, if this actor has children, positions and sizes each child, calls Layout.invalidate() any each child whose width or height has changed, and calls Layout.validate() on each child. This method should almost never be called directly, instead Layout.validate() should be used.

Specified by:

layout in interface Layout

Overrides:

layout in class WidgetGroup

draw

public void draw(Batch batch,
                 float parentAlpha)

Description copied from class: WidgetGroup

If this method is overridden, the super method or WidgetGroup.validate() should be called to ensure the widget group is laid out.

Overrides:

draw in class WidgetGroup

parentAlpha - Should be multiplied with the actor's alpha, allowing a parent's alpha to affect all children.

fling

public void fling(float flingTime,
                  float velocityX,
                  float velocityY)

Generate fling gesture.

Parameters:

flingTime - Time in seconds for which you want to fling last.

velocityX - Velocity for horizontal direction.

velocityY - Velocity for vertical direction.

getPrefWidth

public float getPrefWidth()

Specified by:

getPrefWidth in interface Layout

Overrides:

getPrefWidth in class WidgetGroup

getPrefHeight

public float getPrefHeight()

Specified by:

getPrefHeight in interface Layout

Overrides:

getPrefHeight in class WidgetGroup

getMinWidth

public float getMinWidth()

Specified by:

getMinWidth in interface Layout

Overrides:

getMinWidth in class WidgetGroup

getMinHeight

public float getMinHeight()

Specified by:

getMinHeight in interface Layout

Overrides:

getMinHeight in class WidgetGroup

setWidget

public void setWidget(Actor widget)

Sets the Actor embedded in this scroll pane.

Parameters:

widget - May be null to remove any current actor.

getWidget

public Actor getWidget()

Returns the actor embedded in this scroll pane, or null.

addActor

public void addActor(Actor actor)

Deprecated. ScrollPane may have only a single child.

Description copied from class: Group

Adds an actor as a child of this group. The actor is first removed from its parent group, if any.

Overrides:

addActor in class Group

See Also:

setWidget(Actor)

addActorAt

public void addActorAt(int index,
                       Actor actor)

Deprecated. ScrollPane may have only a single child.

Description copied from class: Group

Adds an actor as a child of this group, at a specific index. The actor is first removed from its parent group, if any.

Overrides:

addActorAt in class Group

Parameters:

index - May be greater than the number of children.

See Also:

setWidget(Actor)

addActorBefore

public void addActorBefore(Actor actorBefore,
                           Actor actor)

Deprecated. ScrollPane may have only a single child.

Description copied from class: Group

Adds an actor as a child of this group, immediately before another child actor. The actor is first removed from its parent group, if any.

Overrides:

addActorBefore in class Group

See Also:

setWidget(Actor)

addActorAfter

public void addActorAfter(Actor actorAfter,
                          Actor actor)

Deprecated. ScrollPane may have only a single child.

Description copied from class: Group

Adds an actor as a child of this group, immediately after another child actor. The actor is first removed from its parent group, if any.

Overrides:

addActorAfter in class Group

See Also:

setWidget(Actor)

removeActor

public boolean removeActor(Actor actor)

Description copied from class: Group

Removes an actor from this group. If the actor will not be used again and has actions, they should be cleared so the actions will be returned to their pool, if any. This is not done automatically.

Overrides:

removeActor in class Group

hit

public Actor hit(float x,
                 float y,
                 boolean touchable)

Description copied from class: Actor

Returns the deepest actor that contains the specified point and is touchable and visible, or null if no actor was hit. The point is specified in the actor's local coordinate system (0,0 is the bottom left of the actor and width,height is the upper right).

This method is used to delegate touchDown, mouse, and enter/exit events. If this method returns null, those events will not occur on this Actor.

The default implementation returns this actor if the point is within this actor's bounds.

Overrides:

hit in class Group

touchable - If true, the hit detection will respect the touchability.

See Also:

Touchable

setScrollX

public void setScrollX(float pixels)

getScrollX

public float getScrollX()

Returns the x scroll position in pixels.

setScrollY

public void setScrollY(float pixels)

getScrollY

public float getScrollY()

Returns the y scroll position in pixels.

updateVisualScroll

public void updateVisualScroll()

Sets the visual scroll amount equal to the scroll amount. This can be used when setting the scroll amount without animating.

getVisualScrollX

public float getVisualScrollX()

getVisualScrollY

public float getVisualScrollY()

getScrollPercentX

public float getScrollPercentX()

setScrollPercentX

public void setScrollPercentX(float percentX)

getScrollPercentY

public float getScrollPercentY()

setScrollPercentY

public void setScrollPercentY(float percentY)

setFlickScroll

public void setFlickScroll(boolean flickScroll)

scrollTo

public void scrollTo(float x,
                     float y,
                     float width,
                     float height)

Sets the scroll offset so the specified rectangle is fully in view, if possible. Coordinates are in the scroll pane widget's coordinate system.

scrollToCenter

public void scrollToCenter(float x,
                           float y,
                           float width,
                           float height)

Sets the scroll offset so the specified rectangle is fully in view and centered vertically in the scroll pane, if possible. Coordinates are in the scroll pane widget's coordinate system.

getMaxX

public float getMaxX()

Returns the maximum scroll value in the x direction.

getMaxY

public float getMaxY()

Returns the maximum scroll value in the y direction.

getScrollBarHeight

public float getScrollBarHeight()

getScrollBarWidth

public float getScrollBarWidth()

getScrollWidth

public float getScrollWidth()

Returns the width of the scrolled viewport.

getScrollHeight

public float getScrollHeight()

Returns the height of the scrolled viewport.

isScrollX

public boolean isScrollX()

isScrollY

public boolean isScrollY()

setScrollingDisabled

public void setScrollingDisabled(boolean x,
                                 boolean y)

Disables scrolling in a direction. The widget will be sized to the FlickScrollPane in the disabled direction.

isDragging

public boolean isDragging()

isPanning

public boolean isPanning()

isFlinging

public boolean isFlinging()

setVelocityX

public void setVelocityX(float velocityX)

getVelocityX

public float getVelocityX()

Gets the flick scroll y velocity.

setVelocityY

public void setVelocityY(float velocityY)

getVelocityY

public float getVelocityY()

Gets the flick scroll y velocity.

setOverscroll

public void setOverscroll(boolean overscrollX,
                          boolean overscrollY)

For flick scroll, if true the widget can be scrolled slightly past its bounds and will animate back to its bounds when scrolling is stopped. Default is true.

setupOverscroll

public void setupOverscroll(float distance,
                            float speedMin,
                            float speedMax)

For flick scroll, sets the overscroll distance in pixels and the speed it returns to the widget's bounds in seconds. Default is 50, 30, 200.

setForceScroll

public void setForceScroll(boolean x,
                           boolean y)

Forces enabling scrollbars (for non-flick scroll) and overscrolling (for flick scroll) in a direction, even if the contents do not exceed the bounds in that direction.

isForceScrollX

public boolean isForceScrollX()

isForceScrollY

public boolean isForceScrollY()

setFlingTime

public void setFlingTime(float flingTime)

For flick scroll, sets the amount of time in seconds that a fling will continue to scroll. Default is 1.

setClamp

public void setClamp(boolean clamp)

For flick scroll, prevents scrolling out of the widget's bounds. Default is true.

setScrollBarPositions

public void setScrollBarPositions(boolean bottom,
                                  boolean right)

Set the position of the vertical and horizontal scroll bars (if they exist).

Parameters:

bottom - sets horizontal scroll bar to be at the bottom or the top

right - sets vertical scroll bar to be at the right or the left

setFadeScrollBars

public void setFadeScrollBars(boolean fadeScrollBars)

When true the scroll bars fade out after some time of not being used.

setupFadeScrollBars

public void setupFadeScrollBars(float fadeAlphaSeconds,
                                float fadeDelaySeconds)

setSmoothScrolling

public void setSmoothScrolling(boolean smoothScrolling)

setScrollbarsOnTop

public void setScrollbarsOnTop(boolean scrollbarsOnTop)

When false (the default), the widget is clipped so it is not drawn under the scrollbars. When true, the widget is clipped to the entire scroll pane bounds and the scrollbars are drawn on top of the widget. If setFadeScrollBars(boolean) is true, the scroll bars are always drawn on top.

getVariableSizeKnobs

public boolean getVariableSizeKnobs()

setVariableSizeKnobs

public void setVariableSizeKnobs(boolean variableSizeKnobs)

If true, the scroll knobs are sized based on getMaxX() or getMaxY(). If false, the scroll knobs are sized based on Drawable.getMinWidth() or Drawable.getMinHeight(). Default is true.

setCancelTouchFocus

public void setCancelTouchFocus(boolean cancelTouchFocus)

When true (default), the Stage.cancelTouchFocus() touch focus} is cancelled when flick scrolling begins. This causes widgets inside the scrollpane that have received touchDown to receive touchUp when flick scrolling begins.