easel.ui.layouts

Class VerticalLayout

java.lang.Object

easel.ui.AbstractWidget<T>

easel.ui.layouts.VerticalLayout

public class VerticalLayout
extends AbstractWidget<T>

Layout widgets vertically from top to bottom. Use the withChild(AbstractWidget) family of methods to manage new widgets. The following example code constructs a new layout with a desired width of 100px and three widgets spaced 20px apart vertically. From top to bottom: widget1, 20px spacing, widget2, 20px spacing, and widget3. The default child anchor is set to center, so all children added after this line will be centered horizontally inside the 100px width, except for widget3 which specifies that it overrides this anchor and will be aligned to the right most side.

 
 VerticalLayout layout = new VerticalLayout(100.0f, 20.0f)
     .withDefaultChildAnchor(AnchorPosition.CENTER)
     .withChild(widget1)
     .withChild(widget2)
     .withChild(widget3, AnchorPosition.RIGHT_CENTER)
     .anchoredAt(x, y, AnchorPosition.LEFT_TOP);
 
 

NOTE: child widgets are only given enough room as their preferred heights allow but can move around horizontally within the preferred width; because of this, the child anchor positions only consider the horizontal position of the anchor and the vertical information is ignored.

See Also:

HorizontalLayout

Field Summary

Fields

Modifier and Type	Field and Description
protected java.util.ArrayList<easel.ui.layouts.LayoutItem>	children
protected AnchorPosition	defaultChildAnchorPosition
protected boolean	shouldAutoScaleToContent
protected float	spacing
protected float	totalHeight
protected float	totalWidth

Fields inherited from class easel.ui.AbstractWidget

hasInteractivity, hb, isHovered, leftClickStarted, onLeftClick, onMouseEnter, onMouseLeave, onRightClick, rightClickStarted

Constructor Summary

Constructors

Constructor and Description
VerticalLayout(float spacing) Constructs a new vertical layout with the given vertical spacing.
VerticalLayout(float desiredWidth, float spacing) Constructs a new vertical layout with the given column width and vertical spacing.

Method Summary

Modifier and Type	Method and Description
protected void	anchorChildren(InterpolationSpeed withDelay)
T	anchoredAt(float x, float y, AnchorPosition anchorPosition, InterpolationSpeed movementSpeed) Moves the widget towards a specific spot.
protected void	autoscale()
protected void	cancelMovementQueueForAllChildren(boolean shouldTryAndResolveOneLastTime)
void	clear() Stop managing all widgets previously managed by this layout.
T	forceChildAnchors(AnchorPosition forcedChildAnchorPosition) Forcibly sets the anchor position of all current children to the given value.
float	getContentHeight() The internal content height of the widget (excludes margins).
float	getContentWidth() The internal content width of the widget (excludes margins).
void	hide()
java.util.stream.Stream<AbstractWidget>	iterator()
<T> java.util.stream.Stream<T>	iteratorOfType(java.lang.Class<T> clz) A stream of children handled by this widget who are of the specific type, for convenience purposes.
void	renderTopLevel(com.badlogic.gdx.graphics.g2d.SpriteBatch sb) Renders top level (especially tooltip) effects.
protected void	renderWidget(com.badlogic.gdx.graphics.g2d.SpriteBatch sb) Custom widgets should implement this method for rendering.
VerticalLayout	scaleToWidestChild() Replaces the desiredWidth set in the constructor (VerticalLayout(float, float)) with the width of the widest child.
protected void	setChildrenDelayedMovement(float deltaX, float deltaY, InterpolationSpeed movementSpeed, long startingTimeMillis) For use with AbstractWidget.delayedTranslate(float, float, InterpolationSpeed, long).
void	show()
protected void	updateSize(AbstractWidget newChild)
T	withChild(AbstractWidget child) Let this layout manage the given child using the defaultChildAnchorPosition as its internal anchor.
T	withChild(AbstractWidget child, AnchorPosition anchor) Let this layout manage the given child using the provided internal anchor.
T	withDefaultChildAnchorPosition(AnchorPosition defaultChildAnchorPosition) Sets the AnchorPosition for all future children added to this widget.

Methods inherited from class easel.ui.AbstractWidget

