Urho.Gui.UIElement Class

Base class for UI elements.

See Also: UIElement

Syntax

public class UIElement : Animatable

Remarks

User interface elements are serializable, so they can be serialized to/from XML using their attributes. There are two distinct use cases for UI definition files: either defining just the UI element style and leaving the actual position and dimensions to be filled in later, or fully defining an UI element layout. The default element style definitions, used for example by the editor and the debug console, are in the file bin/Data/UI/DefaultStyle.xml.

The method UI.LoadLayout in UI will take an XML file and instantiate the elements defined in it. To be valid XML, there should be one root-level UI element. An optional style XML file can be specified; the idea is to first read the element's style from that file, then fill in the rest from the actual layout XML file. This way the layout file can be relatively simple, as the majority of the data is already defined.

Note that a style can not be easily applied recursively to the loaded elements afterward. Therefore remember to specify the style file already when loading, or alternatively assign a default style file to the UI root element, which will then be picked up by all loaded layouts. This works because the UI subsystem searches the style file by going up the parental chain starting from target parent UI element. The search stops immediately when a style file is found or when it has reached the root element. Also note that UrhoSharp does not limit the number of style files being used at the same time in an application. You may have different style file set along the UI parental hierarchy, if your application needs that.

You can also use the Editor application to create UI layouts. The serialization format is similar to scene XML serialization, with three important differences:

1) The element type to instantiate, and the style to use for it can be set separately. For example the following element definition tells to instantiate a Button element, and that it should use the style "CloseButton" defined in the style XML file.

2) Internal child elements, for example the scroll bars of a ScrollView, need to be marked as such to avoid instantiating them as duplicates. This is done by adding the attribute internal="true" to the XML element, and is required in both layout and style XML files. Furthermore, the elements must be listed in the order they have been added as children of the parent element (if in doubt, see the element's C++ constructor code. Omitting elements in the middle is OK)

3) The popup element shown by Menu and DropDownList is not an actual child element. In XML serialization, it is nevertheless stored as a child element, but is marked with the attribute popup="true”.

You can associate one or more strings to a UIElement, by using the UIElement.AddTag and the UIElement.RemoveTag methods.

.

UI Element Layout

By default UI elements operate in a "free" layout mode, where child elements' positions can be specified relative to any of the parent element corners, but they are not automatically positioned or resized.

To create automatically adjusting layouts, the layout mode can be switched to either "horizontal" or "vertical". Now the child elements will be positioned left to right or top to bottom, based on the order in which they were added. They will be preferably resized to fit the parent element, taking into account their minimum and maximum sizes, but failing to do that, the parent element will be resized.

Left, top, right and bottom border widths and spacing between elements can also be specified for the layout. A grid layout is not directly supported, but it can be manually created with a horizontal layout inside a vertical layout, or vice versa.

Requirements

Namespace: Urho.Gui
Assembly: Urho (in Urho.dll)
Assembly Versions: 1.0.0.0

The members of Urho.Gui.UIElement are listed below.

See Also: Animatable

Public Constructors

Constructs a new instance of Urho.Gui.UIElement which is tied to the Application.CurrentContext.
Constructs a new instance of Urho.Gui.UIElement, given a raw pointer to an unmanaged object
Constructs a new instance of Urho.Gui.UIElement linked to a specific Context.

Protected Constructors

Empty constructor, chain to this constructor when you provide your own constructor that sets the handle field.

Public Properties

