The file-select Reference Manual

Next: , Previous: , Up: (dir)   [Contents][Index]

The file-select Reference Manual

This is the file-select Reference Manual, version 1.0.0, generated automatically by Declt version 4.0 beta 2 "William Riker" on Thu Sep 15 04:44:30 2022 GMT+0.

Table of Contents


1 Introduction

## 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.

:: lisp
(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``


2 Systems

The main system appears first, followed by any subsystem dependency.


Previous: , Up: Systems   [Contents][Index]

2.1 file-select

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

Maintainer

Nicolas Hafner <shinmera@tymoon.eu>

Author

Nicolas Hafner <shinmera@tymoon.eu>

Home Page

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

Source Control

(GIT https://github.com/shinmera/file-select.git)

Bug Tracker

https://github.com/shinmera/file-select/issues

License

zlib

Version

1.0.0

Defsystem Dependency

trivial-features (system).

Dependencies
  • cffi (system).
  • float-features (system).
  • trivial-main-thread (system)., for feature :darwin
  • com-on (system)., for feature :windows
  • documentation-utils (system).
Source

file-select.asd.

Child Components

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp   [Contents][Index]

3.1.1 file-select/file-select.asd

Source

file-select.asd.

Parent Component

file-select (system).

ASDF Systems

file-select.


3.1.3 file-select/protocol.lisp

Dependency

package.lisp (file).

Source

file-select.asd.

Parent Component

file-select (system).

Public Interface
Internals

3.1.4 file-select/gtk.lisp

If Feature

:linux

Dependency

protocol.lisp (file).

Source

file-select.asd.

Parent Component

file-select (system).

Public Interface
Internals

3.1.5 file-select/zenity.lisp

If Feature

:linux

Dependencies
Source

file-select.asd.

Parent Component

file-select (system).

Public Interface
Internals

zenity* (function).


3.1.6 file-select/macos.lisp

If Feature

:darwin

Dependencies
Source

file-select.asd.

Parent Component

file-select (system).


3.1.7 file-select/win32.lisp

If Feature

:windows

Dependencies
Source

file-select.asd.

Parent Component

file-select (system).


3.1.8 file-select/defaults.lisp

Dependencies
Source

file-select.asd.

Parent Component

file-select (system).

Public Interface
Internals

3.1.9 file-select/documentation.lisp

Dependency

defaults.lisp (file).

Source

file-select.asd.

Parent Component

file-select (system).


4 Packages

Packages are listed by definition order.


4.1 org.shirakumo.file-select.zenity

Source

package.lisp.

Use List
Public Interface
Internals

zenity* (function).


4.2 org.shirakumo.file-select.macos

Source

package.lisp.

Use List

4.3 org.shirakumo.file-select.win32

Source

package.lisp.

Use List

4.4 org.shirakumo.file-select

Source

package.lisp.

Use List

common-lisp.

Used By List
Public Interface
Internals

4.5 org.shirakumo.file-select.gtk

Source

package.lisp.

Use List
Public Interface

gtk (class).

Internals

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Public Interface


5.1.1 Special variables

Special Variable: *default-backend*

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

Package

org.shirakumo.file-select.

Source

protocol.lisp.


5.1.2 Ordinary functions

Function: determine-default-backend ()

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

Package

org.shirakumo.file-select.

Source

defaults.lisp.

Function: existing (&rest args &key title default filter multiple backend)

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*

Package

org.shirakumo.file-select.

Source

protocol.lisp.

Function: native-namestring (path)
Package

org.shirakumo.file-select.

Source

protocol.lisp.

Function: new (&rest args &key title default filter multiple backend)

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*

Package

org.shirakumo.file-select.

Source

protocol.lisp.

Function: parse-native-namestring (path)
Package

org.shirakumo.file-select.

Source

protocol.lisp.

Function: zenity (&rest args)
Package

org.shirakumo.file-select.zenity.

Source

zenity.lisp.


5.1.3 Generic functions

Generic Function: existing-with (backend &key title default filter multiple &allow-other-keys)

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

The implementation must adhere to the protocol specified in EXISTING.

See EXISTING
See BACKEND

Package

org.shirakumo.file-select.

Source

protocol.lisp.

Methods
Method: existing-with ((backend zenity) &rest args)
Source

zenity.lisp.

Method: existing-with ((backend gtk) &key title default filter multiple &allow-other-keys)
Source

gtk.lisp.

Method: existing-with ((backend class) &rest args &key title)
Method: existing-with ((backend symbol) &rest args)
Generic Function: finalize (backend)

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

Package

org.shirakumo.file-select.

Source

protocol.lisp.

Methods
Method: finalize ((backend zenity))
Source

zenity.lisp.

Method: finalize ((backend gtk))
Source

gtk.lisp.

Method: finalize ((all (eql t)))
Method: finalize :after ((backend backend))
Method: finalize ((backend class))
Method: finalize ((backend symbol))
Generic Function: new-with (backend &key title default filter multiple &allow-other-keys)

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

The implementation must adhere to the protocol specified in NEW.

see NEW
See BACKEND

Package

org.shirakumo.file-select.

Source

protocol.lisp.

Methods
Method: new-with ((backend zenity) &rest args)
Source

zenity.lisp.

Method: new-with ((backend gtk) &key title default filter multiple &allow-other-keys)
Source

gtk.lisp.

Method: new-with ((backend class) &rest args &key title)
Method: new-with ((backend symbol) &rest args)

5.1.4 Standalone methods

Method: initialize-instance :after ((backend gtk) &key)
Source

gtk.lisp.


5.1.5 Conditions

Condition: file-select-error

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.

Package

org.shirakumo.file-select.

Source

protocol.lisp.

Direct superclasses

error.

Direct subclasses

no-backend-found.

Condition: no-backend-found

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

Package

org.shirakumo.file-select.

Source

defaults.lisp.

Direct superclasses

file-select-error.


Previous: , Up: Public Interface   [Contents][Index]

5.1.6 Classes

Class: backend

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

Package

org.shirakumo.file-select.

Source

protocol.lisp.

Direct subclasses
Direct methods

finalize.

Class: gtk

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

Package

org.shirakumo.file-select.gtk.

Source

gtk.lisp.

Direct superclasses

backend.

Direct methods
Direct slots
Slot: closure
Readers

closure.

Writers

(setf closure).

Class: zenity

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

Package

org.shirakumo.file-select.zenity.

Source

zenity.lisp.

Direct superclasses

backend.

Direct methods

5.2 Internals


Next: , Previous: , Up: Internals   [Contents][Index]

5.2.1 Special variables

Special Variable: *backend-cache*
Package

org.shirakumo.file-select.

Source

protocol.lisp.


5.2.2 Ordinary functions

Function: add-filter (chooser filter)
Package

org.shirakumo.file-select.gtk.

Source

gtk.lisp.

Function: add-pattern (filter pattern)
Package

org.shirakumo.file-select.gtk.

Source

gtk.lisp.

Function: default-backend ()
Package

org.shirakumo.file-select.

Source

protocol.lisp.

Function: dialog-run (dialog)
Package

org.shirakumo.file-select.gtk.

Source

gtk.lisp.

Function: dostrey (widget)
Package

org.shirakumo.file-select.gtk.

Source

gtk.lisp.

Function: find-in-path (file)
Package

org.shirakumo.file-select.

Source

defaults.lisp.

Function: g-application-run (app argc argv)
Package

org.shirakumo.file-select.gtk.

Source

gtk.lisp.

Function: g-free (object)
Package

org.shirakumo.file-select.gtk.

Source

gtk.lisp.

Function: g-get-path (file)
Package

org.shirakumo.file-select.gtk.

Source

gtk.lisp.

Function: g-signal-connect (instance signal handler data destroy flags)
Package

org.shirakumo.file-select.gtk.

Source

gtk.lisp.

Function: g-slist-data (pointer-to-g-slist)
Package

org.shirakumo.file-select.gtk.

Source

gtk.lisp.

Function: (setf g-slist-data) (pointer-to-g-slist)
Package

org.shirakumo.file-select.gtk.

Source

gtk.lisp.

Function: g-slist-free (list)
Package

org.shirakumo.file-select.gtk.

Source

gtk.lisp.

Function: g-slist-next (pointer-to-g-slist)
Package

org.shirakumo.file-select.gtk.

Source

gtk.lisp.

Function: (setf g-slist-next) (pointer-to-g-slist)
Package

org.shirakumo.file-select.gtk.

Source

gtk.lisp.

Function: g-unref (object)
Package

org.shirakumo.file-select.gtk.

Source

gtk.lisp.

Function: get-backend (class)
Package

org.shirakumo.file-select.

Source

protocol.lisp.

Function: get-filename (chooser)
Package

org.shirakumo.file-select.gtk.

Source

gtk.lisp.

Function: get-filenames (chooser)
Package

org.shirakumo.file-select.gtk.

Source

gtk.lisp.

Function: get-files (chooser)
Package

org.shirakumo.file-select.gtk.

Source

gtk.lisp.

Function: new-application (name flags)
Package

org.shirakumo.file-select.gtk.

Source

gtk.lisp.

Function: new-file-chooser (title parent action button-a action-a button-b action-b delim)
Package

org.shirakumo.file-select.gtk.

Source

gtk.lisp.

Function: new-filter ()
Package

org.shirakumo.file-select.gtk.

Source

gtk.lisp.

Function: set-current-folder (chooser filename)
Package

org.shirakumo.file-select.gtk.

Source

gtk.lisp.

Function: set-filename (chooser filename)
Package

org.shirakumo.file-select.gtk.

Source

gtk.lisp.

Function: set-name (filter name)
Package

org.shirakumo.file-select.gtk.

Source

gtk.lisp.

Function: set-select-multiple (chooser multiple)
Package

org.shirakumo.file-select.gtk.

Source

gtk.lisp.

Function: show (title mode default filter multiple)
Package

org.shirakumo.file-select.gtk.

Source

gtk.lisp.

Function: show* (backend &rest args)
Package

org.shirakumo.file-select.gtk.

Source

gtk.lisp.

Function: split (char string)
Package

org.shirakumo.file-select.

Source

defaults.lisp.

Function: zenity* (&key title default filter multiple save backend)
Package

org.shirakumo.file-select.zenity.

Source

zenity.lisp.


Next: , Previous: , Up: Internals   [Contents][Index]

5.2.3 Generic functions

Generic Reader: closure (object)
Package

org.shirakumo.file-select.gtk.

Methods
Reader Method: closure ((gtk gtk))

automatically generated reader method

Source

gtk.lisp.

Target Slot

closure.

Generic Writer: (setf closure) (object)
Package

org.shirakumo.file-select.gtk.

Methods
Writer Method: (setf closure) ((gtk gtk))

automatically generated writer method

Source

gtk.lisp.

Target Slot

closure.


Previous: , Up: Internals   [Contents][Index]

5.2.4 Classes

Class: g-slist
Package

org.shirakumo.file-select.gtk.

Source

gtk.lisp.

Direct superclasses
  • foreign-struct-type.
  • translatable-foreign-type.

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts


Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   (  
A   C   D   E   F   G   I   M   N   P   S   Z  
Index Entry  Section

(
(setf closure): Private generic functions
(setf closure): Private generic functions
(setf g-slist-data): Private ordinary functions
(setf g-slist-next): Private ordinary functions

A
add-filter: Private ordinary functions
add-pattern: Private ordinary functions

C
closure: Private generic functions
closure: Private generic functions

D
default-backend: Private ordinary functions
determine-default-backend: Public ordinary functions
dialog-run: Private ordinary functions
dostrey: Private ordinary functions

E
existing: Public ordinary functions
existing-with: Public generic functions
existing-with: Public generic functions
existing-with: Public generic functions
existing-with: Public generic functions
existing-with: Public generic functions

F
finalize: Public generic functions
finalize: Public generic functions
finalize: Public generic functions
finalize: Public generic functions
finalize: Public generic functions
finalize: Public generic functions
finalize: Public generic functions
find-in-path: Private ordinary functions
Function, (setf g-slist-data): Private ordinary functions
Function, (setf g-slist-next): Private ordinary functions
Function, add-filter: Private ordinary functions
Function, add-pattern: Private ordinary functions
Function, default-backend: Private ordinary functions
Function, determine-default-backend: Public ordinary functions
Function, dialog-run: Private ordinary functions
Function, dostrey: Private ordinary functions
Function, existing: Public ordinary functions
Function, find-in-path: Private ordinary functions
Function, g-application-run: Private ordinary functions
Function, g-free: Private ordinary functions
Function, g-get-path: Private ordinary functions
Function, g-signal-connect: Private ordinary functions
Function, g-slist-data: Private ordinary functions
Function, g-slist-free: Private ordinary functions
Function, g-slist-next: Private ordinary functions
Function, g-unref: Private ordinary functions
Function, get-backend: Private ordinary functions
Function, get-filename: Private ordinary functions
Function, get-filenames: Private ordinary functions
Function, get-files: Private ordinary functions
Function, native-namestring: Public ordinary functions
Function, new: Public ordinary functions
Function, new-application: Private ordinary functions
Function, new-file-chooser: Private ordinary functions
Function, new-filter: Private ordinary functions
Function, parse-native-namestring: Public ordinary functions
Function, set-current-folder: Private ordinary functions
Function, set-filename: Private ordinary functions
Function, set-name: Private ordinary functions
Function, set-select-multiple: Private ordinary functions
Function, show: Private ordinary functions
Function, show*: Private ordinary functions
Function, split: Private ordinary functions
Function, zenity: Public ordinary functions
Function, zenity*: Private ordinary functions

G
g-application-run: Private ordinary functions
g-free: Private ordinary functions
g-get-path: Private ordinary functions
g-signal-connect: Private ordinary functions
g-slist-data: Private ordinary functions
g-slist-free: Private ordinary functions
g-slist-next: Private ordinary functions
g-unref: Private ordinary functions
Generic Function, (setf closure): Private generic functions
Generic Function, closure: Private generic functions
Generic Function, existing-with: Public generic functions
Generic Function, finalize: Public generic functions
Generic Function, new-with: Public generic functions
get-backend: Private ordinary functions
get-filename: Private ordinary functions
get-filenames: Private ordinary functions
get-files: Private ordinary functions

I
initialize-instance: Public standalone methods

M
Method, (setf closure): Private generic functions
Method, closure: Private generic functions
Method, existing-with: Public generic functions
Method, existing-with: Public generic functions
Method, existing-with: Public generic functions
Method, existing-with: Public generic functions
Method, finalize: Public generic functions
Method, finalize: Public generic functions
Method, finalize: Public generic functions
Method, finalize: Public generic functions
Method, finalize: Public generic functions
Method, finalize: Public generic functions
Method, initialize-instance: Public standalone methods
Method, new-with: Public generic functions
Method, new-with: Public generic functions
Method, new-with: Public generic functions
Method, new-with: Public generic functions

N
native-namestring: Public ordinary functions
new: Public ordinary functions
new-application: Private ordinary functions
new-file-chooser: Private ordinary functions
new-filter: Private ordinary functions
new-with: Public generic functions
new-with: Public generic functions
new-with: Public generic functions
new-with: Public generic functions
new-with: Public generic functions

P
parse-native-namestring: Public ordinary functions

S
set-current-folder: Private ordinary functions
set-filename: Private ordinary functions
set-name: Private ordinary functions
set-select-multiple: Private ordinary functions
show: Private ordinary functions
show*: Private ordinary functions
split: Private ordinary functions

Z
zenity: Public ordinary functions
zenity*: Private ordinary functions

Jump to:   (  
A   C   D   E   F   G   I   M   N   P   S   Z  

Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   B   C   D   F   G   M   N   O   P   S   W   Z  
Index Entry  Section

B
backend: Public classes

C
Class, backend: Public classes
Class, g-slist: Private classes
Class, gtk: Public classes
Class, zenity: Public classes
Condition, file-select-error: Public conditions
Condition, no-backend-found: Public conditions

D
defaults.lisp: The file-select/defaults․lisp file
documentation.lisp: The file-select/documentation․lisp file

F
File, defaults.lisp: The file-select/defaults․lisp file
File, documentation.lisp: The file-select/documentation․lisp file
File, file-select.asd: The file-select/file-select․asd file
File, gtk.lisp: The file-select/gtk․lisp file
File, macos.lisp: The file-select/macos․lisp file
File, package.lisp: The file-select/package․lisp file
File, protocol.lisp: The file-select/protocol․lisp file
File, win32.lisp: The file-select/win32․lisp file
File, zenity.lisp: The file-select/zenity․lisp file
file-select: The file-select system
file-select-error: Public conditions
file-select.asd: The file-select/file-select․asd file

G
g-slist: Private classes
gtk: Public classes
gtk.lisp: The file-select/gtk․lisp file

M
macos.lisp: The file-select/macos․lisp file

N
no-backend-found: Public conditions

O
org.shirakumo.file-select: The org․shirakumo․file-select package
org.shirakumo.file-select.gtk: The org․shirakumo․file-select․gtk package
org.shirakumo.file-select.macos: The org․shirakumo․file-select․macos package
org.shirakumo.file-select.win32: The org․shirakumo․file-select․win32 package
org.shirakumo.file-select.zenity: The org․shirakumo․file-select․zenity package

P
Package, org.shirakumo.file-select: The org․shirakumo․file-select package
Package, org.shirakumo.file-select.gtk: The org․shirakumo․file-select․gtk package
Package, org.shirakumo.file-select.macos: The org․shirakumo․file-select․macos package
Package, org.shirakumo.file-select.win32: The org․shirakumo․file-select․win32 package
Package, org.shirakumo.file-select.zenity: The org․shirakumo․file-select․zenity package
package.lisp: The file-select/package․lisp file
protocol.lisp: The file-select/protocol․lisp file

S
System, file-select: The file-select system

W
win32.lisp: The file-select/win32․lisp file

Z
zenity: Public classes
zenity.lisp: The file-select/zenity․lisp file

Jump to:   B   C   D   F   G   M   N   O   P   S   W   Z