dialog

Documentation

Overview

Package dialog implements native, cross-platform message boxes, yes/no/okay/cancel confirmation prompts, file pickers, and others.

This is a light-weight implementation (without using cgo or gtk bindings etc.) for developers who just need these basic features with a basic API.

There are more complete options. Here are some:

• sqweek/dialog
• ncruces/zenity

sqweek/dialog: https://github.com/sqweek/dialog ncruces/zenity:https://github.com/ncruces/zenity

On Windows, this package uses the native windows dialogs, converts Go strings into Windows UTF-16, handles null terminators, and uses the right-to-left display mode when using a RTL writing system such as Arabic or Hebrew. This package uses the older (pre-Vista) APIs because the new APIs make an awkward mix with Go's concurrency model and we don't want that to complicate our API just for simple features.

On other systems (Linux, etc), this package uses (in order of priority) one or more of:

• zenity
• xmessage
• whiptail in an xterm
• osascript (Apple script) (TODO) (Note: not tested!)

Native windows and zenity dialogs will use localised text where possible, but fallback implementations based on xmessage and others may default to using English.

Feature support:

Platform/software | Message.Raise | Message.Ask | FilePicker
------------------------------------------------------------
Windows           | Yes           | Yes         | Yes
zenity            | Yes           | Yes         | Yes
xmessage          | Yes           | Yes         |  No
whiptail + xterm  |  No           | Yes         | Yes

Additional feature support:

Platform/software | ColorPicker | DatePicker
----------------------------------------------------------
Windows           |  No         |  No
zenity            | Yes         | Yes
xmessage          |  No         |  No
whiptail + xterm  | Yes         | Yes

Please note: the message box appears on the local system. If you are writing a web application and want a message to appear in a client's web browser, output HTML such as "<script>alert('Hello');</script>" instead!

Index

• func Alert(message string, args ...interface{})
• func Ask(message string, args ...interface{}) (bool, error)
• func Error(message string, args ...interface{}) error
• func Open(file string) (string, bool, error)
• func OpenMultiple(file string) ([]string, bool, error)
• func Raise(message string, args ...interface{}) error
• func Save(file string) (string, bool, error)
• func Warning(message string, args ...interface{}) error
• type FilePicker
  • func (m FilePicker) Open() (string, bool, error)
  • func (m FilePicker) OpenMultiple() ([]string, bool, error)
  • func (m FilePicker) Save() (string, bool, error)
• type IconType
• type Message
  • func (m Message) Ask() (bool, error)
  • func (m Message) Raise() error
  • func (m Message) WithArgs(args ...interface{}) Message
• type Support
  • func Supported() (Support, error)

Functions

func Alert

func Alert(message string, args ...interface{})

Alert is like Raise, but doesn't return any error message on failure.

Deprecated. This is here for legacy reasons. Use Raise instead.

func Ask

func Ask(message string, args ...interface{}) (bool, error)

Ask is a convenience function to display a modal message box asking a question. The message string can be a printf-style format string for an optional sequence of additional arguments of any type. It blocks until an option is picked. Where not supported, immediately returns true without blocking.

func Error

func Error(message string, args ...interface{}) error

Error is like Raise, but uses an error icon and title bar.

func Open

func Open(file string) (string, bool, error)

Open is a convenience function to display a file picker dialog to select a single file. It blocks until an option is picked, then returns the selected path as an absolute path, and true, or an empty string and false if no file was selected (i.e. the user selected the cancel option).

Where not supported, immediately returns ("", false, nil) without blocking (see Supported).

Note that this does not actually read the file or open it for writing, but merely selects a path.

func OpenMultiple

func OpenMultiple(file string) ([]string, bool, error)

OpenMultiple is like Open, but allows multiple files to be selected. Each returned path is still an absolute path.

func Raise

func Raise(message string, args ...interface{}) error

Raise is a convenience function to display a modal message box with a message. The message string can be a printf-style format string for an optional sequence of additional arguments of any type. It blocks until an option is picked. Where not supported, immediately returns without blocking.

func Save

func Save(file string) (string, bool, error)

Save is like Open, but for picking a file to write to. This may change the look of the file picker (e.g. to have a button that says "Save" instead of "Open").

Note that this does not actually write to the file or open it for writing, but merely selects a path.

func Warning

func Warning(message string, args ...interface{}) error

Warning is like Raise, but uses a warning icon and title bar.

Types

type FilePicker

