flutter

README

go-flutter - A package that brings Flutter to the desktop

Purpose

Flutter allows you to build beautiful native apps on iOS and Android from a single codebase.

This project brings Flutter to the desktop through the power of Go and GLFW.

The flutter engine itself doesn't know how to deal with desktop platforms (eg handling mouse/keyboard input). Instead, it exposes an abstraction layer for whatever platform to implement. This project implements the Flutter's Embedding API using a single code base that runs on Windows, MacOS, and Linux. For rendering, GLFW fits the job because it provides the right abstractions over the OpenGL's Buffer/Mouse/Keyboard for each platform.

The choice of Golang comes from the fact that it has the same tooling on every platform. Plus Golang is a great language because it keeps everything simple and readable, which makes it easy to build cross-platform plugins.

Getting started

The best way to get started is to install hover, the official go-flutter tool to set up, build and run Flutter apps on the desktop, including hot-reload.

Read the hover tutorial to run your app on desktop, or start with one of our example apps.

It's also possible to manually install and use go-flutter, but this is not recomended for new users.

Supported features

• Linux 🐧
• MacOS 🍎
• Windows 🏁
• Hot Reload
• Plugin system
  • BinaryMessageCodec, BinaryMessageChannel
  • StandardMessageCodec, JSONMessageCodec
  • StandardMethodCodec, MethodChannel
• Importable as Go library into custom projects
• Text input handling
• Clipboard copy & paste
• Window title and icon
• Standard keyboard shortcuts
  • ctrl-c ctrl-v ctrl-x ctrl-a
  • Home End shift-Home shift-End
  • Left ctrl-Left ctrl-shift-Left
  • Right ctrl-Right ctrl-shift-Right
  • Backspace ctrl-Backspace Delete
• Mouse-over/hovering
• RawKeyboard events (RawKeyEventDataLinux)

Are you missing a feature? Open an issue!

Examples

A separate repository contains example Flutter apps that also run on the desktop. Go to github.com/go-flutter-desktop/examples to give them a try.

Plugins

Some popular plugins are already implemented over at github.com/go-flutter-desktop/plugins. If you have implemented a plugin that you would like to share, feel free to open a PR on the plugins repository!

Version compatibility

Flutter version

Flutter itself is a relatively young project. Its framework and engine are updated often. The go-flutter project tries to stay compatible with the beta channel of Flutter.

Go version

Updating Go is simple, and Go seldomly has backwards incompatible changes. This project remains compatible with the latest Go stable release.

GLFW version

This project uses go-gl/glfw for GLFW v3.2.

License

BSD 3-Clause License

Documentation

Overview

Package flutter combines the embedder API with GLFW and plugins. Flutter and Go on the desktop.

go-flutter is in active development. API's must be considered alpha/unstable and may be changed at any time.

Index

• Constants
• Variables
• func Run(opt ...Option) (err error)
• type Application
  • func NewApplication(opt ...Option) *Application
  • func (a *Application) Run() error
• type KeyboardShortcuts
• type Option
  • func AddPlugin(p Plugin) Option
  • func ApplicationICUDataPath(p string) Option
  • func ApplicationWindowDimension(x, y int) Option
  • func ForcePixelRatio(ratio float64) Option
  • func OptionKeyboardLayout(keyboardLayout KeyboardShortcuts) Option
  • func OptionPixelRatio(ratio float64) Option
  • func OptionVMArguments(a []string) Option
  • func OptionWindowInitializer(ini func(*glfw.Window) error) Option
  • func PopBehavior(p popBehavior) Option
  • func ProjectAssetPath(p string) Option
  • func ProjectAssetsPath(p string) Option
  • func WindowDimensionLimits(minWidth, minHeight, maxWidth, maxHeight int) Option
  • func WindowIcon(iconProivder func() ([]image.Image, error)) Option
  • func WindowInitialDimensions(width, height int) Option
  • func WindowMode(w windowMode) Option
• type Plugin
• type PluginGLFW

Constants

const (
	// PopBehaviorNone means the system navigation pop event is ignored.
	PopBehaviorNone popBehavior = iota
	// PopBehaviorHide hides the application window on a system navigation pop
	// event.
	PopBehaviorHide
	// PopBehaviorIconify minimizes/iconifies the application window on a system
	// navigation pop event.
	PopBehaviorIconify
	// PopBehaviorClose closes the application on a system navigation pop event.
	PopBehaviorClose
)

const (
	// WindowModeDefault is the default window mode. Windows are created with
	// borders and close/minimize buttons.
	WindowModeDefault windowMode = iota
	// WindowModeBorderless removes decorations such as borders and
	// close/minimize buttons from the window.
	WindowModeBorderless
	// WindowModeBorderlessFullscreen starts the application in borderless
	// fullscreen mode. Currently, only fullscreen on the primary monitor is
	// supported. This option overrides WindowInitialDimensions. Note that on
	// some systems a fullscreen window is very hard to close. Make sure your
	// Flutter application has a close button and use PopBehaviorIconify to
	// minimize or PopBehaviorClose to close the application.
	WindowModeBorderlessFullscreen
)

Variables

var KeyboardAzertyLayout = KeyboardShortcuts{
	Cut:       glfw.KeyX,
	Copy:      glfw.KeyC,
	Paste:     glfw.KeyV,
	SelectAll: glfw.KeyQ,
}

