Base GUI Elements - jMonkeyEngine-Contributions/Lemur GitHub Wiki

Base GUI Elements

The main Lemur set of GUI elements is organized as a simple class hierarchy extending JME's Spatial but this is mostly for convenience. Each Spatial subclass is simply a setup of a regular spatial that provides setters/getters for GUI element attributes as well as convenience constructors. Underneath, it's just a Spatial with a GuiControl. GuiControl is what gives it the component stack and parent/child relationships necessary for layouts. All of these GUI elements attempt to be a 'best practice' example of how to use the underlying Lemur modules to make new GUI elements. It's probably worth studying the code if you ever intend to write your own elements.

Overview

Positioning and Size

In OpenGL and jMonkeyEngine, the lower left corner of the screen is 0,0. In UI layouts, this is often a painful translation to make all the time. Lemur chooses to compromise by having GUI elements positioning in standard OpenGL space but otherwise grow and layout as if 0,0 is in the upper left.

Element Expansion

So all GUI elements are positioned by their upper left corner and their size causes them to grow down and right. Furthermore, in Containers, added children also grow down as one would expect in a user interface.

Base Element Class Hierarchy

Class Hierarchy

Panel

This the base class for all of the standard GUI elements. It supports the following properties (thus all other components also support these properties):

  • background: The background component for this element such as a QuadComponent.
  • border: The border component for this element. The border is 'underneath' the background.
  • insets: The Insets3f value for this element which controls how far in the border component is pushed in from the outer laid out sides. (the same as margin in CSS).
  • insetsComponent: Overrides the insets value with a component that sits under the border component and can provide dynamic insets capability. Defaults to InsetsComponent if the insets property is set.
  • alpha: Sets the alpha for any ColoredComponents in the component stack and also recurses to any child elements. This can be used to fade in/out a whole hierarchy of GUI elements.

See: Component Layer Breakout for an overview of how border, background, etc. components fit together.

See also: javadoc

Container

Extends Panel to provide child layout support. Any of the standard layouts (BorderLayout, SpringLayout, etc.) can be used or any custom GuiLayout implementation. Layout-specific constraints can be passed as part of the addChild() call to pass information about where and how the element might go in the layout.

Properties:

  • layout: the layout used by this container.

See also: javadoc

Label

Extends Panel to provide text and icon display. Includes three additional components in the component stack for text, shadow, and icon.

Properties:

  • text: the text that will be displayed in the label.
  • icon: an icon layer that can be any component but will typically be an IconComponent.
  • font: sets the font used to render the text.
  • fontSize: sets the font size of the rendered text.
  • textVAlignment: sets the vertical alignment of the text inside the element area. One of: VAlignment.Top, VAlignment.Bottom, or VAlignment.Center.
  • textHAlignment: sets the horizontal alignment of the text inside the element area. One of: HAlignment.Left, HAlighnment.Right, or HAlignment.Center.
  • color: sets the text color.
  • shadowColor: sets the shadow color. Defaults to 'null' indicating that there will be no shadow.
  • shadowOffset: sets the 3D offset of the shadow text from the main text. This can be used to position the shadow to look farther or closer to the text as needed. It can also be used to move the shadow above the text which when combined with the shadowColor can be used to make a bevel highlight instead. Defaults to Vector3f(1,-1,-1).

Component Layer Breakout

The above layers combined with the Panel layers, combine to look like the following image: Button Breakout

Because Button inherits all of its component layer settings from Label the image works here. The only different between a Button and a Label in this case is that a Button typically has a default background where as a Label doesn't.

Note: the 'border' layer is not represented in the diagram but it would fall below the 'background' layer. It's a relatively new default layer which is part of the reason why Button styles tend to use 'background' instead of 'border'.

See also: javadoc

Button

Extends a Label to provide click and button action support. This includes automatic text color change for mouse fly-over.

Action commands can be registered to receive notification for different button events. An addClickCommands() method provides convenience support for registering 'click' listeners. Otherwise, commands can be registered to be notified for the following actions: ButtonAction.Down, ButtonAction.Up, ButtonAction.Click, ButtonAction.HighlightOn, and ButtonAction.HighlightOff

Includes all of Label's properties in addition to the following:

  • enabled: if set to false, the button will not notify button action commands. No visible state change is enacted when the button is disabled (yet).
  • pressed: (read only) returns true if the button is currently being pressed (Down received but no Up yet.)
  • highlightOn: (read only) returns true if the button is in HighlightOn state, ie: the mouse is hovering over the button.

See: Component Layer Breakout for an overview of how border, background, etc. components fit together.

See also: javadoc

TextField

Allows single or multiline entry from the user if the text field is clicked. Also supports specific key-map actions for what to do for tab, enter, etc. by adding entries to the actionMap.

Properties:

  • text: the entered text value for the TextField. It can also be set in code to change the value.
  • font: sets the font used to render the text.
  • fontSize: sets the font size of the rendered text.
  • textVAlignment: sets the vertical alignment of the text inside the element area. One of: VAlignment.Top, VAlignment.Bottom, or VAlignment.Center.
  • textHAlignment: sets the horizontal alignment of the text inside the element area. One of: HAlignment.Left, HAlighnment.Right, or HAlignment.Center.
  • color: sets the text color.
  • singleLine: sets whether this element is a single line or multiline text entry field. Defaults to true.
  • preferredWidth: sets the preferred width of the text field when used in layouts.

See also: javadoc