type FilePicker struct {
	// Title is the file picker window title (may be empty) e.g. "Open" or
	// "Save". If the implementation has a locale-aware default, then this
	// is ignored and the default is used instead.
	Title string

	// Path is the initial file selected (if empty, defaults to
	// current working directory). To open in a specific directory without
	// specifying a file name, use a trailing slash.
	Path string

	// FileTypes is hint describing known file types and file extensions. It
	// may be used to filter visible files. May be nil. This is a slice of
	// 2-tuples. The first item in the tuple is a human-readable label, the
	// second item in the tuple is a list of patterns delimited by space. Can
	// be left as nil as default. ("All Files", "*.*") is automatically added
	// to the end if the last item doesn't have the exact filter "*.*".
	//
	// For example:
	//
	//   FileTypes: [][2]string{
	//       {"Text Document", "*.txt *.rtf"},
	//       {"Image",         "*.png"},
	//       ...
	//       {"Pob Ffeil",      "*.*"}, // suppress English "All Files"
	//   }
	FileTypes [][2]string

	// DefaultFileType is an index into the FileTypes array identifying the
	// default file type to use.
	DefaultFileType int

	// AlwaysShowHidden, if true, is a hint that hidden files should always be
	// revealed if possible. If false, is a hint that hidden files should be
	// shown, or not shown, as normal depending on the user's settings.
	AlwaysShowHidden bool

	// AddToRecent, if true, is a hint that the opened or saved file should
	// be added to the user's history of recent files. If false, is a hint
	// that the file should not be added to that history.
	AddToRecent bool
}

FilePicker is a dialog to select file(s) to load or save.

func (FilePicker) Open

func (m FilePicker) Open() (string, bool, error)

Open displays a file picker dialog to select a single file. It blocks until an option is picked, then returns the selected path as an absolute path, and true, or an empty string and false if no file was selected (i.e. the user selected the cancel option).

Where not supported, immediately returns ("", false, nil) without blocking (see Supported).

Note that this does not actually read the file or open it for writing, but merely selects a path.

func (FilePicker) OpenMultiple

func (m FilePicker) OpenMultiple() ([]string, bool, error)

OpenMultiple is like FilePicker.Open, but allows multiple files to be selected. Each returned path is still an absolute path.

func (FilePicker) Save

func (m FilePicker) Save() (string, bool, error)

Save is like FilePicker.Open, but for writing to a file. This may change the look of the file picker (e.g. to have a button that says "Save" instead of "Open").

Note that this does not actually write to the file or open it for writing, but merely selects a path.

type IconType

type IconType int

const (
	IconInfo IconType = iota
	IconWarning
	IconError
)

type Message

type Message struct {
	// Title is the message box window title (may be empty).
	Title string

	// Format is a printf-style format string. This is word-wrapped for you.
	Format string

	// Args are printf-style arguments
	Args []interface{}

	// Icon is a IconInfo, IconWarning, or IconError and is displayed when
	// possible on the message box.
	Icon IconType
}

Message is a prompt or question.

func (Message) Ask

func (m Message) Ask() (bool, error)

Ask displays a message as a question and returns true if the affirmative option (such as "yes" or "okay") is picked, or false if the negative option (such as "no" or "cancel") is picked. It blocks until an option is picked.

Where fully supported by a platform, the options are "yes" and "no" as appropriate for the current language and locale. Otherwise, the options may default to English-language.

Where not supported, immediately returns true without blocking.

Ask also ignores the supplied icon option and sets an appropriate question icon instead.

func (Message) Raise

func (m Message) Raise() error

Raise displays a message. It blocks until the message is acknowledged (for example by clicking "Okay").

Where not supported, returns immediately without blocking.

func (Message) WithArgs

func (m Message) WithArgs(args ...interface{}) Message

WithArgs returns Message with the Args field set.

type Support

type Support struct {
	MessageRaise    bool // Can use Message.Raise?
	MessageAsk      bool // Can use Message.Ask?
	FilePicker      bool // Can use FilePicker.Open, FilePicker.Save?
	MultiFilePicker bool // Can use FilePicker.OpenMultiple?
	ColorPicker     bool // Can use ColorPicker.Pick?
	DatePicker      bool // Can use DatePicker.Pick?
}

func Supported

func Supported() (Support, error)

Supported returns a Support struct detailing what features are available on the current system. Using a feature that isn't supported will silently proceed as documented.