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

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
• on macOS:
  • only dependency is osascript (with JXA)
    • JavaScript is easier to template with html/template
• on other UNIXes:
  • wraps either one of qarma, zenity, matedialog
    • in that order of preference

Documentation

Index

• Constants
• func ConfirmOverwrite(o *options)
• func DefaultCancel(o *options)
• func Directory(o *options)
• func Ellipsize(o *options)
• func Error(text string, options ...Option) (bool, error)
• func Info(text string, options ...Option) (bool, error)
• func NoWrap(o *options)
• func Question(text string, options ...Option) (bool, 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
  • func (f FileFilters) New() Option
• type MessageIcon
• type Option
  • func CancelLabel(cancel string) Option
  • func ExtraButton(extra string) Option
  • func Filename(filename string) Option
  • func Icon(icon MessageIcon) Option
  • func OKLabel(ok string) Option
  • func Title(title string) Option

Examples

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

Constants

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

Functions

func ConfirmOverwrite

func ConfirmOverwrite(o *options)

Option to confirm file selection if filename already exists.

func DefaultCancel

func DefaultCancel(o *options)

Option to give Cancel button focus by default.

func Directory

func Directory(o *options)

Option to activate directory-only selection.

func Ellipsize

func Ellipsize(o *options)

Option to enable ellipsizing in the dialog text.

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 occured.",
		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 NoWrap

func NoWrap(o *options)

Option to disable enable text wrapping.

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 SelectFile

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

Display file selection dialog.

Returns an empty string on cancel.

Valid options: Title, Directory, Filename, FileFilters.

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"}},
		}.New())
}

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, FileFilters.

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"}},
		}.New())
}

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, FileFilters.

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"}},
		}.New())
}

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.

type FileFilters

type FileFilters []FileFilter

FileFilters is a list of filename filters.

macOS hides filename filters from the user, and only supports filtering by extension (or "type"). We make an effort to convert any "*.EXT" like patterns.

func (FileFilters) New

func (f FileFilters) New() Option

Creates Option to set the filename filter list.

type MessageIcon

type MessageIcon int

MessageIcon is the enumeration for message dialog icons.

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

type Option

type Option func(*options)

Options are arguments you pass to dialog functions to customize their behavior.

func CancelLabel

func CancelLabel(cancel string) Option

Option to set the label of the Cancel button.

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, make it the default dialog location.

func Icon

func Icon(icon MessageIcon) Option

Option to set the dialog icon.

func OKLabel

func OKLabel(ok string) Option

Option to set the label of the OK button.

func Title

func Title(title string) Option

Option to set the dialog title.