clui/docs/fselect.md

File Picker

Use file picker if you need to select a single file or directory.

The dialog includes:

• title that shows the custom text followed by file masks
• current directory
• list of directories and files inside the current directory
• edit field to a) enter a name of a new file or directory b) quick search. When edit field has focus you can use arrows up and down to select previous or next object
• button Open enters the selected directory. The button is useful in select directory mode
• button Select closes the dialog and returns a path to the selected object. If edit field is empty the path is the path to the object selected in the file list box, otherwise the path is made from current directory and edit field text
• button Cancel closes the dialog and does not return path to selected object

Returned values

After the dialog is closed a few its properties contains information what object a user has selected:

• Selected contains information about how the dialog was closed: true - a user has selected an object and clicked Select, false - a user canceled the dialog without selecting any object
• Exists is true if a user has selected existing file or directory, and it is false if a user entered name of a new object and clicked Select. The latter is possible only if option mustExist is set to false
• FilePath is a full path to the selected object

API

To show a dialog, call the function

func CreateFileSelectDialog(title, fileMasks, initPath string, selectDir, mustExist bool) *FileSelectDialog

Function arguments:

• title is a custom dialog title. It should not contain file masks because the dialog always shows title and the file masks follows it
• fileMasks is list of file masks separated with comma or OS path separator (';' - for Windows, ':' - for Linux). Empty, "", and ".*" mean all files
• initPath sets the starting directory for the dialog. If it is empty then the dialog uses the current working directory. If the intiPath does not exist, then the dialog looks up for the first existing directory in the directory tree starting from initPath. In case it fails to find any existing directory, the dialog opens the current working directory
• selectDir - set it to true if you want to select a directory instead of a file. In case of selectDir is true, the file list box does not display regular files
• mustExist set it to true if you want a user to select only existing object. If it is false then the dialog allows a user to enter any name into edit field and click Select. The latter is useful for "File save" dialog.

Do not forget to set a callback that is called after the dialog is closed:

bookFile := ""
dlg := CreateFileSelectDialog("Select a book to read", "*.fb2,*.epub,*.txt", "", false, true)
dlg.OnClose(func() {
    if !dlg.Selected {
        // a user canceled the dialog
        return
    }
    bookFile = dlg.FilePath
})

Please, check the dialog demo for more details.