Class Region
The base class of all elements in the GUI.
Objects of this class offers core functionalities needed by every element of the interface. They have a name, and a corresponding variable created in Lua to access them. They can have a parent Frame. They can be placed on the screen at an absolute position, or relative to other Regions. They can be shown or hidden.
Apart form this, a Region does not contain anything, nor can it display anything on the screen. Any functionality beyond the list above is implemented in specialized subclasses (see the full list below).
Interaction between C++, Lua, and layout files. When a Region is created,
it must be given a name, for example "PlayerHealthBar". For as long as the
object lives, this name will be used to refer to it. In particular, as soon
as the object is created, regardless of whether this was done in C++, layout
files, or Lua, a new variable will be created in the Lua state with the exact
same name, PlayerHealthBar. This variable is a reference to the Region,
and can be used to interact with it dynamically. Because of this, each object
must have a unique name, otherwise it could not be accessible from Lua.
Note: Although you can destroy this Lua variable by setting it to nil, this is not recommended: the object will not be destroyed (nor garbage-collected) because it still exists in the C++ memory space. The only way to truly destroy an object is to call GUI.delete_frame (for Frames only). Destroying and creating objects has a cost however. If the object is likely to reappear later with the same content, simply hide it and show it again later on. If the content may change, you can also recycle the object, i.e., keep it alive and simply change its content when it later reappears.
Parent-child relationship. Parents of Regions are Frames. See
the Frame class documentation for more information. One important
aspect of the parent-child relationship is related to the object name. If a
region has a parent, it can be given a name starting with "$parent".
The name of the parent will automatically replace the "$parent" string.
For example, if an object is named "$parentButton" and its parent is named
"ErrorMessage", the final name of the object will be "ErrorMessageButton".
It can be accessed from the Lua state as ErrorMessageButton, or as
ErrorMessage.Button. This is particularly important when using inheritance,
as the final name of an inherited child region then naturally depends on the
name of its parent.
A child will inherit some properties from its parent: transparency, scaling, visibility (show/hide), strata (if not explicitly specified), level (incremented from its parent's), and renderer (if not explicitly specified). Note in particular that the parent-child relationship does not impose any link between the child and its parent's position and size: this must be done explicitly with anchors, as required.
Lastly, a child is owned by its parent: if the parent is destroyed, the child will be destroyed as well.
Positioning. Regions have a position on the screen, but this is not parametrized as a simple pair of X and Y coordinates. Instead, objects are positioned based on a list of "anchors". Anchors are links between objects, which force one edge or one corner of a given object to match with the edge or corner of another object. For example, given two objects A and B, you can create an anchor that links the top-left corner of A to the top-left corner of B. The position of A will automatically be linked to the position of B, hence if B moves, A will follow. To further refine this positioning, you can specify anchor offsets: for example, you may want A's top-left corner to be shifted from B's top-left corner by two pixels in the X direction, and five in the Y direction. This offset can be defined either as an absolute number of pixels, or as a relative fraction of the size of the object being anchored to. For example, you can specify that A's top-left corner links to B's top-left corner, with an horizontal offset equal to 30% of B's width. Read the "Anchors" section below for more information.
An object which has no anchor will be considered "invalid" and will not be displayed.
Sizing. There are two ways to specify the size of a Region. The first and most straightforward approach is to directly set its width and/or height. This must be specified as an absolute number of pixels. The second and more versatile method is to use more than one anchor for opposite sides of the object, for example an anchor for the "left" and another for the "right" edge. This will implicitly give a width to the object, depending on the position of the other objects to which it is anchored. Anchors will always override the absolute width and height of an object if they provide any constraint on the extents of the object in a given dimension.
An object which has neither a fixed absolute size, nor has it size implicitly constrained by anchors, is considered "invalid" and will not be displayed.
Anchors. There are nine available anchor points:
TOP_LEFT: constrains the max Y and min X.TOP_RIGHT: constrains the max Y and max X.BOTTOM_LEFT: constrains the min Y and min X.BOTTOM_RIGHT: constrains the min Y and max X.LEFT: constrains the min X and the midpoint in Y.RIGHT: constrains the max X and the midpoint in Y.TOP: constrains the max Y and the midpoint in X.BOTTOM: constrains the min Y and the midpoint in X.CENTER: constrains the midpoint in X and Y.
If you specify two constraints on the same point (for example: TOP_LEFT
and BOTTOM_LEFT both constrain the min X coordinate), the most stringent
constraint always wins. Constraints on the midpoints are more subtle however,
as they will always be discarded when both the min and max are constrained.
For example, consider an object A of fixed size 30x30 and some other object
B of fixed size 40x40. If we anchor the RIGHT of A to the LEFT of B,
A's vertical center will be automatically aligned with B's vertical center.
This is the effect of the midpoint constraint. Now, if we further anchor the
TOP of A to the TOP of B, we have more than one anchor constraining
the vertical extents of A (see "Sizing" above), therefore A's fixed height
of 30 pixels will be ignored from now on. It will shrink to a height of 20
pixels, i.e., the distance between B's top edge and its vertical center.
Finally, if we further anchor the BOTTOM of A to the BOTTOM of B, the
constraint on A's midpoint will be ignored: A will be enlarged to a height
of 40 pixels, i.e., the distance between B's top and bottom edges.
Inherits all methods from: none.
Child classes: Frame, LayeredRegion, FontString, Texture, Button, CheckButton, EditBox, ScrollFrame, Slider, StatusBar.
Methods
Methods
- region:get_alpha()
- region:get_name()
- region:get_region_type()
- region:is_region_type()
- region:set_alpha()
- region:clear_all_anchors()
- region:get_bottom()
- region:get_center()
- region:get_height()
- region:get_left()
- region:get_anchor_count()
- region:get_parent()
- region:get_anchor()
- region:get_right()
- region:get_top()
- region:get_width()
- region:hide()
- region:is_shown()
- region:is_visible()
- region:is_valid()
- region:set_all_anchors()
- region:set_height()
- region:set_parent()
- region:set_anchor()
- region:set_rel_point()
- region:set_width()
- region:show()