Class GUIObject

java.lang.Object
com.blackrook.gui.GUIObject
Direct Known Subclasses:
GUILabel, GUIPanel, GUITogglePanel
public abstract class GUIObject extends Object
All GUI Objects inherit this class for creating entry points for GUI events.
Author:
Matthew Tropiano

  • Field Details

    • EVENT_UNKNOWN

      public static final String EVENT_UNKNOWN
      Unknown type of event.
      See Also:

    • EVENT_MOUSE_OVER

      public static final String EVENT_MOUSE_OVER
      Mouse cursor is (directly) over this object.
      See Also:

    • EVENT_MOUSE_LEAVE

      public static final String EVENT_MOUSE_LEAVE
      Mouse cursor leaves this object (not over it anymore).
      See Also:

    • EVENT_MOUSE_PRESS

      public static final String EVENT_MOUSE_PRESS
      Mouse button is pressed on this object.
      See Also:

    • EVENT_MOUSE_RELEASE

      public static final String EVENT_MOUSE_RELEASE
      Mouse button is released on this object.
      See Also:

    • EVENT_MOUSE_MOVE

      public static final String EVENT_MOUSE_MOVE
      Mouse is moved on this object.
      See Also:

    • EVENT_MOUSE_DRAG

      public static final String EVENT_MOUSE_DRAG
      Mouse is dragged on this object (not moved, button is down).
      See Also:

    • EVENT_MOUSE_CLICK

      public static final String EVENT_MOUSE_CLICK
      Mouse is clicked on this object.
      See Also:

    • EVENT_MOUSE_WHEEL

      public static final String EVENT_MOUSE_WHEEL
      Mouse wheel is scrolled on this object.
      See Also:

    • EVENT_KEY_PRESS

      public static final String EVENT_KEY_PRESS
      Keyboard key is pressed on this object.
      See Also:

    • EVENT_KEY_RELEASE

      public static final String EVENT_KEY_RELEASE
      Keyboard key is released on this object.
      See Also:

    • EVENT_KEY_TYPE

      public static final String EVENT_KEY_TYPE
      Keyboard key is typed on this object.
      See Also:

    • EVENT_GAMEPAD_PRESS

      public static final String EVENT_GAMEPAD_PRESS
      Gamepad button is pressed on this object.
      See Also:

    • EVENT_GAMEPAD_RELEASE

      public static final String EVENT_GAMEPAD_RELEASE
      Gamepad button is released on this object.
      See Also:

    • EVENT_GAMEPAD_AXIS

      public static final String EVENT_GAMEPAD_AXIS
      Gamepad axis is changed on this object.
      See Also:

    • EVENT_GAMEPAD_TAP_PRESS

      public static final String EVENT_GAMEPAD_TAP_PRESS
      Gamepad axis is tapped (press) on this object.
      See Also:

    • EVENT_GAMEPAD_TAP_RELEASE

      public static final String EVENT_GAMEPAD_TAP_RELEASE
      Gamepad axis is untapped (release) on this object.
      See Also:

    • EVENT_GENERIC_INPUT

      public static final String EVENT_GENERIC_INPUT
      Some kind of generic input is sent to the GUI in the form of a code.
      See Also:

    • EVENT_NAMED

      public static final String EVENT_NAMED
      Denotes an event triggered by name.
      See Also:

    • EVENT_FOCUS

      public static final String EVENT_FOCUS
      Object is focused.
      See Also:

    • EVENT_BLUR

      public static final String EVENT_BLUR
      Object loses focus.
      See Also:

    • EVENT_CHANGE_ENABLE_STATE

      public static final String EVENT_CHANGE_ENABLE_STATE
      Object is enabled/disabled.
      See Also:

    • EVENT_CHANGE_VISIBLE_STATE

      public static final String EVENT_CHANGE_VISIBLE_STATE
      Object is shown/hidden.
      See Also:

    • absoluteBounds

      protected GUIBounds absoluteBounds
      This object's absolute bounds.

  • Constructor Details

    • GUIObject

      protected GUIObject()
      Creates a new GUI object.

  • Method Details

    • getGUI

      public final GUI getGUI()
      Returns:
      the reference to which GUI scene this belongs to.

    • getParent

      public final GUIObject getParent()
      Gets the parent object of this one. Can be null if this is not a child object.
      Returns:
      the parent object, or null if not added to an object.

    • addChild

      public final GUIObject addChild(GUIObject obj, Object attrib)
      Add a child object to this one and sets a layout attribute to it, as though setLayoutAttrib(Object)
      Parameters:
      obj - the object to add.
      attrib - the layout attribute.
      Returns:
      itself, to chain calls.

    • addChild

      public final GUIObject addChild(GUIObject obj)
      Add a child object to this one.
      Parameters:
      obj - the object to add.
      Returns:
      itself, to chain calls.

    • removeChild

      public final GUIObject removeChild(GUIObject obj)
      Removes a child object from this one.
      Parameters:
      obj - the object to remove.
      Returns:
      itself, to chain calls.

    • remove

      public final GUIObject remove()
      Removes this object from its GUI.
      Returns:
      itself, to chain calls.

    • moveUp

      public final GUIObject moveUp()
      Moves the order of this object up among its siblings, so that it is rendered later than the one after it (bringing it "closer to the camera").

      If this is the last one anyway, nothing happens.

      If this is not the child of an object, nor does it belong to a GUI, nothing happens.

      Returns:
      itself, to chain calls.

    • moveToFront

      public final GUIObject moveToFront()
      Moves the order of this object up among its siblings, so that it is rendered last (bringing it "closest to the camera").

      If this is the last one anyway, nothing happens.

      If this is not the child of an object, nor does it belong to a GUI, nothing happens.

      Returns:
      itself, to chain calls.

    • moveDown

      public final GUIObject moveDown()
      Moves the order of this object back among its siblings, so that it is rendered earlier than the one before it (pushing it "further from the camera").

      If this is the first one anyway, nothing happens.

      If this is not the child of an object, nor does it belong to a GUI, nothing happens.

      Returns:
      itself, to chain calls.

    • moveToBack

      public final GUIObject moveToBack()
      Moves the order of this object back among its siblings, so that it is rendered first (pushing it "farthest from the camera").

      If this is the first one anyway, nothing happens.

      If this is not the child of an object, nor does it belong to a GUI, nothing happens.

      Returns:
      itself, to chain calls.

    • addToRenderSet

      protected final void addToRenderSet(GUIRenderSet set)
      Called when this object needs adding to a render set for rendering later. Usually, this should add itself plus its children to the set. Assumes the render set's GUI bounds are set.
      Parameters:
      set - the set to add it to.

    • hasAction

      public final boolean hasAction(String type)
      Checks if an action has at least one binding.
      Parameters:
      type - the event type.
      Returns:
      true if so, false if not.

    • bindAction

      public final GUIObject bindAction(GUIAction action, String... types)
      Adds an action bound to an event type. The action is enqueued, so the added action will happen after other actions bound to this event type.
      Parameters:
      action - the action to bind.
      types - the event types.
      Returns:
      itself, to chain calls.

    • unbindAction

      public final GUIObject unbindAction(GUIAction action, String... types)
      Removes an action bound to an event type.
      Parameters:
      action - the action to unbind.
      types - the event types.
      Returns:
      itself, to chain calls.

    • unbindAllActions

      public final GUIObject unbindAllActions(String... types)
      Removes all actions bound to event types.
      Parameters:
      types - the event types.
      Returns:
      itself, to chain calls.

    • callAction

      public final void callAction(GUIAction action)
      Calls an action on this object.
      Parameters:
      action - the action to call on this object.

    • fireEvent

      protected final void fireEvent(String type)
      Fires a non-specific event to the GUI system.
      Parameters:
      type - the event type to fire.

    • addName

      public final void addName(String... names)
      Adds a single name or series of names to this object, used for selecting objects.
      Parameters:
      names - the names to add.

    • removeName

      public final GUIObject removeName(String... names)
      Removes a single name or series of names from this object.
      Parameters:
      names - the names to remove.
      Returns:
      itself, to chain calls.

    • hasName

      public final boolean hasName(String name)
      Checks if this object has a particular name.
      Parameters:
      name - the name to search for.
      Returns:
      true if found, false if not.

    • hasNamePattern

      public final String hasNamePattern(Pattern pattern)
      Returns true if one of this object's names matches the provided pattern, false otherwise.
      Parameters:
      pattern - the pattern to use.
      Returns:
      the name matched, or null if no matches.

    • getBounds

      public GUIBounds getBounds()
      Returns a copy of this object's bounding rectangle. Any changes to the returned Rectangle2F will not change the bounds of this object, and thus will NOT trigger any events triggered by a bounds change.

      NOTE: The returned object reference is used by other calls to this method on this thread. If you wish to preserve the values returned, they will need to be copied.

      Returns:
      a rectangle of this object's bounds.
      See Also:

    • getNativeBounds

      protected GUIBounds getNativeBounds()
      Returns a reference to this object's bounds rectangle. Any changes made to this rectangle will affect the object's bounds, but will NOT trigger any events triggered by a bounds change.
      Returns:
      the rectangle reference.
      See Also:

    • setRotationZ

      public GUIObject setRotationZ(float degrees)
      Sets this object's rotation in degrees.
      Parameters:
      degrees - the new rotation in degrees. 0 is no rotation.
      Returns:
      itself, to chain calls.

    • rotate

      public GUIObject rotate(float degrees)
      Rotates this object by a number of degrees.
      Parameters:
      degrees - the rotation in degrees to add.
      Returns:
      itself, to chain calls.

    • setColor

      public GUIObject setColor(float red, float green, float blue, float alpha)
      Sets the color of this object.
      Parameters:
      red - the red component value for the color.
      green - the green component value for the color.
      blue - the blue component value for the color.
      alpha - the alpha component value for the color.
      Returns:
      itself, to chain calls.

    • setColor

      public GUIObject setColor(GUIColor color)
      Sets the object's color.
      Parameters:
      color - the color to set.
      Returns:
      itself, to chain calls.

    • getColor

      public GUIColor getColor()
      Gets the object's color. If the object returned is changed, it will not affect this object's color.
      Returns:
      an GUIColor with this object's color components.

    • setTexture

      public GUIObject setTexture(String texture)
      Sets this object's texture.
      Parameters:
      texture - the new texture.
      Returns:
      itself, to chain calls.

    • setVisible

      public GUIObject setVisible(boolean visible)
      Sets if the object is visible (and its children). Fires an event if the visibility state changed. This attribute affects this object's descendants - they are not visible if this is not visible. Objects that are not visible are ignored when testing for mouse collisions, nor are they drawn by the renderer.
      Parameters:
      visible - true to set, false to unset.
      Returns:
      itself, to chain calls.

    • setRendered

      public GUIObject setRendered(boolean rendered)
      Sets if the object is visible (and its children). Fires an event if the visibility state changed. This attribute affects this object's descendants - they are not visible if this is not visible. Objects that are not visible are ignored when testing for mouse collisions, nor are they drawn by the renderer.
      Parameters:
      rendered - true to set, false to unset.
      Returns:
      itself, to chain calls.

    • setEnabled

      public GUIObject setEnabled(boolean enabled)
      Sets if the object can accept input (and its children). Fires an event if the enabled state changed. If this object was focused, it tells the GUI that owns it to unfocus it if it was disabled.
      Parameters:
      enabled - true to set, false to clear.
      Returns:
      itself, to chain calls.

    • setInert

      public GUIObject setInert(boolean inert)
      Sets if the object can accept/intercept input, but does NOT affect its "enabled" state, unless its parent is enabled/disabled. Unlike isVisible() and isEnabled(), this is not hierarchically significant (inert-ness is set on this and ONLY this object). Objects that are inert are ignored when testing for mouse collisions. This fires NO EVENTS on change. If this object was focused, it tells the GUI that owns it to unfocus it if it was set to be inert.
      Parameters:
      inert - true to set, false to clear.
      Returns:
      itself, to chain calls.

    • setBounds

      public GUIObject setBounds(GUIBounds r)
      Sets the object bounds.
      Parameters:
      r - the rectangle to use for bounds.
      Returns:
      itself, to chain calls.

    • setBounds

      public GUIObject setBounds(float x, float y, float width, float height)
      Sets the object bounds.
      Parameters:
      x - its position x.
      y - its position y.
      width - its width.
      height - its height.
      Returns:
      itself, to chain calls.

    • getAbsoluteBounds

      public GUIBounds getAbsoluteBounds()
      Gets this object's ABSOLUTE bounds, i.e. the object's current position after considering its inherited hierarchy. The Rectangle2F returned can be changed and it will not affect this object's bounds.
      Returns:
      a Rectangle2F of the current object bounds.

    • setPosition

      public GUIObject setPosition(float x, float y)
      Sets the object position.
      Parameters:
      x - its position x.
      y - its position y.
      Returns:
      itself, to chain calls.

    • setDimensions

      public GUIObject setDimensions(float width, float height)
      Sets the object width and height.
      Parameters:
      width - its width.
      height - its height.
      Returns:
      itself, to chain calls.

    • translate

      public GUIObject translate(float x, float y)
      Changes this object's position by an x or y-coordinate amount.
      Parameters:
      x - the x movement.
      y - the y movement.
      Returns:
      itself, to chain calls.

    • stretch

      public GUIObject stretch(float width, float height)
      Changes this object's width/height by an x or y-coordinate amount.
      Parameters:
      width - the width amount.
      height - the height amount.
      Returns:
      itself, to chain calls.

    • getRenderPositionX

      public final float getRenderPositionX()
      Returns:
      the object's rendering position, x-axis.

    • getRenderPositionY

      public final float getRenderPositionY()
      Returns:
      the object's rendering position, y-axis.

    • getRenderWidth

      public float getRenderWidth()
      Returns:
      the object's rendering width.

    • getRenderHeight

      public float getRenderHeight()
      Returns:
      the object's rendering height.

    • getRenderRotationZ

      public float getRenderRotationZ()
      Returns:
      the object's rotation in degrees, z-axis.

    • getRenderRadius

      public float getRenderRadius()
      Gets the object's radius, for use with determining what is on the screen or not.

      Since this could be an expensive call, this is not always used - it is used if the object's useRenderRadius() function returns true, which leaves it in the hands of the implementor.

      Returns:
      the radius.

    • useRenderRadius

      public boolean useRenderRadius()
      Should the object's radius value be used for collision, with the camera, rather than its half-height or half-width?
      Returns:
      the radius.

    • getRenderRed

      public float getRenderRed()
      Returns:
      the object's red channel value.

    • getRenderGreen

      public float getRenderGreen()
      Returns:
      the object's green channel value.

    • getRenderBlue

      public float getRenderBlue()
      Returns:
      the object's blue channel value.

    • getRenderAlpha

      public float getRenderAlpha()
      Returns:
      the object's alpha channel value.

    • getFinalOpacity

      protected float getFinalOpacity()
      Returns:
      this object's inherited opacity.

    • getRenderTextureScaleS

      public float getRenderTextureScaleS()
      Gets the object's texture scaling, S-axis (U). Should, in most cases, return 1f.
      Returns:
      the scaling value.

    • getRenderTextureScaleT

      public float getRenderTextureScaleT()
      Gets the object's texture scaling, T-axis (V). Should, in most cases, return 1f.
      Returns:
      the scaling value.

    • getGeneration

      public final int getGeneration()
      Returns how far down the generation tree this object is.
      Returns:
      How many parents are above this one.

    • getTexture

      public String getTexture()
      Returns this object's texture. If no texture is set on this, this will take the one from the theme, if getThemeKey() returns a non-null value.
      Returns:
      the texture name.
      See Also:

    • getThemeKey

      public abstract String getThemeKey()
      Returns this object's theme key. This is the key that is used to look up the texture used to render this object. This may return null, indicating that this object does not have a default texture.
      Returns:
      the theme key.

    • isVisible

      public boolean isVisible()
      Gets if the object is visible, which means that this object has its "visible" member set to true, and its opacity is nonzero. This object is not visible if any of its ancestors are not visible. Objects that are not visible are ignored when testing for mouse collisions.
      Returns:
      true if visible, false if not.

    • getVisible

      public boolean getVisible()
      Gets if this object is flagged as "visible". This differs from isVisible() as this is not a calculated value.
      Returns:
      true, if this particular object is flagged as visible, false otherwise.

    • getRendered

      public boolean getRendered()
      Gets if this object is rendered. The object's children can still be rendered. Unlike isVisible(), this is not hierarchically significant ("rendered" affects this and ONLY this object).
      Returns:
      true if so, false if not.

    • isFocused

      public boolean isFocused()
      Gets if this object is currently focused in its GUI.
      Returns:
      true if so. False if not, or this doesn't belong to a GUI.

    • isAnimating

      public boolean isAnimating()
      Gets if this object is currently animating
      Returns:
      true if so. False if not, or this doesn't belong to a GUI.

    • isEnabled

      public boolean isEnabled()
      Gets if the object can accept/intercept input. This affects this object's "enabled" state, as the name suggests. This object is not enabled if any of its ancestors are not enabled. Objects that are not enabled cannot be focused, and are also ignored when testing mouse collisions/events. They can still be manipulated through user-enacted methods that are not direct input.
      Returns:
      true if enabled, false if not.

    • isInert

      public boolean isInert()
      Gets if the object can accept/intercept input, but does NOT affect its "enabled" state, unless its parent is enabled/disabled. Unlike isVisible() and isEnabled(), this is not hierarchically significant (inert-ness is set on this and ONLY this object). Objects that are inert are ignored when testing for mouse collisions.
      Returns:
      true if inert, false if not.

    • isConstrainedToParent

      public boolean isConstrainedToParent()
      Checks if this constrains its position to its parent.
      Returns:
      true of so, false if not.

    • setConstrainToParent

      public GUIObject setConstrainToParent(boolean constrainToParent)
      Sets if this should constrain its position to its parent.
      Parameters:
      constrainToParent - true if so, false if not.
      Returns:
      itself, to chain calls.

    • getAsQuery

      public GUIQuery getAsQuery()
      Gets this object wrapped in an GUIQuery. Convenience method for GUIQuery.wrap(this).
      Returns:
      a new GUIQuery with this object in it.

    • getParentAsQuery

      public GUIQuery getParentAsQuery()
      Gets this object's parent wrapped in an GUIQuery. Convenience method for GUIQuery.wrap(this.getParent()).
      Returns:
      a new GUIQuery with this object's parent in it.

    • getChildrenAsQuery

      public GUIQuery getChildrenAsQuery()
      Gets this object's children wrapped in an GUIQuery.
      Returns:
      a new GUIQuery with this object's children in it.

    • getDescendantsAsQuery

      public GUIQuery getDescendantsAsQuery()
      Gets this object's entire descendant tree wrapped in an GUIQuery.
      Returns:
      a new GUIQuery with this object's descendants in it.

    • getSiblingsAsQuery

      public GUIQuery getSiblingsAsQuery()
      Gets this object's siblings wrapped in an GUIQuery.
      Returns:
      a new GUIQuery with this object's siblings in it.

    • getLayout

      public GUILayout getLayout()
      Gets this object's layout type for resizing object children, should this object get resized itself. By default, this value is null.
      Returns:
      the layout, or null if no layout.

    • setLayout

      public GUIObject setLayout(GUILayout layout)
      Sets this object's layout type for resizing object children, should this object get resized itself. By default, this value is null.
      Parameters:
      layout - the layout to use.
      Returns:
      itself, to chain calls.

    • getLayoutAttrib

      public Object getLayoutAttrib()
      Gets this object's layout attribute, used by some layouts in order to affect the parent's layout behavior when resizing this component (as a child). By default, this value is null.
      Returns:
      the layout attribute on this object, or null if none was set.

    • setLayoutAttrib

      public GUIObject setLayoutAttrib(Object attrib)
      Sets this object's layout attribute, used by some layouts in order to affect the parent's layout behavior when resizing this component (as a child). By default, this value is null. Changing this value while this object is a part of its parent's layout will trigger resizeChildren() on the parent.
      Parameters:
      attrib - the layout attribute to set (or null).
      Returns:
      itself, to chain calls.

    • getColorNotInherited

      public boolean getColorNotInherited()
      Gets if this object DOESN'T pass on its color to its children.
      Returns:
      true of so, false if not.

    • setColorNotInherited

      public GUIObject setColorNotInherited(boolean enabled)
      Sets if this object DOESN'T pass on its color to its children.
      Parameters:
      enabled - true if
      Returns:
      itself, to chain calls.

    • getTheme

      public final GUITheme getTheme()
      Returns the current theme used by this object. If no current theme, this returns the parent's theme. If no parent, this returns the theme attached the owning GUI.
      Returns:
      the theme to use.

    • setTheme

      public GUIObject setTheme(GUITheme theme)
      Sets the theme used by this object, and its descendants if they do not have a theme set. Setting this to null allows this object to inherit the current theme from its parents.
      Parameters:
      theme - the theme to use. Can be null.
      Returns:
      itself, to chain calls.

    • getOpacity

      public float getOpacity()
      Gets this object's opacity (0 to 1). Opacity is always inherited by children, regardless of if getColorNotInherited() is true or false. This affects visibility - if this is 0.0, this object is considered NOT VISIBLE.
      Returns:
      this object's opacity.
      See Also:

    • setOpacity

      public GUIObject setOpacity(float opacity)
      Gets this object's opacity (0 to 1). Opacity is always inherited by children, regardless of if getColorNotInherited() is true or false. This affects visibility - setting this to 0.0 is like setting setVisible(boolean) to false.
      Parameters:
      opacity - the new opacity factor.
      Returns:
      itself, to chain calls.

    • getScaleType

      public GUIObject.ScaleType getScaleType()
      Returns:
      this object's texture scaling type.

    • setScaleType

      public GUIObject setScaleType(GUIObject.ScaleType scaleType)
      Sets this object's texture scaling type.
      Parameters:
      scaleType - the scaling type to use.
      Returns:
      itself, to chain calls.

    • setBoundsByChildren

      public void setBoundsByChildren()
      Sets this object's width and height based on the bounds of its children. If it has no children, nothing happens.

    • requestFocus

      public GUIObject requestFocus()
      Requests focus on this object in the scene it belongs to.
      Returns:
      itself, to chain calls.

    • releaseFocus

      public GUIObject releaseFocus()
      Releases focus on this object if this object currently has focus in the scene it belongs to.
      Returns:
      itself, to chain calls.

    • resizeChildren

      public void resizeChildren()
      Calls upon the layouts to resize the children.

    • animate

      public GUIObject animate(GUIAnimation... animations)
      Enqueues an animation on this GUI Object, no duration.
      Parameters:
      animations - the animations to perform (at once) for this animation.
      Returns:
      itself, to chain calls.

    • animate

      public GUIObject animate(long duration, GUIAnimation... animations)
      Enqueues an animation on this GUI Object, linear transition.
      Parameters:
      duration - the duration of the action in time units.
      animations - the animations to perform (at once) for this animation.
      Returns:
      itself, to chain calls.

    • animate

      public GUIObject animate(long duration, GUIEasingType transition, GUIAnimation... animations)
      Enqueues an animation on this GUI Object.
      Parameters:
      duration - the duration of the action in time units.
      transition - the transition type for the action.
      animations - the animations to perform (at once) for this animation.
      Returns:
      itself, to chain calls.

    • animateDelay

      public GUIObject animateDelay(long duration)
      Enqueues a delay between animations on this GUI Object.
      Parameters:
      duration - the duration of the action in time units.
      Returns:
      itself, to chain calls.

    • animateAbort

      public GUIObject animateAbort()
      Aborts the animation on this object, abandoning it mid-animation.
      Returns:
      itself, to chain calls.

    • animateFinish

      public GUIObject animateFinish()
      Finishes the animation on this object all the way to the end.
      Returns:
      itself, to chain calls.

    • correctPosition

      protected void correctPosition()
      Corrects the position of this object, if this is constrained to the parent's position.

    • updateScenePosition

      protected void updateScenePosition()
      Updates this GUI Object's position and absolute bounds in the scene's collision field.

    • updateDirty

      protected final void updateDirty()
      Update the dirty flag on the GUI that this object belongs to.

    • onGUIChange

      protected void onGUIChange(GUI gui)
      Called when this object is added to a GUI. Does nothing, unless overridden.
      Parameters:
      gui - the reference to the GUI that this was added to.

    • toString

      public String toString()
      Overrides:
      toString in class Object