README

alt tag

GoGi is part of the GoKi Go language (golang) full strength tree structure system (ki = 木 = tree in Japanese)

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

Go Report Card GoDoc Travis TODOs

NOTE: Requires Go version 1.13+ due to use of math.Round, os.UserCacheDir, and reflect.Value.IsZero().

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), 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 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 the go-gl/gl OpenGL bindings, to support the 3D (gi3d) aspect of the framework.

  • 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 gpu packages provide interface abstractions for hardware-level implementations. Currently the gpu implementation is OpenGL, but Vulkan is planned, hopefully with not too many changes to the gpu interface. The basic platform-specific details are handled by glfw (version 3.3), 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 https://github.com/fogleman/gg, and we use https://github.com/srwiley/rasterx for CPU-based rasterization to the image, which is fast and SVG performant. The Viewport2D image is uploaded to a GPU-backed oswin.Texture and composited with sprite overlays up to the window.

Status / News

  • 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.

Expand ▾ Collapse ▴

Documentation

Overview

    Package gi is the top-level repository for the GoGi GUI framework.

    All of the code is in the sub-packages within this repository:

    * gi: contains the main 2D GUI code

    * giv: are more complex Views of Go data structures, built out of gi widgets, supporting the Model-View paradigm.

    * svg is something: provides a full SVG rendering framework, used for Icons, and in its own right.

    * oswin: is the OS-specific framework, originally based on Shiny, that provides all the gory guts for dealing with different OS's.

    * examples: contains a number of useful examples for learning how to use GoGi -- see widgets and its README file for a basic introduction. marbles is really fun!

    Source Files

    Directories

    Path Synopsis
    examples
    svg
    Package Gi (GoGi) provides a Graphical Interface based on GoKi Tree Node structs 2D and 3D (in gi3d) scenegraphs supported, each rendering to respective Viewport or Scene.
    Package Gi (GoGi) provides a Graphical Interface based on GoKi Tree Node structs 2D and 3D (in gi3d) scenegraphs supported, each rendering to respective Viewport or Scene.
    Package gi3d provides a 3D scenegraph for the GoGi GUI framework.
    Package gi3d provides a 3D scenegraph for the GoGi GUI framework.
    io/obj
    Package obj is used to parse the Wavefront OBJ file format (*.obj), including associated materials (*.mtl).
    Package obj is used to parse the Wavefront OBJ file format (*.obj), including associated materials (*.mtl).
    Package gimain provides a Main function that encapsulates the standard oswin driver main function, and also ensures that standard sub-packages that are required for typical gi gui usage are automatically included
    Package gimain provides a Main function that encapsulates the standard oswin driver main function, and also ensures that standard sub-packages that are required for typical gi gui usage are automatically included
    Package GiRl is the GoGi render library -- renders to an image.RGBA using styles defined in GiSt styles Original rendering borrows heavily from: https://github.com/fogleman/gg and has been integrated with https://github.com/srwiley/rasterx which provides fully SVG compliant and fast rendering.
    Package GiRl is the GoGi render library -- renders to an image.RGBA using styles defined in GiSt styles Original rendering borrows heavily from: https://github.com/fogleman/gg and has been integrated with https://github.com/srwiley/rasterx which provides fully SVG compliant and fast rendering.
    Package GiSt contains the style structures for the GoGi GUI framework.
    Package GiSt contains the style structures for the GoGi GUI framework.
    giv
    Package GiV (GoGi Views) provides a model / view framework to view Go data using reflection Views are Widgets that automatically display and interact with standard Go data, including structs, maps, slices, and the primitive data elements (string, int, etc).
    Package GiV (GoGi Views) provides a model / view framework to view Go data using reflection Views are Widgets that automatically display and interact with standard Go data, including structs, maps, slices, and the primitive data elements (string, int, etc).
    package histyle provides syntax highlighting styles -- it is based on github.com/alecthomas/chroma which in turn was based on the python pygments package.
    package histyle provides syntax highlighting styles -- it is based on github.com/alecthomas/chroma which in turn was based on the python pygments package.
    Package oswin provides interfaces for OS-specific GUI hardware for portable two-dimensional graphics and input events.
    Package oswin provides interfaces for OS-specific GUI hardware for portable two-dimensional graphics and input events.
    clip
    Package clip defines the system clipboard for the GoGi GUI system.
    Package clip defines the system clipboard for the GoGi GUI system.
    cursor
    Package cursor defines the oswin cursor interface and standard system cursors that are supported across platforms
    Package cursor defines the oswin cursor interface and standard system cursors that are supported across platforms
    dnd
    Package dnd defines the system drag-and-drop events for the GoGi GUI system.
    Package dnd defines the system drag-and-drop events for the GoGi GUI system.
    driver
    Package driver provides the default driver for accessing a screen.
    Package driver provides the default driver for accessing a screen.
    gpu
    Package gpu provides an abstract interface to a graphical processing unit (GPU).
    Package gpu provides an abstract interface to a graphical processing unit (GPU).
    key
    Package key defines an event for physical keyboard keys, for the GoGi GUI system.
    Package key defines an event for physical keyboard keys, for the GoGi GUI system.
    mimedata
    Package mimedata defines MIME data support used in clipboard and drag-and-drop functions in the GoGi GUI.
    Package mimedata defines MIME data support used in clipboard and drag-and-drop functions in the GoGi GUI.
    mouse
    Package mouse defines mouse events, for the GoGi GUI system.
    Package mouse defines mouse events, for the GoGi GUI system.
    osevent
    Package osevent defines operating system level events, not associated with a particular window.
    Package osevent defines operating system level events, not associated with a particular window.
    touch
    Package touch defines an event for touch input, for the GoGi GUI system.
    Package touch defines an event for touch input, for the GoGi GUI system.
    window
    Package window defines events associated with windows -- including changes in the dimensions, physical resolution and orientation of the app's window, and iconify, open and close events.
    Package window defines events associated with windows -- including changes in the dimensions, physical resolution and orientation of the app's window, and iconify, open and close events.
    Package svg provides SVG rendering classes, I/O parsing: full SVG rendering SVG currently supports most of SVG, but not: * Flow * Filter Effects * 3D Perspective transforms See gi/examples/svg for a basic SVG viewer app, using the svg.Editor, which will ultimately be expanded to support more advanced editing.
    Package svg provides SVG rendering classes, I/O parsing: full SVG rendering SVG currently supports most of SVG, but not: * Flow * Filter Effects * 3D Perspective transforms See gi/examples/svg for a basic SVG viewer app, using the svg.Editor, which will ultimately be expanded to support more advanced editing.
    Package undo supports generic undo / redo functionality, using an efficient diff of string-valued state representation of a 'document' being edited which can be JSON or XML or actual text -- whatever.
    Package undo supports generic undo / redo functionality, using an efficient diff of string-valued state representation of a 'document' being edited which can be JSON or XML or actual text -- whatever.
    Package Units supports full range of CSS-style length units (em, px, dp, etc) The unit is stored along with a value, and can be converted at a later point into a raw display pixel value using the Context which contains all the necessary reference values to perform the conversion.
    Package Units supports full range of CSS-style length units (em, px, dp, etc) The unit is stored along with a value, and can be converted at a later point into a raw display pixel value using the Context which contains all the necessary reference values to perform the conversion.