This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Gi

Gi is a pure Go 2D and 3D GUI framework, built on Ki and widely used standards in the web, like CSS for styling and SVG for vector graphics.

Gi is a scenegraph-based 2D and 3D GUI / graphics interface (Gi) in Go, that functions similar to HTML / CSS / SVG and Qt.

NOTE: Requires Go version 1.18+ – now using the new generics.

See the Wiki for more docs (increasingly extensive), Install instructions (mostly basic go build procedure, but does now depend on cgo on all platforms due to glfw, so see details for each platform – for mac you must now install the Vulkan SDK, and Google Groups goki-gi email list, and the new github Discussions tool.

GoGi uses the Goki tree infrastructure to implement a scenegraph-based GUI framework in full native idiomatic Go, with minimal OS-specific backend interfaces based originally on the Shiny drivers, now using go-gl/glfw and vulkan-based vgpu, and supporting MacOS, Linux, and Windows.

The overall design integrates existing standards and conventions from widely-used frameworks, including Qt (overall widget design), HTML / CSS (styling), and SVG (rendering). The core Layout object automates most of the complexity associated with GUI construction (including scrolling), so the programmer mainly just needs to add the elements, and set their style properties – similar to HTML. The main 2D framework also integrates with a 3D scenegraph, supporting interesting combinations of these frameworks (see gi3d package and examples/gi3d). Currently GoGi is focused on desktop systems, but nothing should prevent adaptation to mobile.

See Gide for a complete, complex application written in GoGi (an IDE), and likewise the Emergent neural network simulation environment (the prime motivator for the whole project), along with the various examples in this repository for lots of useful demonstrations – start with the Widgets example which has a bit of a tutorial introduction.

Main Features

  • Has all the standard widgets: Button, Menu, Slider, TextField, SpinBox, ComboBox etc, with tooltips, hover, focus, copy / paste (full native clipboard support), drag-n-drop – the full set of standard GUI functionality. See gi/examples/widgets for a demo of all the widgets.

  • Layout auto-organizes and auto-sizes everything to configure interfaces that “just work” across different scales, resolutions, platforms. Automatically remembers and reinstates window positions and sizes across sessions, and supports standard Ctrl+ and Ctrl- zooming of display scale.

  • CSS-based styling allows customization of everything – native style properties are HTML compatible (with all standard em, px, pct etc units), including HTML “rich text” styling for all text rendering (e.g., in Label widget) – can decorate any text with inline tags (<strong>, <em> etc), and even include links. Styling is now separated out into gist package, for easier navigation.

  • Compiles in seconds, compared to many minutes to hours for comparable alternatives such as Qt, and with minimal cgo dependency. As of April 2019 we now depend on the glfw cross-platform GUI infrastructure system, and as of May 2022 vulkan provides all the rendering (2D via vdraw, 3D via vphong): vgpu.

  • Fully self-contained – does not use OS-specific native widgets – results in simpler, consistent code across platforms, and is HiDPI capable and scalable using standard Ctrl/Cmd+Plus or Minus key, and in Preferences. This also allows a complete 2D GUI to be embedded into a 3D scene, for example.

  • SVG element (in svg sub-package) supports SVG rendering – used for Icons internally and available for advanced graphics displays – see gi/examples/svg for viewer and start on editor, along with a number of test .svg files.

  • Model / View paradigm with reflection-based view elements that display and manipulate all the standard Go types (in giv sub-package), from individual types (e.g., int, float display in a SpinBox, “enum” const int types in a ComboBox chooser) to composite data structures, including StructView editor of struct fields, MapView and SliceView displays of map and slice elements (including full editing / adding / deleting of elements), and full-featured TableView for a slice-of-struct and TreeView for Goki trees.

    • TreeView enables a built-in GUI editor / inspector for designing gui elements themselves. Just press Control+Alt+I in any window to pull up this editor / inspector. Scene graphs can be automatically saved / loaded from JSON files, to provide a basic GUI designer framework – just load and add appropriate connections..

  • GoGi is a “standard” retained-mode (scenegraph-based) GUI, as compared to immediate-mode GUIs such as Gio. As such, GoGi automatically takes care of everything for you, but as a result you sacrifice control over every last detail. Immediate mode gives you full control, but also the full burden of control – you have to code every last behavior yourself. In GoGi, you have extensive control through styling and closure-based “callback” methods, in the same way you would in a standard front-end web application (so it will likely be more familiar to many users), but if you want to do something very different, you will likely need to code a new type of Widget, which can be more difficult as then you need to know more about the overall infrastructure. Thus, if you are likely to be doing fairly standard things and don’t feel the need for absolute control, GoGi will likely be an easier experience.

Screenshot of Widgets demo

Screenshot of Gi3D demo

Screenshot of GiEditor, Dark mode

Code Overview

There are three main types of 2D nodes:

  • Viewport2D nodes that manage their own image.RGBA bitmap and can upload that directly to the oswin.Texture (GPU based) that then uploads directly to the oswin.Window. The parent Window has a master Viewport2D that backs the entire window, and is what most Widget’s render into.

    • Popup Dialog and Menu’s have their own viewports that are layered on top of the main window viewport.
    • SVG and its subclass Icon are containers for SVG-rendering nodes.

  • Widget nodes that use the full CSS-based styling (e.g., the Box model etc), are typically placed within a Layout – they use units system with arbitrary DPI to transform sizes into actual rendered dots (term for actual raw resolution-dependent pixels – “pixel” has been effectively co-opted as a 96dpi display-independent unit at this point). Widgets have non-overlapping bounding boxes (BBox – cached for all relevant reference frames).

  • SVG rendering nodes that directly set properties on the girl.Paint object and typically have their own geometry etc – they should be within a parent SVG viewport, and their geom units are determined entirely by the transforms etc and we do not support any further unit specification – just raw float values.

General Widget method conventions:

  • SetValue kinds of methods are wrapped in UpdateStart / End, but do NOT emit a signal.
  • SetValueAction calls SetValue and emits the signal. This allows other users of the widget that also recv the signal to not trigger themselves, but typically you want the update, so it makes sense to have that in the basic version. ValueView in particular requires this kind of behavior.

The best way to see how the system works are in the examples directory, and by interactively modifying any existing gui using the interactive reflective editor via Control+Alt+I.

Backend

The oswin and oswin/driver/vkos packages provide interface abstractions for hardware-level implementations, now using vgpu and glfw (version 3.3) provides the basic platform-specific details along with a few other bits of platform-specific code.

All of the main “front end” code just deals with image.RGBA through the girl rendering library, using girl.Paint methods, which was adapted from fogleman/gg, and we use srwiley/rasterx for CPU-based rasterization to the image, which is fast and SVG performant. The vgpu/vdraw package performs optimized GPU texture-based compositing to assemble the final display in a way that minimizes the copying of image data up to the GPU, and supports overlays such as popups and sprites. Any 3D scene elements are accessed directly within the GPU.

Status / News

  • Version 1.3 released May, 2022, uses the new vulkan based vgpu rendering framework.

  • Version 1.2 released Feb, 2021, had lots of bug fixes.

  • Version 1.1 released Nov, 2020, has the styling parameters and code broken out in the gist style package, and basic rendering code, including a complete text layout and rendering system, in the girl render library.

  • Version 1.0 released April, 2020! The 3D gi3d component is ready for use, and the code has been widely tested by students and researchers, including extensive testing under gide. The API will remain stable at this point.

  • Active users should join Google Groups goki-gi emailing list to receive more detailed status updates.

  • Please file Issues for anything that does not work.

  • 3/2019: python wrapper is now available! you can do most of GoGi from python now. See README.md file there for more details.

1 - Getting Started

Set up prerequisites, install Gi, and run the Widgets example.

Prerequisites

On all platforms, you must download and install Go from the Go website if you do not already have Go 1.18+ installed.

MacOS

  1. Install the xcode command-line tools if you don’t already have them by running xcode-select --install
  2. If you don’t already have the Vulkan SDK installed, install it by doing the following:
    • Run curl -O https://sdk.lunarg.com/sdk/download/latest/mac/vulkan_sdk.dmg
    • Run open vulkan_sdk.dmg
    • Double click InstallVulkan.app
    • Follow the installation prompts and ignore all warnings about the Vulkan Portability Enumeration extension

Windows

  1. Download and install Git for Windows from the git website if you don’t already have it. You should install Git Bash as part of this process and use it for development.
  2. Download and install TDM-GCC from this website
  3. Open Windows Command Prompt and run cd C:\TDM-GCC-64
  4. Then, run mingwvars.bat

Linux

  • If you are on Ubuntu or Debian, run sudo apt-get install libgl1-mesa-dev xorg-dev
  • If you are on CentOS or Fedora, run sudo dnf install libX11-devel libXcursor-devel libXrandr-devel libXinerama-devel mesa-libGL-devel libXi-devel libXxf86vm-devel

Installation

Clone the Gi repository by running git clone https://github.com/goki/gi

Try it out!

  1. Navigate to the widgets example by running cd gi/examples/widgets
  2. Build the widgets example by running go build
  3. Run the widgets example by running ./widgets if you are on MacOS or Linux and ./widgets.exe if you are on Windows. This should create a window with a variety of widgets, similar to the screenshot below: Screenshot of Widgets Demo

1.1 - Hello World

Create a simple Hello World example app with Gi.

Create a new Go project

  1. Navigate back to your home directory by running cd
  2. Create a new directory called myapp by running mkdir myapp
  3. Navigate to your newly created directory by running cd myapp
  4. Create a new Go module by running go mod init myapp
  5. Create a new Go file by running touch main.go
  6. Open main.go using an editor of your choice

Make a simple app

  1. Add the following code to your editor:

    package main

import (
  "github.com/goki/gi/gi"
  "github.com/goki/gi/gimain"
)

func main() {
  // Run the window event loop function as the main function
  gimain.Main(func() {
    mainrun()
  })
}

func mainrun() {
  // Create a window called My App Window with width 512 and height 384
  win := gi.NewMainWindow("myapp", "My App Window", 512, 384)
  // Get the viewport within the window
  vp := win.WinViewport2D()
  // Start a protect update on the viewport
  updt := vp.UpdateStart()
  // Create a standard frame within the window and make it the main widget
  mfr := win.SetMainFrame()

  // Add a label to the main frame with the text "Hello, World!"
  label := gi.AddNewLabel(mfr, "label", "Hello, World!")
  // Make the font size of the label large
  label.SetProp("font-size", "large")

  // End the protected update on the viewport without a signal.
  // Update signals cause things to be redrawn, which is unnecessary at the start
  // because it is already drawing everything new.
  vp.UpdateEndNoSig(updt)
  // Start the event loop that keeps the window rendering.
  // This is a blocking call, and it will not return until
  // the user quits the app or gi.Quit() is called
  win.StartEventLoop()
}

  2. Update your dependencies by running go mod tidy

  3. Build the code by running go build

  4. Run the app by running ./myapp if you are on MacOS or Linux and ./myapp.exe if you are on Windows. This should create a window with text that says “Hello, World,” similar to the screenshot below:

Screenshot of Hello World App

1.2 - Increment

Extend the Hello World example to support incrementing a number by clicking on a button.

In the last section, you built a simple app that says, “Hello, World!” In this section, you will add to that app by creating a button that increments a label. To do that, you need to add the following code after the “Hello, World!” label:

	// Add a new label to the main frame with the text "0"
	// This label will track the number of times the button has been clicked
	numLabel := gi.AddNewLabel(mfr, "numLabel", "0")
	// Make the label redrawable so that it can be updated when the
	// number of times the button has been clicked changes
	numLabel.Redrawable = true
	// Add a new button to the main frame
	button := gi.AddNewButton(mfr, "button")
	// Set the text of the button to "Increment"
	button.Text = "Increment"
	// Keep track of the number of times that the button has been clicked
	numClicked := 0
	// The OnClicked function is called every time the button is clicked
	button.OnClicked(func() {
		// In it, we increment the number of times the button has been clicked
		numClicked++
		// Then, we set the text of the number label to the number of the times
		// the button has been clicked. strconv.Itoa converts integers to strings.
		numLabel.SetText(strconv.Itoa(numClicked))
	})

Then, run go build and ./myapp if you are on MacOS or Linux and ./myapp.exe if you are on Windows. This should create a window similar to the last one, except with a new label and button. Each time you click the Increment button, the number in the new label should increase by 1. If you click the button 7 times, the app should look like this:

Screenshot of Increment App

2 - Examples

Examples of projects built using Gi.