Panels


Panels work by serving as a parent object to groups of controls, and are able to apply transitions to their child objects. Individual panels can be used for things such as toolbars, while multiple panels can be grouped together as children of a UIPanelManager to create things such as menus and wizards. One of the key attributes of panels is that, when grouped as children to a UIPanelManager, the panels in this group are mutually exclusive. That is, the UIPanelManager can manage them so that only one of them displays at a time, and they will automatically transition in/out as needed.

You can use a single UIPanelManager to make a full-screen menu, or you can use multiple UIPanelManagers at a time to have multiple groups of mutually exclusive panels to create things like tabbed interfaces.

There are currently two types of panels available in EZ GUI:
  • UIPanel - A simple panel type and the preferred type for use with UIPanelManager to create menus, etc.
  • UIInteractivePanel - A panel type that, once a collider is added, supports a degree of interactivity via input using the pointing device.
  • All panels have the following common settings:
Index
Index of the panel. When the panel is part of a UIPanelManager, this allows you to set the sequence of the panels when navigating a menu by using "forward" and "back" buttons. The panel at the lowest index value will be displayed first.
Deactivate All On Dismiss
When true, the panel, along with all child objects, will be set to inactive when the panel's dismissal transition is complete.
UIPanel
The UIPanel class is the main type that should be used for things such as menus and wizards.
UIInteractivePanel
The UIInteractivePanel class, when combined with a collider, adds a certain amount of interactivity via the pointing device. It includes the draggable setting, which allows you to drag the panel, and contents (children), around when any part of its collider is clicked and dragged.

When a UIInteractivePanel is set to draggable, there are a few additional settings which become relevant:
Constrain Drag Area
If the draggable option is enabled, this setting indicates whether the position of the panel should be constrained to a certain area in world space when being dragged. If set to true, the panel's world space position will be constrained to the boundary specified by the dragBondaryMin and dragBoundaryMax points.
Drag Boundary Min
Specifies the minimum point in space where the panel can be dragged.

NOTE: Only has effect if draggable and constrainDragArea are set to true.
Drag Boundary Max
Specifies the maximum point in space where the panel can be dragged.

NOTE: Only has effect if draggable and constrainDragArea are set to true.
UIInteractivePanel also includes 5 additional transitions on top of the basic 4: "Normal from Over", "Normal from Dragging", "Over from Normal", "Over from Dragging", and "Dragging". These transition types work very similar to how they do on the Button control. "Normal" is when the panel enters the "normal" state (no pointing device is over the panel's collider or any of its child controls) from either the "over" or "dragging" states, and the "Over" transitions are when the panel enters the "over" state from one of the other two states (a pointing device is over the panel's collider or that of one of its child controls). "Dragging" is entered when the panel is being dragged.

Using these state-based transitions, you can implement things such as "dock"-like menu bars, etc. See the recipes section in Using Panels for more ideas.
UIBistateInteractivePanel (two-state interactive panel)
The UIBistateInteractivePanel class is somewhat similar to the UIInteractivePanel in that unlike "regular" panels, it is typically not managed by a panel manager, and also in the fact that it includes settings governing its interactivity. As its name implies, it possess two state: hiding and showing. Thus it is primarily intended to be used to implement pop-up menus and selections. For example, think of a pop-up selection box. When you click on something, it appears, you can use the content of the pop-up, and then either when you make your selection, or click outside of it, the pop-up is immediately dismissed (or "hidden").

UIBistateInteractivePanel contains the same standard transitions of a regular panel. The "Bring In Forward" is used internally by the panel to "show" itself, and the "Dismiss Forward" transition is used to "hide" itself automatically. So these are the transitions you will want to define to utilize its built-in behaviors.

The UIBistateInteractivePanel includes these additional settings:
Require Tap
When true, a PRESS is not sufficient, but rather a TAP event is required (press and release).
Always Show On Click
When true, the panel will always show itself when it is clicked, and some other action will be required to dismiss/hide it.
Dismiss On Outside Click
When true, the panel will dismiss itself when a PRESS event occurs anywhere outside of the panel.
Dismiss On Peer Click
When true, the panel dismisses itself when a control or panel is clicked which is not a child.
Dismiss On Child Click
When true, the panel will dismiss itself when one of its child controls are clicked. This is useful, for example, in pop-up menus where you want to offer a selection to the user, and then immediately hide the selection as soon as a selection is made.
Dismiss On Move Off
When true, the panel will be dismissed when the pointer is moved away from the panel and its child controls. This is useful, for example, when you want a menu that only remains showing only while the pointer is hovering over it. Such as a menu bar drop-down.
Show On Child Click
When true, if any child is clicked/tapped while the panel is hidden, the panel will be shown.
Initial State
The starting state of the panel (i.e. HIDDEN or SHOWING). Set this to match whether the panel will be hidden or showing at start.