file select

1.0.0

A library to invoke the native file selection dialogs to open or save files.

About File-Select

This library allows you to open native file dialogs to open and save files. This is useful if you have an application that's primarily text based and would like a more convenient file selection utility, or if you are working with a UI toolkit that does not offer a way to access the native file dialogs directly.

How To

After loading it, simply invoke new or existing. This should bring up a file dialog in the preferred backend for your current system. The backend to use is determined on first call.

(org.shirakumo.file-select:new :type "png")
(org.shirakumo.file-select:existing :multiple T)

Returned are two values – the file or files selected as pathnames, and whether the user successfully completed the selection. If the second value is NIL, it means the user aborted the operation by closing or cancelling the dialog.

Supported Backends

The following file selection backends are currently supported:

gtk
macos (AppKit/Cocoa)
win32 (IFileDialog)
zenity

System Information

Version: 1.0.0

Dependencies:

Author: Nicolas Hafner

License: zlib

Homepage: https://shinmera.github.io/file-select/

Definition Index

ORG.SHIRAKUMO.FILE-SELECT

No documentation provided.

EXTERNAL SPECIAL-VARIABLE

DEFAULT-BACKEND

Source

Holds the name of the default file selection backend to use.

This should be a value suitable for the first argument of NEW-WITH and
EXISTING-WITH.

On first call of NEW or EXISTING, if this variable is still unbound,
it is set to the value of DETERMINE-DEFAULT-BACKEND.

See NEW
See EXISTING
See DETERMINE-DEFAULT-BACKEND

EXTERNAL CLASS

BACKEND

Source

Superclass for all file selection backend implementations.

The user should not create instances of this class, or any of its
subclasses. The system will automatically construct singleton
instances of the class when used with NEW-WITH and EXISTING-WITH.

When creating a subclass, you may use INITIALIZE-INSTANCE to perform
one-time setup, such as loading and initialising foreign libraries.

In order to uninitialize the libraries, you should implement a
FINALIZE method.

The user may call FINALIZE on a backend instance or name. The instance
will be invalidated afterwards, and a repeat call on NEW-WITH or
EXISTING-WITH with the backend name will create a new instance.

See FINALIZE
See NEW-WITH
See EXISTING-WITH

EXTERNAL CONDITION

FILE-SELECT-ERROR

Source

Superclass for any kind of error signalled during the file selection.

Typically a subclass of this error is signalled depending on the
backend used. This kind of error should only every be signalled if
critical problems occur that prevent the backend from operating
correctly.

EXTERNAL CONDITION

NO-BACKEND-FOUND

Source

Error signalled when no backend could be found.

This usually means that no implementation for file selection is
available. It could mean that auto-detection failed, in which case
*DEFAULT-BACKEND* should be manually set to the proper value.

See *DEFAULT-BACKEND*
See DETERMINE-DEFAULT-BACKEND

EXTERNAL FUNCTION

DETERMINE-DEFAULT-BACKEND

Source

Attempt to determine the proper backend to use for the current system.

This will return the name of the class to use for the backend, or
signal an error of type NO-BACKEND-FOUND if no usable backend could be
found at all.

More specifically, the following detection heuristic is used:

- On WIN32, the WIN32 backend is used.
- On DARWIN, the MACOS backend is used.
- If a "zenity" binary is found in one of the PATH directories, the
  ZENITY backend is used.
- If the gtk3 shared library file can be loaded, the GTK backend is
  used.
- Otherwise NO-BACKEND-FOUND is signalled.

See NO-BACKEND-FOUND

EXTERNAL FUNCTION

EXISTING

&REST
ARGS
&KEY
TITLE
DEFAULT
FILTER
MULTIPLE
BACKEND

Source

Select an existing file.

This will open an "open file" dialog.

Returns two values:

- The selected file as a pathname, or as a list if multiple.
- Whether the user completed the operation successfully

If no BACKEND is specified, *DEFAULT-BACKEND* is used.

TITLE may be a string to designate the file dialog window title.

DEFAULT should be a pathname pointing to a default file or directory
that the dialog should present on opening.

