[![Build Status](https://travis-ci.org/andlabs/ui.png?branch=master)](https://travis-ci.org/andlabs/ui) # Native UI library for Go ### THIS PACKAGE IS UNDER ACTIVE DEVELOPMENT. It can be used; the API is stable enough at this point, but keep in mind there may still be crashes and API changes, as suggestions are always open. If you can help, please do! Run `./test` to build a test binary `test/test` which runs a (mostly) feature-complete UI test. Run `./d32 ./test` to build a 32-bit version (you will need a cgo-enabled 32-bit go environment, and I have only tested this on Mac OS X). For Windows targets, you will need a cgo-enabled windows/386 *AND* windows/amd64 to regenerate the autogenerated zconstants_windows_*.go files (cross-compiling multiple cgo-enabled targets in Go isn't possible yet; [I have a CL pending that will make it so](https://codereview.appspot.com/93580043) (it's too late for Go 1.3 but it might land in 1.4; you can try applying it yourself but; I also don't intend on adding a flag to suppress regeneration lest I get complacent and start using it myself and introduce some mystery bug); native Windows targets should be able to work fine, but I haven't tested it). ### UPDATE 12 March 2014: Windows 2000 is no longer supported [as it is no longer supported by Go](https://codereview.appspot.com/74790043). ### UPDATE 18 March 2014: Resizes are now assumed to stop other UI event processing, and thus do not run with locks anymore. I changed real control resizing so that it doesn't need to lock (it just fills an array with data fed in), but real control `preferredSize()` and `Stack`/`Grid.setRect()` could potentially still be racy... if I am right it won't be an issue, but if anyone else knows, please let me know. (Everything else is thread-safe again.) ### UPDATE 27 March 2014: Unix builds now require go tip due to a [cgo fix that affected this package](https://code.google.com/p/go/issues/detail?id=7548). ### UPDATE 12 April 2014: Areas now require their images to be `image.RGBA`, not `image.NRGBA`. Update your code appropriately. This is a simple library for building cross-platform GUI programs in Go. It targets Windows, Mac OS X, Linux, and other Unixes, and provides a thread-safe, channel-based API. The API itself is minimal; it aims to provide only what is necessary for GUI program design. That being said, suggestions are welcome. Layout is done using various layout managers, and some effort is taken to conform to the target platform's UI guidelines. Otherwise, the library uses native toolkits. ui aims to run on all supported versions of supported platforms. To be more precise, the system requirements are: * Windows: Windows XP or newer. The Windows backend uses package `syscall` and calls Windows DLLs directly, so does not rely on cgo. * Note: it does, however, rely on a pregenerated set of constants based on the Windows header files. I locally build a new one each time and these are included in the repo as zconstants_windows_*.go; you can rebuild them yourself with the included tools/windowsconstgen.go (see test.sh). * Mac OS X: Mac OS X 10.6 (Snow Leopard) or newer. Objective-C code is used directly for maximum portability, and thus this uses cgo. * Note: you will need Go 1.3 or newer (so until it is released, [go tip](http://tip.golang.org/doc/install/source#head)) for this verison, as it uses Objective-C. * Other Unixes: The Unix backend uses GTK+, and thus cgo. It requires GTK+ 3.4 or newer; for Ubuntu this means 12.04 LTS (Precise Pangolin) at minimum. Check your distribution. * Note: you will need Go 1.3 or newer (as above) due to various cgo errors fixed in this version (such as [this one](https://code.google.com/p/go/issues/detail?id=7548)). ui itself has no outside Go package dependencies; it is entirely self-contained. To install, simply `go get` this package. On Mac OS X, make sure you have the Apple development headers. On other Unixes, make sure you have the GTK+ development files: * for Ubuntu, `libgtk-3-dev` is sufficient * for FreeBSD with the pkgng system, `gtk3` is sufficient, however you will need to manually install `pkgconf` to please cgo (and you may need to specify `CC=gcc47`) (this should be put on the Go wiki) Package documentation is available at http://godoc.org/github.com/andlabs/ui. For an example of how ui is used, see https://github.com/andlabs/wakeup, which is a small program that implements a basic alarm clock. ## Known To Have Ever Been Built Matrices For convenience's sake, here are matrices of builds that I have personally done at least once. Each cell represents the run status. These matrices represent builds that I have done at any point in development; it is not a guarantee that the current version works. (I built this list to answer questions of whether or not ui works with a specific configuration.) Only configurations marked with a * are tested during active development. "(invalid)" means the given OS/arch combination is not supported by Go. | 386 | amd64 | arm ----- | ----- | ----- | ----- windows | works on windows; works on wine* | works on windows; fails on wine | (invalid) linux | see table below | see table below | Raspian: works darwin (Mac OS X) | works* (cross-compiled from 64-bit) | works* | (invalid) dragonfly | untested | untested | (invalid) freebsd | works | untested (VM failure) | untested netbsd | untested | untested | untested openbsd | untested | untested | (invalid) solaris | (invalid) | Oracle Solaris 11: **GTK+ 3 not available from official repos** | (invalid) plan9 | (not written yet; problems building Go) | (not written) | (invalid) nacl | (not sure how to handle) | (not sure how to handle) | (invalid) linux | 386 | amd64 ----- | ----- | ----- | ----- Kubuntu (14.04) | works; cross-compiling on 64-bit Linux fails due to nonexistent .so symlinks | works* Fedora | untested | untested openSUSE | untested | untested Arch Linux | untested | untested Mandriva (TODO choose between PCLinuxOS and Mageia - it appears the original Mandriva is either dead or nonfree and I would rather choose the fork that structures packages identically for parity; do they both?) | untested | untested Slackware | untested | untested Gentoo | untested | untested (The above list should cover all the bases of major Linux distributions and variants thereof; I might add a dedicated Debian test later but other than that... suggestions welcome. Kubuntu 64-bit is my main system and the main development platform; the Windows builds are cross-compiled from here. And yes, this also implies I seriously consider a Plan 9 port of the library using [libcontrol](http://plan9.bell-labs.com/magic/man2html/2/control), though I'm guessing this will blow up in my face due to any possible conflicts between libthread and Go's runtime (I need to see how the Go runtime implements OS threads on Plan 9).) ## Contributing Contributions are welcome. File issues, pull requests, approach me on IRC (pietro10 in #go-nuts; andlabs elsewhere), etc. Even suggestions are welcome: while I'm mainly drawing from my own GUI programming experience, everyone is different. I have received emails, however I am not likely to see those right away, so I don't suggest contacting me by email if your communication is urgent. If you want to dive in, read implementation.md: this is a description of how the library works. (Feel free to suggest improvements to this as well.) The other .md files in this repository contain various development notes. Please suggest documentation improvements as well.