gogui

README

gogui

gogui is an easy-to-use library for creating simple GUIs in Go. I intend to implement it for Mac OS X and have no plans to support other operating systems, although such implementations would be very welcome.

Usage

gogui uses a simple runloop architecture. The runloop needs to run on the main OS thread, so you must call it directly from your main function:

package main

import "github.com/unixpickle/gogui"

func main() {
    // some of your setup code here...
    gogui.Main(&gogui.AppInfo{Name: "Demo"})
}

All GUI events and modifications must occur on the main goroutine. This can be achieved through the RunOnMain function, which runs a function asynchronously on the main goroutine:

gogui.RunOnMain(func() {
    // Modify the GUI here...
})

You may call RunOnMain before running gogui.Main(), so it is perfectly valid to do something like this:

package main

import "github.com/unixpickle/gogui"

func main() {
    gogui.RunOnMain(func() {
		w, _ := gogui.NewWindow(gogui.Rect{0, 0, 400, 400})
		w.Show()
    })
    gogui.Main(&gogui.AppInfo{Name: "Demo"})
}

Further demonstrations can be found in the demo folder. And, as always, the GoDoc gives a full overview of the package.

Screenshots

So far, gogui supports keyboard and mouse events, window management, and canvas drawing. Here is an example of what you can create with a simple canvas:

TODO

• Map keyboard events to match JavaScript keycodes.
• Fix crashes when font does not exist.
• Add canvas features
  • Font decoration (i.e. italics, bold, underline)
  • Translation + rotation + save/restore state
  • Arcs
  • Images
  • Line cap
  • Line join

License

gogui is licensed under the BSD 2-clause license. See LICENSE.

Copyright (c) 2015, Alex Nichol.
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this
   list of conditions and the following disclaimer. 
2. Redistributions in binary form must reproduce the above copyright notice,
   this list of conditions and the following disclaimer in the documentation
   and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Documentation

Overview

Package gogui provides a very simple library for creating user interfaces in Go.

Index

• func Main(info *AppInfo)
• func RunOnMain(evt func())
• type AppInfo
• type Canvas
  • func NewCanvas(r Rect) (Canvas, error)
• type Color
• type DrawContext
• type DrawHandler
• type KeyEvent
• type KeyEventer
• type KeyHandler
• type MouseEvent
• type MouseEventer
• type MouseHandler
• type Rect
• type Widget
• type Window
  • func NewWindow(r Rect) (Window, error)
  • func ShowingWindows() []Window

Functions

func Main

func Main(info *AppInfo)

Main runs the main loop of the app. This should be called from the main function, since it may require execution on the main OS thread.

func RunOnMain

func RunOnMain(evt func())

RunOnMain runs a function on the main goroutine asynchronously.

Types

type AppInfo

type AppInfo struct {
	Name string
}

The AppInfo object represents information about the application which the implementation may choose to display to the user in some form.

type Canvas

type Canvas interface {
	Widget

	DrawHandler() DrawHandler
	NeedsUpdate()
	SetDrawHandler(d DrawHandler)
}

A Canvas is a widget that can be drawn into.

func NewCanvas

func NewCanvas(r Rect) (Canvas, error)

NewCanvas creates a new canvas or fails with an error. The returned canvas will not be added to any window and will have a nil draw function by default.

type Color

type Color struct {
	R float64
	G float64
	B float64
	A float64
}

A Color stores an RGBA color.

type DrawContext

type DrawContext interface {
	// BeginPath starts a path which can be filled or stroked.
	BeginPath()

	// ClosePath closes the current path by connecting the first and last points
	// in it.
	ClosePath()

	// FillEllipse fills an ellipse inside a rectangle.
	FillEllipse(r Rect)

	// FillPath fills the current path.
	// If the path was not closed, the behaviour of FillPath may vary on
	// different platforms.
	FillPath()

	// FillRect fills a rectangle.
	FillRect(r Rect)

	// FillText draws text at a given point.
	FillText(text string, x, y float64)

	// LineTo adds a line from the current point in the path to another point.
	LineTo(x, y float64)

	// MoveTo moves the current path to a point without connecting said point to
	// the rest of the path.
	MoveTo(x, y float64)

	// SetFill sets the color for every Fill method.
	SetFill(c Color)

	// SetFont sets the font and font size used by FillText
	SetFont(size float64, name string)

	// SetStroke sets the color for every Stroke method.
	SetStroke(c Color)

	// SetThickness sets the thickness for every Stroke method.
	SetThickness(thickness float64)

	// StrokeEllipse strokes an ellipse inside a rectangle.
	StrokeEllipse(r Rect)

	// StrokePath outlines the current path.
	StrokePath()

	// StrokeRect outlines a rectangle.
	StrokeRect(r Rect)

	// TextSize computes the width and height for a given string as it would be
	// drawn by FillText.
	TextSize(text string) (width, height float64)
}

