dialog

README

dialog

Simple cross-platform dialog API for go-lang

examples

ok := dialog.Message("%s", "Do you want to continue?").Title("Are you sure?").YesNo()

Creates a dialog box titled "Are you sure?", containing the message "Do you want to continue?", a "Yes" button and a "No" button. Returns true iff the dialog could be displayed and the user pressed the "Yes" button.

filename, err := dialog.File().Filter("Mp3 audio file", "mp3").Load()

Creates a file selection dialog allowing the user to select a .mp3 file. The absolute path of the file is returned, unless an error is encountered or the user cancels/closes the dialog. In the latter case, filename will be the empty string and err will equal dialog.Cancelled.

filename, err := dialog.File().Filter("XML files", "xml").Title("Export to XML").Save()

Asks the user for a filename to write data into. If the user selects a file which already exists, an additional dialog is spawned to confirm they want to overwrite the existing file.

directory, err := dialog.Directory().Title("Load images").Browse()

Asks the user for a directory.

platform details

• OSX: uses Cocoa's NSAlert/NSSavePanel/NSOpenPanel/NSApp classes
  • requires macOS 10.6+ for NSApplicationActivationPolicyAccessory
• Win32: uses MessageBox/GetOpenFileName/GetSaveFileName (via package github.com/TheTitanrain/w32)
• Linux: uses Gtk's MessageDialog/FileChooserDialog (via cgo; requires gtk3 development packages)

build

go mod download
go build

bugs

On windows, the Load() and Save() calls change the working directory for the whole process while the dialog is open (after which it reset). This is an apparently unavoidable side effect of the underlying W32API; see #63 for more details.

Documentation

Overview

Package dialog provides a simple cross-platform common dialog API. Eg. to prompt the user with a yes/no dialog:

if dialog.MsgDlg("%s", "Do you want to continue?").YesNo() {
    // user pressed Yes
}

The general usage pattern is to call one of the toplevel *Dlg functions which return a *Builder structure. From here you can optionally call configuration functions (eg. Title) to customise the dialog, before using a launcher function to run the dialog.

Index

• Variables
• type DirectoryBuilder
  • func Directory() *DirectoryBuilder
  • func (b *DirectoryBuilder) Browse() (string, error)
  • func (b *DirectoryBuilder) SetStartDir(dir string) *DirectoryBuilder
  • func (b *DirectoryBuilder) Title(title string) *DirectoryBuilder
• type Dlg
• type FileBuilder
  • func File() *FileBuilder
  • func (b *FileBuilder) Filter(desc string, extensions ...string) *FileBuilder
  • func (b *FileBuilder) Load() (string, error)
  • func (b *FileBuilder) Save() (string, error)
  • func (b *FileBuilder) SetStartDir(startDir string) *FileBuilder
  • func (b *FileBuilder) SetStartFile(startFile string) *FileBuilder
  • func (b *FileBuilder) Title(title string) *FileBuilder
• type FileFilter
• type MsgBuilder
  • func Message(format string, args ...interface{}) *MsgBuilder
  • func (b *MsgBuilder) Error()
  • func (b *MsgBuilder) Info()
  • func (b *MsgBuilder) Title(title string) *MsgBuilder
  • func (b *MsgBuilder) YesNo() bool

Variables

var Cancelled = ErrCancelled

Cancelled refers to ErrCancelled. Deprecated: Use ErrCancelled instead.

var ErrCancelled = errors.New("Cancelled")

ErrCancelled is an error returned when a user cancels/closes a dialog.

Types

type DirectoryBuilder

type DirectoryBuilder struct {
	Dlg
	StartDir string
}

DirectoryBuilder is used for directory browse dialogs.

func Directory

func Directory() *DirectoryBuilder

Directory initialises a DirectoryBuilder using the default configuration.

func (*DirectoryBuilder) Browse

func (b *DirectoryBuilder) Browse() (string, error)

Browse spawns the directory selection dialog using the configured settings, asking the user to select a single folder. Returns ErrCancelled as the error if the user cancels or closes the dialog.

func (*DirectoryBuilder) SetStartDir

func (b *DirectoryBuilder) SetStartDir(dir string) *DirectoryBuilder

StartDir specifies the initial directory to be used for the dialog.

func (*DirectoryBuilder) Title

func (b *DirectoryBuilder) Title(title string) *DirectoryBuilder

Title specifies the title to be used for the dialog.

type Dlg

type Dlg struct {
	Title string
}

Dlg is the common type for dialogs.

type FileBuilder

type FileBuilder struct {
	Dlg
	StartDir  string
	StartFile string
	Filters   []FileFilter
}

FileBuilder is used for creating file browsing dialogs.

func File

func File() *FileBuilder

File initialises a FileBuilder using the default configuration.

func (*FileBuilder) Filter

func (b *FileBuilder) Filter(desc string, extensions ...string) *FileBuilder

Filter adds a category of files to the types allowed by the dialog. Multiple calls to Filter are cumulative - any of the provided categories will be allowed. By default all files can be selected.

The special extension '*' allows all files to be selected when the Filter is active.

func (*FileBuilder) Load

func (b *FileBuilder) Load() (string, error)

Load spawns the file selection dialog using the configured settings, asking the user to select a single file. Returns ErrCancelled as the error if the user cancels or closes the dialog.

func (*FileBuilder) Save

func (b *FileBuilder) Save() (string, error)

Save spawns the file selection dialog using the configured settings, asking the user for a filename to save as. If the chosen file exists, the user is prompted whether they want to overwrite the file. Returns ErrCancelled as the error if the user cancels/closes the dialog, or selects not to overwrite the file.

func (*FileBuilder) SetStartDir

func (b *FileBuilder) SetStartDir(startDir string) *FileBuilder

SetStartDir specifies the initial directory of the dialog.

func (*FileBuilder) SetStartFile

func (b *FileBuilder) SetStartFile(startFile string) *FileBuilder

SetStartFile specifies the initial file name of the dialog.

func (*FileBuilder) Title

func (b *FileBuilder) Title(title string) *FileBuilder

Title specifies the title to be used for the dialog.

type FileFilter

type FileFilter struct {
	Desc       string
	Extensions []string
}

FileFilter represents a category of files (eg. audio files, spreadsheets).

type MsgBuilder

type MsgBuilder struct {
	Dlg
	Msg string
}

MsgBuilder is used for creating message boxes.

func Message

func Message(format string, args ...interface{}) *MsgBuilder

Message initialises a MsgBuilder with the provided message.

func (*MsgBuilder) Error

func (b *MsgBuilder) Error()

Error spawns the message dialog with an error icon and single button, "Ok".

func (*MsgBuilder) Info

func (b *MsgBuilder) Info()

Info spawns the message dialog with an information icon and single button, "Ok".

func (*MsgBuilder) Title

func (b *MsgBuilder) Title(title string) *MsgBuilder

Title specifies what the title of the message dialog will be.

func (*MsgBuilder) YesNo

func (b *MsgBuilder) YesNo() bool

YesNo spawns the message dialog with two buttons, "Yes" and "No". Returns true iff the user selected "Yes".