cfd

Documentation

Overview

Common File Dialogs

Index

• Variables
• type Dialog
• type DialogConfig
• type FileDialog
• type FileFilter
• type OpenFileDialog
  • func NewOpenFileDialog(config DialogConfig) (OpenFileDialog, error)
• type OpenMultipleFilesDialog
  • func NewOpenMultipleFilesDialog(config DialogConfig) (OpenMultipleFilesDialog, error)
• type SaveFileDialog
  • func NewSaveFileDialog(config DialogConfig) (SaveFileDialog, error)
• type SelectFolderDialog
  • func NewSelectFolderDialog(config DialogConfig) (SelectFolderDialog, error)
• type SelectMultipleFoldersDialog
  • func NewSelectMultipleFoldersDialog(config DialogConfig) (SelectMultipleFoldersDialog, error)

Variables

var (
	ErrorCancelled = errors.New("cancelled by user")
)

Types

type Dialog

type Dialog interface {
	// Show the dialog to the user.
	// Blocks until the user has closed the dialog.
	Show() error
	// Sets the dialog's parent window. Use 0 to set the dialog to have no parent window.
	SetParentWindowHandle(hwnd uintptr)
	// Show the dialog to the user.
	// Blocks until the user has closed the dialog and returns their selection.
	// Returns an error if the user cancelled the dialog.
	// Do not use for the Open Multiple Files dialog. Use ShowAndGetResults instead.
	// Do not use for Select Multiple Folders dialog. Use ShowAndGetResults instead.
	ShowAndGetResult() (string, error)
	// Sets the title of the dialog window.
	SetTitle(title string) error
	// Sets the "role" of the dialog. This is used to derive the dialog's GUID, which the
	// OS will use to differentiate it from dialogs that are intended for other purposes.
	// This means that, for example, a dialog with role "Import" will have a different
	// previous location that it will open to than a dialog with role "Open". Can be any string.
	SetRole(role string) error
	// Sets the folder used as a default if there is not a recently used folder value available
	SetDefaultFolder(defaultFolder string) error
	// Sets the folder that the dialog always opens to.
	// If this is set, it will override the "default folder" behaviour and the dialog will always open to this folder.
	SetFolder(folder string) error
	// Gets the selected file or folder path, as an absolute path eg. "C:\Folder\file.txt"
	// Do not use for the Open Multiple Files dialog. Use GetResults instead.
	GetResult() (string, error)
	// Sets the file name, I.E. the contents of the file name text box.
	// For Select Folder Dialog, sets folder name.
	SetFileName(fileName string) error
	// Release the resources allocated to this Dialog.
	// Should be called when the dialog is finished with.
	Release() error
}

type DialogConfig

type DialogConfig struct {
	// The title of the dialog
	Title string
	// The role of the dialog. This is used to derive the dialog's GUID, which the
	// OS will use to differentiate it from dialogs that are intended for other purposes.
	// This means that, for example, a dialog with role "Import" will have a different
	// previous location that it will open to than a dialog with role "Open". Can be any string.
	Role string
	// The default folder - the folder that is used the first time the user opens it
	// (after the first time their last used location is used).
	DefaultFolder string
	// The initial folder - the folder that the dialog always opens to if not empty.
	// If this is not empty, it will override the "default folder" behaviour and
	// the dialog will always open to this folder.
	Folder string
	// The file filters that restrict which types of files the dialog is able to choose.
	// Ignored by Select Folder Dialog.
	FileFilters []FileFilter
	// Sets the initially selected file filter. This is an index of FileFilters.
	// Ignored by Select Folder Dialog.
	SelectedFileFilterIndex uint
	// The initial name of the file (I.E. the text in the file name text box) when the user opens the dialog.
	// For the Select Folder Dialog, this sets the initial folder name.
	FileName string
	// The default extension applied when a user does not provide one as part of the file name.
	// If the user selects a different file filter, the default extension will be automatically updated to match the new file filter.
	// For Open / Open Multiple File Dialog, this only has an effect when the user specifies a file name with no extension and a file with the default extension exists.
	// For Save File Dialog, this extension will be used whenever a user does not specify an extension.
	// Ignored by Select Folder Dialog.
	DefaultExtension string
	// ParentWindowHandle is the handle (HWND) to the parent window of the dialog.
	// If left as 0 / nil, the dialog will have no parent window.
	ParentWindowHandle uintptr
}

type FileDialog

type FileDialog interface {
	Dialog
	// Set the list of file filters that the user can select.
	SetFileFilters(fileFilter []FileFilter) error
	// Set the selected item from the list of file filters (set using SetFileFilters) by its index. Defaults to 0 (the first item in the list) if not called.
	SetSelectedFileFilterIndex(index uint) error
	// Sets the default extension applied when a user does not provide one as part of the file name.
	// If the user selects a different file filter, the default extension will be automatically updated to match the new file filter.
	// For Open / Open Multiple File Dialog, this only has an effect when the user specifies a file name with no extension and a file with the default extension exists.
	// For Save File Dialog, this extension will be used whenever a user does not specify an extension.
	SetDefaultExtension(defaultExtension string) error
}

type FileFilter

type FileFilter struct {
	// The display name of the filter (That is shown to the user)
	DisplayName string
	// The filter pattern. Eg. "*.txt;*.png" to select all txt and png files, "*.*" to select any files, etc.
	Pattern string
}

type OpenFileDialog

type OpenFileDialog interface {
	FileDialog
}

func NewOpenFileDialog

func NewOpenFileDialog(config DialogConfig) (OpenFileDialog, error)

TODO doc

type OpenMultipleFilesDialog

type OpenMultipleFilesDialog interface {
	FileDialog
	// Show the dialog to the user.
	// Blocks until the user has closed the dialog and returns the selected files.
	ShowAndGetResults() ([]string, error)
	// Gets the selected file paths, as absolute paths eg. "C:\Folder\file.txt"
	GetResults() ([]string, error)
}

func NewOpenMultipleFilesDialog

func NewOpenMultipleFilesDialog(config DialogConfig) (OpenMultipleFilesDialog, error)

TODO doc

type SaveFileDialog

type SaveFileDialog interface {
	FileDialog
}

func NewSaveFileDialog

func NewSaveFileDialog(config DialogConfig) (SaveFileDialog, error)

TODO doc

type SelectFolderDialog

type SelectFolderDialog interface {
	Dialog
}

func NewSelectFolderDialog

func NewSelectFolderDialog(config DialogConfig) (SelectFolderDialog, error)

TODO doc

type SelectMultipleFoldersDialog

type SelectMultipleFoldersDialog interface {
	Dialog
	// Show the dialog to the user.
	// Blocks until the user has closed the dialog and returns the selected files.
	ShowAndGetResults() ([]string, error)
	// Gets the selected file paths, as absolute paths eg. "C:\Folder\file.txt"
	GetResults() ([]string, error)
}

func NewSelectMultipleFoldersDialog

func NewSelectMultipleFoldersDialog(config DialogConfig) (SelectMultipleFoldersDialog, error)