portal

README

Portal

Portal is a Go module providing developer friendly functions for accessing the XDG Desktop Protocol D-Bus API. The goal of this project is to be toolkit agnostic and allow using the portals without needing to access libportal through CGo.

This repository is a maintained fork of rymdport/portal. It provides predictable releases for Refyne and xfilepicker, while keeping changes suitable for contributing back upstream whenever possible.

Maintenance scope

The actively supported surface is the shared request and signal machinery plus the filechooser, notification, openuri, settings, and settings/appearance packages. Other packages are retained for upstream compatibility and accept fixes on a best-effort basis.

The fork follows upstream changes selectively. Releases use this repository's module path and are tested before Refyne or xfilepicker adopt them.

Using the portals allow applications to request information from the user even when running inside a sandbox like Flatpak. As such, it is possible to open file dialogs, open links in the browser, send notifications and much more in a way that integrates well with the desktop environment. This also avoids needing to open up permissions in the sandbox.

API

The api of this Go module is designed to closely follow the structure naming of the upstream APIs. This means, in practice, that each D-Bus interface is implemented as its own package here. However, care is taken to be developer friendly and integrate seamlessly with native Go types.

• Documentation for this module and all of its packages can be found on pkg.go.dev: https://pkg.go.dev/github.com/alexballas/portal
• Documentation for the D-Bus protocol of the portals: https://flatpak.github.io/xdg-desktop-portal/docs/api-reference.html

The version of this module's API is still in a v0.X.Y state and is subject to change in the future. A release with breaking changes will increment X while Y will be incremented when there are minor bug or feature improvements.

Window Handles

The portal APIs often provide a windowHandle parameter that allow dialogs and other actions to be attached to a specific window.

From Fyne

With Fyne running in X11 mode it is easy to get the window handle like below. However, note that the snippet will not work with -tags wayland.

// based on https://github.com/fyne-io/fyne/blob/19dcdbdb5f5a9b293a21a29b5235c163345b36d0/dialog/file_xdg_flatpak.go#L124
func getWindowHandle(window fyne.Window) string {
	windowHandle := ""
	window.(driver.NativeWindow).RunNative(func(context any) {
		handle := context.(driver.X11WindowContext).WindowHandle
		windowHandle = portal.FormatX11WindowHandle(handle)
	})

	return windowHandle
}

Example

The following example showcases how a file chooser can be opened for selecting one or more files.

package main

import (
	"fmt"
	"log"

	"github.com/alexballas/portal/filechooser"
)

func main() {
	options := filechooser.OpenFileOptions{Multiple: true}
	files, err := filechooser.OpenFile("", "Select files", &options)
	if err != nil {
		log.Fatalln(err)
	}

	fmt.Println(files)
}

Every function that opens a portal dialog has a *Context variant. Cancelling the context asks the portal to dismiss the dialog:

ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()

files, err := filechooser.OpenFileContext(ctx, "", "Select files", nil)
if errors.Is(err, context.DeadlineExceeded) {
	// user did not pick a file within 30s; dialog was dismissed
}

Supported Portal Interfaces

The list below contains all of the portal interfaces available within the project. Checked boxes are partially or completely implemented within this project. Note that this list usually refers to the state of the main branch and not necessarily the latest release.

• Account
• Background
• Camera
• Clipboard
• Documents
• Dynamic Launcher
• Email
• File Chooser
• File Transfer
• Game Mode
• Global Shortcuts
• Inhibit
• Input Capture
• Location
• Memory Monitor
• Network Monitor
• Notification
• OpenURI
• Power Profile Monitor
• Print
• Proxy Resolver
• Realtime
• Remote Desktop
• Request
• ScreenCast
• Screenshot
• Secret
• Session
• Settings
• Trash
• Usb
• Wallpaper

Used by other projects

This section is meant as a reference to where this project is being used. Feel free to add yours if desired.

• This project is used as of the v2.5.0 release of Fyne.
  • All the old theme watching code has been replaced by the settings package (and appearance subpackage) from this module. The filechooser and notification packages replace the old Fyne-code when compiling with -tags flatpak.

Contributing

Contributions are strongly appreciated. Everything from creating bug reports to contributing code will help the project a lot, so please feel free to help in any way, shape, or form that you feel comfortable with.

License

• Portal is licensed under Apache License Version 2.0 and will forever continue to be free and open source.

Documentation

Index

• Variables
• func FormatX11WindowHandle(handle uintptr) string

Variables

var ErrUnexpectedResponse = errors.New("unexpected response from dbus")

ErrunexpectedResonse is returned when the received dbus data was in an unexpected format.

Functions

func FormatX11WindowHandle

func FormatX11WindowHandle(handle uintptr) string

FormatX11WindowHandle takes an X11 window handle and formats it in the string format that is required for the portal APIs.