UIX

This article or section is a Stub. You can help the Resonite Wiki by expanding it.

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.

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.

Concepts

Canvases

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

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.

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 referenceing that original slot, components, or fields, you will need to re-reference them using the new duplicated slot.

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.

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.

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.

Recipes

Empty canvas

1. Using the Developer Tool, Create New > Empty Object.
2. In that object, Attach Component > UIX > Canvas.
3. Change the Scale of the object to 0.001 on all axes to get the object to be a more reasonable size.
4. You can then change the Canvas's Size x and y (in pixels) to your liking.
5. Next, on the same empty object, Attach Component > UIX > Graphics > Image. You can change the image's Tint to change the base color of the canvas.
6. Again using the Developer Tool, Create New > Materials > UI > UI Unlit.
7. Change the material's ZWrite property to On, and the OffsetFactor and OffsetUnits properties to 1.
8. 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.
9. You may also want to make the canvas grabbable (Attach Component > Transform > Interaction > Grabbable).

You can now add children to be displayed on the canvas.

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

1. Add a child to your canvas (or layout or whatever) and call it Button.
2. In that object, Attach Component > UIX > Graphics > Image. You can change the image's Tint to change the base color of the button.
3. 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%).
4. Attach Component > UIX > Interaction > Button. Based on the image's Tint, the button will automatically fill out the colors for its normal, highlight, press, and disabled states.
5. You may add text to the button:
   1. Create a child object of the button and call it Text.
   2. On that child, Attach Component > UIX > Graphics > Text.
   3. Change the text to what you want.
   4. Alter the font size, set up autosize, change the alignment to what you want.
6. You can hook the button up to ProtoFlux by creating a Button Events node, grabbing a reference to the Button component from the inspector, and dropping it into the reference field on the Button Events node.

You can also put an icon on a button.

1. On the Button object, Attach Component > Assets > SpriteProvider.
2. Drop your chosen image into the Texture property of the SpriteProvider.
3. Grab the SpriteProvider and drop it into the Sprite property of the Button's Image.
4. Use the Tint property on the Image to color the icon.
5. You can parent the Button to another object with an Image to set the background.

ProbablePrime's public folder, under UI Stuff > Icons > Shapes, has many icons for your use.

Scrollable text

1. Add a child to your canvas (or layout or whatever) and call it Mask.
2. In that object, Attach Component > UIX > Mask. This effectively makes any graphical elements from children that wander outside the RectTransform invisible.
3. In the same object, Attach Component > UIX > Graphics > Image.
4. Turn on the Mask's ShowMaskGraphic property.
5. Add a child to the Mask object and call it ScrollRect.
6. In that object, Attach Component > UIX > Interaction > ScrollRect.
7. In the same object, Attach Component > UIX > Layout > ContentSizeFitter.
8. Set the ContentSizeFitter's VerticalFit property to MinSize.
9. In the same object, Attach Component > UIX > Layout > VerticalLayout.
10. Add a child to the ScrollRect object and call it Content.
11. In that object, Attach Component > UIX > Graphics > Text.
12. 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.
13. Alter the font size, set up autosize, change the alignment to what you want.
14. Change the font color to something that will show up against the mask image color!

A simple vertical layout

1. Add a child to your canvas (or layout or whatever) and call it Layout.
2. In that object, Attach Component > UIX > Graphics > Image. Set the Tint to something that will differentiate this object from child objects.
3. Also in that object, Attach Component > UIX > Layout > VerticalLayout.
4. Change all the Padding and the Spacing properties on the VerticalLayout to 4.
5. Add a child of Layout, and call it Element.
6. In that object, Attach Component > UIX > Graphics > Image. Set the Tint to something that will differentiate this object from the layout object.
7. Duplicate this object a few times. They will all be children of Layout.
8. You may need to heed the warning above, and duplicate the canvas to get the layout to recalculate.
9. You can add LayoutElement to each Element. This tells the parent layout how to calculate widths and heights.