explorer

README

explorer

---

Integrates a simple Save As... or Open... mechanism to your Gio application.

What can it be used for?

Well, for anything that manipulates user's file. You can use os.Open to open and write file, but sometimes you want to know where to save the data, in those case Explorer is useful.

Status

Currently, Explorer supports most platforms, including Android 6+, JS, Linux (with XDG Portals), Windows 10+, iOS 14+ and macOS 10+. It will return ErrAvailableAPI for any other platform that isn't supported.

Limitations

Edit file content via explorer.ReadFile():

It may not be possible to edit/write data using explorer.ReadFile(). Because of that, it returns a io.ReadCloser instead of io.ReadWriteCloser, since some operational systems (such as JS) doesn't allow us to modify the file. However, you can use type-assertion to check if it's possible or not:

reader, _ := explorer.ReadFile()
if f, ok := reader.(*os.File); ok {
    // We can use `os.File.Write` in that case. It's NOT possible in all OSes.
    f.Write(...)
}

Select folders:

It's not possible to select folders.

Documentation

Index

• Variables
• func ListenEventsWindow(win *app.Window, event event.Event)
• func ReadFile(extensions ...string) (io.ReadCloser, error)
• func WriteFile(name string) (io.WriteCloser, error)
• type Explorer
  • func NewExplorer(w *app.Window) (e *Explorer)
  • func (e *Explorer) ChooseFile(extensions ...string) (io.ReadCloser, error)
  • func (e *Explorer) ChooseFiles(extensions ...string) ([]io.ReadCloser, error)
  • func (e *Explorer) CreateFile(name string) (io.WriteCloser, error)
  • func (e *Explorer) ListenEvents(evt event.Event)

Variables

var (
	// ErrUserDecline is returned when the user doesn't select the file.
	ErrUserDecline = errors.New("user exited the file selector without selecting a file")

	// ErrNotAvailable is return when the current OS isn't supported.
	ErrNotAvailable = errors.New("current OS not supported")
)

Functions

func ListenEventsWindow

func ListenEventsWindow(win *app.Window, event event.Event)

ListenEventsWindow calls Explorer.ListenEvents on DefaultExplorer, and creates a new Explorer, if needed.

Deprecated: Use NewExplorer instead.

func ReadFile

func ReadFile(extensions ...string) (io.ReadCloser, error)

ReadFile calls Explorer.ChooseFile on DefaultExplorer.

Deprecated: Use NewExplorer and Explorer.ChooseFile instead.

func WriteFile

func WriteFile(name string) (io.WriteCloser, error)

WriteFile calls Explorer.CreateFile on DefaultExplorer.

Deprecated: Use NewExplorer and Explorer.CreateFile instead.

Types

type Explorer

type Explorer struct {
	// contains filtered or unexported fields
}

Explorer facilitates opening OS-native dialogs to choose files and create files.

var (
	DefaultExplorer *Explorer
)

func NewExplorer

func NewExplorer(w *app.Window) (e *Explorer)

NewExplorer creates a new Explorer for the given *app.Window. The given app.Window must be unique and you should call NewExplorer once per new app.Window.

It's mandatory to use Explorer.ListenEvents on the same *app.Window.

func (*Explorer) ChooseFile

func (e *Explorer) ChooseFile(extensions ...string) (io.ReadCloser, error)

ChooseFile shows the file selector, allowing the user to select a single file. Optionally, it's possible to define which file extensions is supported to be selected (such as `.jpg`, `.png`).

Example: ChooseFile(".jpg", ".png") will only accept the selection of files with .jpg or .png extensions.

In some platforms the resulting `io.ReadCloser` is a `os.File`, but it's not a guarantee.

In most known browsers, when user clicks cancel then this function never returns.

It's a blocking call, you should call it on a separated goroutine. For most OSes, only one ChooseFile or CreateFile, can happen at the same time, for each app.Window/Explorer.

func (*Explorer) ChooseFiles

func (e *Explorer) ChooseFiles(extensions ...string) ([]io.ReadCloser, error)

ChooseFiles shows the files selector, allowing the user to select multiple files. Optionally, it's possible to define which file extensions is supported to be selected (such as `.jpg`, `.png`).

Example: ChooseFiles(".jpg", ".png") will only accept the selection of files with .jpg or .png extensions.

In some platforms the resulting `io.ReadCloser` is a `os.File`, but it's not a guarantee.

In most known browsers, when user clicks cancel then this function never returns.

It's a blocking call, you should call it on a separated goroutine. For most OSes, only one ChooseFile{,s} or CreateFile, can happen at the same time, for each app.Window/Explorer.

func (*Explorer) CreateFile

func (e *Explorer) CreateFile(name string) (io.WriteCloser, error)

CreateFile opens the file selector, and writes the given content into some file, which the use can choose the location.

It's important to close the `io.WriteCloser`. In some platforms the file will be saved only when the writer is closer.

In some platforms the resulting `io.WriteCloser` is a `os.File`, but it's not a guarantee.

It's a blocking call, you should call it on a separated goroutine. For most OSes, only one ChooseFile or CreateFile, can happen at the same time, for each app.Window/Explorer.

func (*Explorer) ListenEvents

func (e *Explorer) ListenEvents(evt event.Event)

ListenEvents must get all the events from Gio, in order to get the GioView. You must include that function where you listen for Gio events.

Similar as:

select {
case e := <-window.Events():

	explorer.ListenEvents(e)
	switch e := e.(type) {
		(( ... your code ...  ))
	}
}