LavishGUI:Elements

Introduction

What is an element?

An LavishGUI element is an individual portion of the user interface with its own characteristics, intended to be rendered with the user interface when "visible".

All LavishGUI elements are relative to their parent element. This means that its position is always based on its parent position, and if its parent is not visible, the element will also not be visible.

There are no restrictions on where elements can be placed, with exceptions only when specific elements indicate that they may only be used under other specific elements (for example, hudelement should only be used as a child of hud). This means that you do not need to place elements in a "window" -- you can have freefloating buttons (or anything else). Likewise, you can have a tab control inside a button.

LavishGUI elements with no parents are actually children of an inaccessible "screen" element, which has X and Y position set to 0,0 and Height and Width set to the game's resolution.

Using Elements

Attributes

• Name

All elements must have a name. The name must not be the same as any of its siblings, but may be the same as another element elsewhere (including this element's parent and children)

Notes on Element Names

1. The element's Fully-Qualified Name (FQN) is made up of the element name and each of its parents' names (from this element to its outermost parent), separated by the @ character. For example, if an element named "Output" resides in a top-level element named "Console", the element's FQN is "Output@Console".

Properties

2D Positioning

• X

Leftmost pixel, relative to its parent's left edge. May begin with "r" (short for reverse) to mean backwards, relative to the parent's right edge, such as r10 to mean "the parent's right edge, minus 10". May use a % to indicate a percentage of its parent's width (e.g. using 50% will place the leftmost pixel exactly halfway across its parent)

• Y

Topmost pixel, relative to its parent's top edge. May begin with "r" (short for reverse) to mean upwards, relative to the parent's bottom edge, such as r10 to mean "the parent's bottom edge, minus 10". May use a % to indicate a percentage of its parent's height (e.g. using 50% will place the topmost pixel exactly halfway down its parent)

• Width

Width in pixels. May begin with "r" (short for reverse) to indicate a width relative to the parent's width, such as r10 to mean "the parent's width, minus 10". May use a % to indicate a percentage of its parent's width

• Height

Height in pixels. May begin with "r" (short for reverse) to indicate a height relative to the parent's height, such as r10 to mean "the parent's height, minus 10". May use a % to indicate a percentage of its parent's height

Notes on 2D Positioning

1. An Element with non-fixed positions will have positioning recalculated when its parent's positioning changes
2. The area designated by X,Y,Width,Height is used for display of this specific element, and mouse control of this specific element and its children. In other words, child elements may be placed outside of the parent element's area and will be visible, but the user will not be able to interact with the element (so it may be useful for display-only elements, but not an element requiring mouse input).

Embedded Script

• OnLoad

Executes after the element and its children have been loaded.

• OnUnload

Executes just before the element has been unloaded.

• OnRender

Executes just before the element and its children would be rendered each frame.

• OnLeftClick

Executes after performing any built-in left mouse button release (click) behavior for the element. Integer variables X and Y contain the present mouse position.

• OnLeftDown

Executes after performing any built-in left mouse button press behavior for the element. Integer variables X and Y contain the present mouse position.

• OnDoubleLeftClick

Executes after performing any built-in double left click behavior for the element. Integer variables X and Y contain the present mouse position.

• OnRightClick

Executes after performing any built-in right mouse button release (click) behavior for the element. Integer variables X and Y contain the present mouse position.

• OnRightDown

Executes after performing any built-in right mouse button press behavior for the element. Integer variables X and Y contain the present mouse position.

• OnDoubleRightClick

Executes after performing any built-in double right click behavior for the element. Integer variables X and Y contain the present mouse position.

• OnMouseEnter

Executes when the mouse cursor enters the element. Integer variables X and Y contain the present mouse position.

• OnMouseExit

Executes when the mouse cursor exits the element.

• OnMouseMove

Executes when the mouse cursor is above the element and has moved. Integer variables X and Y contain the present mouse position.

• OnMouseWheel

Executes when the mouse wheel is moved. An integer variable "Offset" contains the mousewheel change "offset". As described by MSDN, "the wheel rotation will be a multiple of WHEEL_DELTA, which is set at 120. This is the threshold for action to be taken, and one such action (for example, scrolling one increment) should occur for each delta."

• OnKeyboardEnter

Executes when the element receives keyboard focus

• OnKeyboardExit

Executes when the element keyboard focus changes away from this element

• OnKeyUp

Executes when a key is released. A string variable "Key" contains the name of the key as defined by the keyboard driver.

• OnKeyDown

Executes when a key is pressed. A string variable "Key" contains the name of the key as defined by the keyboard driver.

Notes on Embedded Script

1. All embedded scripts set the This Top-Level Object to the current element

Others

• AlwaysOnTop

A toggle. Enable if this element should "always be on top", relative to its siblings

• AutoTooltip

Text to be used for a tooltip for this element. Hovering over the element will automatically display this text in a tooltip

• Children

A container. Place any elements to be children of this element in this container.

• Visible

A toggle. Elements are visible by default. Disable if this element should not be visible by default.

• StorePosition

A toggle. Enable if this element should have its position (relative to its parent) stored and restored automatically when unloading and loading this element. The element's fully qualified name is used for this storage.

Creating Element Types

Custom element types are created in Inner Space extensions. See ISXDK

See Also

• LavishGUI
• lguielement (Data Type)
• LavishGUI:Data_Types