FILTER can be one of the following:

  :DIRECTORY     --- Only allow selecting directories.
  STRING         --- Shorthand for (("" TYPE))
  ((NAME TYPE)*) --- Restrict the file selection to the specified
                     types. NAME should be a human-readable
                     description, and TYPE should be a PATHNAME-TYPE
                     to allow for selection.

MULTIPLE designates whether multiple files can be selected. In that
case, the first return value is always a list.

A backend may support additional arguments.

See EXISTING-WITH
See *DEFAULT-BACKEND*

EXTERNAL FUNCTION
NATIVE-NAMESTRING
- PATH
Source
No documentation provided.

EXTERNAL FUNCTION

NEW

&REST
ARGS
&KEY
TITLE
DEFAULT
FILTER
MULTIPLE
BACKEND

Source

Select a new file.

This will open a "save file" dialog.

Returns two values:

- The selected file as a pathname, if any
- Whether the user completed the operation successfully

If no BACKEND is specified, *DEFAULT-BACKEND* is used.

TITLE may be a string to designate the file dialog window title.

DEFAULT should be a pathname pointing to a default file or directory
that the dialog should present on opening.

FILTER can be one of the following:

  :DIRECTORY     --- Only allow selecting directories.
  STRING         --- Shorthand for (("" TYPE))
  ((NAME TYPE)*) --- Restrict the file selection to the specified
                     types. NAME should be a human-readable
                     description, and TYPE should be a PATHNAME-TYPE
                     to allow for selection.

A backend may support additional arguments.

See NEW-WITH
See *DEFAULT-BACKEND*

EXTERNAL FUNCTION
PARSE-NATIVE-NAMESTRING
- PATH
Source
No documentation provided.

EXTERNAL GENERIC-FUNCTION

EXISTING-WITH

BACKEND
&KEY
TITLE
DEFAULT
FILTER
MULTIPLE
&ALLOW-OTHER-KEYS

Source

Open an "open file" dialog with the specified backend.

The implementation must adhere to the protocol specified in EXISTING.

See EXISTING
See BACKEND

EXTERNAL GENERIC-FUNCTION

FINALIZE

BACKEND

Source

Finalize the backend and free any resources it might have allocated.

This will NOT close any foreign libraries it might have opened.
After calling FINALIZE on a backend, the backend instance is
invalidated and may not be used again.

See BACKEND

EXTERNAL GENERIC-FUNCTION

NEW-WITH

BACKEND
&KEY
TITLE
DEFAULT
FILTER
MULTIPLE
&ALLOW-OTHER-KEYS

Source

Open a "save file" dialog with the specified backend.

The implementation must adhere to the protocol specified in NEW.

See NEW
See BACKEND

ORG.SHIRAKUMO.FILE-SELECT.GTK

No documentation provided.

EXTERNAL CLASS

GTK

Source

Implementation using the GTK3 framework.

Note that this will create and destroy a new GTK application on every
use, and requires the GTK3 libraries to be present.

See BACKEND

ORG.SHIRAKUMO.FILE-SELECT.MACOS

No documentation provided.

EXTERNAL CLASS

MACOS

Source

Implementation using the AppKit/Cocoa framework (OSX 10.0 and above).

Note that MacOS requires all UI to happen in Thread 0. To this end,
this implementation makes use of TRIVIAL-MAIN-THREAD to schedule the
file selection in the main thread, if it isn't already.

See BACKEND

ORG.SHIRAKUMO.FILE-SELECT.WIN32

No documentation provided.

EXTERNAL CLASS

WIN32

Source

Implementation using the Win32 IFileDialog framework (Win Vista and above).

See BACKEND

ORG.SHIRAKUMO.FILE-SELECT.ZENITY

No documentation provided.

EXTERNAL CLASS

ZENITY

Source

Implementation using the Zenity GTK dialog utility.

This is preferable over the native GTK backend as it does not require
loading the foreign libraries or constructing a GTK application
in-process. UIOP:RUN-PROGRAM is used to launch the Zenity process.

See BACKEND

EXTERNAL FUNCTION
ZENITY
- &REST
- ARGS
Source
No documentation provided.