Property System

The RUI library utilizes its own property system. Its purpose is to managing and facilitating of setting and getting attributes and events of UI controls. Attributes and events combined constitute what is referred to as properties. Every UI control offers various properties to manage its appearance and to capture user interactions.

Each property has a name that is defined by the PropertyName type:

type PropertyName string

Properties hold the values of the any type. Library still has constraints which allow assigning the values of a particular types to a specific property. The Reference documentation has the description of each property of the UI controls and outline the values of which types can be assigned to them. The values of the properties can have a text representation which allows us to use them in RUI description files when describing user interfaces:

RUI

ListLayout {
    width = 100%, // Property "width", "100%" is a text representation of the SizeUnit type
    content = [ // Property "content", has an array of child views description
        ImageView {
            src = "search.png", // Property "src", "search.png" is a text which represents the path to a resource
        },
        EditView {
            hint = "Enter name or description", // Property "hint", "Enter name or description" is the hint text
            shadow = [ // Property "shadow", contains an array of objects which are a text representation of the ShadowProperty type
                _{  
                    blur = 0.1em, // Property "blur", "0.1em" is a text representation of the SizeUnit type
                    color = red, // Property "color", "red" is an internal constant name for the color #ffff0000
                    spread-radius = 0.1em, // Property "spread-radius", "0.1em" is a text representation of the SizeUnit type
                },
            ],
        },
    ],
}

In the source code each property has a corresponding string constant which reflect it's name. So to refer "width" property we have to use rui.Width constant, rui.SpreadRadius for "spread-radius" property, rui.ColorTag for "color" property, and so on. We can find the information about which constant to use in description of the property.

When specifying properties of the UI control during its creation from the source code, the Params type is used, which is a map of the properties containing values of arbitrary types:

Go

type Params map[PropertyName]any

The value of that type is usually passed to a constructor function of a particular UI control:

Go

view := rui.NewListLayout(session, rui.Params{     // Constructor function of the ListLayout control
    rui.Width: rui.Percent(100),                   // Property "width" set to 100% using SizeUnit type
    rui.Content: []rui.View {                      // Property "content" set to an array of child UI controls
        rui.NewImageView(session, rui.Params{      // Constructor function of the ImageView control
            rui.Source: "search.png",              // Property "src" set to an image path from resources
        }),
        rui.NewEditView(session, rui.Params{       // Constructor function of the EditView control
            rui.Hint: "Enter name or description", // Property "hint" set to a string
            rui.Shadow: []rui.ShadowProperty{      // Property "shadow" set to an array of ShadowProperty values
                rui.NewShadow(
                    rui.Px(0),                     // X offset
                    rui.Px(0),                     // Y offset
                    rui.Em(0.1),                   // Blur radius
                    rui.Em(0.1),                   // Spread radius
                    rui.Red                        // Shadow color
                ),
            },
        }),
    },
})

Besides the creation of UI controls, the Params type is also used while creating the value of some properties. For example, the value of the "radius" property is created using the NewRadiusProperty() function with the help of the Params type:

Go

view := rui.NewEditView(session, rui.Params{
    rui.Hint: "User name",
    rui.Radius: rui.NewRadiusProperty(rui.Params{
        rui.TopLeft:     rui.Em(0.5),
        rui.TopRight:    rui.Em(0.5),
        rui.BottomRight: rui.Em(0.5),
        rui.BottomLeft:  rui.Em(0.5),
    }),
})

To understand what properties can be set in the params map, we should refer to the Reference documentation or our tutorials for a specific property that outlines the appearance of the UI controls.

Before applying properties listed in params map or in resource description file, library will sort them alphabetically. This approach allows us to apply the most generic properties first and then refine their values, for example:

RUI

EditView {
    hint = "User name",
    radius-bottom-left = 0.1em,
    radius-top-right = 0.1em,
    radius = 0.5em,
},

The final sequence of applying the properties to EditView will be as follows:

radius = 0.5em,
radius-bottom-left = 0.1em,
radius-top-right = 0.1em,

Setting properties during creation of UI controls is not only the choice. Each control implements the Properties interface which allows for advanced manipulation of the properties:

Go

type Properties interface {
    Get(tag PropertyName) any
    Set(tag PropertyName, value any) bool
    Remove(tag PropertyName)
    Clear()
    AllTags() []PropertyName
}

The tag parameter in Get(), Set(), and Remove() methods is the property name, remember that the library provides constants for all property names. We can perform operations listed above on any instance of the controls at any time we want. As an example, if during user interaction we want to reset the text entered in the EditView control, we can do this using the Set() method of its instance:

Go

// Variable to refer EditView
var nameEdit rui.EditView

