zenity

README

Zenity dialogs for Golang, Windows and macOS

This repo includes both a cross-platform Go package providing Zenity-like dialogs (simple dialogs that interact graphically with the user), 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

Overview

Package zenity provides cross-platform access to simple dialogs that interact graphically with the user.

It is inspired by, and closely follows the API of, the zenity program, which it uses to provide the functionality on various Unixes. See:

https://help.gnome.org/users/zenity/

This package does not require cgo, and it does not impose any threading or initialization requirements.

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
• type FileFilters
• 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.")

ErrExtraButton is returned by dialog functions when the extra button is pressed.

Functions

func Error

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

Error displays the 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)

Info displays the 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)

Question displays the 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)

SelectColor displays the 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)

SelectFile displays the 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"}},
		})
}

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)

SelectFileMutiple displays the 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"}},
		})
}

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)

SelectFileSave displays the 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"}},
		})
}

func Warning

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

Warning displays the 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 is an Option that sets a filename filter.

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

type FileFilters

type FileFilters []FileFilter

FileFilters is an Option that sets multiple filename filters.

type MessageIcon

type MessageIcon int

MessageIcon is the enumeration for message dialog icons.

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

Icons for

type Option

type Option interface {
	// contains filtered or unexported methods
}

An Option is an argument passed to dialog functions to customize their behavior.

func CancelLabel

func CancelLabel(cancel string) Option

CancelLabel returns an Option to set the label of the Cancel button.

func Color

func Color(c color.Color) Option

Color returns an Option to set the color.

func ConfirmCreate

func ConfirmCreate() Option

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

func ConfirmOverwrite

func ConfirmOverwrite() Option

ConfirmOverwrite returns an Option to confirm file selection if filename already exists.

func DefaultCancel

func DefaultCancel() Option

DefaultCancel returns an Option to give Cancel button focus by default.

func Directory

func Directory() Option

Directory returns an Option to activate directory-only selection.

func Ellipsize

func Ellipsize() Option

Ellipsize returns an Option to enable ellipsizing in the dialog text.

func ExtraButton

func ExtraButton(extra string) Option

ExtraButton returns an Option to add an extra button.

func Filename

func Filename(filename string) Option

Filename returns an 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

Icon returns an Option to set the dialog icon.

func NoWrap

func NoWrap() Option

NoWrap returns an Option to disable enable text wrapping.

func OKLabel

func OKLabel(ok string) Option

OKLabel returns an Option to set the label of the OK button.

func ShowHidden

func ShowHidden() Option

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

func ShowPalette

func ShowPalette() Option

ShowPalette returns an Option to show the palette.

func Title

func Title(title string) Option

Title returns an Option to set the dialog title.