[read-only]
AppliedStyleString. Return applied style name. Return an empty string when the applied style is an 'auto' style (i.e. style derived from instance's type).
BringToBackOnFocusBoolean. Return whether should be put to background when another element is focused. Or Set whether should be put to background when another element is focused.
BringToFrontOnFocusBoolean. Return whether should be brought to front when focused. Or Set whether should be brought to front when focused.
ChildOffsetIntVector2. Return child element offset. Or Set child offset.
[read-only]
ChildrenIReadOnlyList<UIElement>. Return immediate child elements.
ClipBorderIntRect. Return child element clipping border. Or Set child element clipping border.
ClipChildrenBoolean. Return whether should clip child elements. Or Set whether should clip child elements. Default false.
[read-only]
ColorAttrColor. Return color attribute. Uses just the top-left color.
[read-only]
CombinedScreenRectIntRect. Return combined screen coordinate rect of element and its children.
[read-only]
DerivedColorColor. Return derived color. Only valid when no gradient.
[read-only]
DerivedOpacitySingle. Return derived opacity (affected by parent elements.) If UseDerivedOpacity is false, returns same as element's own opacity.
[read-only]
DragButtonComboInt32. Return the drag button combo if this element is being dragged.
[read-only]
DragButtonCountUInt32. Return the number of buttons dragging this element.
DragDropModeUInt32. Return drag and drop flags. Or Set drag and drop flags.
EditableBoolean. Controls whether value is editable through input.
[read-only]
EffectiveMinSizeIntVector2. Return effective color, multiplied by brightness and affected by temperature when "use physical values" is enabled. Alpha is always 1 so that can compare against the default black color to detect a light with no effect.
[read-only]
ElementEventSenderUIElement. Get element which should send child added / removed events.
EnableAnchorBoolean. Enable automatic positioning & sizing of the element relative to its parent using min/max anchor and min/max offset. Default false.
EnabledBoolean. Controls whether the element reacts to input.
[read-only]
EnabledSelfBoolean. Returns the element's last own enabled state. May be different than the value returned by IsEnabled when SetDeepEnabled has been used.
[read-only]
FixedHeightBoolean. Return true if height is fixed.
[read-only]
FixedSizeBoolean. Return true if size is fixed.
[read-only]
FixedWidthBoolean. Return true if width is fixed.
FocusModeFocusMode. Return focus mode. Or Set focus mode.
HeightInt32. Return height. Or Set height only.
HorizontalAlignmentHorizontalAlignment. Return horizontal alignment. Or Set horizontal alignment.
HoveringBoolean. Return whether the cursor is hovering on this element.
IndentInt32. Return horizontal indentation. Or Set horizontal indentation.
IndentSpacingInt32. Return indent spacing (number of pixels per indentation level). Or Set indent spacing (number of pixels per indentation level).
[read-only]
IndentWidthInt32. Return indent width in pixels.
InternalBoolean. Flag that determines whether is internally created.
LayoutBorderIntRect. Return layout border. Or Set layout border.
[read-only]
LayoutElementMaxSizeInt32. Return maximum layout element size in the layout direction. Only valid after layout has been calculated. Used internally by UI for optimizations.
LayoutFlexScaleVector2. Return layout flex scale. Or Set layout flex scale.
LayoutModeLayoutMode. Return layout mode. Or Set layout mode only.
LayoutSpacingInt32. Return layout spacing. Or Set layout spacing.
MaxAnchorVector2. Set maximum (bottom right) anchor in relation to the parent element (from 0 to 1.) No effect when anchor is not enabled.
MaxHeightInt32. Return minimum height. Or Set maximum height.
MaxOffsetIntVector2. Return maximum offset. Or Set offset of element's bottom right from the maximum anchor in pixels. No effect when anchor is not enabled.
MaxSizeIntVector2. Return maximum size. Or Set maximum size.
MaxWidthInt32. Return minimum width. Or Set maximum width.
MinAnchorVector2. Return minimum anchor. Or Set minimum (top left) anchor in relation to the parent element (from 0 to 1.) No effect when anchor is not enabled.
MinHeightInt32. Return minimum height. Or Set minimum height.
MinOffsetIntVector2. Return minimum offset. Or Set offset of element's top left from the minimum anchor in pixels. No effect when anchor is not enabled.
MinSizeIntVector2. Return minimum size. Or Set minimum size.
MinWidthInt32. Return minimum width. Or Set minimum width.
NameString. Return name. Or Set name.
OpacitySingle. Return opacity. Or Set opacity.
[read-only]
ParentUIElement. Return parent element.
PivotVector2. Return pivot. Or Set pivot relative to element's size (from 0 to 1, where 0.5 is center.) Overrides horizontal & vertical alignment.
PositionIntVector2. Return position. Or Set position.
PriorityInt32. Return priority. Or Set priority.
[read-only]
RootUIElement. Return root element.
[read-only]
ScreenPositionIntVector2. Update and return screen position.
SelectedBoolean. Return whether is selected. Actual meaning is element dependent.
ShouldSortChildrenBoolean. Return whether should sort child elements according to priority. Or Set whether should sort child elements according to priority. Default true.
SizeIntVector2. Return size. Or Set size.
TraversalModeTraversalMode. Return traversal mode for rendering. Or Set traversal mode for rendering. The default traversal mode is TM_BREADTH_FIRST for non-root element. Root element should be set to TM_DEPTH_FIRST to avoid artifacts during rendering.
[read-only]
override
TypeStringHash. Urho's type system type.
[read-only]
override
TypeNameString. Urho's low-level type name.
[read-only]
static
TypeNameStaticString. Urho's low-level type name, accessible as a static method.
[read-only]
static
TypeStaticStringHash. Urho's low-level type, accessible as a static method.
UseDerivedOpacityBoolean. Return whether parent elements' opacity affects opacity. Or Set whether parent elements' opacity affects opacity. Default true.
VerticalAlignmentVerticalAlignment. Return vertical alignment. Or Set vertical alignment.
VisibleBoolean. Determines whether element itself should be visible. Elements can be also hidden due to the parent being not visible, use VisibleEffective to check.
[read-only]
VisibleEffectiveBoolean. Return whether element is effectively visible (parent element chain is visible.)
WidthInt32. Return width. Or Set width only.

Public Methods

AddChild(UIElement)
Add a child element.
AddTag(String)
Attaches the specified string as a tag to this UIElement.
override
ApplyAttributes()
Apply attribute changes that can not be applied immediately.
BringToFront()
Bring UI element to front.
CreateBorderImage(String, UInt32) : BorderImage
CreateButton(String, UInt32) : Button
Creates a Button.
CreateCheckBox(String, UInt32) : CheckBox
Creates a CheckBox.
CreateChild(StringHash, String, UInt32) : UIElement
Create and add a child element and return it.
CreateChild<T>(StringHash, String, UInt32) : T
Create and add a child element and return it.
CreateCursor(String, UInt32) : Cursor
Creates a Cursor.
CreateDropDownList(String, UInt32) : DropDownList
Creates a DropDownList.
CreateLineEdit(String, UInt32) : LineEdit
Creates a LineEdit.
CreateListView(String, UInt32) : ListView
Creates a ListView.
CreateMenu(String, UInt32) : Menu
Creates a Menu.
CreateScrollBar(String, UInt32) : ScrollBar
Creates a ScrollBar.
CreateScrollView(String, UInt32) : ScrollView
Creates a ScrollView.
CreateSlider(String, UInt32) : Slider
Creates a Slider.
CreateSprite(String, UInt32) : Sprite
Creates a Sprite.
CreateText(String, UInt32) : Text
Creates a Text.
CreateToolTip(String, UInt32) : ToolTip
CreateView3D(String, UInt32) : View3D
Creates a View3D.
CreateWindow(String, UInt32) : Window
Creates a Window.
DisableLayoutUpdate()
Disable automatic layout update. Should only be used if there are performance problems.
ElementToScreen(IntVector2) : IntVector2
Convert element coordinates to screen coordinates.
EnableLayoutUpdate()
Enable automatic layout update.
FilterAttributes(XmlElement) : Boolean
Filter attributes in serialization process.
FindChild(UIElement) : UInt32
Find child index. Return M_MAX_UNSIGNED if not found.
GetChild(UInt32) : UIElement
Return child element by index.
GetChild(String, Boolean) : UIElement
Return child element by name.
GetColor(Corner) : Color
Return corner color.
GetDefaultStyle(Boolean) : XmlFile
Return default style.
GetNumChildren(Boolean) : UInt32
Return number of child elements.
HasColorGradient() : Boolean
Return whether has different color in at least one corner.
HasFocus() : Boolean
Return whether has focus.
HasTag(String) : Boolean
Determines if the UIElement has the associated tag attached to it.
InsertChild(UInt32, UIElement)
Insert a child element into a specific position in the child list.
IsElementEventSender() : Boolean
Return whether element should send child added / removed events by itself. If false, defers to parent element.
IsInside(IntVector2, Boolean) : Boolean
Return whether a point (either in element or screen coordinates) is inside the element.
IsInsideCombined(IntVector2, Boolean) : Boolean
Return whether a point (either in element or screen coordinates) is inside the combined rect of the element and its children.
IsWithinScissor(IntRect) : Boolean
Return whether is visible and inside a scissor rectangle and should be rendered.
LoadChildXml(XmlElement, XmlFile, Boolean) : UIElement
Create a child by loading from XML data with style. Returns the child element if successful, null if otherwise.
LoadXml(File) : Boolean
Load from XML data. Return true if successful.
LoadXml(MemoryBuffer) : Boolean
override
LoadXml(XmlElement, Boolean) : Boolean
Load from XML data. Return true if successful.
LoadXml(XmlElement, XmlFile, Boolean) : Boolean
Create a child by loading from XML data with style. Returns the child element if successful, null if otherwise.
OnClickBegin(IntVector2, IntVector2, Int32, Int32, Int32, Cursor)
React to mouse click begin.
OnClickEnd(IntVector2, IntVector2, Int32, Int32, Int32, Cursor, UIElement)
React to mouse click end.
OnDoubleClick(IntVector2, IntVector2, Int32, Int32, Int32, Cursor)
React to double mouse click.
OnHover(IntVector2, IntVector2, Int32, Int32, Cursor)
React to mouse hover.
OnIndentSet()
React to indent change.
OnKey(Int32, Int32, Int32)
React to a key press.
OnPositionSet(IntVector2)
React to position change.
OnResize(IntVector2, IntVector2)
React to resze.
OnSetEditable()
React to editable status change.
OnTextInput(String)
OnWheel(Int32, Int32, Int32)
React to mouse wheel.
static
RegisterObject(Context)
Register object factory.
Remove()
Remove from the parent element. If no other shared pointer references exist, causes immediate deletion.
RemoveAllChildren()
Remove all child elements.
RemoveAllTags()
Remove all tags.
RemoveChild(UIElement, UInt32)
Remove a child element. Starting search at specified index if provided.
RemoveChildAtIndex(UInt32)
Remove a child element at index.
RemoveTag(String) : Boolean
Removes the specified tag from the UIElement.
ResetDeepEnabled()
Reset enabled state to the element's remembered state prior to calling SetDeepEnabled.
override
SaveXml(XmlElement) : Boolean
Save as XML data. Return true if successful.
SaveXml(File, String) : Boolean
Save as XML data. Return true if successful.
SaveXml(MemoryBuffer, String) : Boolean
ScreenToElement(IntVector2) : IntVector2
Convert screen coordinates to element coordinates.
SetAlignment(HorizontalAlignment, VerticalAlignment)
Set horizontal and vertical alignment.
SetColor(Color)
Set color on all corners.
SetColor(Corner, Color)
Set color on one corner.
SetDeepEnabled(Boolean)
Set enabled state on self and child elements. Elements' own enabled state is remembered (IsEnabledSelf) and can be restored.
SetDefaultStyle(XmlFile)
Set default style file for later use by children elements.
SetElementEventSender(Boolean)
Set element event sender flag. When child element is added or deleted, the event would be sent using UIElement found in the parental chain having this flag set. If not set, the event is sent using UI's root as per normal.
SetEnabledRecursive(Boolean)
Set enabled state on self and child elements. Unlike SetDeepEnabled this does not remember the elements' own enabled state, but overwrites it.
SetFixedHeight(Int32)
Set fixed height.
SetFixedSize(IntVector2)
Set fixed size.
SetFixedSize(Int32, Int32)
Set fixed size.
SetFixedWidth(Int32)
Set fixed width.
SetFocus(Boolean)
Set whether is focused. Only one element can be focused at a time.
SetLayout(LayoutMode, Int32, IntRect)
Set layout.
SetMaxAnchor(Single, Single)
Set maximum (bottom right) anchor in relation to the parent element (from 0 to 1.) No effect when anchor is not enabled.
SetMaxSize(Int32, Int32)
Set maximum size.
SetMinAnchor(Single, Single)
Set minimum (top left) anchor in relation to the parent element (from 0 to 1.) No effect when anchor is not enabled.
SetMinSize(Int32, Int32)
Set minimum size.
SetParent(UIElement, UInt32)
Set parent element. Same as parent->InsertChild(index, this).
SetPivot(Single, Single)
Set pivot relative to element's size (from 0 to 1, where 0.5 is center.) Overrides horizontal & vertical alignment.
SetPosition(Int32, Int32)
Set position.
SetSize(Int32, Int32)
Set size.
SetStyle(XmlElement) : Boolean
Set style from an XML element. Return true if the style is applied successfully.
SetStyle(String, XmlFile) : Boolean
Set style from an XML file. Find the style element by name. If the style file is not explicitly provided, use the default style from parental chain. Return true if the style is applied successfully.
SetStyleAuto(XmlFile) : Boolean
Set style from an XML file. Find the style element automatically by using the element's typename. If the style file is not explicitly provided, use the default style from parental chain. Return true if the style is applied successfully.
SetVar(StringHash, Int32)
Set a user variable.
SetVar(StringHash, Single)
Set a user variable.
SetVar(StringHash, String)
Set a user variable.
SetVar(StringHash, Color)
Set a user variable.
SetVar(StringHash, IntRect)
Set a user variable.
SetVar(StringHash, IntVector2)
Set a user variable.
SetVar(StringHash, Matrix3x4)
Set a user variable.
SetVar(StringHash, Matrix4)
Set a user variable.
SetVar(StringHash, Quaternion)
Set a user variable.
SetVar(StringHash, Vector2)
Set a user variable.
SetVar(StringHash, Vector3)
Set a user variable.
SetVar(StringHash, Vector4)
Set a user variable.
SortChildren()
Sort child elements if sorting enabled and order dirty. Called by UI.
SubscribeToDefocused(Action<DefocusedEventArgs>) : Subscription
Subscribes to the Defocused event raised by the UIElement.
SubscribeToDragBegin(Action<DragBeginEventArgs>) : Subscription
Subscribes to the DragBegin event raised by the UIElement.
SubscribeToDragCancel(Action<DragCancelEventArgs>) : Subscription
Subscribes to the DragCancel event raised by the UIElement.
SubscribeToDragDropFinish(Action<DragDropFinishEventArgs>) : Subscription
Subscribes to the DragDropFinish event raised by the UIElement.
SubscribeToDragDropTest(Action<DragDropTestEventArgs>) : Subscription
Subscribes to the DragDropTest event raised by the UIElement.
SubscribeToDragEnd(Action<DragEndEventArgs>) : Subscription
Subscribes to the DragEnd event raised by the UIElement.
SubscribeToDragMove(Action<DragMoveEventArgs>) : Subscription
Subscribes to the DragMove event raised by the UIElement.
SubscribeToElementAdded(Action<ElementAddedEventArgs>) : Subscription
Subscribes to the ElementAdded event raised by the UIElement.
SubscribeToElementRemoved(Action<ElementRemovedEventArgs>) : Subscription
Subscribes to the ElementRemoved event raised by the UIElement.
SubscribeToFocused(Action<FocusedEventArgs>) : Subscription
Subscribes to the Focused event raised by the UIElement.
SubscribeToHoverBegin(Action<HoverBeginEventArgs>) : Subscription
Subscribes to the HoverBegin event raised by the UIElement.
SubscribeToHoverEnd(Action<HoverEndEventArgs>) : Subscription
Subscribes to the HoverEnd event raised by the UIElement.
SubscribeToLayoutUpdated(Action<LayoutUpdatedEventArgs>) : Subscription
Subscribes to the LayoutUpdated event raised by the UIElement.
SubscribeToNameChanged(Action<NameChangedEventArgs>) : Subscription
Subscribes to the NameChanged event raised by the UIElement.
SubscribeToPositioned(Action<PositionedEventArgs>) : Subscription
Subscribes to the Positioned event raised by the UIElement.
SubscribeToResized(Action<ResizedEventArgs>) : Subscription
Subscribes to the Resized event raised by the UIElement.
SubscribeToVisibleChanged(Action<VisibleChangedEventArgs>) : Subscription
Subscribes to the VisibleChanged event raised by the UIElement.
Update(Single)
Perform UI element update.
UpdateLayout()
Manually update layout. Should not be necessary in most cases, but is provided for completeness.

Public Events

DefocusedHandle being defocused.
DragBeginReact to mouse drag begin.
DragCancelReact to a mouse drag cancel event (ie, when an extra button is pressed).
DragDropFinishReact to drag and drop finish. Return true to signal that the drop was accepted.
DragDropTestReact to drag and drop test. Return true to signal that the drop is acceptable.
DragEndReact to mouse drag end.
DragMoveReact to mouse drag motion.
ElementAddedA child element has been added to an element. Sent by the UI root element, or element-event-sender if set.
ElementRemovedA child element is about to be removed from an element. Sent by the UI root element, or element-event-sender if set.
FocusedHandle being focused.
HoverBeginHovering on an UI element has started
HoverEndHovering on an UI element has ended
LayoutUpdatedUI element layout updated.
NameChangedUI element name changed.
PositionedReact to position change.
ResizedReact to resize.
VisibleChangedReact to visibility change.