impress

README

impress. Go GUI cross-platform library

See project wiki for a library overview.

Some usage examples are in the examples folder.

Basic Principles of Library Design

• Performance of the application as well as native applications.
• Facade pattern for masking complex components behind an API.
• Simple and clean application code.
• Minimal library API to follow the Go-way.
• Limited use of other libraries (graphic, low-level or native).
• Creating a GUI application without form designer or hard-coded widgets.

The basic idea is to avoid the event-driven programming paradigm. See "What's wrong with event-driven programming" page.

Go is a perfect language for developing desktop GUI applications. Compiled language is fast enough to spin an interactive application. Goroutines are helpful to handle the state of separate windows. The small runtime means that the application starts instantly. Go implement high level abstractions to complex application development.

Hello World Example

Let's say hello:

package main

import (
    "image"
    "image/color"

    "github.com/codeation/impress"
    "github.com/codeation/impress/event"

    _ "github.com/codeation/impress/duo"
)

func main() {
    app := impress.NewApplication(image.Rect(0, 0, 480, 240), "Hello World Application")
    defer app.Close()

    font := impress.NewFont(15, map[string]string{"family": "Verdana"})
    defer font.Close()

    w := app.NewWindow(image.Rect(0, 0, 480, 240), color.RGBA{255, 255, 255, 255})
    defer w.Drop()

    w.Text("Hello, world!", font, image.Pt(200, 100), color.RGBA{0, 0, 0, 255})
    w.Line(image.Pt(200, 120), image.Pt(300, 120), color.RGBA{255, 0, 0, 255})
    w.Show()
    app.Sync()

    for {
        action := <-app.Chan()
        if action == event.DestroyEvent || action == event.KeyExit {
            break
        }
    }
}

See an explanation of the source code in a library overview.

To run this example on Debian/ Ubuntu:

1. Install GTK+ 3 libraries, pkg-config and some libraries if you don't have them installed:

sudo apt-get install libgtk-3-dev
sudo apt-get install pkg-config libsystemd-dev libwebp-dev

1. Build impress terminal from source (see impress terminal page):

git clone https://github.com/codeation/it.git
cd it
make
cd ..

1. Then run example:

git clone https://github.com/codeation/impress.git
cd impress
IMPRESS_TERMINAL_PATH=../it/it go run ./examples/simple/

To run this example on macOS:

1. Install Homebrew if you don't have it installed.
2. Install GTK+ 3 (brew install gtk+3) and pkg-config (brew install pkg-config) if you don't have them installed.
3. Build impress terminal from source (see impress terminal page):

git clone https://github.com/codeation/it.git
cd it
make
cd ..

1. Then run example:

git clone https://github.com/codeation/impress.git
cd impress
IMPRESS_TERMINAL_PATH=../it/it go run ./examples/simple/

The latest releases aren't tested on Apple machines. The earlier version tested on both Intel and Silicon platform and worked well. Please, use earlier release or open issue if some bugs have raised. PRs and MRs are welcome too.

GTK-3 driver

The library uses a separate application for drawing instead of binding low-level library to a Golang.

Pros:

• To compile the application, it is not necessary to install low-level libraries.
• There are no additional restrictions on the application, such as GTK functions should only be called by the main thread.
• It will be possible to run several applications for a low-level drawing from different devices, thereby using the screens of different devices for the same application.
• Abnormal termination of low-level drawing application may not result in data loss.

Cons:

• Some loss of speed due to data transfer between applications.
• Additional complexity due to state synchronization between applications.

You can download the compiled binary it file or make it again from the source.

You can specify the full path and name for the GUI driver via the environment variable, for example:

IMPRESS_TERMINAL_PATH=/path/it go run ./examples/simple/

or just copy the downloaded GUI driver to the working directory and run example:

go run ./examples/simple/

On Debian 12, libharfbuzz-gobject should be installed. If you are getting error while loading shared libraries: libharfbuzz-gobject.so.0: cannot open shared object file: No such file or directory, run sudo apt-get install libharfbuzz-gobject0.

Project State

Notes

• The project is in a beta stage. It's suitable for developing in-house applications.
• The project tested on Debian 12.0.
• The API is stable, but the details are subject to change.

A cross-platform mind-map application is being developed to prove the underlying principles of the library.

Short term roadmap

• Recommended Event Propagation module.
• Additional library with a set of widgets (text input, dialog, etc.).
• Developer version of the library with debugging and profiling.
• Auto build GTK-3 driver for a fixed set of Linux distributions.
• Distribution tool to pack the GUI application into Debian package.

Long term roadmap

• WebAssembly driver for turning a browser into a client terminal.
• Two or more cooperate drivers for the same GUI application.
• GTK-4 driver version when Debian will contain GTK-4 apps.
• Apple Silicon native driver for macOS.
• iOS app used as GUI app remote client.

Stay tuned for more.

Contributing

First, welcome:

• Any like to the project (star, post, link, etc.).
• Any recommendations about library design principles.
• Contribution to project, project wiki, examples.
• Bug report, open issue.
• Or any help to fix grammatical or writing errors (PR or issue).

Documentation

Index

• func Register(current driver.Driver)
• type Application
  • func NewApplication(rect image.Rectangle, title string) *Application
  • func (app *Application) Chan() <-chan event.Eventer
  • func (app *Application) Close()
  • func (app *Application) NewFrame(rect image.Rectangle) *Frame
  • func (app *Application) NewMenu(label string) *Menu
  • func (app *Application) NewWindow(rect image.Rectangle, background color.Color) *Window
  • func (app *Application) Size(rect image.Rectangle)
  • func (app *Application) Sync()
  • func (app *Application) Title(title string)
