Difference between revisions of "LavishGUI:Elements"

From Lavish Software Wiki
Jump to navigation Jump to search
 
(8 intermediate revisions by 2 users not shown)
Line 7: Line 7:
 
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.
 
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 parents 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.
+
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 ==
 
== Using Elements ==
 
=== Attributes ===
 
=== Attributes ===
*Name
+
*'''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)
 
: 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
+
==== Notes on Element Names ====
# The element's <tt>Fully Qualified Name</tt> (FQN) is made up of the element name and each of its parent's 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".
+
# The element's <tt>Fully-Qualified Name</tt> (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 ===
 
=== Properties ===
 
==== 2D Positioning ====
 
==== 2D Positioning ====
*X
+
*'''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)
 
: 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
+
*'''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)
 
: 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'''
 
: 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
 
: 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'''
 
: 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
 
: 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
  
Line 30: Line 30:
 
# An Element with non-fixed positions will have positioning recalculated when its parent's positioning changes
 
# An Element with non-fixed positions will have positioning recalculated when its parent's positioning changes
 
# 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).
 
# 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).
 +
 +
==== Z Order ====
 +
*'''Strata'''
 +
: A number (-128 to 127) indicating where an element should appear within the Z order, with 127 being topmost.
 +
*'''AlwaysOnTop'''
 +
: A toggle. Enable if this element should "always be on top", relative to its siblings. This is equal to Strata 127.
 +
 +
==== 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 =====
 +
# All embedded scripts set the [[TLO:This|This]] Top-Level Object to the current element
 +
 +
==== Fading ====
 +
*'''Alpha'''
 +
: A number generally between 0 and 1 indicating the alpha level for this element.  0 is transparent, 1 is opaque.  Default is 1.
 +
*'''FadeAlpha'''
 +
: The alpha level for this element when faded (requires a non-zero fade delay).  Default is the normal Alpha level.
 +
*'''FadeDelay'''
 +
: Amount of time in milliseconds that the mouse must not be over this element in order to begin fading.  Very low numbers (such as 1) can be used to achieve an essentially instant delay, as 0 indicates that fading should not occur.  Default is 0.
 +
*'''FadeDuration'''
 +
: Amount of time in milliseconds that the process of fading will take after the delay.  Default is 0.
  
 
==== Others ====
 
==== Others ====
*AlwaysOnTop
+
*'''AutoTooltip'''
: 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
 
: Text to be used for a tooltip for this element.  Hovering over the element will automatically display this text in a tooltip
*Children
+
*'''Children'''
 
: A container. Place any elements to be children of this element in this container.
 
: A container. Place any elements to be children of this element in this container.
*Visible
+
*'''Visible'''
 
: A toggle. Elements are visible by default.  Disable if this element should not be visible by default.
 
: A toggle. Elements are visible by default.  Disable if this element should not be visible by default.
*StorePosition
+
*'''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.
 
: 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.
  
Line 47: Line 99:
  
 
== See Also ==
 
== See Also ==
[[LavishGUI]]
+
*[[LavishGUI]]
 
+
*[[LavishGUI:lguielement_%28Data_Type%29|lguielement (Data Type)]]
 +
* [[LavishGUI:Data_Types]]
 
[[Category:LavishGUI]]
 
[[Category:LavishGUI]]

Latest revision as of 15:31, 16 May 2016

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).

Z Order

  • Strata
A number (-128 to 127) indicating where an element should appear within the Z order, with 127 being topmost.
  • AlwaysOnTop
A toggle. Enable if this element should "always be on top", relative to its siblings. This is equal to Strata 127.

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

Fading

  • Alpha
A number generally between 0 and 1 indicating the alpha level for this element. 0 is transparent, 1 is opaque. Default is 1.
  • FadeAlpha
The alpha level for this element when faded (requires a non-zero fade delay). Default is the normal Alpha level.
  • FadeDelay
Amount of time in milliseconds that the mouse must not be over this element in order to begin fading. Very low numbers (such as 1) can be used to achieve an essentially instant delay, as 0 indicates that fading should not occur. Default is 0.
  • FadeDuration
Amount of time in milliseconds that the process of fading will take after the delay. Default is 0.

Others

  • 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