anchoredAt, anchoredAtClamped, anchoredAtClamped, anchoredCenteredOnMouse, anchoredCenteredOnMouse, anchoredCenteredOnMouseClamped, anchoredCenteredOnMouseClamped, anchoredCenteredOnScreen, anchoredCenteredOnScreen, cancelMovementQueue, delayedTranslate, getBottom, getContentBottom, getContentCenterX, getContentCenterY, getContentLeft, getContentRight, getContentTop, getHeight, getLeft, getRight, getTop, getWidth, initializeInteractivity, isMouseInBounds, isMouseInContentBounds, leftMouseClick, mouseEnter, mouseLeave, onLeftClick, onMouseEnter, onMouseLeave, onRightClick, refreshAnchor, render, resolveMovementQueue, rightMouseClick, scaleHitboxToContent, setAllDelayedMovement, toString, translate, update, updateInteractivity, updateWidget, withMargins, withMargins, withMargins

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

children

protected java.util.ArrayList<easel.ui.layouts.LayoutItem> children

defaultChildAnchorPosition

protected AnchorPosition defaultChildAnchorPosition

totalWidth

protected float totalWidth

totalHeight

protected float totalHeight

spacing

protected float spacing

shouldAutoScaleToContent

protected boolean shouldAutoScaleToContent

Constructor Detail

VerticalLayout

public VerticalLayout(float desiredWidth,
                      float spacing)

Constructs a new vertical layout with the given column width and vertical spacing. Child widgets of width less than this desiredWidth will be able to float around horizontally in their assigned slot using their anchor position. You can use the other constructor (VerticalLayout(float)) if you want to automatically scale the widths to the tallest child, but using this version means the height allowed for children will not be changed unless you manually alter it using scaleToWidestChild().

Parameters:

desiredWidth - the width of the vertical layout (for child anchoring purposes)

spacing - the vertical gap in between elements of the layout

See Also:

VerticalLayout(float)

VerticalLayout

public VerticalLayout(float spacing)

Constructs a new vertical layout with the given vertical spacing. This constructor guarantees that scaleToWidestChild() will be called the FIRST time that any AbstractWidget.anchoredAt(float, float, AnchorPosition) anchoring occurs (only the first time). This is essentially a convenience method for the usual pattern where the column width set by the other constructor is ignored with a manual scaleToWidestChild() before anchoring. This variant just does it automatically. To ensure performance, this auto-scaling only occurs the first time an anchoring occurs (which, presumably is after all children have been added), and must be done manually later if things change beyond that.

Parameters:

spacing - the vertical gap in between elements of the layout

See Also:

VerticalLayout(float, float)

Method Detail

getContentWidth

public float getContentWidth()

Description copied from class: AbstractWidget

The internal content width of the widget (excludes margins). Safe to use before anchoring (values should be accurate after constructor).

Specified by:

getContentWidth in class AbstractWidget<VerticalLayout>

Returns:

the width of this widget (excluding margins)

See Also:

AbstractWidget.getWidth(), AbstractWidget.getContentHeight()

getContentHeight

public float getContentHeight()

Description copied from class: AbstractWidget

The internal content height of the widget (excludes margins). Safe to use before anchoring (values should be accurate after constructor).

Specified by:

getContentHeight in class AbstractWidget<VerticalLayout>

Returns:

the height of this widget (excluding margins)

See Also:

AbstractWidget.getHeight(), AbstractWidget.getContentWidth()

updateSize

protected void updateSize(AbstractWidget newChild)

clear

public void clear()

Stop managing all widgets previously managed by this layout.

autoscale

protected void autoscale()

anchorChildren

protected void anchorChildren(InterpolationSpeed withDelay)

scaleToWidestChild

public VerticalLayout scaleToWidestChild()

Replaces the desiredWidth set in the constructor (VerticalLayout(float, float)) with the width of the widest child. Useful for dynamically scaling the width of this widget to fit the widths of its children. NOTE: should call this function AFTER adding all children and before anchoring.

Returns:

this widget

withDefaultChildAnchorPosition

public T withDefaultChildAnchorPosition(AnchorPosition defaultChildAnchorPosition)

Sets the AnchorPosition for all future children added to this widget. If this is not set or children are added before this method is called, it defaults to a value of AnchorPosition.LEFT_TOP. Only referred to when using the add child methods that do not specify a specific anchor position (if specified, this default child anchor position is ignored). NOTE: For horizontal layouts, only the vertical position in the anchor matters. This is because children are only allowed to grow horizontally up to their preferred width. However, the total height of the layout is arbitrary and that means that the vertical anchoring can affect the vertical positioning. A similar restriction exists for vertical layouts but for left/right anchors.

Parameters:

defaultChildAnchorPosition - the internal anchor position of each future child

Returns:

this layout

forceChildAnchors

public T forceChildAnchors(AnchorPosition forcedChildAnchorPosition)