// function to create a root view of the application
func (app *appSession) CreateRootView(session rui.Session) rui.View {
    nameEdit = rui.NewEditView(session, rui.Params{})

    // Create root view of the app from mainView.rui file
    rootView := rui.NewListLayout(session, rui.Params{
        rui.Padding:     rui.Em(1),
        rui.Orientation: rui.TopDownOrientation,
        rui.ListRowGap:  rui.Em(1),
        rui.Content: []rui.View{
            rui.NewTextView(session, rui.Params{
                rui.Text: "Name:",
            }),
            nameEdit, // set EditView as a child of the ListLayout
            rui.NewButton(session, rui.Params{
                rui.Content:    "Clear",
                rui.ClickEvent: clearClicked,
            }),
        },
    })

    return rootView
}

// Handler function for the "Clear" button click event
func clearClicked(view rui.View, event rui.MouseEvent) {
    if nameEdit != nil {
        if val := nameEdit.Get(rui.Text); val != nil {
            switch strVal := val.(type) {
            case string:
                if len(strVal) > 0 {
                    // Reset text of the EditView
                    if !nameEdit.Set(rui.Text, "") {
                        // If something went wrong
                    }
                }
            }
        }
    }
}

The Set() method returns feedback indicating whether the property value was successfully changed. If we attempt to set a non-existent property or provide a value of unsupported type, the method will return false. Property value passed to that function usually converted(if required) to an internal type of that property. Information about internal type and other supported types can be found in the Reference documentation for a particular property.

Many of the properties allow us to set a name of the constant which is described in theme file. In this case the property will hold a name of the constant and not a real value.

The Get() function returns the value of the property, or nil if the property was not set. We must be careful while working with this function. The type returned may not be what we actually expect. Since its return value has the any type, we must perform a type check and conversion. As an example, if the property contains the name of a constant that refers to a real value, then this function will return that constant's name and not the real value, it does not resolve constants!

The Remove() function removes property with its value, we can use Set(nil) which will do the same thing.

Examples

Go

// Setting property value
if view.Set(rui.Width, rui.Percent(100)) == true {
    // Property value set successfully
}

// Getting property value
if value := view.Get(rui.Width); value != nil {
    switch value.(type) {
        case string:
            text := value.(string)
            // Do something with the value

        case SizeUnit:
            size := value.(SizeUnit)
            // Do something with the value
    }
}

In most cases we didn't have the references for each UI control we've created. If we still need to operate on control's properties, we can explicitly set its "id" property and utilize the global Get() or Set() functions:

Go

func Get(rootView View, viewID, tag PropertyName) any
func Set(rootView View, viewID, tag PropertyName, value any) bool

These functions work mostly the same way as the methods of the Properties interface, except they require additional information. This additional information helps to find the real reference to the UI control on which we want to set or query the property value. The "rootView" is the starting point for the search, usually, it is a root view of our application but can be a reference to any UI control in the hierarchy. The "viewID" is the value of the "id" property of the desired UI control. We can pass an empty string as the "viewID," which means that we want to set or get the property value of the "rootView" control itself.

Example

Go

// Variable to refer root view of the application
var rootView rui.View

// EditView ID
const editViewId = "edit-view"

// Function to create a root view of the application
func (app *appSession) CreateRootView(session rui.Session) rui.View {
    rootView = rui.NewListLayout(session, rui.Params{
        rui.Padding:     rui.Em(1),
        rui.Orientation: rui.TopDownOrientation,
        rui.ListRowGap:  rui.Em(1),
        rui.Content: []rui.View{
            rui.NewTextView(session, rui.Params{
                rui.Text: "Name:",
            }),
            rui.NewEditView(session, rui.Params{
                rui.ID: editViewId,
            }),
            rui.NewButton(session, rui.Params{
                rui.Content:    "Clear",
                rui.ClickEvent: clearClicked,
            }),
        },
    })

    return rootView
}

// Handler function for the "Clear" button click event
func clearClicked(view rui.View, event rui.MouseEvent) {
    // Check if EditView has some text
    if value := rui.Get(rootView, editViewId, rui.Text); value != nil {
        switch text := value.(type) {
            case string:
                if len(text) > 0 {
                    // Reset text of the EditView
                    if !rui.Set(rootView, editViewId, rui.Text, "") {
                        // If something went wrong
                    }
                }
        }
    }
}

Getting a property value using the Get() function is not very convenient because it still requires a type conversion and doesn't resolve constants. Fortunately, the RUI library provides dedicated getter functions for each property, which return the property value using its internal type and resolve constants assigned to that property.

As an example, to get "width" property value we can use a global rui.GetWidth() function:

Go

func GetWidth(view View, subviewID ...string) SizeUnit

Examples

Getting "width" property value of the view which has an "id" property set to "login-button":

Go

if value := rui.GetWidth(rootView, "login-button"); value != nil {
    //Do something with the value
}

Examples for other view properties:

Go

if value := rui.IsDisabled(rootView, "login-button"); value != nil {
    //Do something with the value
}

if value := rui.GetTextColor(rootView, "login-button"); value != nil {
    //Do something with the value
}

if value := rui.GetVisibility(rootView, "login-button"); value != nil {
    //Do something with the value
}

// And so on

We can find all getter functions for view's properties in the library's Reference documentation, they are usually listed in Related global functions section of each UI control description.

© Alxanosoft inc.