KeyboardAzertyLayout gives an Azerty layout (french)

var KeyboardQwertyLayout = KeyboardShortcuts{
	Cut:       glfw.KeyX,
	Copy:      glfw.KeyC,
	Paste:     glfw.KeyV,
	SelectAll: glfw.KeyA,
}

KeyboardQwertyLayout is the default key for shortcuts (US-layout)

Functions

func Run

func Run(opt ...Option) (err error)

Run executes a flutter application with the provided options. given limitations this method must be called by the main function directly.

Run(opt) is short for NewApplication(opt).Run()

Types

type Application

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

Application provides the flutter engine in a user friendly matter.

func NewApplication

func NewApplication(opt ...Option) *Application

NewApplication creates a new application with provided options.

func (*Application) Run

func (a *Application) Run() error

Run starts the application and waits for it to finish.

type KeyboardShortcuts

type KeyboardShortcuts struct {
	Cut       glfw.Key
	Copy      glfw.Key
	Paste     glfw.Key
	SelectAll glfw.Key
}

KeyboardShortcuts contains the configuration for keyboard shortcut keys. This allows an application to support keyboard layout different from US layout.

type Option

type Option func(*config)

Option for Application

func AddPlugin

func AddPlugin(p Plugin) Option

AddPlugin adds a plugin to the flutter application.

func ApplicationICUDataPath

func ApplicationICUDataPath(p string) Option

ApplicationICUDataPath specify the path to the ICUData.

func ApplicationWindowDimension

func ApplicationWindowDimension(x, y int) Option

ApplicationWindowDimension specify the startup's dimensions of the window.

Deprecated, please use WindowInitialDimensions(x, y).

func ForcePixelRatio

func ForcePixelRatio(ratio float64) Option

ForcePixelRatio forces the the scale factor for the screen. By default, go-flutter will calculate the correct pixel ratio for the user, based on their monitor DPI. Setting this option is not advised.

func OptionKeyboardLayout

func OptionKeyboardLayout(keyboardLayout KeyboardShortcuts) Option

OptionKeyboardLayout allow application to support keyboard that have a different layout and therefore different keyboard shortcuts.

func OptionPixelRatio

func OptionPixelRatio(ratio float64) Option

OptionPixelRatio forces the the scale factor for the screen. By default, go-flutter will calculate the correct pixel ratio for the user, based on their monitor DPI. Setting this option is not advised.

Deprecated, please use ForcePixelRatio(ratio).

func OptionVMArguments

func OptionVMArguments(a []string) Option

OptionVMArguments specify the arguments to the Dart VM.

func OptionWindowInitializer

func OptionWindowInitializer(ini func(*glfw.Window) error) Option

OptionWindowInitializer allow initializing the window.

Deprecated, please use WindowIcon if you'd like to set the window icon.

func PopBehavior

func PopBehavior(p popBehavior) Option

PopBehavior sets the PopBehavior on the application

func ProjectAssetPath

func ProjectAssetPath(p string) Option

ProjectAssetPath specify the flutter assets directory.

Deprecated, please use ProjectAssetsPath(path).

func ProjectAssetsPath

func ProjectAssetsPath(p string) Option

ProjectAssetsPath specify the flutter assets directory.

func WindowDimensionLimits

func WindowDimensionLimits(minWidth, minHeight, maxWidth, maxHeight int) Option

WindowDimensionLimits specify the dimension limits of the window. Does not work when the window is fullscreen or not resizable.

func WindowIcon

func WindowIcon(iconProivder func() ([]image.Image, error)) Option

WindowIcon sets an icon provider func, which is called during window initialization. For tips on the kind of images to provide, see https://godoc.org/github.com/go-gl/glfw/v3.2/glfw#Window.SetIcon

func WindowInitialDimensions

func WindowInitialDimensions(width, height int) Option

WindowInitialDimensions specify the startup's dimension of the window.

func WindowMode

func WindowMode(w windowMode) Option

WindowMode sets the window mode on the application.

type Plugin

type Plugin interface {
	// InitPlugin is called during the startup of the flutter application. The
	// plugin is responsible for setting up channels using the BinaryMessenger.
	// If an error is returned it is printend the application is stopped.
	InitPlugin(messenger plugin.BinaryMessenger) error
}

Plugin defines the interface that each plugin must implement. When InitPlugin is called, the plugin may execute setup operations. The BinaryMessenger is passed to allow the plugin to register channels. A plugin may optionally implement PluginGLFW.

type PluginGLFW

type PluginGLFW interface {
	// Any type inmplementing PluginGLFW must also implement Plugin.
	Plugin
	// InitPluginGLFW is called after the call to InitPlugin. When an error is
	// returned it is printend the application is stopped.
	InitPluginGLFW(window *glfw.Window) error
}

PluginGLFW defines the interface for plugins that are GLFW-aware. Plugins may implement this interface to receive access to the *glfw.Window. Note that plugins must still implement the Plugin interface. The call to InitPluginGLFW is made afther the call to InitPlugin.

PluginGLFW is separated because not all plugins need to know about glfw, Adding glfw.Window to the InitPlugin call would add glfw as dependency to every plugin implementation. Also, this helps in a scenarion where glfw is moved into a separate renderer/glfw package.

The PluginGLFW interface is not stable and may change at any time.