A DrawContext receives draw commands.

type DrawHandler

type DrawHandler func(DrawContext)

A DrawHandler is called to draw into a canvas's drawing context.

type KeyEvent

type KeyEvent struct {
	// CharCode stores a char code similar to the char codes in JavaScript.
	CharCode int

	// KeyCode stores the OS-specific key code (if available).
	KeyCode int

	AltKey   bool
	CtrlKey  bool
	MetaKey  bool
	ShiftKey bool
}

A KeyEvent holds information for a key event.

type KeyEventer

type KeyEventer interface {
	KeyDownHandler() KeyHandler
	KeyPressHandler() KeyHandler
	KeyUpHandler() KeyHandler
	SetKeyDownHandler(k KeyHandler)
	SetKeyPressHandler(k KeyHandler)
	SetKeyUpHandler(k KeyHandler)
}

A KeyEventer listens to key events and sends them to handlers.

type KeyHandler

type KeyHandler func(KeyEvent)

A KeyHandler handles keyboard events.

type MouseEvent

type MouseEvent struct {
	X float64
	Y float64
}

A MouseEvent holds information for a mouse event.

type MouseEventer

type MouseEventer interface {
	MouseDownHandler() MouseHandler
	MouseDragHandler() MouseHandler
	MouseMoveHandler() MouseHandler
	MouseUpHandler() MouseHandler
	SetMouseDownHandler(m MouseHandler)
	SetMouseDragHandler(m MouseHandler)
	SetMouseMoveHandler(m MouseHandler)
	SetMouseUpHandler(m MouseHandler)
}

A MouseEventer listens to mouse events and sends them to handlers.

type MouseHandler

type MouseHandler func(MouseEvent)

A MouseHandler handles mouse events.

type Rect

type Rect struct {
	X      float64
	Y      float64
	Width  float64
	Height float64
}

A Rect holds the position and dimensions for a Widget.

The X value starts from the left of the parent. The Y value starts from the top of the parent.

Width extends to the right and Height extends downward.

type Widget

type Widget interface {
	// Frame returns the bounding box for this widget.
	Frame() Rect

	// Parent returns the widget which contains this widget, or nil.
	Parent() Widget

	// Remove removes this widget from its parent if it has one.
	Remove()

	// SetFrame sets the bounding box for this widget.
	SetFrame(r Rect)
}

A Widget is any item that can be shown visually to the user.

type Window

type Window interface {
	KeyEventer
	MouseEventer

	// Add adds a widget to the window. The widget cannot already be added to
	// something else.
	Add(w Widget)

	// Center centers the window on the screen.
	Center()

	// Children returns every direct child of this window.
	Children() []Widget

	// CloseHandler returns the window's close handler.
	CloseHandler() func()

	// Focus brings the window to the front if it is showing.
	Focus()

	// Frame returns the content rectangle for the window.
	Frame() Rect

	// Hide closes the window if it was open.
	Hide()

	// Parent returns nil; it exists to implement the Widget interface.
	Parent() Widget

	// Remove does nothing; it exists to implement the Widget interface.
	Remove()

	// SetCloseHandler sets a function to be called when the user closes the
	// window.
	SetCloseHandler(h func())

	// SetFrame sets the content rectangle for the window.
	SetFrame(r Rect)

	// SetTitle sets the title of the window.
	SetTitle(t string)

	// Show opens the window if it was not open before.
	Show()

	// Showing returns whether the window is showing or not.
	Showing() bool
}

A Window is container Widget which shows the user its sub-widgets.

func NewWindow

func NewWindow(r Rect) (Window, error)

NewWindow creates a new window or fails with an error. The returned window will not be shown until its Show() method is called.

func ShowingWindows

func ShowingWindows() []Window

ShowingWindows returns all of the windows which are showing.