zenity

package module
v0.8.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 7, 2022 License: MIT Imports: 11 Imported by: 130

README

Zenity dialogs for Golang, Windows and macOS

Go Reference Go Report Go Cover Mentioned in Awesome Go

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.

Implemented dialogs:

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

Installing

The Go package:

go get github.com/ncruces/zenity

The zenity command on macOS/WSL using Homebrew:

brew install ncruces/tap/zenity

The zenity command on macOS/Windows if you have Go:

go install github.com/ncruces/zenity/cmd/zenity@latest

Or download the latest release.

Why?

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

Benefits:
  • no cgo (see benefits, mostly cross-compilation)
  • no main loop (or any other threading or initialization requirements)
  • cancelation through context
  • on Windows:
    • no additional dependencies
      • Explorer shell not required
      • works in Server Core
    • Unicode support
    • High DPI (no manifest required)
    • Visual Styles (no manifest required)
    • 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/stable/

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

Index

Examples

Constants

View Source 
const ErrCanceled = zenutil.ErrCanceled

ErrCanceled is returned when the cancel button is pressed, or window functions are used to close the dialog.

View Source 
const ErrExtraButton = zenutil.ErrExtraButton

ErrExtraButton is returned when the extra button is pressed.

View Source 
const ErrUnsupported = zenutil.ErrUnsupported

ErrUnsupported is returned when a combination of options is not supported.

Variables

This section is empty.

Functions

func Calendar added in v0.8.0 

func Calendar(text string, options ...Option) (time.Time, error)

Calendar displays the calendar dialog.

Valid options: Title, Width, Height, OKLabel, CancelLabel, ExtraButton, Icon, DefaultDate.

May return: ErrCanceled.

Example 
package main

import (
	"time"

	"github.com/ncruces/zenity"
)

func main() {
	zenity.Calendar("Select a date from below:",
		zenity.DefaultDate(2006, time.January, 1))
}

Output:

func Entry added in v0.6.0 

func Entry(text string, options ...Option) (string, error)

Entry displays the text entry dialog.

Valid options: Title, Width, Height, OKLabel, CancelLabel, ExtraButton, Icon, EntryText, HideText.

May return: ErrCanceled, ErrExtraButton.

Example 
package main

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

func main() {
	zenity.Entry("Enter new text:",
		zenity.Title("Add a new entry"))
}

Output:

func Error 

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

Error displays the error dialog.

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

May return: ErrCanceled, ErrExtraButton.

Example 
package main

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

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

Output:

func Info 

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

Info displays the info dialog.

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

May return: ErrCanceled, ErrExtraButton.

Example 
package main

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

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

Output:

func List added in v0.6.2 

func List(text string, items []string, options ...Option) (string, error)

List displays the list dialog.

Valid options: Title, Width, Height, OKLabel, CancelLabel, ExtraButton, Icon, DefaultItems, DisallowEmpty.

May return: ErrCanceled, ErrExtraButton, ErrUnsupported.

Example 
package main

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

func main() {
	zenity.List(
		"Select items from the list below:",
		[]string{"apples", "oranges", "bananas", "strawberries"},
		zenity.Title("Select items from the list"),
		zenity.DisallowEmpty(),
	)
}

Output:

func ListItems added in v0.6.2 

func ListItems(text string, items ...string) (string, error)

ListItems displays the list dialog.

May return: ErrCanceled, ErrExtraButton.

Example 
package main

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

func main() {
	zenity.ListItems(
		"Select items from the list below:",
		"apples", "oranges", "bananas", "strawberries")
}

Output:

func ListMultiple added in v0.6.2 

func ListMultiple(text string, items []string, options ...Option) ([]string, error)

ListMultiple displays the list dialog, allowing multiple items to be selected.

Valid options: Title, Width, Height, OKLabel, CancelLabel, ExtraButton, Icon, DefaultItems, DisallowEmpty.

May return: ErrCanceled, ErrExtraButton, ErrUnsupported.

Example 
package main

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

func main() {
	zenity.ListMultiple(
		"Select items from the list below:",
		[]string{"apples", "oranges", "bananas", "strawberries"},
		zenity.Title("Select items from the list"),
		zenity.DefaultItems("apples", "bananas"),
	)
}

