UIX: Difference between revisions

From Resonite Wiki
VisualWikitext
Zandario (talk | contribs)
209 edits
mNo edit summary
 
Another way to recalculate and redraw layouts.
 
(12 intermediate revisions by 2 users not shown)
Line 1: Line 1:
{{stub}}
[[File:UIX Canvas Sample.png|alt=The UIX Canvas Sample|thumb|The UIX Canvas Sample]]
 
<!--T:1-->
<!--T:1-->
UIX is Resonite's UI system. It allows you to create two-dimensional user interfaces, and is conceptually similar to the [https://docs.unity3d.com/Manual/com.unity.ugui.html Unity UI] system. It underpins the Dash Menu and Scene Inspector.
== Introduction ==
'''UIX''' is [[Resonite|Resonite's]] UI system. It allows you to create two-dimensional user interfaces, and is conceptually similar to the [https://docs.unity3d.com/Manual/com.unity.ugui.html Unity UI] system. It underpins the [[Dash Menu]] and [[Scene Inspector]].
 
There is a dedicated [[:Category:Components:UIX|UIX Category]] for building UIX and its elements and components.


<!--T:2-->
<!--T:2-->
A useful UIX demo, ''UIX Canvas'', can be spawned with the [[Developer Tool]], found under the Objects category. It provides examples of layouts, images, buttons, and sliders.
=== Demos & Starting Points ===
A useful UIX demo, ''UIX Canvas Blank'' or ''UIX Canvas Sample'', can be spawned with the [[Developer Tool]], found under the Objects category. It provides examples of layouts, images, buttons, and sliders.
 
Another useful starting point is using the panel in the UI Presets folder provided in the Resonite Essentials folder. Double click the panel item to spawn it, then edit it from there.
 
There is a [[UIX Tutorial]] to put together UIX easily.
 
=== Facets ===
 
UIX helps with making [[Facets]], customizable [[Dash]] add-ons that give the user more functionality in userspace.


= Concepts = <!--T:3-->
== Concepts == <!--T:3-->


== Canvases == <!--T:4-->
=== Canvases === <!--T:4-->


<!--T:5-->
<!--T:5-->
A UI requires a [[Canvas (Component)|Canvas]] at its root. The Canvas defines the size of the UI.
A UI requires a [[Canvas (Component)|Canvas]] at its root. The Canvas defines the size of the UI.


== RectTransforms == <!--T:6-->
The components that utilizes the canvas concept:
{| class="wikitable mw-collapsible"
|+
! Components !! Description
|-
| '''[[Component:Canvas|Canvas]]''' || The root UIX for all your elements.
|-
| '''[[Component:NestedCanvas|Nested Canvas]]''' || A secondary root for UIX elements, this is mainly used to be consistent with the main canvas.
|-
|}
 
=== RectTransforms === <!--T:6-->


<!--T:7-->
<!--T:7-->
Every slot involved in a UI must have a [[RectTransform (Component)|RectTransform]] on it. RectTransforms are automatically added when you attach other UI components. The RectTransform determines the boundaries of that UI element, expressed as a fraction of the total space available -- so a default RectTransform has anchors at 0,0 and 1,1.
Every slot involved in a UI must have a [[RectTransform (Component)|RectTransform]] on it. RectTransforms are automatically added when you attach other UI components. The RectTransform determines the boundaries of that UI element, expressed as a fraction of the total space available -- so a default RectTransform has anchors at 0,0 and 1,1.


== Layouts == <!--T:8-->
The components that utilizes the RectTransforms concept:
{| class="wikitable mw-collapsible"
|+
! Components !! Description
|-
| '''[[Component:RectTransform |RectTransform ]]''' || The container designed to hold your UIX elements like buttons, fields, sliders, etc.
|-
| '''[[Component:RectTransformComputedProperties|RectTransformComputedProperties]]''' || A component that can return the size of the rect transform and all its contents.
|-
|}
 
=== Layouts === <!--T:8-->


<!--T:9-->
<!--T:9-->
Whilst you can manually position elements by adjusting their RectTransforms, you often want this to be handled automatically. A layout overrides the RectTransforms of its slot's children. For example, the HorizontalLayout will try to position its children in a horizontal line.
Whilst you can manually position elements by adjusting their RectTransforms, you often want this to be handled automatically. A layout overrides the RectTransforms of its slot's children. For example, the [[Component:HorizontalLayout|Horizontal Layout]] component will try to position its children in a horizontal line.


<!--T:14-->
<!--T:14-->
'''WARNING''': Layouts calculate the positions and sizes of their children based on the children themselves. If you modify or add or delete a child and don't get the expected result, you may need to force recalculation. The only way to do this currently is to duplicate your entire object (or maybe just the layout?) and delete the original.
{{Note|'''WARNING''': Layouts calculate the positions and sizes of their children based on the children themselves. If you modify or add or delete a child and don't get the expected result, you may need to force recalculation. The only way to do this currently is to duplicate your entire object or just that slot holding the layout and delete the original. If there was [[ProtoFlux]] referencing that original slot, components, or fields, you will need to re-reference them using the new duplicated slot.
 
Sometimes, for certain UIX breakages, you can do the following:
* You can disable and enable the [[Component:Canvas|Canvas]] to get UIX working again.
* You can disable and enable the layout's <code>ForceExpandWidth</code> and/or <code>ForceExpandHeight</code> to get UIX working again.
|warning}}


<!--T:15-->
<!--T:15-->
Since layouts depend on the order of their children, and you can't drag children around in the inspector, you must specify a child's OrderOffset property. Normally these are 0, but if you change it, the children will be ordered by increasing OrderOffset, with children of equal OrderOffset being ordered by some effectively random process.
Since layouts depend on the order of their children, and you can't drag children around in the inspector, you must specify a child's OrderOffset property. Normally these are 0, but if you change it, the children will be ordered by increasing OrderOffset, with children of equal OrderOffset being ordered by time of creation of that slot.


<!--T:16-->
<!--T:16-->
Again, if you change the OrderOffset of a child, your layout will have to be recalculated, which may run into the above warning.
Again, if you change the OrderOffset of a child, your layout will have to be recalculated, which may run into the above warning.


== Graphics == <!--T:10-->
The components that utilizes the layout concept:
{| class="wikitable mw-collapsible"
|+
! Components !! Description
|-
| '''[[Component:ArcLayout|ArcLayout]]''' & '''[[Component:ArcSegmentLayout|ArcSegmentLayout]]''' || Creates a layout that arcs around the center, making circular menus.
|-
| '''[[Component:GridLayout|GridLayout]]''' || A layout that forms a grid of sized areas, with rows and columns.
|-
| '''[[Component:HorizontalLayout|HorizontalLayout]]''' || A layout that lines up elements in a horizontal way.
|-
| '''[[Component:IgnoreLayout|IgnoreLayout]]''' || Ignores the above layout in the hierarchy.
|-
| '''[[Component:LayoutElement|LayoutElement]]''' || Controls how this layout should be shaped, controlled and placed.
|-
| '''[[Component:OverlappingLayout|OverlappingLayout]]''' || A layout overlaps or places on top of another layout in the same space.
|-
| '''[[Component:VerticalLayout|VerticalLayout]]''' || A layout that lines up elements in a vertical way.
|-
|}
 
=== Graphics === <!--T:10-->


<!--T:11-->
<!--T:11-->
To actually display things, your UI needs one or more Graphics components. [[Image (Component)|Image]] will fill the element, optionally taking a material (to define its appearance) and sprite (to define its shape). Other elements include [[Text (Component)|Text]], to display text, and [[Mask (Component)|Mask]], to hide parts of child UI elements.
To actually display things, your UI needs one or more Graphics components. [[Image (Component)|Image]] will fill the element, optionally taking a [[Material|material]] (to define its appearance) and [[Component:SpriteProvider|sprite]] (to define its shape). Other elements include [[Text (Component)|Text]], to display text, and [[Mask (Component)|Mask]], to hide parts of child UI elements.


== Interaction == <!--T:12-->
The components that utilizes the layout concept:
{| class="wikitable mw-collapsible"
|+
! Components !! Description
|-
| '''[[Component:Image|Image]]''' || Creates an image component for this graphic UIX element.
|-
| '''[[Component:Mask|Mask]]''' || Creates a mask for this graphic UIX element. Taking a child slot element and making it the focus, and masking the rest out.
|-
| '''[[Component:Text|Text]]''' || Creates a text graphic UIX element, using a string of text as the element.
|-
|}
 
=== Interaction === <!--T:12-->


<!--T:13-->
<!--T:13-->
Interaction components allow for input. [[Button (Component)|Button]] will respond visibly to hovering and pressing, and will trigger other components on the slot (as well as on child slots). [[Slider (Component)|Slider]] works similarly, but can also control a child element's RectTransform to move it around.
Interaction components allow for input. [[Button (Component)|Button]] will respond visibly to hovering and pressing, and will trigger other components on the slot (as well as on child slots). [[Slider`1 (Component)|Slider]] works similarly, but can also control a child element's RectTransform to move it around.
 
= Recipes = <!--T:17-->
 
== Empty canvas == <!--T:18-->
 
<!--T:19-->
# Using the [[Developer Tool]], Create New > Empty Object.
# In that object, Attach Component > UIX > [[Canvas]].
# Change the Scale of the object to 0.001 on all axes to get the object to be a more reasonable size.
# You can then change the Canvas's Size x and y (in pixels) to your liking.
# Next, on the same empty object, Attach Component > UIX > Graphics > [[Image (Component)|Image]]. You can change the image's Tint to change the base color of the canvas.
# Again using the [[Developer Tool]], Create New > Materials > UI > UI Unlit.
# Change the material's ZWrite property to On, and the OffsetFactor and OffsetUnits properties to 1.
# Grab the material ball and click on your empty object's Image Material slot to load it in. This fixes the "bleed-through" effect which would cause different UIX objects to bleed through each other if placed on top of each other.
# You may also want to make the canvas grabbable (Attach Component > Transform > Interaction > [[Grabbable (Component)|Grabbable]]).
 
<!--T:20-->
You can now add children to be displayed on the canvas.
 
<!--T:21-->
[[User:ProbablePrime|ProbablePrime]]'s public folder, under Tutorials > UIX, contains a CanvasTemplate which has already done all the above steps for you. Simply spawn one out and start from there.
 
== A button == <!--T:22-->
 
<!--T:23-->
# Add a child to your canvas (or layout or whatever) and call it Button.
# In that object, Attach Component > UIX > Graphics > [[Image (Component)|Image]]. You can change the image's Tint to change the base color of the button.
# Change the RectTransform's AnchorMin/Max to add a border around the button. This effectively tells the parent where the child is and how to scale it.
#* AnchorMin (x,y) is the lower left corner of a rectangle on the parent canvas that the child should be fit into, ranging from 0 to 1. (0,0) is the lower left of the parent.
#* AnchorMax (x,y) is the upper right corner of a rectangle on the parent canvas that the child should be fit into, ranging from 0 to 1. (1,1) is the upper right of the parent.
#* Adding a small border of, say, 5% of the parent's size, means the AnchorMin should be (0.05,0.05) (i.e. 0,0 plus 5%) and AnchorMax should be (0.95,0.95) (i.e. 1,1 minus 5%).
# Attach Component > UIX > Interaction > [[Button (Component)|Button]]. Based on the image's Tint, the button will automatically fill out the colors for its normal, highlight, press, and disabled states.
# You may add text to the button:
## Create a child object of the button and call it Text.
## On that child, Attach Component > UIX > Graphics > [[Text (Component)|Text]].
## Change the text to what you want.
## Alter the font size, set up autosize, change the alignment to what you want.
# You can hook the button up to [[ProtoFlux]] by creating a [[Button Events (ProtoFlux Node)|Button Events]] node, dragging out the Button interface card, and hooking it up to the Button Events node.
 
<!--T:24-->
You can also put an icon on a button.


<!--T:25-->
The components that utilizes the layout concept:
# On the Button object, Attach Component > Assets > [[SpriteProvider (Component)|SpriteProvider]].
{| class="wikitable mw-collapsible"
# Drop your chosen image into the Texture property of the SpriteProvider.
|+
# Grab the SpriteProvider and drop it into the Sprite property of the Button's Image.
! Components !! Description
# Use the Tint property on the Image to color the icon.
|-
# You can parent the Button to another object with an Image to set the background.
| '''[[Component:Button|Button]]''' || Creates a button component element, which will allow a user to press a button to make something happen.
|-
| '''[[Component:Checkbox|Checkbox]]''' || Creates a Checkbox component element, which will allow a user to press a toggle button to make something happen based on a state.
|-
| '''[[Component:Slider|Slider]]''' || Creates a Slider that can allow the user to slide the handle, changing the value.
|-
| '''[[Component:TextField|TextField]]''' || Creates a TextField that can allow the user to enter text within it.
|-
| '''[[Component:ReferenceRadio|ReferenceRadio]]''' & '''[[Component:ValueRadio|ValueRadio]]''' || Creates a radio component value holder.
|-
|}


<!--T:26-->
=== Utility ===
[[User:ProbablePrime|ProbablePrime]]'s public folder, under UI Stuff > Icons > Shapes, has many icons for your use.


== Scrollable text == <!--T:27-->
Utilities for UIX are for helper components that can help make UIX either work or do something specific, such as controlling slides and panners, as well as getting rect drivers.


<!--T:28-->
The components that utilizes the utility concept:
# Add a child to your canvas (or layout or whatever) and call it Mask.
{| class="wikitable mw-collapsible"
# In that object, Attach Component > UIX > [[Mask (Component)|Mask]]. This effectively makes any graphical elements from children that wander outside the RectTransform invisible.
|+
# In the same object, Attach Component > UIX > Graphics > [[Image (Component)|Image]].
! Components !! Description
# Turn on the Mask's ShowMaskGraphic property.
|-
# Add a child to the Mask object and call it ScrollRect.
| '''[[Component:AxisMultiViewportPanner|AxisMultiViewportPanner]]''' || This makes a panner with diferent elements on a UIX canvas, panel, or element.
# In that object, Attach Component > UIX > Interaction > [[ScrollRect (Component)|ScrollRect]].
|-
# In the same object, Attach Component > UIX > Layout > [[ContentSizeFitter (Component)|ContentSizeFitter]].
|}
# Set the ContentSizeFitter's VerticalFit property to MinSize.
# In the same object, Attach Component > UIX > Layout > [[VerticalLayout (Component)|VerticalLayout]].
# Add a child to the ScrollRect object and call it Content.
# In that object, Attach Component > UIX > Graphics > [[Text (Component)|Text]].
# Change the text to what you want. Typically for long text that you get from a file, you would import a text file from your computer, inspect the result, navigate to the text component (object > ScrollRect > Content), and grab and drag the Text component's Content property into your object's Text Content.
# Alter the font size, set up autosize, change the alignment to what you want.
# Change the font color to something that will show up against the mask image color!


== A simple vertical layout == <!--T:29-->
== ProtoFlux Notes ==


<!--T:30-->
There is not many [[ProtoFlux]] nodes that can interact with UIX, but here is a list of nodes and what you can do with them:
# Add a child to your canvas (or layout or whatever) and call it Layout.
* For interacting with [[Component:Button|Buttons]] on a UIX, using the node [[ProtoFlux:Button Events|Button Events]] can refer to the button being pressed and fire events from that button.
# In that object, Attach Component > UIX > Graphics > [[Image (Component)|Image]]. Set the Tint to something that will differentiate this object from child objects.
* For interacting with [[Component:TextField|TextField]] components and listening for a user's actions when they input text, using the nodes in the [[:Category:ProtoFlux:Interaction:UI|UI Category]] may help with this.
# Also in that object, Attach Component > UIX > Layout > [[VerticalLayout (Component)|VerticalLayout]].
# Change all the Padding and the Spacing properties on the VerticalLayout to 4.
# Add a child of Layout, and call it Element.
# In that object, Attach Component > UIX > Graphics > [[Image (Component)|Image]]. Set the Tint to something that will differentiate this object from the layout object.
# Duplicate this object a few times. They will all be children of Layout.
# You may need to heed the warning above, and duplicate the canvas to get the layout to recalculate.
# You can add [[LayoutElement (Component)|LayoutElement]] to each Element. This tells the parent layout how to calculate widths and heights.


= Tutorials = <!--T:31-->
[[Category:Information Hub]]

Latest revision as of 23:48, 28 July 2024

The UIX Canvas Sample
The UIX Canvas Sample

Introduction

UIX is Resonite's UI system. It allows you to create two-dimensional user interfaces, and is conceptually similar to the Unity UI system. It underpins the Dash Menu and Scene Inspector.

There is a dedicated UIX Category for building UIX and its elements and components.

Demos & Starting Points

A useful UIX demo, UIX Canvas Blank or UIX Canvas Sample, can be spawned with the Developer Tool, found under the Objects category. It provides examples of layouts, images, buttons, and sliders.

Another useful starting point is using the panel in the UI Presets folder provided in the Resonite Essentials folder. Double click the panel item to spawn it, then edit it from there.

There is a UIX Tutorial to put together UIX easily.

Facets

UIX helps with making Facets, customizable Dash add-ons that give the user more functionality in userspace.

Concepts

Canvases

A UI requires a Canvas at its root. The Canvas defines the size of the UI.

The components that utilizes the canvas concept:

Components Description
Canvas The root UIX for all your elements.
Nested Canvas A secondary root for UIX elements, this is mainly used to be consistent with the main canvas.

RectTransforms

Every slot involved in a UI must have a RectTransform on it. RectTransforms are automatically added when you attach other UI components. The RectTransform determines the boundaries of that UI element, expressed as a fraction of the total space available -- so a default RectTransform has anchors at 0,0 and 1,1.

The components that utilizes the RectTransforms concept:

Components Description
RectTransform The container designed to hold your UIX elements like buttons, fields, sliders, etc.
RectTransformComputedProperties A component that can return the size of the rect transform and all its contents.

Layouts

Whilst you can manually position elements by adjusting their RectTransforms, you often want this to be handled automatically. A layout overrides the RectTransforms of its slot's children. For example, the Horizontal Layout component will try to position its children in a horizontal line.

WARNING: Layouts calculate the positions and sizes of their children based on the children themselves. If you modify or add or delete a child and don't get the expected result, you may need to force recalculation. The only way to do this currently is to duplicate your entire object or just that slot holding the layout and delete the original. If there was ProtoFlux referencing that original slot, components, or fields, you will need to re-reference them using the new duplicated slot.

Sometimes, for certain UIX breakages, you can do the following:

  • You can disable and enable the Canvas to get UIX working again.
  • You can disable and enable the layout's ForceExpandWidth and/or ForceExpandHeight to get UIX working again.

Since layouts depend on the order of their children, and you can't drag children around in the inspector, you must specify a child's OrderOffset property. Normally these are 0, but if you change it, the children will be ordered by increasing OrderOffset, with children of equal OrderOffset being ordered by time of creation of that slot.

Again, if you change the OrderOffset of a child, your layout will have to be recalculated, which may run into the above warning.

The components that utilizes the layout concept:

Components Description
ArcLayout & ArcSegmentLayout Creates a layout that arcs around the center, making circular menus.
GridLayout A layout that forms a grid of sized areas, with rows and columns.
HorizontalLayout A layout that lines up elements in a horizontal way.
IgnoreLayout Ignores the above layout in the hierarchy.
LayoutElement Controls how this layout should be shaped, controlled and placed.
OverlappingLayout A layout overlaps or places on top of another layout in the same space.
VerticalLayout A layout that lines up elements in a vertical way.

Graphics

To actually display things, your UI needs one or more Graphics components. Image will fill the element, optionally taking a material (to define its appearance) and sprite (to define its shape). Other elements include Text, to display text, and Mask, to hide parts of child UI elements.

The components that utilizes the layout concept:

Components Description
Image Creates an image component for this graphic UIX element.
Mask Creates a mask for this graphic UIX element. Taking a child slot element and making it the focus, and masking the rest out.
Text Creates a text graphic UIX element, using a string of text as the element.

Interaction

Interaction components allow for input. Button will respond visibly to hovering and pressing, and will trigger other components on the slot (as well as on child slots). Slider works similarly, but can also control a child element's RectTransform to move it around.

The components that utilizes the layout concept:

Components Description
Button Creates a button component element, which will allow a user to press a button to make something happen.
Checkbox Creates a Checkbox component element, which will allow a user to press a toggle button to make something happen based on a state.
Slider Creates a Slider that can allow the user to slide the handle, changing the value.
TextField Creates a TextField that can allow the user to enter text within it.
ReferenceRadio & ValueRadio Creates a radio component value holder.

Utility

Utilities for UIX are for helper components that can help make UIX either work or do something specific, such as controlling slides and panners, as well as getting rect drivers.

The components that utilizes the utility concept:

Components Description
AxisMultiViewportPanner This makes a panner with diferent elements on a UIX canvas, panel, or element.

ProtoFlux Notes

There is not many ProtoFlux nodes that can interact with UIX, but here is a list of nodes and what you can do with them:

  • For interacting with Buttons on a UIX, using the node Button Events can refer to the button being pressed and fire events from that button.
  • For interacting with TextField components and listening for a user's actions when they input text, using the nodes in the UI Category may help with this.
Retrieved from "https://wiki.resonite.com/index.php?title=UIX&oldid=88821"