Events Processing
Table of contents
Events processing is a crucial component of GUI applications as it allows for real-time interaction between the user and the application. It enables the program to respond to specific actions or inputs from the user, such as clicking on a button or moving the mouse cursor over an element. This makes the interface more responsive and intuitive, allowing users to interact with the software in a natural way.
In RUI library all events processing is done on the server side, which allows the developer to have a full control of the application and UI flow.
In this tutorial, we will add event processing to our previous project from the Creating User Interfaces tutorial. Our goal will be to enable the login button only when user name and password fields contain some text. We will also process login action by logging user credentials to the console. Regardless of whether you construct user interfaces from source code or resource files, all event handlers are set up from the application's source code. First, we will cover the case when our user interface is described in a resource file.
Here is how our "loginPage.rui" looks like:
RUI
// Root container
GridLayout {
// Occupy all window space
width = 100%,
height = 100%,
// Place content at the center
cell-vertical-align = center,
cell-horizontal-align = center,
// Use radial gradient as a background
background = radial-gradient {
center-x = 50%,
center-y = 50%,
radial-gradient-radius = 50%,
gradient = "lightgray 0%, black 100%",
},
// Container's content
content = [
// Layout content vertically
ListLayout {
orientation = up-down,
// Space between content items
gap = 1em,
// Container's content
content = [
// User name input field
EditView {
id = username,
hint = "User name",
radius = 1em,
padding = 0.3em,
border = _{
style = none,
},
},
// Password input field
EditView {
id = password,
hint = "Password",
radius = 1em,
// Input field used as a password entry
edit-view-type = password,
padding = 0.3em,
border = _{
style = none,
},
},
// Login button
ListLayout {
orientation = up-down,
horizontal-align = center,
content = Button {
id = login,
content = "Login",
radius = 1em,
disabled = true,
},
},
],
},
],
}
In resource file, we have set "id" properties for our user name, password field, and login button.
This allows us to quickly find and manipulate views properties from the source code.
Additionally, we have set the "disabled" property to true for the login button, so it will be initially un-clickable.
Our "main.go" source file of the application looks like this:
Go
// Import RUI library
import (
"github.com/anoshenko/rui"
)
// Address to listen on
const address = "localhost:8080"
type appSession struct {
}
func (app *appSession) CreateRootView(session rui.Session) rui.View {
// Create root view of the app from loginPage.rui file
view := rui.CreateViewFromResources(session, "loginPage")
return view
}
func createSession(session rui.Session) rui.SessionContent {
return new(appSession)
}
func main() {
// Include embedded resources folder with our "views/loginPage.rui" file
rui.AddEmbedResources(&resources)
// Initialize RUI library and wait for incoming connections
rui.StartApp(address, createSession, rui.AppParams{
Title: "Events example",
})
}
The CreateRootView() function creates the UI from the resource file.
To enable handling of the login action, we need to set login button's click event handler as a value for its "click-event" property.
Let's modify the implementation of the CreateRootView() function accordingly:
Go
func (app *appSession) CreateRootView(session rui.Session) rui.View {
// Create root view of the app from loginPage.rui file
view := rui.CreateViewFromResources(session, "loginPage")
// Setup click event handler
rui.Set(view, "login", rui.ClickEvent, app.loginClickedEvent)
return view
}
The Set() method of the RUI library will look for a button view with an "id" property set to "login".
It then assigns the app.loginClickedEvent() method to the "click-event" property (which is represented by the constant rui.ClickEvent) as a handler.
The "click-event" property is available in the View UI control, which serves as the base for all other UI controls.
Therefore, the Button control has all the properties that the View control has.
We can find the signature of the "click-event" handler in the View reference documentation.
Let's define this function as:
Go
func (app *appSession) loginClickedEvent(view rui.View, event rui.MouseEvent) {
// Sanity check
if rui.IsDisabled(view, "") {
return
}
rootView := view.Session().RootView()
usernameText := rui.GetText(rootView, "username")
passwordText := rui.GetText(rootView, "password")
log.Printf("Logging in as %s with password %s\n", usernameText, passwordText)
}
The app.loginClickedEvent() function gets called when the user presses the button (which can only happen if the button is enabled).
In this function, we first query the text of the username and password fields and then log that information to the console.
To handle changes in the user name and password fields' text, we need to set up handler functions for the "edit-text-changed" property.
Here's how updated CreateRootView() function will look like with these changes:
Go
func (app *appSession) CreateRootView(session rui.Session) rui.View {
// Create root view of the app from loginPage.rui file
view := rui.CreateViewFromResources(session, "loginPage")
// Setup click event handler
rui.Set(view, "login", rui.ClickEvent, app.loginClickedEvent)
// Setup of the text changed handlers
rui.Set(view, "username", rui.EditTextChangedEvent, app.usernameChangedEvent)
rui.Set(view, "password", rui.EditTextChangedEvent, app.passwordChangedEvent)
return view
}
For each edit field we use a Set() function which will look for a view by its ID and set its "edit-text-changed" property (which is represented by the constant rui.EditTextChangedEvent) to a desired values(methods) like app.usernameChangedEvent() and app.passwordChangedEvent() respectively.
The signature of the "edit-text-changed" handler can be found in the EditView reference documentation.
Let's define these methods now:
Go
func (app *appSession) usernameChangedEvent(editView rui.EditView, newText, oldText string) {
// Session root view
rootView := editView.Session().RootView()
// Password text
passwordText := rui.GetText(rootView, "password")
if len(passwordText) > 0 && len(newText) > 0 {
// Enable button when both fields are not empty
if rui.IsDisabled(rootView, "login") {
button := rui.ButtonByID(rootView, "login")
button.Set(rui.Disabled, false)
}
} else {
// Disable button when any of the fields is empty
if !rui.IsDisabled(rootView, "login") {
button := rui.ButtonByID(rootView, "login")
button.Set(rui.Disabled, true)
}
}
}
func (app *appSession) passwordChangedEvent(editView rui.EditView, newText, oldText string) {
// Session root view
rootView := editView.Session().RootView()
// User name text
usernameText := rui.GetText(rootView, "username")
if len(usernameText) > 0 && len(newText) > 0 {
// Enable button when both fields are not empty
if rui.IsDisabled(rootView, "login") {
button := rui.ButtonByID(rootView, "login")
button.Set(rui.Disabled, false)
}
} else {
// Disable button when any of the fields is empty
if !rui.IsDisabled(rootView, "login") {
button := rui.ButtonByID(rootView, "login")
button.Set(rui.Disabled, true)
}
}
}
These functions get called whenever either the username or password field's text is changed. We get the text for both user name and password fields and update the login button's disabled state to enable it only when both the user name and password fields are not empty.
The RUI library supports different signatures of event handlers for the same property (event).
We can use shorter ones and simplify our code by merging usernameChangedEvent() and passwordChangedEvent() methods:
Go
func (app *appSession) credentialsChangedEvent(edit rui.EditView) {
rootView := edit.Session().RootView()
name := rui.GetText(rootView, "username")
pwd := rui.GetText(rootView, "password")
if len(name) > 0 && len(pwd) > 0 {
if rui.IsDisabled(rootView, "login") {
rui.Set(rootView, "login", rui.Disabled, false)
}
} else {
if !rui.IsDisabled(rootView, "login") {
rui.Set(rootView, "login", rui.Disabled, true)
}
}
}
Update our CreateRootView() function to use that text changed handler for both user name and password fields:
Go
func (app *appSession) CreateRootView(session rui.Session) rui.View {
// Create root view of the app from loginPage.rui file
view := rui.CreateViewFromResources(session, "loginPage")
// Setup click event handler
rui.Set(view, "login", rui.ClickEvent, app.loginClickedEvent)
// Setup of the text changed handler
rui.Set(view, "username", rui.EditTextChangedEvent, app.credentialsChangedEvent)
rui.Set(view, "password", rui.EditTextChangedEvent, app.credentialsChangedEvent)
return view
}
Finally here is the full resulting source code of our "main.go" file:
Go
// Import RUI library
import (
"github.com/anoshenko/rui"
)
// Address to listen on
const address = "localhost:8080"
type appSession struct {
}
func (app *appSession) CreateRootView(session rui.Session) rui.View {
// Create root view of the app from loginPage.rui file
view := rui.CreateViewFromResources(session, "loginPage")
// Setup click event handler
rui.Set(view, "login", rui.ClickEvent, app.loginClickedEvent)
// Setup of the text changed handler
rui.Set(view, "username", rui.EditTextChangedEvent, app.credentialsChangedEvent)
rui.Set(view, "password", rui.EditTextChangedEvent, app.credentialsChangedEvent)
return view
}
func (app *appSession) loginClickedEvent(view rui.View, event rui.MouseEvent) {
// Sanity check
if rui.IsDisabled(view, "") {
return
}
rootView := view.Session().RootView()
usernameText := rui.GetText(rootView, "username")
passwordText := rui.GetText(rootView, "password")
log.Printf("Logging in as %s with password %s\n", usernameText, passwordText)
}
func (app *appSession) credentialsChangedEvent(edit rui.EditView) {
rootView := edit.Session().RootView()
name := rui.GetText(rootView, "username")
pwd := rui.GetText(rootView, "password")
if len(name) > 0 && len(pwd) > 0 {
if rui.IsDisabled(rootView, "login") {
rui.Set(rootView, "login", rui.Disabled, false)
}
} else {
if !rui.IsDisabled(rootView, "login") {
rui.Set(rootView, "login", rui.Disabled, true)
}
}
}
func createSession(session rui.Session) rui.SessionContent {
return new(appSession)
}
func main() {
// Include embedded resources folder with our "views/loginPage.rui" file
rui.AddEmbedResources(&resources)
// Initialize RUI library and wait for incoming connections
rui.StartApp(address, createSession, rui.AppParams{
Title: "Events example",
})
}
After building the application and launching it from our projects folder using:
$ go run .
command, open the page localhost:8080 and play with user name and password fields, you'll see that our login button gets enabled and disabled based on user credentials text changes.
When pressing on the button navigate to application's console output, you'll see the user credentials:
2024/10/07 12:36:56 Logging in as myname with password Mypassword
In this part of tutorial we've used application's UI which was described in the resource file, now lets figure out the case when all our UI was created directly from the source code.
Here is our initial "main.go" source file for this part:
Go
package main
// Import RUI library
import (
"github.com/anoshenko/rui"
)
// Address to listen on
const address = "localhost:8080"
type appSession struct {
}
func (app *appSession) CreateRootView(session rui.Session) rui.View {
// Create a root view
view := rui.NewGridLayout(session, rui.Params{
// Occupy all window space
rui.Width: rui.Percent(100),
rui.Height: rui.Percent(100),
// Place content at the center
rui.CellVerticalAlign: rui.CenterAlign,
rui.CellHorizontalAlign: rui.CenterAlign,
// Use radial gradient as a background
rui.Background: rui.NewBackgroundRadialGradient(rui.Params{
rui.CenterX: rui.Percent(50),
rui.CenterY: rui.Percent(50),
rui.RadialGradientRadius: rui.Percent(50),
rui.Gradient: []rui.GradientPoint{
{Offset: 0, Color: rui.LightGray},
{Offset: 1, Color: rui.Black},
},
}),
// Container's content
rui.Content: rui.NewListLayout(session, rui.Params{
// Layout content vertically
rui.Orientation: rui.TopDownOrientation,
// Space between content items
rui.Gap: rui.Em(1),
// Container's content
rui.Content: []rui.View{
// User name input field
rui.NewEditView(session, rui.Params{
rui.ID: "username",
rui.Hint: "User name",
rui.Radius: rui.Em(1),
rui.Padding: rui.Em(0.3),
rui.Border: rui.NewBorder(rui.Params{
rui.Style: rui.NoneLine,
}),
}),
// Password input field
rui.NewEditView(session, rui.Params{
rui.ID: "password",
rui.Hint: "Password",
rui.Radius: rui.Em(1),
rui.Padding: rui.Em(0.3),
rui.Border: rui.NewBorder(rui.Params{
rui.Style: rui.NoneLine,
}),
// Edit view used as a password entry
rui.EditViewType: rui.PasswordText,
}),
// Login button
rui.NewListLayout(session, rui.Params{
rui.Orientation: rui.TopDownOrientation,
rui.HorizontalAlign: rui.CenterAlign,
rui.Content: rui.NewButton(session, rui.Params{
rui.ID: "login",
rui.Content: "Login",
rui.Radius: rui.Em(1),
// Disabled by default
rui.Disabled: true,
}),
}),
},
}),
})
return view
}
func createSession(session rui.Session) rui.SessionContent {
return new(appSession)
}
func main() {
// Initialize RUI library and wait for incoming connections
rui.StartApp(address, createSession, rui.AppParams{
Title: "Events example",
})
}
Now let's add the setup of event handlers for "edit-text-changed" property of the user name and password edit views within the CreateRooView() function:
Go
...
// Set text changed event handler
rui.EditTextChangedEvent: app.credentialsChangedEvent,
...
Also set handler for login button:
Go
...
// Set click event handler
rui.ClickEvent: app.loginClickedEvent,
...
When we're done, let's add the implementation of credentialsChangedEvent() and loginClickedEvent() methods.
These methods are identical to what we had in our previous example, so we can simply copy and paste them without any modifications.
Our final "main.go" source file will look like this:
Go
package main
// Import RUI library
import (
"log"
"github.com/anoshenko/rui"
)
// Address to listen on
const address = "localhost:8080"
type appSession struct {
}
func (app *appSession) CreateRootView(session rui.Session) rui.View {
// Create a root view
view := rui.NewGridLayout(session, rui.Params{
// Occupy all window space
rui.Width: rui.Percent(100),
rui.Height: rui.Percent(100),
// Place content at the center
rui.CellVerticalAlign: rui.CenterAlign,
rui.CellHorizontalAlign: rui.CenterAlign,
// Use radial gradient as a background
rui.Background: rui.NewBackgroundRadialGradient(rui.Params{
rui.CenterX: rui.Percent(50),
rui.CenterY: rui.Percent(50),
rui.RadialGradientRadius: rui.Percent(50),
rui.Gradient: []rui.GradientPoint{
{Offset: 0, Color: rui.LightGray},
{Offset: 1, Color: rui.Black},
},
}),
// Container's content
rui.Content: rui.NewListLayout(session, rui.Params{
// Layout content vertically
rui.Orientation: rui.TopDownOrientation,
// Space between content items
rui.Gap: rui.Em(1),
// Container's content
rui.Content: []rui.View{
// User name input field
rui.NewEditView(session, rui.Params{
rui.ID: "username",
rui.Hint: "User name",
rui.Radius: rui.Em(1),
rui.Padding: rui.Em(0.3),
rui.Border: rui.NewBorder(rui.Params{
rui.Style: rui.NoneLine,
}),
// Set text changed event handler
rui.EditTextChangedEvent: app.credentialsChangedEvent,
}),
// Password input field
rui.NewEditView(session, rui.Params{
rui.ID: "password",
rui.Hint: "Password",
rui.Radius: rui.Em(1),
rui.Padding: rui.Em(0.3),
rui.Border: rui.NewBorder(rui.Params{
rui.Style: rui.NoneLine,
}),
// Edit view used as a password entry
rui.EditViewType: rui.PasswordText,
// Set text changed event handler
rui.EditTextChangedEvent: app.credentialsChangedEvent,
}),
// Login button
rui.NewListLayout(session, rui.Params{
rui.Orientation: rui.TopDownOrientation,
rui.HorizontalAlign: rui.CenterAlign,
rui.Content: rui.NewButton(session, rui.Params{
rui.ID: "login",
rui.Content: "Login",
rui.Radius: rui.Em(1),
// Disabled by default
rui.Disabled: true,
// Set click event handler
rui.ClickEvent: app.loginClickedEvent,
}),
}),
},
}),
})
return view
}
func (app *appSession) loginClickedEvent(view rui.View, event rui.MouseEvent) {
// Sanity check
if rui.IsDisabled(view, "") {
return
}
rootView := view.Session().RootView()
usernameText := rui.GetText(rootView, "username")
passwordText := rui.GetText(rootView, "password")
log.Printf("Logging in as %s with password %s\n", usernameText, passwordText)
}
func (app *appSession) credentialsChangedEvent(edit rui.EditView) {
rootView := edit.Session().RootView()
name := rui.GetText(rootView, "username")
pwd := rui.GetText(rootView, "password")
if len(name) > 0 && len(pwd) > 0 {
if rui.IsDisabled(rootView, "login") {
rui.Set(rootView, "login", rui.Disabled, false)
}
} else {
if !rui.IsDisabled(rootView, "login") {
rui.Set(rootView, "login", rui.Disabled, true)
}
}
}
func createSession(session rui.Session) rui.SessionContent {
return new(appSession)
}
func main() {
// Initialize RUI library and wait for incoming connections
rui.StartApp(address, createSession, rui.AppParams{
Title: "Events example",
})
}
After building and running this example we'll have the same result.
When working with event handlers, we recommend consulting our Reference documentation for information on available events and handler signatures for UI controls.
Most UI controls in the RUI library inherit properties and events from the base UI control, which is a View.
Advanced usage
UI controls have numerous properties. The RUI library provides a method for setting up listeners (functions that are executed when a property changes).
To achieve this, we can use the following function from the View interface of UI controls:
Go
SetChangeListener(tag PropertyName, listener func(rui.View, PropertyName))
where "tag" is a name of the property.
Example
Go
view.SetChangeListener(rui.BackgroundColor, func(view rui.View, tag PropertyName) {
// The background color has been changed
})
Many UI controls generate events in response to user interactions, and these events are also considered properties of the controls. These properties have names that are similar to other properties, and they typically store arrays of listener functions. Therefore, we can assign multiple listeners to a specific event. Listener functions may also have different signatures, but the library will handle wrapping them into the main listener format behind the scenes.
Let's take a look at the EditView UI control as an example.
It has a property called "edit-text-changed" which is an event.
The main listener format for this event follows a specific pattern:
Go
func(editView rui.EditView, newText, oldText string)
If we don't need all of the parameters provided by the main listener format, there are alternative ways to define a listener function. For example, we could use:
Go
func(editView rui.EditView, newText string)
func(newText, oldText string)
func(newText string)
func(editView rui.EditView)
func()
These functions will be automatically converted into the main listener format by the library during the assignment process, which involves using the Set() function from the base View interface:
Go
view.Set(rui.EditTextChanged, func(edit EditView, newText, oldText string) {
// Do something
})
or a global RUI function Set():
Go
ok := rui.Set(rootView, viewID, rui.EditTextChanged, func(edit EditView, newText, oldText string) {
// Do something
})
where "rootView" and "viewID" are used to find the view for which we need to set that listener.
As previously mentioned, multiple listener functions can be assigned to a specific event.
For example, for the EditView UI control and its "edit-text-changed" event, we could assign an array of listener functions:
Go
[]func(editView rui.EditView, newText string)
[]func(newText, oldText string)
[]func(newText string)
[]func(editView rui.EditView)
[]func()
or
Go
[]any
which contains non-array versions of the listener functions above.
When we retrieve the value of an event, we'll receive a slice of listener functions in the main listener format for that specific event.
Go
listeners := editView.Get(rui.EditTextChangedEvent)
switch listeners.(type) {
case []func(rui.EditView, string, string):
// Do something
}
If the event has not been assigned any listener functions, we will retrieve an empty slice when accessing its value.