Output:

func ListMultipleItems added in v0.6.2 

func ListMultipleItems(text string, items ...string) ([]string, error)

ListMultipleItems displays the list dialog, allowing multiple items to be selected.

May return: ErrCanceled, ErrExtraButton.

Example 
package main

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

func main() {
	zenity.ListMultipleItems(
		"Select items from the list below:",
		"apples", "oranges", "bananas", "strawberries")
}

Output:

func Notify added in v0.4.0 

func Notify(text string, options ...Option) error

Notify displays a notification.

Valid options: Title, Icon.

Example 
package main

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

func main() {
	zenity.Notify("There are system updates necessary!",
		zenity.Title("Warning"),
		zenity.InfoIcon)
}

Output:

func Password added in v0.6.0 

func Password(options ...Option) (usr string, pwd string, err error)

Password displays the password dialog.

Valid options: Title, OKLabel, CancelLabel, ExtraButton, Icon, Username.

May return: ErrCanceled, ErrExtraButton, ErrUnsupported.

Example 
package main

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

func main() {
	zenity.Password(zenity.Title("Type your password"))
}

Output:
Example (Username) 
package main

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

func main() {
	zenity.Password(
		zenity.Title("Type your username and password"),
		zenity.Username())
}

Output:

func Question 

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

Question displays the question dialog.

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

May return: ErrCanceled, ErrExtraButton.

Example 
package main

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

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

Output:

func SelectColor added in v0.2.2 

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

SelectColor displays the color selection dialog.

Valid options: Title, Color, ShowPalette.

May return: ErrCanceled.

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}))
}

Output:
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}))
}

Output:

func SelectFile 

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

SelectFile displays the file selection dialog.

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

May return: ErrCanceled.

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

Output:
Example (Directory) 
package main

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

const defaultPath = ``

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

Output:

func SelectFileMutiple 

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

SelectFileMutiple displays the multiple file selection dialog.

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

May return: ErrCanceled, ErrUnsupported.

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

Output:
Example (Directory) 
package main

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

const defaultPath = ``

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

Output:

func SelectFileSave 

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

SelectFileSave displays the save file selection dialog.

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

May return: ErrCanceled.

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

Output:

func Warning 

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

Warning displays the warning dialog.

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

May return: ErrCanceled, ErrExtraButton.

Example 
package main

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

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

Output:

Types

type DialogIcon added in v0.4.0 

type DialogIcon int

DialogIcon is the enumeration for dialog icons. 

const (
	ErrorIcon DialogIcon
	WarningIcon
	InfoIcon
	QuestionIcon
	PasswordIcon
	NoIcon
)

The stock dialog icons.

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 "uniform type identifiers").

Patterns may use the fnmatch syntax on all platforms: https://docs.python.org/3/library/fnmatch.html

type FileFilters 

type FileFilters []FileFilter

FileFilters is an Option that sets multiple filename filters.

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 added in v0.2.2 

func Color(c color.Color) Option

Color returns an Option to set the color.

func ConfirmCreate added in v0.2.0 

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 Context added in v0.4.2 

func Context(ctx context.Context) Option

Context returns an Option to set a Context that can dismiss the dialog.

Dialogs dismissed by the Context return Context.Err.

func DefaultCancel 

func DefaultCancel() Option

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

func DefaultDate added in v0.8.0 

func DefaultDate(year int, month time.Month, day int) Option

DefaultDate returns an Option to set the date.

func DefaultItems added in v0.6.2 

func DefaultItems(items ...string) Option

DefaultItems returns an Option to set the items to initially select (macOS only).

func Directory 

func Directory() Option

Directory returns an Option to activate directory-only selection.

func DisallowEmpty added in v0.6.2 

func DisallowEmpty() Option

DisallowEmpty returns an Option to not allow zero items to be selected (macOS only).

func Ellipsize 

func Ellipsize() Option

Ellipsize returns an Option to enable ellipsizing in the dialog text (Unix only).

func EntryText added in v0.6.0 

func EntryText(text string) Option