• type Font
  • func NewFont(height int, attributes map[string]string) *Font
  • func (f *Font) Close()
  • func (f *Font) Size(text string) image.Point
  • func (f *Font) Split(text string, edge int, indent int) []string
• type Frame
  • func (f *Frame) Drop()
  • func (f *Frame) NewFrame(rect image.Rectangle) *Frame
  • func (f *Frame) NewWindow(rect image.Rectangle, background color.Color) *Window
  • func (f *Frame) Raise()
  • func (f *Frame) Size(rect image.Rectangle)
• type Image
  • func NewImage(img image.Image) *Image
  • func (i *Image) Close()
• type Menu
  • func (m *Menu) NewItem(label string, event event.Menu)
  • func (m *Menu) NewMenu(label string) *Menu
• type Window
  • func (w *Window) Clear()
  • func (w *Window) Drop()
  • func (w *Window) Fill(rect image.Rectangle, foreground color.Color)
  • func (w *Window) Image(rect image.Rectangle, img *Image)
  • func (w *Window) Line(from image.Point, to image.Point, foreground color.Color)
  • func (w *Window) Raise()
  • func (w *Window) Show()
  • func (w *Window) Size(rect image.Rectangle)
  • func (w *Window) Text(text string, font *Font, from image.Point, foreground color.Color)

Functions

func Register

func Register(current driver.Driver)

Register is an internal function that makes the GUI driver available.

Types

type Application

type Application struct {
	// contains filtered or unexported fields
}

Application represents application top level window

func NewApplication

func NewApplication(rect image.Rectangle, title string) *Application

NewApplication creates main application window

func (*Application) Chan

func (app *Application) Chan() <-chan event.Eventer

Chan returns event channel

func (*Application) Close

func (app *Application) Close()

Close destroys application resources

func (*Application) NewFrame

func (app *Application) NewFrame(rect image.Rectangle) *Frame

NewFrame create new inner frame with a specified size

func (*Application) NewMenu

func (app *Application) NewMenu(label string) *Menu

NewMenu returns a new top-level menu node

func (*Application) NewWindow

func (app *Application) NewWindow(rect image.Rectangle, background color.Color) *Window

NewWindow creates new inner window with a specified size and background color

func (*Application) Size

func (app *Application) Size(rect image.Rectangle)

Size sets application window size

func (*Application) Sync

func (app *Application) Sync()

Sync flushes graphics content to screen driver

func (*Application) Title

func (app *Application) Title(title string)

Title sets application window title

type Font

type Font struct {
	driver.Fonter
	Height     int
	LineHeight int
	Baseline   int
	Ascent     int
	Descent    int
	Attributes map[string]string
}

Font represents a font selection

func NewFont

func NewFont(height int, attributes map[string]string) *Font

NewFont return a font selection struct. Note than "family" and other attributes are driver specific. Open duo/font.go for details.

func (*Font) Close

func (f *Font) Close()

Close destroys font selection

func (*Font) Size

func (f *Font) Size(text string) image.Point

Size returns the width and height of the drawing area

func (*Font) Split

func (f *Font) Split(text string, edge int, indent int) []string

Split breaks the text into lines that fit in the specified width; indent is a width to indent first line

type Frame

type Frame struct {
	// contains filtered or unexported fields
}

func (*Frame) Drop

func (f *Frame) Drop()

Drop deletes frame Note that a dropped frame can no longer be used

func (*Frame) NewFrame

func (f *Frame) NewFrame(rect image.Rectangle) *Frame

NewFrame create new child frame with a specified size

func (*Frame) NewWindow

func (f *Frame) NewWindow(rect image.Rectangle, background color.Color) *Window

NewWindow creates new frame window with a specified size and background color

func (*Frame) Raise

func (f *Frame) Raise()

Raise brings the frame to the forefront

func (*Frame) Size

func (f *Frame) Size(rect image.Rectangle)

Size changes frame size and position

type Image

type Image struct {
	driver.Imager
	Size image.Point
}

Image represents a draw-ready image

func NewImage

func NewImage(img image.Image) *Image

NewImage returns a image resources struct

func (*Image) Close

func (i *Image) Close()

Close destroys image resources

type Menu

type Menu struct {
	// contains filtered or unexported fields
}

Menu represents any menu node

func (*Menu) NewItem

func (m *Menu) NewItem(label string, event event.Menu)

NewItem adds a item to menu node

func (*Menu) NewMenu

func (m *Menu) NewMenu(label string) *Menu

NewMenu returns new submenu node

type Window

type Window struct {
	// contains filtered or unexported fields
}

Window represents inner window

func (*Window) Clear

func (w *Window) Clear()

Clear clears current window

func (*Window) Drop

func (w *Window) Drop()

Drop deletes window Note that a dropped window can no longer be used

func (*Window) Fill

func (w *Window) Fill(rect image.Rectangle, foreground color.Color)

Fill draws a rectangle with specified size and foreground color

func (*Window) Image

func (w *Window) Image(rect image.Rectangle, img *Image)

ImageScale draws a image into specified rectangle

func (*Window) Line

func (w *Window) Line(from image.Point, to image.Point, foreground color.Color)

Line draws a color line connecting two specified points

func (*Window) Raise

func (w *Window) Raise()

Raise brings the window to the forefront

func (*Window) Show

func (w *Window) Show()

Show sends the contents of the window to the screen Note that a drawings are not visible until Show

func (*Window) Size

func (w *Window) Size(rect image.Rectangle)

Size changes window size and position

func (*Window) Text

func (w *Window) Text(text string, font *Font, from image.Point, foreground color.Color)

Text draws a text at specified location using a specified font and foreground color