Forcibly sets the anchor position of all current children to the given value. This is useful if you change desired anchors later and have previously added children with different anchors. This function does not update the defaultChildAnchorPosition, so any future children added will continue to use that value if not manually set.

Parameters:

forcedChildAnchorPosition - the new anchor for all existing children

Returns:

this layout

withChild

public final T withChild(AbstractWidget child,
                         AnchorPosition anchor)

Let this layout manage the given child using the provided internal anchor. The child is added to the end of the layout (right-most for a horizontal layout, bottom-most for a vertical layout).

Parameters:

child - the child widget to be added

anchor - where the child will be anchored internally to the space given (see withDefaultChildAnchorPosition(AnchorPosition) for details about the limitations of the internal anchor)

Returns:

this layout

See Also:

withChild(AbstractWidget)

withChild

public final T withChild(AbstractWidget child)

Let this layout manage the given child using the defaultChildAnchorPosition as its internal anchor. This child is added to the end of the layout (right-most for a horizontal layout, bottom-most for a vertical layout). If the defaultChildAnchorPosition hasn't been set previously (i.e. through withDefaultChildAnchorPosition(AnchorPosition)), the default value is AnchorPosition.LEFT_TOP.

Parameters:

child - the child widget to be added

Returns:

this layout

See Also:

withChild(AbstractWidget, AnchorPosition)

anchoredAt

public T anchoredAt(float x,
                    float y,
                    AnchorPosition anchorPosition,
                    InterpolationSpeed movementSpeed)

Description copied from class: AbstractWidget

Moves the widget towards a specific spot. The anchorPosition defines the point on the widget that will be placed at the position (x, y).

For example, anchoredAt(100, 200, AnchorPosition.LEFT_BOTTOM, InterpolationSpeed.FAST) will set the bottom-left corner of the widget to 100 pixels from the left side of the screen and 200 pixels from the bottom of the screen. The widget then renders up and to the right of this point since we anchored at an AnchorPosition.LEFT_BOTTOM. As a second example, using AnchorPosition.CENTER ensures that (x, y) will be the center of the widget.

The interpolation speed movementSpeed determines how quickly the widget moves to the target location. Using a speed other than InterpolationSpeed.INSTANT makes the widget move towards the desired position over the next few frames in a smoothly animated manner. For convenience since instant moving is often the desired effect, see AbstractWidget.anchoredAt(float, float, AnchorPosition).

Note: you should always anchor at least once before rendering. For more dynamic widgets that move a lot (e.g. a tooltip dependent on the mouse cursor location using InputHelper.mX and InputHelper.mY), a general pattern is to call anchoredAt right before rendering in your main render function, e.g.:

 
 widget.anchoredAt(x, y, AnchorPosition.CENTER, InterpolationSpeed.INSTANT)
       .render(sb);
 
 

Overrides:

anchoredAt in class AbstractWidget<T extends easel.ui.layouts.AbstractOneDimensionalLayout<T>>

Parameters:

x - the x position in pixels from the left edge of the screen

y - the y position in pixels from the bottom edge of the screen

anchorPosition - what piece of the widget will be moved to (x, y)

movementSpeed - how quickly the widget will move towards the desired position

Returns:

this widget

See Also:

AbstractWidget.anchoredAt(float, float, AnchorPosition), AbstractWidget.anchoredAtClamped(float, float, AnchorPosition, float), AbstractWidget.anchoredAtClamped(float, float, AnchorPosition, InterpolationSpeed, float)

setChildrenDelayedMovement

protected void setChildrenDelayedMovement(float deltaX,
                                          float deltaY,
                                          InterpolationSpeed movementSpeed,
                                          long startingTimeMillis)

Description copied from class: AbstractWidget

For use with AbstractWidget.delayedTranslate(float, float, InterpolationSpeed, long). Make sure any widget with children (e.g. containers, layouts, etc.) overrides this function and calls AbstractWidget.setAllDelayedMovement(float, float, InterpolationSpeed, long) using the input to this function on all direct descendants. This is required if you want to be able to use a delayed anchoredAt command on custom widgets.

Overrides:

setChildrenDelayedMovement in class AbstractWidget<T extends easel.ui.layouts.AbstractOneDimensionalLayout<T>>

Parameters:

deltaX - how much movement horizontally

deltaY - how much movement vertically

movementSpeed - how fast the widget will move towards the target, once startingTimeMillis is reached (i.e. System.currentTimeMillis() is greater than or equal to this starting time)