EntryText returns an Option to set the entry 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 Height added in v0.5.3 

func Height(height uint) Option

Height returns an Option to set the dialog height (Unix only).

func HideText added in v0.6.0 

func HideText() Option

HideText returns an Option to hide the entry text.

func Icon 

func Icon(icon DialogIcon) Option

Icon returns an Option to set the dialog icon.

func MaxValue added in v0.7.0 

func MaxValue(value int) Option

MaxValue returns an Option to set the maximum value (Windows and macOS only). The default maximum value is 100.

func NoCancel added in v0.7.0 

func NoCancel() Option

NoCancel returns an Option to hide the Cancel button (Windows and Unix only).

func NoWrap 

func NoWrap() Option

NoWrap returns an Option to disable enable text wrapping (Unix only).

func OKLabel 

func OKLabel(ok string) Option

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

func Pulsate added in v0.7.0 

func Pulsate() Option

Pulsate returns an Option to pulsate the progress bar.

func ShowHidden added in v0.2.0 

func ShowHidden() Option

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

func ShowPalette added in v0.2.2 

func ShowPalette() Option

ShowPalette returns an Option to show the palette.

func TimeRemaining added in v0.7.0 

func TimeRemaining() Option

TimeRemaining returns an Option to estimate when progress will reach 100% (Unix only).

func Title 

func Title(title string) Option

Title returns an Option to set the dialog title.

func Username added in v0.6.0 

func Username() Option

Username returns an Option to display the username (Unix only).

func Width added in v0.5.3 

func Width(width uint) Option

Width returns an Option to set the dialog width (Unix only).

type ProgressDialog added in v0.7.0 

type ProgressDialog interface {
	// Text sets the dialog text.
	Text(string) error

	// Value sets how much of the task has been completed.
	Value(int) error

	// MaxValue gets how much work the task requires in total.
	MaxValue() int

	// Complete marks the task completed.
	Complete() error

	// Close closes the dialog.
	Close() error

	// Done returns a channel that's closed when the dialog is closed.
	Done() <-chan struct{}
}

ProgressDialog allows you to interact with the progress indication dialog.

func Progress added in v0.7.0 

func Progress(options ...Option) (ProgressDialog, error)

Progress displays the progress indication dialog.

Valid options: Title, Width, Height, OKLabel, CancelLabel, ExtraButton, Icon, MaxValue, Pulsate, NoCancel, TimeRemaining.

May return: ErrUnsupported

Example 
package main

import (
	"time"

	"github.com/ncruces/zenity"
)

func main() {
	dlg, err := zenity.Progress(
		zenity.Title("Update System Logs"))
	if err != nil {
		return
	}
	defer dlg.Close()

	dlg.Text("Scanning mail logs...")
	dlg.Value(0)
	time.Sleep(time.Second)

	dlg.Value(25)
	time.Sleep(time.Second)

	dlg.Text("Updating mail logs...")
	dlg.Value(50)
	time.Sleep(time.Second)

	dlg.Text("Resetting cron jobs...")
	dlg.Value(75)
	time.Sleep(time.Second)

	dlg.Text("Rebooting system...")
	dlg.Value(100)
	time.Sleep(time.Second)

	dlg.Complete()
	time.Sleep(time.Second)

}

Output:
Example (Pulsate) 
package main

import (
	"time"

	"github.com/ncruces/zenity"
)

func main() {
	dlg, err := zenity.Progress(
		zenity.Title("Update System Logs"),
		zenity.Pulsate())
	if err != nil {
		return
	}
	defer dlg.Close()

	dlg.Text("Scanning mail logs...")
	time.Sleep(time.Second)

	dlg.Text("Updating mail logs...")
	time.Sleep(time.Second)

	dlg.Text("Resetting cron jobs...")
	time.Sleep(time.Second)

	dlg.Text("Rebooting system...")
	time.Sleep(time.Second)

	dlg.Complete()
	time.Sleep(time.Second)

}

Output:

Source Files

View all Source files

Directories

Path Synopsis
cmd
zenity
internal
zenutil
Package zenutil is internal.
 Package zenutil is internal.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.