fynedesk

README

About

FyneDesk is an easy to use Linux/Unix desktop environment following material design. It is built using the Fyne toolkit and is designed to be easy to use as well as easy to develop. We use the Go language and welcome any contributions or feedback for the project.

Dependencies

For a full desktop experience you will also need the following external tools installed:

• arandr
• xbacklight or brightnessctl for laptop brightness
• connman-gtk is currently used for configuring Wi-Fi network settings

Compositor support currently requires compton to be installed.

Getting Started

Using standard Go tools you can install FyneDesk using:

go get fyne.io/fynedesk/cmd/fynedesk

This will add fynedesk to your $GOPATH (usually ~/go/bin). You can now run the app in "preview" mode like any other Fyne app. Doing so is not running a window manager, to do so requires another few steps:

Setting up as a desktop environment

To use this as your main desktop you can run the following commands to set up fynedesk as a selectable desktop option in your login manager (such as LightDM for example):

git clone https://github.com/fyne-io/fynedesk
cd fynedesk
make
sudo make install

You can now log out and see that it is in your desktop selection list at login.

Debugging a window manager

You can also run the window manager components in an embedded X window for testing. You will need the Xephyr tool installed for your platform (often installed as part of Xorg). Once it is present you can use the following command from the same directory as above:

make embed

It should look like this:

If you run the command when there is a window manager running, or on an operating system that does not support window managers (Windows or macOS) then the app will start in UI test mode. When loaded in this way you can run all of the features except the controlling of windows - they will load on your main desktop.

Runner

A desktop needs to be rock solid, and whilst we are working hard to get there, any alpha or beta software can run into unexpected issues. For that reason, we have included a fynedesk_runner utility that can help manage unexpected events. If you start the desktop using the runner, then if a crash occurs, it will normally recover where it left off with no loss of data in your applications.

Using standard Go tools you can install the runner using:

go get fyne.io/fynedesk/cmd/fynedesk_runner

From then on execute that instead of the fynedesk command for a more resilient desktop when testing out pre-release builds.

Shipping FyneDesk

If you are installing FyneDesk by default on a distribution, or making it available as a standard option, you should consider the following points. You do not need to ship the library or any dependencies, but it is recommended to add the following apps as well:

app	go get	description
fin	github.com/fyne-io/fin	A display manager app that matches the look and feel of FyneDesk

Please do let us know if you package FyneDesk for your system, so we can include a link from here :).

Documentation

Index

• Constants
• func RegisterModule(m ModuleMetadata)
• func SetInstance(desk Desktop)
• type AppData
• type ApplicationProvider
• type DeskSettings
• type Desktop
  • func Instance() Desktop
• type KeyBindModule
• type LaunchSuggestion
• type LaunchSuggestionModule
• type Module
• type ModuleMetadata
  • func AvailableModules() []ModuleMetadata
• type Screen
  • func (s *Screen) CanvasScale() float32
• type ScreenAreaModule
• type ScreenList
• type Shortcut
  • func NewShortcut(name string, key fyne.KeyName, mods deskDriver.Modifier) *Shortcut
  • func (s *Shortcut) ShortcutName() string
• type Stack
• type StackListener
• type StatusAreaModule
• type Window
• type WindowManager
• type WindowProperties

Constants

const (
	// AnyModifier is the shortcut modifier to use if the shortcut should always trigger - use sparingly
	AnyModifier deskDriver.Modifier = 0
	// UserModifier is the shortcut modifier to use if the shortcut should respect user preference.
	// This will be offered as a choice of Alt or Super (Command)
	UserModifier deskDriver.Modifier = deskDriver.SuperModifier << 1

	// KeyBrightnessDown is the virtual keyboard key for reducing brightness
	KeyBrightnessDown fyne.KeyName = "BrightnessDown"
	// KeyBrightnessUp is the virtual keyboard key for increasing brightness
	KeyBrightnessUp fyne.KeyName = "BrightnessUp"
	// KeyCalculator is available on some multimedia keyboards to open a calculator
	KeyCalculator fyne.KeyName = "Calculator"

	// KeyVolumeMute is the virtual keyboard key for muting sound
	KeyVolumeMute fyne.KeyName = "VolumeMute"
	// KeyVolumeDown is the virtual keyboard key for reducing sound level
	KeyVolumeDown fyne.KeyName = "VolumeDown"
	// KeyVolumeUp is the virtual keyboard key for increasing sound level
	KeyVolumeUp fyne.KeyName = "VolumeUp"
)

