Documentation.

This commit is contained in:
Nuno Cruces 2020-01-10 12:00:38 +00:00
parent 92d793d294
commit 36bf362ec9
7 changed files with 129 additions and 94 deletions

View file

@ -12,14 +12,14 @@ For now, these are the only implemented dialogs:
* message (error, info, question, warning) * message (error, info, question, warning)
* file selection * file selection
Behavior on Windows, macOS and other UNIXes might differ sliglty. Behavior on Windows, macOS and other UNIXes might differ slightly.
Some of that is intended (reflecting platform differences), Some of that is intended (reflecting platform differences),
other bits are unfortunate limitations, other bits are unfortunate limitations,
others still open to be fixed. others still are open to be fixed.
## Why? ## Why?
There are a bunch of other dialog packages for Go. There are a bunch of other dialog packages for Go.\
Why reinvent this particular wheel? Why reinvent this particular wheel?
#### Requirements: #### Requirements:

View file

@ -90,7 +90,7 @@ func setupFlags() {
// Message options // Message options
flag.StringVar(&text, "text", "", "Set the dialog text") flag.StringVar(&text, "text", "", "Set the dialog text")
flag.StringVar(&iconName, "icon-name", "", "Set the dialog icon (error, information, question, warning)") flag.StringVar(&iconName, "icon-name", "", "Set the dialog icon (error, info, question, warning)")
flag.StringVar(&okLabel, "ok-label", "", "Set the label of the OK button") flag.StringVar(&okLabel, "ok-label", "", "Set the label of the OK button")
flag.StringVar(&cancelLabel, "cancel-label", "", "Set the label of the Cancel button") flag.StringVar(&cancelLabel, "cancel-label", "", "Set the label of the Cancel button")
flag.StringVar(&extraButton, "extra-button", "", "Add an extra button") flag.StringVar(&extraButton, "extra-button", "", "Add an extra button")

View file

@ -1,67 +1,54 @@
package zenity package zenity_test
import "testing" import "github.com/ncruces/zenity"
const defaultPath = "" const defaultPath = ""
const defaultName = ""
func TestSelectFile(t *testing.T) { func ExampleSelectFile() {
res, err := SelectFile(Filename(defaultPath), FileFilters{ zenity.SelectFile(
zenity.Filename(defaultPath),
zenity.FileFilters{
{"Go files", []string{"*.go"}}, {"Go files", []string{"*.go"}},
{"Web files", []string{"*.html", "*.js", "*.css"}}, {"Web files", []string{"*.html", "*.js", "*.css"}},
{"Image files", []string{"*.png", "*.gif", "*.ico", "*.jpg", "*.webp"}}, {"Image files", []string{"*.png", "*.gif", "*.ico", "*.jpg", "*.webp"}},
}.New()) }.New())
// Output:
if err != nil {
t.Error(err)
} else {
t.Logf("%#v", res)
}
} }
func TestSelectFileMutiple(t *testing.T) { func ExampleSelectFileMutiple() {
res, err := SelectFileMutiple(Filename(defaultPath), FileFilters{ zenity.SelectFileMutiple(
zenity.Filename(defaultPath),
zenity.FileFilters{
{"Go files", []string{"*.go"}}, {"Go files", []string{"*.go"}},
{"Web files", []string{"*.html", "*.js", "*.css"}}, {"Web files", []string{"*.html", "*.js", "*.css"}},
{"Image files", []string{"*.png", "*.gif", "*.ico", "*.jpg", "*.webp"}}, {"Image files", []string{"*.png", "*.gif", "*.ico", "*.jpg", "*.webp"}},
}.New()) }.New())
// Output:
if err != nil {
t.Error(err)
} else {
t.Logf("%#v", res)
}
} }
func TestSelectFileSave(t *testing.T) { func ExampleSelectFileSave() {
res, err := SelectFileSave(Filename(defaultPath), ConfirmOverwrite, FileFilters{ zenity.SelectFileSave(
zenity.ConfirmOverwrite,
zenity.Filename(defaultName),
zenity.FileFilters{
{"Go files", []string{"*.go"}}, {"Go files", []string{"*.go"}},
{"Web files", []string{"*.html", "*.js", "*.css"}}, {"Web files", []string{"*.html", "*.js", "*.css"}},
{"Image files", []string{"*.png", "*.gif", "*.ico", "*.jpg", "*.webp"}}, {"Image files", []string{"*.png", "*.gif", "*.ico", "*.jpg", "*.webp"}},
}.New()) }.New())
// Output:
if err != nil {
t.Error(err)
} else {
t.Logf("%#v", res)
}
} }
func TestSelectDirectory(t *testing.T) { func ExampleSelectFile_directory() {
res, err := SelectFile(Directory, Filename(defaultPath)) zenity.SelectFile(
zenity.Filename(defaultPath),
if err != nil { zenity.Directory)
t.Error(err) // Output:
} else {
t.Logf("%#v", res)
}
} }
func TestSelectDirectoryMultiple(t *testing.T) { func ExampleSelectFileMutiple_directory() {
res, err := SelectFileMutiple(Directory, Filename(defaultPath)) zenity.SelectFileMutiple(
zenity.Filename(defaultPath),
if err != nil { zenity.Directory)
t.Error(err) // Output:
} else {
t.Logf("%#v", res)
}
} }

View file

@ -10,6 +10,11 @@ import (
"github.com/ncruces/zenity/internal/zen" "github.com/ncruces/zenity/internal/zen"
) )
// Display file selection dialog.
//
// Returns an empty string on cancel.
//
// Valid options: Title, Directory, Filename, FileFilters.
func SelectFile(options ...Option) (string, error) { func SelectFile(options ...Option) (string, error) {
opts := optsParse(options) opts := optsParse(options)
@ -38,6 +43,11 @@ func SelectFile(options ...Option) (string, error) {
return string(out), nil return string(out), nil
} }
// Display multiple file selection dialog.
//
// Returns a nil slice on cancel.
//
// Valid options: Title, Directory, Filename, FileFilters.
func SelectFileMutiple(options ...Option) ([]string, error) { func SelectFileMutiple(options ...Option) ([]string, error) {
opts := optsParse(options) opts := optsParse(options)
@ -66,6 +76,11 @@ func SelectFileMutiple(options ...Option) ([]string, error) {
return strings.Split(string(out), cmd.Separator), nil return strings.Split(string(out), cmd.Separator), nil
} }
// Display save file selection dialog.
//
// Returns an empty string on cancel.
//
// Valid options: Title, Filename, ConfirmOverwrite, FileFilters.
func SelectFileSave(options ...Option) (string, error) { func SelectFileSave(options ...Option) (string, error) {
opts := optsParse(options) opts := optsParse(options)

View file

@ -1,43 +1,31 @@
package zenity package zenity_test
import "testing" import "github.com/ncruces/zenity"
func TestError(t *testing.T) { func ExampleError() {
res, err := Error("An error has occured.", Title("Error"), Icon(ErrorIcon)) zenity.Error("An error has occured.",
zenity.Title("Error"),
if err != nil { zenity.Icon(zenity.ErrorIcon))
t.Error(err) // Output:
} else {
t.Logf("%#v", res)
}
} }
func TestInfo(t *testing.T) { func ExampleInfo() {
res, err := Info("All updates are complete.", Title("Information"), Icon(InfoIcon)) zenity.Info("All updates are complete.",
zenity.Title("Information"),
if err != nil { zenity.Icon(zenity.InfoIcon))
t.Error(err) // Output:
} else {
t.Logf("%#v", res)
}
} }
func TestWarning(t *testing.T) { func ExampleWarning() {
res, err := Warning("Are you sure you want to proceed?", Title("Warning"), Icon(WarningIcon)) zenity.Warning("Are you sure you want to proceed?",
zenity.Title("Warning"),
if err != nil { zenity.Icon(zenity.WarningIcon))
t.Error(err) // Output:
} else {
t.Logf("%#v", res)
}
} }
func TestQuestion(t *testing.T) { func ExampleQuestion() {
res, err := Question("Are you sure you want to proceed?", Title("Question"), Icon(QuestionIcon)) zenity.Question("Are you sure you want to proceed?",
zenity.Title("Question"),
if err != nil { zenity.Icon(zenity.QuestionIcon))
t.Error(err) // Output:
} else {
t.Logf("%#v", res)
}
} }

View file

@ -8,18 +8,39 @@ import (
"github.com/ncruces/zenity/internal/zen" "github.com/ncruces/zenity/internal/zen"
) )
// Display error dialog.
//
// Returns true on OK, false on dismiss, or ErrExtraButton.
//
// Valid options: Title, Icon, OKLabel, ExtraButton, NoWrap, Ellipsize.
func Error(text string, options ...Option) (bool, error) { func Error(text string, options ...Option) (bool, error) {
return message("--error", text, options) return message("--error", text, options)
} }
// Display info dialog.
//
// Returns true on OK, false on dismiss, or ErrExtraButton.
//
// Valid options: Title, Icon, OKLabel, ExtraButton, NoWrap, Ellipsize.
func Info(text string, options ...Option) (bool, error) { func Info(text string, options ...Option) (bool, error) {
return message("--info", text, options) return message("--info", text, options)
} }
// Display question dialog.
//
// Returns true on OK, false on Cancel, or ErrExtraButton.
//
// Valid options: Title, Icon, OKLabel, CancelLabel, ExtraButton, NoWrap,
// Ellipsize, DefaultCancel.
func Question(text string, options ...Option) (bool, error) { func Question(text string, options ...Option) (bool, error) {
return message("--question", text, options) return message("--question", text, options)
} }
// Display warning dialog.
//
// Returns true on OK, false on dismiss, or ErrExtraButton.
//
// Valid options: Title, Icon, OKLabel, ExtraButton, NoWrap, Ellipsize.
func Warning(text string, options ...Option) (bool, error) { func Warning(text string, options ...Option) (bool, error) {
return message("--warning", text, options) return message("--warning", text, options)
} }

View file

@ -32,6 +32,7 @@ type options struct {
defcancel bool defcancel bool
} }
// Options are arguments you pass to dialog functions to customize their behavior.
type Option func(*options) type Option func(*options)
func optsParse(options []Option) (res options) { func optsParse(options []Option) (res options) {
@ -43,6 +44,7 @@ func optsParse(options []Option) (res options) {
// General options // General options
// Option to set the dialog title.
func Title(title string) Option { func Title(title string) Option {
return func(o *options) { return func(o *options) {
o.title = title o.title = title
@ -51,27 +53,41 @@ func Title(title string) Option {
// File selection options // File selection options
// 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 Filename(filename string) Option { func Filename(filename string) Option {
return func(o *options) { return func(o *options) {
o.filename = filename o.filename = filename
} }
} }
// Option to activate directory-only selection.
func Directory(o *options) { func Directory(o *options) {
o.directory = true o.directory = true
} }
// Option to confirm file selection if filename already exists.
func ConfirmOverwrite(o *options) { func ConfirmOverwrite(o *options) {
o.overwrite = true o.overwrite = true
} }
// FileFilter encapsulates a filename filter.
type FileFilter struct { type FileFilter struct {
Name string Name string // display string that describes the filter (optional)
Patterns []string Patterns []string // filter patterns for the display string
} }
// 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.
type FileFilters []FileFilter type FileFilters []FileFilter
// Creates Option to set the filename filter list.
func (f FileFilters) New() Option { func (f FileFilters) New() Option {
return func(o *options) { return func(o *options) {
o.filters = f o.filters = f
@ -80,6 +96,7 @@ func (f FileFilters) New() Option {
// Message options // Message options
// MessageIcon is the enumeration for message dialog icons.
type MessageIcon int type MessageIcon int
const ( const (
@ -89,38 +106,45 @@ const (
WarningIcon WarningIcon
) )
// Option to set the dialog icon.
func Icon(icon MessageIcon) Option { func Icon(icon MessageIcon) Option {
return func(o *options) { return func(o *options) {
o.icon = icon o.icon = icon
} }
} }
// Option to set the label of the OK button.
func OKLabel(ok string) Option { func OKLabel(ok string) Option {
return func(o *options) { return func(o *options) {
o.ok = ok o.ok = ok
} }
} }
// Option to set the label of the Cancel button.
func CancelLabel(cancel string) Option { func CancelLabel(cancel string) Option {
return func(o *options) { return func(o *options) {
o.cancel = cancel o.cancel = cancel
} }
} }
// Option to add an extra button.
func ExtraButton(extra string) Option { func ExtraButton(extra string) Option {
return func(o *options) { return func(o *options) {
o.extra = extra o.extra = extra
} }
} }
// Option to disable enable text wrapping.
func NoWrap(o *options) { func NoWrap(o *options) {
o.nowrap = true o.nowrap = true
} }
// Option to enable ellipsizing in the dialog text.
func Ellipsize(o *options) { func Ellipsize(o *options) {
o.ellipsize = true o.ellipsize = true
} }
// Option to give Cancel button focus by default.
func DefaultCancel(o *options) { func DefaultCancel(o *options) {
o.defcancel = true o.defcancel = true
} }