Tutorial: Hello, World!

This tutorial shows how to build a simple Goey application, and introduces a reactive architecture useful for Goey applications. To be clear, the architecture is not fully reactive, but does use a unidirectional flow for data that simplifies writing GUI applications. For this architecture, there are 4 required functions.

Note: For brevity, comments have been stripped from the code samples.

Note: If interested in the full source, the program exists in the examples directory.

func main

With respect to the GUI, the main function has one responsibility, which is to start the GUI's event loop. Event loops are common across the native GUI APIs supported, but obviously the details differ. The package loop is responsible for abstracting away those differences. For our simple program, only one function from that package is required, loop.Run. This function will initialize the event loop, and keep that loop running until there are no more top-level windows.

Before the event loop starts, the top-level window needs to be created, but there is a complication. Details differ between platforms, but none of the major desktop GUI APIs are thread-safe. This means that any GUI objects, such as windows, ought to be created on the same OS thread as the event loop. Rather than leave it to the caller to coordinate the threading, loop instead takes a callback to handle initializing the GUI.

With proper error handling, the two requirements listed above leads to the following definition for the function main.

func main() {
    err := loop.Run(createWindow)
    if err != nil {
        fmt.Fprintf(os.Stderr, "error: %s\n", err)
        os.Exit(1)
    }
}

func createWindow

While the layout and controls within a window use a declarative approach, top-level windows are created imperatively. Windows are created using goey.NewWindow, and properties can be updated using methods. For this simple example, only two properties on the window need to be set, and they are set when the window is created. This means that a single call is sufficient to create and initialize the window.

The first parameter sets a title for the window.

The second parameter sets the contents of the window. We could provide the necessary data here, but the program will also need to generate (and regenerate) the window's contents elsewhere. To avoid duplication, that code is located in main.render.

There is one other important detail. The function copies the *goey.Window into a global variable. Global state is generally bad, but the value of main.mainWindow will not change once initialized. This value is required to update the window's contents when we react to events.

func createWindow() error {
    mw, err := goey.NewWindow("One Button", render())
    if err != nil {
        return err
    }
    mainWindow = mw

    return nil
}

func updateWindow

This is a small helper function that recalculates the contents of the window, using main.render, and then updates the contents of the window. Note that the call to SetChild is where the magic of goey happens, and what makes goey declarative. The package will reconcile any differences between the data-defined contents, and the platform-dependent controls, so that the window's contents match. There is no need for the caller to add, modify, or delete any controls.

func updateWindow() {
    err := mainWindow.SetChild(render())
    if err != nil {
        fmt.Fprintf(os.Stderr, "error: %s\n", err)
    }
}

Beware, this function can only be called on the thread that is also running the GUI event loop. Otherwise, there will be concurrent access to the GUI API, which will likely cause a crash. If you need to call this function from an arbitrary goroutine, please use loop.Do.

func render

This function returns a data structure that defines the desired layout and contents of the top-level window. Ideally, all state that affects the contents would be passed as an argument, but in this simple example, the small bit of state is stored in a global variable, clickCount.

Based on the value of clickCount, the button's label will change. Otherwise, the layout and contents are static. Details on layout will not be covered here, except to say that layout depends on simple, composable widgets. Please look at the widgets available in the package goey to see what layout options are available.

The declarative nature of the GUI definition does not just cover the appearance, it also covers callbacks for events. In this case, note that the button has an event called OnClick. In this case, the event handler is defined inline using a function literal. In response to events, the program can update its state, but note that it does not directly modify any controls. Instead, we call updateWindow. This will again call into render to determine the current layout and contents.

func render() base.Widget {
    text := "Click me!"
    if clickCount > 0 {
        text = text + "  (" + strconv.Itoa(clickCount) + ")"
    }

    return &goey.Padding{
        Insets: goey.DefaultInsets(),
        Child: &goey.Align{
            Child: &goey.Button{Text: text, OnClick: func() {
                clickCount++
                updateWindow()
            }},
        },
    }
}

The callbacks for events are executed on the same OS thread as the GUI event loop. It is therefore safe to create new windows, and modify those windows, within callbacks. Conversely, and long-running code will cause the GUI freeze, so any operations that may take appreciable time should be moved to another goroutine. When a long-running operation has completed, and update of the GUI can be arrange by calling loop.Do.

Note that this function uses a global variable for the program's state. If that state was passed as an argument, then the GUI layout and controls would be functional, and could easily be tested.

Summary

All told, once imports and comments are added, the complete application is 76 lines. A small modification to main.render to make it functional would make a large part of the GUI testable. The complete source file can be viewed in the repository. If interested, please checkout the other examples.