GUI Layers

From HEWIKI
Jump to: navigation, search

Contents

GUI Layers

GUI Layers are a way to separate out various related interface elements into their own autonomous groups. They may be thought of transparent "slices" or "sheets" onto which all GUI controls are placed. The layer system's biggest strength (and primary use) is the ability to turn on/off entire systems and groups of controls simultaneously, and control which interface elements may be present.

Guilayers example.png

The way to place a control on a layer is to set its layer field in the XML, which can be done via HSE2 or the GUI Editor. There is an automatic callback made by the C++ side of things when a new control is created from a prototype, which automatically attempts to place a control on its proper layer, assuming layers are enabled for that player. If the layer does not exist, it will be created, if it is a valid layer. The list of valid layers is currently hardcoded into the GUILayers script, and an invalid layer name will result in a script error when the control is created. To create a new layer, you first need to add it into the when/is structure in the findMyInitialLayer function and insert it in the proper place in the list created in the reorderLayers function.

Note that ultimately, only the top-level parent control's layer will make any difference. It is therefore unnecessary (and kinda pointless) to set the layer on any control which will be a child of another control.

The main difficulty with converting an existing system to work with layers is that layers are simply another type of GUI Control, and as such, must be included in any path information in a FindGUIControlByName call. The exception is the "default" layer, which will automatically be accounted for, if necessary, by FindGUIControlByName. This means that all FindGUIControlByName calls in a system must be altered to add the desired layer name at the beginning of the path, if and only if both of the following conditions are true:

Because layers are handled automatically and may be turned on and off from time to time, support for the layer system may be selectively enabled, i.e. only turned on for certain people. This would mean that any such FindGUIControlByName callbacks must be duplicated, with one callback made for those for whom layers are enabled, and one callback made for those for whom they are not. Example:

if $GUI._GUILayersEnabled()
  var percent = findGUIControlByName(0, "loadingLayer.loadingBackground.progressBar.percentLabel")
else
  var percent = findGUIControlByName(0, "loadingBackground.progressBar.percentLabel")
.

Note that the second callback, for people who do not have layers enabled, does not include "loadingLayer" in the path. Again, this only applies to searches which begin at the screen, i.e. those which use 0 or an empty noderef as their first parameter.

GUI Control Class Methods

These methods should work for all GUI Controls, regardless of race, gender, etc.

method getMyLayer() as NodeRef of Class GUIControl

Returns the noderef of myControl's top-level layer, or 0 if myControl is not on its proper layer. Note that this is based entirely on the layer field of myControl's rootParent, so myControl can be on a GUI layer, but if it is not the proper layer for that control's root parent, this function will still return 0.

Layer Class Methods

These methods are included on all GUI Layers, including the master layer.

method showLayer()

Will cause a layer to become visible, if it exists. Note that you may pass in any control here, and if the control is not a GUI Layer itself, the function will attempt to find that control's layer and show it. If it is not passed a GUI Layer, and is unable to find a GUI Layer for the control passed in, it will simply stop.

Note that if a layer has a popup layer associated with it, that layer will be made visible as well.

method hideLayer()

Just like showLayer, but hides 'em instead.

method showAllOtherLayers()

Will cause all layers to become visible except for the one passed in, which will be made hidden. This is rarely a good idea, since there are some layers which should remain hidden in all but very specific circumstances.

Unlikely to be useful. Not sure why I have it.

method hideAllOtherLayers()

The opposite of showAllOtherLayers. Will cause the layer passed in to become visible, and will hide all other layers. Will quietly die if it is unable to reconcile a layer from the control passed in.

method pushGUILayerState(system as String)

Finds Master Layer and calls this method for it. See below.

method popGUILayerState(system as String)

Finds Master Layer and calls this method for it. See below.

method clearLayer()

Destroys all children of a layer, in a most non-retrievable fashion. Use with caution. Or not, whatever.

Master Layer Class Methods

method pushGUILayerState(system as String)

Packages the current state of all existing layers' visibility and stores it on the master layer, along with the name of the system which requested it (areaload, chatbubbles, etc). See below.

method popGUILayerState(system as String)

Retrieves the most recently archived layer state and restores the layers included in that archive to their previous visibility states, then deletes the archive. Will not alter layers which have been created since that archival. Will script error if the system requesting the pop is not the system that requested the push, or if there are no archived layer states to retrieve. See below.

Layer Functions

Here are all the functions associated with GUI Layers. They're all in the GUILayers script, of course. Some functions in that script mirror the methods above, and I'll ignore those here since they'll go away at some point. Which means you should ignore them, too.

public function layersEnabled() as Boolean

This returns true if layers are enabled for the given player, and false if they are not.

public function showLayerByName(myLayerName as String)

Will attempt to find a GUI Layer based on the name passed in (which is case-insensitive), and will show it if it can find one. Will simply return if it is unable to find a control by that name which is a GUI Layer.

Note that if a layer has a popup layer associated with it, that layer will be hidden as well.

public function hideLayerByName(myLayerName as String)

Just like showLayerByName, but hides the layer instead.

public function showAllLayers()

Will cause all layers to become visible.

public function hideAllLayers()

Will cause all layers to become hidden.

public function getMasterLayer() as NodeRef of Class GUIMasterLayer

Finds and returns the default GUI Layer. Not very useful outside of layer system.

public function pushGUILayerState(system as String)

Packages the current state of all existing layers' visibility and stores it on the default layer, along with the name of the system which requested it (areaload, chatbubbles, etc). See below.

public function popGUILayerState(system as String)

Retrieves the most recently archived layer state and restores the layers included in that archive to their previous visibility states, then deletes the archive. Will not alter layers which have been created since that archival. Will script error if the system requesting the pop is not the system that requested the push, or if there are no archived layer states to retrieve. See below.

public function getLayers() as List of [[Node_Ref]] of Class GUIControl

Returns all existing layers.

public function layerStates()

Spits out a list of all the current layers and their visibility state to the console window.

Layer State Snapshots

Using the pushGUILayerState and popGUILayerState functions, a snapshot of each layer's visibility state may be saved off to a first-in-first-out stack, and subsequently retrieved when desired. Most examples of when you would do this involve a single full screen effect of some sort, such as the loading screen, character manager, or cinematics.

Essentially, it allows you to turn off everything except what's important right then and there, and still be able to restore the player's interface afterwards. It's important to remember that as with all such things, one push requires one pop, no more, no less.

The common sequence of events for doing this would be:

optional layer-getting step: if you have a control, myControl, which you need the layer for, use

var myLayer = myControl.getMyLayer()

next, save off the states of all layers

myLayer.pushGUILayerState("mySystem")

now make yours the One Layer, visible beyond all others

myLayer.hideAllOtherLayers()

Do your thing. Create a letterbox, load them into a new area, kill them with kindness, I don't care.

All done? Now restore the other controls to their previous states, so the player can chat, etc.

myLayer.popGUILayerState("mySystem")

Remember that if your layer was not visible when you pushed the layer states, popping the states will make it once again not visible. If you need it to remain visible for some reason, handle it manually after popping the states.

Personal tools
Namespaces
Variants
Actions
Navigation
Toolbox