Docs UI
This page parovides information on UI, the definitions and usage examples. (Introduced in: v0.2.0)
UI in IceShard was inspired by XAML and designed around a data-oriented appoach. This makes the API large, but separated into three distinct representations.
- User Definition - User "readable" content like a XML document or node graph.
- Binary Definition - Compiled binary versions that follows specific rules how values are saved represented.
- Runtime - Runtime objects using the binary description.
Because of this separation various definitions of UI may exist, as the raw form is never used or expected by the runtime.
Currently we only support support XAML-like documents with simple elements.
A single binary UI object represents a single page. Where a page is a container with runtime provided size that is cappable of hosting other elements inside.
NOTE: A feature to host pages inside other elements is planned.
Pages also provide information about used: styles, shards, resources, fonts and constants.
Styles define how the final UI looks. It allows to provide either colors or textures (at a later point) and define where and when to apply them. This allows to have styles for specific elements and also their states.
The default style, always provided, disables elements from rendering, so at least a single style needs to be provided by the user.
Shards are the main interaction interface defined in a UI and the engine runtime. Before the UI can send events to a frame for interaction, it needs to define the shards it want's to use.
This allows the runtime to easily prepare for interaction events and limit the amount of required searches when reacting to events in the UI itself.
Resources provide information about required runtime data and it's locations. Each resource has a type and ID, and some resource types may also provide additonal data required to properly initialize it. (ex.: A texture resource may provide the asset it want's to be loaded.)
Represent a specific font with additional attached information like: size, italics*, strength*.
* Italics and strength are not yet available.
Values that are part of the binary and need to be retrived using the type, offset and size. The values stored are directly accessed by the runtimes, and have little interaction value.
The .isui files represent a single UI page in a XML document. The syntax resembles a bit XAML, but all the elements and values are specific to this engine. A XAML document is not a valid ISUI document, and vice-versa.
The document strictly follows presentation of the binary form, with few exceptions.
The XML document is using namespaces to distinguish pure UI elements like style or page from strictly engine specific concepts like shards.
Definition: ISUI structure
<isui
xmlns:ui="https://www.iceshard.net/docs/engine/v1_alpha/isui/ui/"
xmlns:ice="https://www.iceshard.net/docs/engine/v1_alpha/isui/iceshard/">
<ice:shards />
<ui:styles />
<ui:resources />
<ui:page />
</isui>A style is defined using the <ui:style> element inside the <ui:styles> element. Multiple styles can be defined with the requirement of unique targets and states, or unique name="" attribute. (No direct check is made at runtime and behavior is undefined.)
Currently styles cannot be inherited, and do not allow to match more than one element type.
A <ui:style> element can have three attributes set:
-
name- The name of the style, which we can the use to apply directly to specific elements. -
target- The target element type, to which the style should be applied. (for example: button) -
state- The state of the target element type.- The only elements this works for are buttons.
- The only state available is
hoover
Each style can contain a <backgroud> element which accepts values in the color and alpha attributes. Both colors and alpha values are defined using float values between 0.0 and 1.0. Color accepts either a single value or three separate values representig red, green and blue.
Example: Style definitions
<ui:styles>
<ui:style name="style_button_default" target="button">
<background color="0.4" alpha="1.0" />
</ui:style>
<ui:style name="style_button_hoover" target="button" state="hoover">
<background color="0.6" alpha="1.0" />
</ui:style>
</ui:styles>A resource is defined using the <ui:resource> element inside the <ui:resources> element. Multiple resource elements can be defined, with the single requirement of a unique name attribute.
Additionally, three types of resources are defined: text, string[N] and font. Where font types also accept size and font attributes.
The types text and string[N] expect values of type ice::Utf8String, with the distinction that string elements provide space for up to N bytes inside the runtime representation. text elements only point to the given string.
Example: Resource definitions
<ui:resources>
<ui:resource type="font" name="default" size="15" font="calibri" />
<ui:resource type="text" name="runtime_text" />
<ui:resource type="string[32]" name="runtime_string" />
</ui:resources>A page defines the actual layout and UI elements it wants to show and render. Because of the sheer amount of them (at least soon'ish) This section is will only contain an example, but proper documentation is on the way!
Example: Page definition
<ui:page>
<ui:layout size="auto" position="auto,20%" padding="2" margin="auto,0" direction="vertical" style="style_light">
<ui:layout size="300,auto" position="0" direction="vertical" style="style_dark">
<ui:label size="*,auto" padding="6" margin="0,0,0,10" text="Menu" style="style_header" />
<ui:button size="*,auto" padding="6" margin="0,5" text="{Resource text_start}" />
<ui:button size="*,auto" padding="6" margin="0,5" text="{Resource text_settings}" />
<ui:button size="*,auto" padding="6" margin="0,5" text="{Resource text_credits}" />
<ui:button size="*,auto" padding="6" margin="0,5,0,0" text="{Resource text_exit}" on_click="{Shard game_exit}" />
</ui:layout>
</ui:layout>
</ui:page>