Functions

func RegisterModule

func RegisterModule(m ModuleMetadata)

RegisterModule adds a module to the list of available modules. New module packages should probably call this in their init().

func SetInstance

func SetInstance(desk Desktop)

SetInstance is an internal call :( TODO

Types

type AppData

type AppData interface {
	Name() string       // Name is the name of the app usually
	Run([]string) error // Run is the command to run the app, passing any environment variables to be set

	Categories() []string                      // Categories is a list of categories that the app fits in (platform specific)
	Hidden() bool                              // Hidden specifies whether instances of this app should be hidden
	Icon(theme string, size int) fyne.Resource // Icon returns an icon for the app in the requested theme and size
}

AppData is an interface for accessing information about application icons

type ApplicationProvider

type ApplicationProvider interface {
	AvailableApps() []AppData
	AvailableThemes() []string
	FindAppFromName(appName string) AppData
	FindAppFromWinInfo(win Window) AppData
	FindAppsMatching(pattern string) []AppData
	DefaultApps() []AppData
	CategorizedApps() map[string][]AppData
}

ApplicationProvider describes a type that can locate icons and applications for the current system

type DeskSettings

type DeskSettings interface {
	Background() string
	IconTheme() string
	BorderButtonPosition() string
	ClockFormatting() string

	LauncherIcons() []string
	LauncherIconSize() float32
	LauncherDisableTaskbar() bool
	LauncherDisableZoom() bool
	LauncherZoomScale() float32

	KeyboardModifier() deskDriver.Modifier
	ModuleNames() []string

	AddChangeListener(listener chan DeskSettings)
}

DeskSettings describes the configuration options available for Fyne desktop

type Desktop

type Desktop interface {
	Run()
	RunApp(AppData) error
	RecentApps() []AppData
	Settings() DeskSettings
	ContentSizePixels(screen *Screen) (uint32, uint32)
	Screens() ScreenList

	IconProvider() ApplicationProvider
	WindowManager() WindowManager
	Modules() []Module

	AddShortcut(shortcut *Shortcut, handler func())
	ShowMenuAt(menu *fyne.Menu, pos fyne.Position)
}

Desktop defines an embedded or full desktop environment that we can run.

func Instance

func Instance() Desktop

Instance returns the current desktop environment and provides access to injected functionality.

type KeyBindModule

type KeyBindModule interface {
	Shortcuts() map[*Shortcut]func()
}

KeyBindModule marks a module that provides key bindings. This is optional but can be enabled for any module by implementing the interface.

type LaunchSuggestion

type LaunchSuggestion interface {
	Icon() fyne.Resource
	Title() string
	Launch()
}

LaunchSuggestion represents an item that can appear in the app launcher and be actioned on tap

type LaunchSuggestionModule

type LaunchSuggestionModule interface {
	Module
	LaunchSuggestions(string) []LaunchSuggestion
}

LaunchSuggestionModule is a module that can provide suggestions for the app launcher

type Module

type Module interface {
	Metadata() ModuleMetadata
	Destroy()
}

Module marks the required methods of a pluggable module in FyneDesk.

type ModuleMetadata

type ModuleMetadata struct {
	Name        string
	NewInstance func() Module
}

ModuleMetadata is the information required to describe a module in FyneDesk

func AvailableModules

func AvailableModules() []ModuleMetadata

AvailableModules lists all of the FyneDesk modules that were found at runtime

type Screen

type Screen struct {
	Name                string  // Name is the randr provided name of the screen
	X, Y, Width, Height int     // Geometry of the screen
	Scale               float32 // Scale of this screen based on size and resolution
}

Screen provides relative information about a single physical screen

func (*Screen) CanvasScale

func (s *Screen) CanvasScale() float32

CanvasScale calculates the scale for the contents of a desktop canvas on this screen

type ScreenAreaModule

type ScreenAreaModule interface {
	Module
	ScreenAreaWidget() fyne.CanvasObject
}

ScreenAreaModule describes a module that can draw on the whole screen - these items will appear over the background image.

type ScreenList

type ScreenList interface {
	RefreshScreens()                                   // RefreshScreens asks the ScreenList implementation to reload it's data
	AddChangeListener(func())                          // Add a change listener to be notified if the screens change
	Screens() []*Screen                                // Screens returns a Screen type slice of each available physical screen
	SetActive(*Screen)                                 // Set the specified screen to be considered active
	Active() *Screen                                   // Active returns the screen index of the currently active screen
	Primary() *Screen                                  // Primary returns the screen index of the primary screen
	ScreenForWindow(Window) *Screen                    // Return the screen that a window is located on
	ScreenForGeometry(x, y, width, height int) *Screen // Return the screen that a geometry is located on
}

ScreenList provides information about available physical screens for Fyne desktop

type Shortcut

type Shortcut struct {
	fyne.KeyName
	deskDriver.Modifier
	Name string
}

Shortcut defines a keyboard shortcut that can be configured by the user

func NewShortcut

func NewShortcut(name string, key fyne.KeyName, mods deskDriver.Modifier) *Shortcut

NewShortcut creates a keyboard shortcut that can be configured by the user

func (*Shortcut) ShortcutName

func (s *Shortcut) ShortcutName() string

ShortcutName gets the name of this shortcut - this should be user presentable

type Stack

type Stack interface {
	AddWindow(Window)    // Add a new window to the stack
	RaiseToTop(Window)   // Request that the passed window become top of the stack.
	RemoveWindow(Window) // Remove a specified window from the stack
	TopWindow() Window   // Get the currently top most window
	Windows() []Window   // Return a list of all managed windows. This should not be modified
}

Stack describes an ordered list of windows. The order of the windows in this list matches the stacking order on screen. TopWindow() returns the 0th element with each item after that being stacked below the previous.

type StackListener

type StackListener interface {
	WindowAdded(Window)
	WindowRemoved(Window)
}

StackListener is used to listen for events in the window manager stack (window list). See WindowManager.AddStackListener.

type StatusAreaModule

type StatusAreaModule interface {
	Module
	StatusAreaWidget() fyne.CanvasObject
}

StatusAreaModule describes a module that can add items to the status area (the bottom of the widget panel)

type Window

type Window interface {
	Focused() bool      // Is this the currently focused window?
	Fullscreened() bool // Is the window Fullscreen?
	Iconic() bool       // Is the window Iconified?
	Maximized() bool    // Is the window Maximized?
	TopWindow() bool    // Is this the window on top?

	Capture() image.Image // Capture the contents of this window to an image
	Close()               // Close this window and possibly the application running it
	Focus()               // Ask this window to get input focus
	Fullscreen()          // Request to fullscreen this window
	Iconify()             // Request to iconify this window
	Maximize()            // Request to resize this window to it's largest possible size
	RaiseAbove(Window)    // Raise this window above a given other window
	RaiseToTop()          // Raise this window to the top of the stack
	Unfullscreen()        // Request to unfullscreen this window
	Uniconify()           // Request to restore this window and possibly children of this window from being minimized
	Unmaximize()          // Request to restore this window to its size before being maximized

	Properties() WindowProperties // Request the properties set on this window
	Position() fyne.Position
}

Window represents a single managed window within a window manager. There may be borders or not depending on configuration.

type WindowManager

type WindowManager interface {
	Stack
	AddStackListener(StackListener)

	Blank()
	Capture() image.Image // Capture the contents of the whole desktop to an image
	Close()
	Run()
	ShowOverlay(fyne.Window, fyne.Size, fyne.Position)
	ShowMenuOverlay(*fyne.Menu, fyne.Size, fyne.Position)
}

WindowManager describes a full window manager which may be loaded as part of the setup.

type WindowProperties

type WindowProperties interface {
	Class() []string     // The class of this window
	Command() string     // The command of this window
	Decorated() bool     // Should this window have borders drawn?
	Icon() fyne.Resource // The icon of this window
	IconName() string    // The icon name of this window
	SkipTaskbar() bool   // Should this window be added to the taskbar?
	Title() string       // The name of this window
}

WindowProperties encapsulates the metadata that a window can provide.