zenity

README

Zenity dialogs for Golang, Windows and macOS

This repo includes both a cross-platform Go package providing Zenity-like dialogs, as well as a “port” of the zenity command to both Windows and macOS based on that library.

This is a work in progress.

Lots of things are missing. For now, these are the only implemented dialogs:

• message (error, info, question, warning)
• file selection
• color selection

Behavior on Windows, macOS and other Unixes might differ slightly. Some of that is intended (reflecting platform differences), other bits are unfortunate limitations, others still are open to be fixed.

Why?

There are a bunch of other dialog packages for Go.
Why reinvent this particular wheel?

Requirements:

• no cgo (see benefits, mostly cross-compilation)
• no main loop (or other threading requirements)
• no initialization
• on Windows:
  • no additional dependencies
    • Explorer shell not required
    • works in Server Core
  • Unicode support
  • WSL/Cygwin/MSYS2 support
• on macOS:
  • only dependency is osascript
• on other Unixes:
  • wraps either one of zenity, qarma, matedialog

Documentation

Index

• Constants
• func Error(text string, options ...Option) (bool, error)
• func Info(text string, options ...Option) (bool, error)
• func Question(text string, options ...Option) (bool, error)
• func SelectColor(options ...Option) (color.Color, error)
• func SelectFile(options ...Option) (string, error)
• func SelectFileMutiple(options ...Option) ([]string, error)
• func SelectFileSave(options ...Option) (string, error)
• func Warning(text string, options ...Option) (bool, error)
• type FileFilter
  • func (f FileFilter) Build() Option
• type FileFilters
  • func (f FileFilters) Build() Option
• type MessageIcon
• type Option
  • func CancelLabel(cancel string) Option
  • func Color(c color.Color) Option
  • func ConfirmCreate() Option
  • func ConfirmOverwrite() Option
  • func DefaultCancel() Option
  • func Directory() Option
  • func Ellipsize() Option
  • func ExtraButton(extra string) Option
  • func Filename(filename string) Option
  • func Icon(icon MessageIcon) Option
  • func NoWrap() Option
  • func OKLabel(ok string) Option
  • func ShowHidden() Option
  • func ShowPalette() Option
  • func Title(title string) Option

Examples

• Error
• Info
• Question
• SelectColor
• SelectColor (Palette)
• SelectFile
• SelectFile (Directory)
• SelectFileMutiple
• SelectFileMutiple (Directory)
• SelectFileSave
• Warning

Constants

const ErrExtraButton = constError("Extra button pressed.")

Functions

func Error

func Error(text string, options ...Option) (bool, error)

Display error dialog.

Returns true on OK, false on dismiss, or ErrExtraButton.

Valid options: Title, Icon, OKLabel, ExtraButton, NoWrap, Ellipsize.

Example

package main

import (
	"github.com/ncruces/zenity"
)

func main() {
	zenity.Error("An error has occurred.",
		zenity.Title("Error"),
		zenity.Icon(zenity.ErrorIcon))
}

func Info

func Info(text string, options ...Option) (bool, error)

Display info dialog.

Returns true on OK, false on dismiss, or ErrExtraButton.

Valid options: Title, Icon, OKLabel, ExtraButton, NoWrap, Ellipsize.

Example

package main

import (
	"github.com/ncruces/zenity"
)

func main() {
	zenity.Info("All updates are complete.",
		zenity.Title("Information"),
		zenity.Icon(zenity.InfoIcon))
}

func Question

func Question(text string, options ...Option) (bool, error)

Display question dialog.

Returns true on OK, false on Cancel, or ErrExtraButton.

Valid options: Title, Icon, OKLabel, CancelLabel, ExtraButton, NoWrap, Ellipsize, DefaultCancel.

Example

package main

import (
	"github.com/ncruces/zenity"
)

func main() {
	zenity.Question("Are you sure you want to proceed?",
		zenity.Title("Question"),
		zenity.Icon(zenity.QuestionIcon))
}

func SelectColor

func SelectColor(options ...Option) (color.Color, error)

Display color selection dialog.

Returns nil on cancel.

Valid options: Title, Color, ShowPalette.

Example

package main

import (
	"image/color"

	"github.com/ncruces/zenity"
)

func main() {
	zenity.SelectColor(
		zenity.Color(color.NRGBA{R: 0x66, G: 0x33, B: 0x99, A: 0x80}))
}

Example (Palette)

package main

import (
	"image/color"

	"github.com/ncruces/zenity"
)

func main() {
	zenity.SelectColor(
		zenity.ShowPalette(),
		zenity.Color(color.NRGBA{R: 0x66, G: 0x33, B: 0x99, A: 0xff}))
}

func SelectFile

func SelectFile(options ...Option) (string, error)

Display file selection dialog.

Returns an empty string on cancel.

Valid options: Title, Directory, Filename, ShowHidden, FileFilter(s).

Example

package main

import (
	"github.com/ncruces/zenity"
)

const defaultPath = ""

