Gooey User's Guide

Gooey is considered experimental and unsupported crate version Live Build Status HTML Coverage Report for main branch Documentation for main branch

Gooey is a Graphical User Interface library written in Rust. At its core, it attempts to provide a framework that allows building truly cross-platform applications.

This user's guide aims to provide a guided walkthrough for users to understand how Gooey works. This guide is meant to be supplemental to the documentation. If you learn best by exploring examples, our primary collection is available in gooey/examples. If, however, you learn best by taking a guided tour of how something works, this guide is specifically for you.

If you have any feedback on this guide, please file an issue, and we will try to address any issues or shortcomings.

Thank you for exploring Gooey.

About Gooey

Gooey is a graphical user interface framework for Rust. It aims to provide a cross-platform way for developing applications to achieve the "write once, deploy anywhere" holy grail.

Where it differs from many is in its core design philosophy: You should never feel boxed in by limitations of your UI framework. In many other frameworks, if you use a third party widget, and you want to target a new platform that the widget doesn't support, you usually need to ask the library author to add support for that platform. Not so with Gooey!

In Gooey, the roles of Widgets, Transmogrifiers, and Frontends are clearly defined, and you would be able to implement your own Transmogrifier for the unsupported widget. Or, if a platform implementation leaves something to be desired, you can use your own Transmogrifier for that as well.

While this may not be the first framework to take this approach, it is not a common approach, and it's one thing that separates Gooey from many user interface frameworks.

Understanding Gooey's Core Concepts

Widget trait

The Widget trait (documentation) is used to define all user interface elements. This is similar to a View, Control, or Component in other user interface frameworks.

In Gooey a Widget is what you will create your cross-platform interfaces with. The built-in widgets are:

A Widget has no knowledge about how it's being presented. When you present your user interface, you will pick a Frontend. The Transmogrifier is responsible for presenting the Widget in the active Frontend.

Implementing a new Widget

Implementing a new widget requires adding the Widget implementor and a Transmogrifier implementor for each Frontend you wish to support. For example, Button provides the cross-platform API that allows you to use a push button in your interface. It also exposes ButtonTransmogrifier, which is the type that implements Transmogrifier for the supported Frontends.

Frontend trait

The Frontend trait (documentation) is what presents a user interface.

Gooey supports two frontends:

Each Frontend will define the necessary APIs that Transmogrifiers need to implement Widgets. In general, you only need to know the details about Transmogrifiers and Frontends if you're implementing new Widgets or Transmogrifiers.

Transmogrifier trait

The Transmogrifier trait (documentation) presents a Widget with a Frontend. If a Widget doesn't have a Transmogrifier for a given Frontend, it will not be able to be used on that Frontend. Never fear, all Widgets built into Gooey support the two built-in Frontends: WebSys and Rasterizer.

One of the unique designs of Gooey is that if a Transmogrifier doesn't exist for a Frontend you wish to target, or if a Transmogrifier doesn't support a feature you need, you can implement a new Transmogrifier and replace it in your application. This flexility ensures that you will always have the ability to implement new Frontends or add support to existing Widgets for an unsupported Frontend.

Creating a Widget

There are generally two types of Widgets you might find yourself wanting to create. The most common approach will be to use a Component to create a new widget using other widgets to power the component. For example, a "New User" form would be a Component with multiple text fields, labels, and buttons. This approach allows you to write Frontend-independent widgets. To learn more, read the chapter about Components.

If the widget you want to create can't be implemented using existing widgets, you will need to implement a new widget.

Implementing Widget

TODO Coming soon.

For now, the simplest widget implementation is Label and can be viewed in gooey-widgets here.

Supported Frontends

The Frontends supported by Gooey are:

  • gooey-browser: Allows deploying applications to modern browsers through WebAssembly.
  • gooey-rasterizer: Allows deploying native applications using a Renderer.
    • gooey-kludgine: A Renderer implementation targeting wgpu using Kludgine.

Browser Frontend

The Browser Frontend enables building applications for WebAssembly that run inside of modern web browsers.

TODO More Coming soon. Revisit after adding more built-in documentation to the browser crate.

Native (Rasterized)

The Rasteizer Frontend enables building native applications that use a Renderer implementation.

Widgets are drawn using primitive drawing calls in this frontend.

TODO More Coming soon. Revisit after adding more built-in documentation to the rasterizer crate.

Provided Widgets

gooey-widgets is a crate containing Widgets that work on the supported Frontends.

  • Button: A push button.
  • Component: A widget designed to facilitate combining multiple widgets into a single widget.
  • Container: A layout widget that spaces and/or aligns a child widget.
  • Label: A text label.
  • Layout: A layout widget that allows positioning child widgets relative to itself using top, left, right, bottom, width, or height measurements.

Button

The Button widget provides a push button that users can click or tap on. The text that the button displays is the label. When the button is clicked, the clicked callback is invoked.

TODO button user guide

Component

The Component widget provides a way to implement a widget that uses one or more other widgets to create a new widget. The Component is driven by a Behavior trait implementation.

TODO component user guide

Container

TODO container user guide

Label

The Label widget displays its label string.

TODO label user guide

Layout

The Layout widget allows positioning children relative to the layout's left, top, right, and bottom locations. It also allows controlling the width and height of the child.

TODO layout user guide

Tutorial: Build a Database-driven App