startingTimeMillis - a time generated by an offset of System.currentTimeMillis(), determined by the original AbstractWidget.delayedTranslate(float, float, InterpolationSpeed, long) function that starts this chain

cancelMovementQueueForAllChildren

protected void cancelMovementQueueForAllChildren(boolean shouldTryAndResolveOneLastTime)

Overrides:

cancelMovementQueueForAllChildren in class AbstractWidget<T extends easel.ui.layouts.AbstractOneDimensionalLayout<T>>

iterator

public java.util.stream.Stream<AbstractWidget> iterator()

Returns:

a stream of all children currently handled by this widget, from top to bottom (or left to right)

iteratorOfType

public <T> java.util.stream.Stream<T> iteratorOfType(java.lang.Class<T> clz)

A stream of children handled by this widget who are of the specific type, for convenience purposes. Follows the same top to bottom / left to right ordering of the regular iterator. If you know you've built the layout with all objects of a particular type, you can quickly recover them all into a stream that remembers the type. This has a slight performance penalty over iterator() due to checking each child against the type for safe casts, but the resulting stream will be properly typed to make it easier to work with. Children managed by this layout who are not of the given type will not be included in the stream, so be wary if using this variant of the iterator.

Type Parameters:

T - the type of child to extract

Parameters:

clz - the class for the type

Returns:

a stream of children who fit the given type

See Also:

iterator()

renderWidget

protected void renderWidget(com.badlogic.gdx.graphics.g2d.SpriteBatch sb)

Description copied from class: AbstractWidget

Custom widgets should implement this method for rendering. Use the inner content positions (e.g. AbstractWidget.getContentLeft(), AbstractWidget.getContentWidth(), etc.) to determine any position information necessary for rendering at a specific location. If the library is used as intended, these content locations should be accurate to where the widget needs to be rendered, as they reflect the most up to date location set by an anchoredAt call (this automatically will be interpolated if the anchorAt move is set to occur over several frames).

Note: you NEED to revert any changes you make to the SpriteBatch (e.g. setting a shader, changing the perspective matrix, etc.) by the time this function returns, as the SpriteBatch will be reused for rendering other widgets which will not expect those changes. You also don't technically need to render to this particular SpriteBatch (e.g. you can render to your own batch if you know what you're doing), as long as you follow the general intent of this function to render the widget.

Specified by:

renderWidget in class AbstractWidget<T extends easel.ui.layouts.AbstractOneDimensionalLayout<T>>

Parameters:

sb - the SpriteBatch the widget should be rendered on

See Also:

AbstractWidget.renderTopLevel(SpriteBatch)

renderTopLevel

public void renderTopLevel(com.badlogic.gdx.graphics.g2d.SpriteBatch sb)

Description copied from class: AbstractWidget

Renders top level (especially tooltip) effects. Like AbstractWidget.render(SpriteBatch), but deliberately delayed. If any of your widgets require custom (Widget-based, not base-game TipHelper based) tooltips or other specific rendering that needs to go on top of all other widgets in the hierarchy, you'll need to set your root node to call this after its main AbstractWidget.render(SpriteBatch) completes.

If you are hooking into BaseMod's RenderSubscriber for your base class, you can simply call this after your main call to rootWidget.render(spriteBatch). All layout managers and other container widgets will extend the calls down the tree automatically (much like how render() works), meaning you only need to call this at the highest level of your widget hierarchy.

 
 public void receiveRender(SpriteBatch spriteBatch) {
     // Our normal render call will trickle down the hierarchy in a breadth-first manner, rendering every descendant widget.
     baseWidget.render(spriteBatch);

     // Call this after the above so that we can support custom tooltips (if desired); also trickles down the tree
     baseWidget.renderTopLevel(spriteBatch);
 }
 
 

Note that this is only required if you are using custom widgets that need to be rendered last (on top of everything). If you are sticking to base game style tooltips (e.g. using something like the TipHelper statics), this is NOT required. However, if you do end up needing to draw on top of all widgets in your hierarchy, this is a solid way to do it as it follows the same breadth-first visit order but occurs after all the regular rendering takes place.

Overrides:

renderTopLevel in class AbstractWidget<T extends easel.ui.layouts.AbstractOneDimensionalLayout<T>>

Parameters:

sb - the SpriteBatch to render on

See Also:

AbstractWidget.render(SpriteBatch)

hide

public void hide()

Overrides:

hide in class AbstractWidget<T extends easel.ui.layouts.AbstractOneDimensionalLayout<T>>

show

public void show()

Overrides:

show in class AbstractWidget<T extends easel.ui.layouts.AbstractOneDimensionalLayout<T>>