func main() {
	zenity.SelectFile(
		zenity.Filename(defaultPath),
		zenity.FileFilters{
			{"Go files", []string{"*.go"}},
			{"Web files", []string{"*.html", "*.js", "*.css"}},
			{"Image files", []string{"*.png", "*.gif", "*.ico", "*.jpg", "*.webp"}},
		}.Build())
}

Example (Directory)

package main

import (
	"github.com/ncruces/zenity"
)

const defaultPath = ""

func main() {
	zenity.SelectFile(
		zenity.Filename(defaultPath),
		zenity.Directory())
}

func SelectFileMutiple

func SelectFileMutiple(options ...Option) ([]string, error)

Display multiple file selection dialog.

Returns a nil slice on cancel.

Valid options: Title, Directory, Filename, ShowHidden, FileFilter(s).

Example

package main

import (
	"github.com/ncruces/zenity"
)

const defaultPath = ""

func main() {
	zenity.SelectFileMutiple(
		zenity.Filename(defaultPath),
		zenity.FileFilters{
			{"Go files", []string{"*.go"}},
			{"Web files", []string{"*.html", "*.js", "*.css"}},
			{"Image files", []string{"*.png", "*.gif", "*.ico", "*.jpg", "*.webp"}},
		}.Build())
}

Example (Directory)

package main

import (
	"github.com/ncruces/zenity"
)

const defaultPath = ""

func main() {
	zenity.SelectFileMutiple(
		zenity.Filename(defaultPath),
		zenity.Directory())
}

func SelectFileSave

func SelectFileSave(options ...Option) (string, error)

Display save file selection dialog.

Returns an empty string on cancel.

Valid options: Title, Filename, ConfirmOverwrite, ConfirmCreate, ShowHidden, FileFilter(s).

Example

package main

import (
	"github.com/ncruces/zenity"
)

const defaultName = ""

func main() {
	zenity.SelectFileSave(
		zenity.ConfirmOverwrite(),
		zenity.Filename(defaultName),
		zenity.FileFilters{
			{"Go files", []string{"*.go"}},
			{"Web files", []string{"*.html", "*.js", "*.css"}},
			{"Image files", []string{"*.png", "*.gif", "*.ico", "*.jpg", "*.webp"}},
		}.Build())
}

func Warning

func Warning(text string, options ...Option) (bool, error)

Display warning dialog.

Returns true on OK, false on dismiss, or ErrExtraButton.

Valid options: Title, Icon, OKLabel, ExtraButton, NoWrap, Ellipsize.

Example

package main

import (
	"github.com/ncruces/zenity"
)

func main() {
	zenity.Warning("Are you sure you want to proceed?",
		zenity.Title("Warning"),
		zenity.Icon(zenity.WarningIcon))
}

Types

type FileFilter

type FileFilter struct {
	Name     string   // display string that describes the filter (optional)
	Patterns []string // filter patterns for the display string
}

FileFilter encapsulates a filename filter.

macOS hides filename filters from the user, and only supports filtering by extension (or "type").

func (FileFilter) Build

func (f FileFilter) Build() Option

Build option to set a filename filter.

type FileFilters

type FileFilters []FileFilter

FileFilters is a list of filename filters.

func (FileFilters) Build

func (f FileFilters) Build() Option

Build option to set filename filters.

type MessageIcon

type MessageIcon int

MessageIcon is the enumeration for message dialog icons.

const (
	ErrorIcon MessageIcon = iota + 1
	WarningIcon
	InfoIcon
	QuestionIcon
)

type Option

type Option func(*options)

Options are arguments passed to dialog functions to customize their behavior.

func CancelLabel

func CancelLabel(cancel string) Option

Option to set the label of the Cancel button.

func Color

func Color(c color.Color) Option

Option to set the color.

func ConfirmCreate

func ConfirmCreate() Option

Option to confirm file selection if filename does not yet exist (Windows only).

func ConfirmOverwrite

func ConfirmOverwrite() Option

Option to confirm file selection if filename already exists.

func DefaultCancel

func DefaultCancel() Option

Option to give Cancel button focus by default.

func Directory

func Directory() Option

Option to activate directory-only selection.

func Ellipsize

func Ellipsize() Option

Option to enable ellipsizing in the dialog text.

func ExtraButton

func ExtraButton(extra string) Option

Option to add an extra button.

func Filename

func Filename(filename string) Option

Option to set the filename.

You can specify a file name, a directory path, or both. Specifying a file name, makes it the default selected file. Specifying a directory path, makes it the default dialog location.

func Icon

func Icon(icon MessageIcon) Option

Option to set the dialog icon.

func NoWrap

func NoWrap() Option

Option to disable enable text wrapping.

func OKLabel

func OKLabel(ok string) Option

Option to set the label of the OK button.

func ShowHidden

func ShowHidden() Option

Option to show hidden files (Windows and macOS only).

func ShowPalette

func ShowPalette() Option

Option to show the palette.

func Title

func Title(title string) Option

Option to set the dialog title.