astilectron

package module
v0.4.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 15, 2017 License: MIT Imports: 34 Imported by: 0

README

GoReportCard GoDoc GoCoverage

Thanks to go-astilectron build cross platform GUI apps with GO and HTML/JS/CSS. It is the official GO bindings of astilectron and is powered by Electron.

Quick start

WARNING: the code below doesn't handle errors for readibility purposes. However you SHOULD!

Import go-astilectron

To import go-astilectron run:

$ go get -u github.com/asticode/go-astilectron
Start go-astilectron
// Initialize astilectron
var a, _ = astilectron.New(astilectron.Options{
    AppName: "<your app name>",
    AppIconDefaultPath: "<your .png icon>",
    AppIconDarwinPath:  "<your .icns icon>",
    BaseDirectoryPath: "<where you want the provisioner to install the dependencies>",
})
defer a.Close()

// Start astilectron
a.Start()

For everything to work properly we need to fetch 2 dependencies : astilectron and Electron. .Start() takes care of it by downloading the sources and setting them up properly.

In case you want to embed the sources in the binary to keep a unique binary you can use the NewDisembedderProvisioner function to get the proper Provisioner and attach it to go-astilectron with .SetProvisioner(p Provisioner). Check out the example to see how to use it with go-bindata.

Beware when trying to add your own app icon as you'll need 2 icons : one compatible with MacOSX (.icns) and one compatible with the rest (.png for instance).

If no BaseDirectoryPath is provided, it defaults to the executable's directory path.

The majority of methods are synchrone which means that when executing them go-astilectron will block until it receives a specific Electron event or until the overall context is cancelled. This is the case of .Start() which will block until it receives the app.event.ready astilectron event or until the overall context is cancelled.

Loader

Provisioning astilectron and electron can take quite some time during which the user doesn't really know what's happening, therefore if you need a way to reassure the user that everything is going according to plan you can use the Loader:

// Start loader before starting astilectron
var l = astiloader.NewForAstilectron(a)
go l.Start()

This will display a native window using the awesome ui and containing a progress bar showing the progress. It will disappear once every steps are done.

This is important not to execute astiloader.NewForAstilectron(a) in a go routine as all steps need to be registered before being able to .Start() properly.

ui relies on C and unfortunately cross compilation when using cgo is a bitch. That's why the Loader has its own package and is not available by default. If you want to use the Loader you'll need to set up the proper cross-compilation toolchains.

You can also add custom steps to the Loader using the .Add() and .Done() methods.

Create a window
// Create a new window
var w, _ = a.NewWindow("http://127.0.0.1:4000", &astilectron.WindowOptions{
    Center: astilectron.PtrBool(true),
    Height: astilectron.PtrInt(600),
    Width:  astilectron.PtrInt(600),
})
w.Create()

When creating a window you need to indicate a URL as well as options such as position, size, etc.

This is pretty straightforward except the astilectron.Ptr* methods so let me explain: GO doesn't do optional fields when json encoding unless you use pointers whereas Electron does handle optional fields. Therefore I added helper methods to convert int, bool and string into pointers and used pointers in structs sent to Electron.

Add listeners
// Add a listener on Astilectron
a.On(astilectron.EventNameAppCrash, func(e astilectron.Event) (deleteListener bool) {
    astilog.Error("App has crashed")
    return
})

// Add a listener on the window
w.On(astilectron.EventNameWindowEventResize, func(e astilectron.Event) (deleteListener bool) {
    astilog.Info("Window resized")
    return
})

Nothing much to say here either except that you can add listeners to Astilectron as well.

Play with the window
// Play with the window
w.Resize(200, 200)
time.Sleep(time.Second)
w.Maximize()

Check out the Window doc for a list of all exported methods

Send messages between GO and your webserver

In your webserver add the following javascript to any of the pages you want to interact with:

<script>
    // This will wait for the astilectron namespace to be ready
    document.addEventListener('astilectron-ready', function() {
    
        // This will listen to messages sent by GO
        astilectron.listen(function(message) {
                            
            // This will send a message back to GO
            astilectron.send("I'm good bro")
        });
    })
</script>

In your GO app add the following:

// Listen to messages sent by webserver
w.On(astilectron.EventNameWindowEventMessage, func(e astilectron.Event) (deleteListener bool) {
    var m string
    e.Message.Unmarshal(&m)
    astilog.Infof("Received message %s", m)
    return
})

// Send message to webserver
w.Send("What's up?")

And that's it!

NOTE: needless to say that the message can be something other than a string. A custom struct for instance!

Handle several screens/displays
// If several displays, move the window to the second display
var displays = a.Displays()
if len(displays) > 1 {
    time.Sleep(time.Second)
    w.MoveInDisplay(displays[1], 50, 50)
}
Menus
// Init a new app menu
// You can do the same thing with a window
var m = a.NewMenu([]*astilectron.MenuItemOptions{
    {
        Label: astilectron.PtrStr("Separator"),
        SubMenu: []*astilectron.MenuItemOptions{
            {Label: astilectron.PtrStr("Normal 1")},
            {Label: astilectron.PtrStr("Normal 2")},
            {Type: astilectron.MenuItemTypeSeparator},
            {Label: astilectron.PtrStr("Normal 3")},
        },
    },
    {
        Label: astilectron.PtrStr("Checkbox"),
        SubMenu: []*astilectron.MenuItemOptions{
            {Checked: astilectron.PtrBool(true), Label: astilectron.PtrStr("Checkbox 1"), Type: astilectron.MenuItemTypeCheckbox},
            {Label: astilectron.PtrStr("Checkbox 2"), Type: astilectron.MenuItemTypeCheckbox},
            {Label: astilectron.PtrStr("Checkbox 3"), Type: astilectron.MenuItemTypeCheckbox},
        },
    },
    {
        Label: astilectron.PtrStr("Radio"),
        SubMenu: []*astilectron.MenuItemOptions{
            {Checked: astilectron.PtrBool(true), Label: astilectron.PtrStr("Radio 1"), Type: astilectron.MenuItemTypeRadio},
            {Label: astilectron.PtrStr("Radio 2"), Type: astilectron.MenuItemTypeRadio},
            {Label: astilectron.PtrStr("Radio 3"), Type: astilectron.MenuItemTypeRadio},
        },
    },
    {
        Label: astilectron.PtrStr("Roles"),
        SubMenu: []*astilectron.MenuItemOptions{
            {Label: astilectron.PtrStr("Minimize"), Role: astilectron.MenuItemRoleMinimize},
            {Label: astilectron.PtrStr("Close"), Role: astilectron.MenuItemRoleClose},
        },
    },
})

// Retrieve a menu item
// This will retrieve the "Checkbox 1" item
mi, _ := m.Item(1, 0)

// Add listener
mi.On(astilectron.EventNameMenuItemEventClicked, func(e astilectron.Event) bool {
    astilog.Infof("Menu item has been clicked. 'Checked' status is now %t", *e.MenuItemOptions.Checked)
    return false
})

// Create the menu
m.Create()

// Manipulate a menu item
mi.SetChecked(true)

// Init a new menu item
var ni = m.NewItem(&astilectron.MenuItemOptions{
    Label: astilectron.PtrStr("Inserted"),
    SubMenu: []*astilectron.MenuItemOptions{
        {Label: astilectron.PtrStr("Inserted 1")},
        {Label: astilectron.PtrStr("Inserted 2")},
    },
})

// Insert the menu item at position "1"
m.Insert(1, ni)

// Fetch a sub menu
s, _ := m.SubMenu(0)

// Init a new menu item
ni = s.NewItem(&astilectron.MenuItemOptions{
    Label: astilectron.PtrStr("Appended"),
    SubMenu: []*astilectron.MenuItemOptions{
        {Label: astilectron.PtrStr("Appended 1")},
        {Label: astilectron.PtrStr("Appended 2")},
    },
})

// Append menu item dynamically
s.Append(ni)

// Pop up sub menu as a context menu
s.Popup(&astilectron.MenuPopupOptions{PositionOptions: astilectron.PositionOptions{X: astilectron.PtrInt(50), Y: astilectron.PtrInt(50)}})

// Close popup
s.ClosePopup()

// Destroy the menu
m.Destroy()

A few things to know:

  • when assigning a role to a menu item, go-astilectron won't be able to capture its click event
  • on MacOS there's no such thing as a window menu, only app menus therefore my advice is to stick to one global app menu instead of creating separate window menus
Final code
// Set up the logger
var l <your logger type>
astilog.SetLogger(l)

// Start an http server
http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
    w.Write([]byte(`<!DOCTYPE html>
    <html lang="en">
    <head>
        <meta charset="UTF-8">
        <title>Hello world</title>
    </head>
    <body>
        <span id="message">Hello world</span>
        <script>
            // This will wait for the astilectron namespace to be ready
            document.addEventListener('astilectron-ready', function() {
                // This will listen to messages sent by GO
                astilectron.listen(function(message) {
                    document.getElementById('message').innerHTML = message
                    // This will send a message back to GO
                    astilectron.send("I'm good bro")
                });
            })
        </script>
    </body>
    </html>`))
})
go http.ListenAndServe("127.0.0.1:4000", nil)

// Initialize astilectron
var a, _ = astilectron.New(astilectron.Options{
    AppName: "<your app name>",
    AppIconDefaultPath: "<your .png icon>",
    AppIconDarwinPath:  "<your .icns icon>",
    BaseDirectoryPath: "<where you want the provisioner to install the dependencies>",
})
defer a.Close()

// Handle quit
a.HandleSignals()
a.On(astilectron.EventNameAppCrash, func(e astilectron.Event) (deleteListener bool) {
    astilog.Error("App has crashed")
    return
})

// Start loader before starting astilectron
var l = astiloader.NewForAstilectron(a)
go l.Start()

// Start astilectron: this will download and set up the dependencies, and start the Electron app
a.Start()

// Init a new app menu
// You can do the same thing with a window
var m = a.NewMenu([]*astilectron.MenuItemOptions{
    {
        Label: astilectron.PtrStr("Separator"),
        SubMenu: []*astilectron.MenuItemOptions{
            {Label: astilectron.PtrStr("Normal 1")},
            {Label: astilectron.PtrStr("Normal 2")},
            {Type: astilectron.MenuItemTypeSeparator},
            {Label: astilectron.PtrStr("Normal 3")},
        },
    },
    {
        Label: astilectron.PtrStr("Checkbox"),
        SubMenu: []*astilectron.MenuItemOptions{
            {Checked: astilectron.PtrBool(true), Label: astilectron.PtrStr("Checkbox 1"), Type: astilectron.MenuItemTypeCheckbox},
            {Label: astilectron.PtrStr("Checkbox 2"), Type: astilectron.MenuItemTypeCheckbox},
            {Label: astilectron.PtrStr("Checkbox 3"), Type: astilectron.MenuItemTypeCheckbox},
        },
    },
    {
        Label: astilectron.PtrStr("Radio"),
        SubMenu: []*astilectron.MenuItemOptions{
            {Checked: astilectron.PtrBool(true), Label: astilectron.PtrStr("Radio 1"), Type: astilectron.MenuItemTypeRadio},
            {Label: astilectron.PtrStr("Radio 2"), Type: astilectron.MenuItemTypeRadio},
            {Label: astilectron.PtrStr("Radio 3"), Type: astilectron.MenuItemTypeRadio},
        },
    },
    {
        Label: astilectron.PtrStr("Roles"),
        SubMenu: []*astilectron.MenuItemOptions{
            {Label: astilectron.PtrStr("Minimize"), Role: astilectron.MenuItemRoleMinimize},
            {Label: astilectron.PtrStr("Close"), Role: astilectron.MenuItemRoleClose},
        },
    },
})

// Retrieve a menu item
// This will retrieve the "Checkbox 1" item
mi, _ := m.Item(1, 0)

// Add listener
mi.On(astilectron.EventNameMenuItemEventClicked, func(e astilectron.Event) bool {
    astilog.Infof("Menu item has been clicked. 'Checked' status is now %t", *e.MenuItemOptions.Checked)
    return false
})

// Create the menu
m.Create()

// Create a new window with a listener on resize
var w, _ = a.NewWindow("http://127.0.0.1:4000", &astilectron.WindowOptions{
    Center: astilectron.PtrBool(true),
    Height: astilectron.PtrInt(600),
    Icon:   astilectron.PtrStr(<your icon path>),
    Width:  astilectron.PtrInt(600),
})
w.On(astilectron.EventNameWindowEventResize, func(e astilectron.Event) (deleteListener bool) {
    astilog.Info("Window resized")
    return
})
w.On(astilectron.EventNameWindowEventMessage, func(e astilectron.Event) (deleteListener bool) {
    var m string
    e.Message.Unmarshal(&m)
    astilog.Infof("Received message %s", m)
    return
})
w.Create()

// Play with the window
w.Resize(200, 200)
time.Sleep(time.Second)
w.Maximize()

// If several displays, move the window to the second display
var displays = a.Displays()
if len(displays) > 1 {
    time.Sleep(time.Second)
    w.MoveInDisplay(displays[1], 50, 50)
}

// Send a message to the server
time.Sleep(time.Second)
w.Send("What's up?")

// Manipulate a menu item
time.Sleep(time.Second)
mi.SetChecked(true)

// Init a new menu item
var ni = m.NewItem(&astilectron.MenuItemOptions{
    Label: astilectron.PtrStr("Inserted"),
    SubMenu: []*astilectron.MenuItemOptions{
        {Label: astilectron.PtrStr("Inserted 1")},
        {Label: astilectron.PtrStr("Inserted 2")},
    },
})

// Insert the menu item at position "1"
time.Sleep(time.Second)
m.Insert(1, ni)

// Fetch a sub menu
s, _ := m.SubMenu(0)

// Init a new menu item
ni = s.NewItem(&astilectron.MenuItemOptions{
    Label: astilectron.PtrStr("Appended"),
    SubMenu: []*astilectron.MenuItemOptions{
        {Label: astilectron.PtrStr("Appended 1")},
        {Label: astilectron.PtrStr("Appended 2")},
    },
})

// Append menu item dynamically
time.Sleep(time.Second)
s.Append(ni)

// Pop up sub menu as a context menu
time.Sleep(time.Second)
s.Popup(&astilectron.MenuPopupOptions{PositionOptions: astilectron.PositionOptions{X: astilectron.PtrInt(50), Y: astilectron.PtrInt(50)}})

// Close popup
time.Sleep(time.Second)
s.ClosePopup()

// Destroy the menu
time.Sleep(time.Second)
m.Destroy()

// Blocking pattern
a.Wait()

Bootstrap

For convenience purposes I've added a bootstrap to help first timers and avoid code duplications.

NOTE: you DON'T have to use the bootstrap, it's entirely up to you whether to use it or not.

The bootstrap allows you to quickly create a one-window application using .html templates.

In order to use the bootstrap you must:

  • follow the following project organization:

      |--+ resources
        |
        |--+ static (contains your static files such as .css, .js, .png, etc.)
        |
        |--+ templates (contains your templates .html files)
  |--+ main.go

  • add the following comment on top of your main() method:

      //go:generate go-bindata -pkg $GOPACKAGE -o resources.go resources/...

    and run the following command before building your binary:

      $ go generate main.go

  • use the bootstrap.Run() method

Check out the example for a detailed working example (see the Examples section below for the specific commands to run).

I want to see it in actions!

To make things clearer I've tried to split features in different examples.

To run any of the examples, run the following commands:

$ go run examples/<name of the example>/main.go -v

Here's a list of the examples:

  • 1.basic_window creates a basic window that displays a static .html file
  • 2.basic_window_events plays with basic window methods and shows you how to set up your own listeners
  • 3.webserver_app sets up a basic webserver app
  • 4.remote_messaging sends a message to the webserver and listens for any response
  • 5.single_binary_distribution shows how to use go-astilectron in a unique binary. For this example you have to run one of the previous examples (so that the .zip files exist) and run the following commands:
$ go generate examples/5.single_binary_distribution/main.go
$ go run examples/5.single_binary_distribution/main.go examples/5.single_binary_distribution/vendor.go -v
  • 6.screens_and_displays plays around with screens and displays
  • 7.menus creates and manipulates menus
  • 8.loader displays a loader until the app is ready
  • 9.bootstrap shows how to use the bootstrap. For this example you have to run the following commands:
$ go generate examples/9.bootstrap/main.go
$ go run examples/9.bootstrap/main.go examples/9.bootstrap/resources.go -v

Features and roadmap

  • custom branding (custom app name, app icon, etc.)
  • window basic methods (create, show, close, resize, minimize, maximize, ...)
  • window basic events (close, blur, focus, unresponsive, crashed, ...)
  • remote messaging (messages between GO and the JS in the webserver)
  • single binary distribution
  • multi screens/displays
  • menu methods and events (create, insert, append, popup, clicked, ...)
  • loader
  • bootstrap
  • accelerators (shortcuts)
  • dialogs (open or save file, alerts, ...)
  • file methods (drag & drop, ...)
  • clipboard methods
  • power monitor events (suspend, resume, ...)
  • notifications (macosx)
  • desktop capturer (audio and video)
  • session methods
  • session events
  • window advanced options (add missing ones)
  • window advanced methods (add missing ones)
  • window advanced events (add missing ones)
  • child windows

Cheers to

go-thrust which is awesome but unfortunately not maintained anymore. It inspired this project.

Documentation

Index

Constants

View Source 
const (
	EventNameAppClose         = "app.close"
	EventNameAppCmdStop       = "app.cmd.stop"
	EventNameAppCrash         = "app.crash"
	EventNameAppErrorAccept   = "app.error.accept"
	EventNameAppEventReady    = "app.event.ready"
	EventNameAppNoAccept      = "app.no.accept"
	EventNameAppTooManyAccept = "app.too.many.accept"
)

App event names

View Source 
const (
	EventNameDisplayEventAdded          = "display.event.added"
	EventNameDisplayEventMetricsChanged = "display.event.metrics.changed"
	EventNameDisplayEventRemoved        = "display.event.removed"
)

Display event names

View Source 
const (
	EventNameMenuCmdCreate      = "menu.cmd.create"
	EventNameMenuCmdDestroy     = "menu.cmd.destroy"
	EventNameMenuEventCreated   = "menu.event.created"
	EventNameMenuEventDestroyed = "menu.event.destroyed"
)

Menu event names

View Source 
const (
	EventNameMenuItemCmdSetChecked   = "menu.item.cmd.set.checked"
	EventNameMenuItemCmdSetEnabled   = "menu.item.cmd.set.enabled"
	EventNameMenuItemCmdSetLabel     = "menu.item.cmd.set.label"
	EventNameMenuItemCmdSetVisible   = "menu.item.cmd.set.visible"
	EventNameMenuItemEventCheckedSet = "menu.item.event.checked.set"
	EventNameMenuItemEventClicked    = "menu.item.event.clicked"
	EventNameMenuItemEventEnabledSet = "menu.item.event.enabled.set"
	EventNameMenuItemEventLabelSet   = "menu.item.event.label.set"
	EventNameMenuItemEventVisibleSet = "menu.item.event.visible.set"
)

Menu item event names

View Source 
const (
	EventNameProvisionAstilectronAlreadyProvisioned = "provision.astilectron.already.provisioned"
	EventNameProvisionAstilectronFinished           = "provision.astilectron.finished"
	EventNameProvisionAstilectronMoved              = "provision.astilectron.moved"
	EventNameProvisionAstilectronUnzipped           = "provision.astilectron.unzipped"
	EventNameProvisionElectronAlreadyProvisioned    = "provision.electron.already.provisioned"
	EventNameProvisionElectronFinished              = "provision.electron.finished"
	EventNameProvisionElectronMoved                 = "provision.electron.moved"
	EventNameProvisionElectronUnzipped              = "provision.electron.unzipped"
)

Provision event names

View Source 
const (
	EventNameSubMenuCmdAppend        = "sub.menu.cmd.append"
	EventNameSubMenuCmdClosePopup    = "sub.menu.cmd.close.popup"
	EventNameSubMenuCmdInsert        = "sub.menu.cmd.insert"
	EventNameSubMenuCmdPopup         = "sub.menu.cmd.popup"
	EventNameSubMenuEventAppended    = "sub.menu.event.appended"
	EventNameSubMenuEventClosedPopup = "sub.menu.event.closed.popup"
	EventNameSubMenuEventInserted    = "sub.menu.event.inserted"
	EventNameSubMenuEventPoppedUp    = "sub.menu.event.popped.up"
)

Sub menu event names

View Source 
const (
	EventNameWindowCmdBlur                     = "window.cmd.blur"
	EventNameWindowCmdCenter                   = "window.cmd.center"
	EventNameWindowCmdClose                    = "window.cmd.close"
	EventNameWindowCmdCreate                   = "window.cmd.create"
	EventNameWindowCmdDestroy                  = "window.cmd.destroy"
	EventNameWindowCmdFocus                    = "window.cmd.focus"
	EventNameWindowCmdHide                     = "window.cmd.hide"
	EventNameWindowCmdMaximize                 = "window.cmd.maximize"
	EventNameWindowCmdMessage                  = "window.cmd.message"
	EventNameWindowCmdMinimize                 = "window.cmd.minimize"
	EventNameWindowCmdMove                     = "window.cmd.move"
	EventNameWindowCmdResize                   = "window.cmd.resize"
	EventNameWindowCmdRestore                  = "window.cmd.restore"
	EventNameWindowCmdShow                     = "window.cmd.show"
	EventNameWindowCmdUnmaximize               = "window.cmd.unmaximize"
	EventNameWindowCmdWebContentsCloseDevTools = "window.cmd.web.contents.close.dev.tools"
	EventNameWindowCmdWebContentsOpenDevTools  = "window.cmd.web.contents.open.dev.tools"
	EventNameWindowEventBlur                   = "window.event.blur"
	EventNameWindowEventClosed                 = "window.event.closed"
	EventNameWindowEventDidFinishLoad          = "window.event.did.finish.load"
	EventNameWindowEventFocus                  = "window.event.focus"
	EventNameWindowEventHide                   = "window.event.hide"
	EventNameWindowEventMaximize               = "window.event.maximize"
	EventNameWindowEventMessage                = "window.event.message"
	EventNameWindowEventMinimize               = "window.event.minimize"
	EventNameWindowEventMove                   = "window.event.move"
	EventNameWindowEventReadyToShow            = "window.event.ready.to.show"
	EventNameWindowEventResize                 = "window.event.resize"
	EventNameWindowEventRestore                = "window.event.restore"
	EventNameWindowEventShow                   = "window.event.show"
	EventNameWindowEventUnmaximize             = "window.event.unmaximize"
	EventNameWindowEventUnresponsive           = "window.event.unresponsive"
)

Window event names

Variables

View Source 
var (
	// All
	MenuItemRoleClose              = PtrStr("close")
	MenuItemRoleCopy               = PtrStr("copy")
	MenuItemRoleCut                = PtrStr("cut")
	MenuItemRoleDelete             = PtrStr("delete")
	MenuItemRoleEditMenu           = PtrStr("editMenu")
	MenuItemRoleForceReload        = PtrStr("forcereload")
	MenuItemRoleMinimize           = PtrStr("minimize")
	MenuItemRolePaste              = PtrStr("paste")
	MenuItemRolePasteAndMatchStyle = PtrStr("pasteandmatchstyle")
	MenuItemRoleQuit               = PtrStr("quit")
	MenuItemRoleRedo               = PtrStr("redo")
	MenuItemRoleReload             = PtrStr("reload")
	MenuItemRoleResetZoom          = PtrStr("resetzoom")
	MenuItemRoleSelectAll          = PtrStr("selectall")
	MenuItemRoleToggleDevTools     = PtrStr("toggledevtools")
	MenuItemRoleToggleFullScreen   = PtrStr("togglefullscreen")
	MenuItemRoleUndo               = PtrStr("undo")
	MenuItemRoleWindowMenu         = PtrStr("windowMenu")
	MenuItemRoleZoomOut            = PtrStr("zoomout")
	MenuItemRoleZoomIn             = PtrStr("zoomin")

	// MacOSX
	MenuItemRoleAbout         = PtrStr("about")
	MenuItemRoleHide          = PtrStr("hide")
	MenuItemRoleHideOthers    = PtrStr("hideothers")
	MenuItemRoleUnhide        = PtrStr("unhide")
	MenuItemRoleStartSpeaking = PtrStr("startspeaking")
	MenuItemRoleStopSpeaking  = PtrStr("stopspeaking")
	MenuItemRoleFront         = PtrStr("front")
	MenuItemRoleZoom          = PtrStr("zoom")
	MenuItemRoleWindow        = PtrStr("window")
	MenuItemRoleHelp          = PtrStr("help")
	MenuItemRoleServices      = PtrStr("services")
)

Menu item roles

View Source 
var (
	MenuItemTypeNormal    = PtrStr("normal")
	MenuItemTypeSeparator = PtrStr("separator")
	MenuItemTypeCheckbox  = PtrStr("checkbox")
	MenuItemTypeRadio     = PtrStr("radio")
)

Menu item types

View Source 
var (
	ErrCancellerCancelled = errors.New("canceller.cancelled")
	ErrObjectDestroyed    = errors.New("object.destroyed")
)

Object errors

View Source 
var (
	TitleBarStyleDefault     = PtrStr("default")
	TitleBarStyleHidden      = PtrStr("hidden")
	TitleBarStyleHiddenInset = PtrStr("hidden-inset")
)

Title bar styles

View Source 
var DefaultProvisioner = &defaultProvisioner{
	moverAstilectron: func(ctx context.Context, p Paths) (err error) {
		if err = Download(ctx, defaultHTTPClient, p.AstilectronDownloadSrc(), p.AstilectronDownloadDst()); err != nil {
			return errors.Wrapf(err, "downloading %s into %s failed", p.AstilectronDownloadSrc(), p.AstilectronDownloadDst())
		}
		return
	},
	moverElectron: func(ctx context.Context, p Paths) (err error) {
		if err = Download(ctx, defaultHTTPClient, p.ElectronDownloadSrc(), p.ElectronDownloadDst()); err != nil {
			return errors.Wrapf(err, "downloading %s into %s failed", p.ElectronDownloadSrc(), p.ElectronDownloadDst())
		}
		return
	},
}

DefaultProvisioner represents the default provisioner

Functions

func Disembed added in v0.2.0 

func Disembed(ctx context.Context, d Disembedder, src, dst string) (err error)

Disembed is a cancellable disembed of an src to a dst using a custom Disembedder

func Download 

func Download(ctx context.Context, c *http.Client, src, dst string) (err error)

Download is a cancellable function that downloads a src into a dst using a specific *http.Client and cleans up on failed downloads

func PtrBool 

func PtrBool(i bool) *bool

PtrBool transforms a bool into a *bool

func PtrFloat added in v0.2.0 

func PtrFloat(i float64) *float64

PtrFloat transforms a float64 into a *float64

func PtrInt 

func PtrInt(i int) *int

PtrInt transforms an int into an *int

func PtrStr 

func PtrStr(i string) *string

PtrStr transforms a string into a *string

func Unzip 

func Unzip(ctx context.Context, src, dst string) error

Unzip unzips a src into a dst. Possible src formats are /path/to/zip.zip or /path/to/zip.zip/internal/path.

Types

type Astilectron 

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

Astilectron represents an object capable of interacting with Astilectron

func New 

func New(o Options) (a *Astilectron, err error)

New creates a new Astilectron instance

func (*Astilectron) Close 

func (a *Astilectron) Close()

Close closes Astilectron properly

func (*Astilectron) Displays added in v0.2.0 

func (a *Astilectron) Displays() []*Display

Displays returns the displays

func (*Astilectron) HandleSignals 

func (a *Astilectron) HandleSignals()

HandleSignals handles signals

func (*Astilectron) NewMenu added in v0.2.0 

func (a *Astilectron) NewMenu(i []*MenuItemOptions) *Menu

NewMenu creates a new app menu

func (*Astilectron) NewWindow 

func (a *Astilectron) NewWindow(url string, o *WindowOptions) (*Window, error)

NewWindow creates a new window

func (*Astilectron) NewWindowInDisplay added in v0.2.0 

func (a *Astilectron) NewWindowInDisplay(d *Display, url string, o *WindowOptions) (*Window, error)

NewWindowInDisplay creates a new window in a specific display This overrides the center attribute

func (*Astilectron) On 

func (a *Astilectron) On(eventName string, l Listener)

On implements the Listenable interface

func (*Astilectron) PrimaryDisplay added in v0.2.0 

func (a *Astilectron) PrimaryDisplay() *Display

PrimaryDisplay returns the primary display

func (*Astilectron) SetProvisioner 

func (a *Astilectron) SetProvisioner(p Provisioner) *Astilectron

SetProvisioner sets the provisioner

func (*Astilectron) Start 

func (a *Astilectron) Start() (err error)

Start starts Astilectron

func (*Astilectron) Stop 

func (a *Astilectron) Stop()

Stop orders Astilectron to stop

func (*Astilectron) Wait 

func (a *Astilectron) Wait()

Wait is a blocking pattern

type Disembedder added in v0.2.0 

type Disembedder func(src string) ([]byte, error)

Disembedder is a functions that allows to disembed data from a path

type Dispatcher added in v0.3.0 

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

Dispatcher represents an object capable of dispatching events

func (Dispatcher) Dispatch added in v0.3.0 

func (d Dispatcher) Dispatch(e Event)

Dispatch dispatches an event

type Display added in v0.2.0 

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

Display represents a display https://github.com/electron/electron/blob/v1.6.5/docs/api/structures/display.md

func (Display) Bounds added in v0.2.0 

func (d Display) Bounds() Rectangle

Bounds returns the display bounds

func (Display) IsPrimary added in v0.2.0 

func (d Display) IsPrimary() bool

IsPrimary checks whether the display is the primary display

func (Display) IsTouchAvailable added in v0.2.0 

func (d Display) IsTouchAvailable() bool

IsTouchAvailable checks whether touch is available on this display

func (Display) Rotation added in v0.2.0 

func (d Display) Rotation() int

Rotation returns the display rotation

func (Display) ScaleFactor added in v0.2.0 

func (d Display) ScaleFactor() float64

ScaleFactor returns the display scale factor

func (Display) Size added in v0.2.0 

func (d Display) Size() Size

Size returns the display size

func (Display) WorkArea added in v0.2.0 

func (d Display) WorkArea() Rectangle

WorkArea returns the display work area

func (Display) WorkAreaSize added in v0.2.0 

func (d Display) WorkAreaSize() Size

WorkAreaSize returns the display work area size

type DisplayOptions added in v0.2.0 

type DisplayOptions struct {
	Bounds       *RectangleOptions `json:"bounds,omitempty"`
	ID           *int              `json:"id,omitempty"`
	Rotation     *int              `json:"rotation,omitempty"` // 0, 90, 180 or 270
	ScaleFactor  *float64          `json:"scaleFactor,omitempty"`
	Size         *SizeOptions      `json:"size,omitempty"`
	TouchSupport *string           `json:"touchSupport,omitempty"` // available, unavailable or unknown
	WorkArea     *RectangleOptions `json:"workArea,omitempty"`
	WorkAreaSize *SizeOptions      `json:"workAreaSize,omitempty"`
}

DisplayOptions represents display options https://github.com/electron/electron/blob/v1.6.5/docs/api/structures/display.md

type Event 

type Event struct {
	// This is the base of the event
	Name     string `json:"name"`
	TargetID string `json:"targetID"`

	// This is a list of all possible payloads.
	// A choice was made not to use interfaces since it's a pain in the ass asserting each an every payload afterwards
	// We use pointers so that omitempty works
	Displays         *EventDisplays    `json:"displays,omitempty"`
	Menu             *EventMenu        `json:"menu,omitempty"`
	MenuItem         *EventMenuItem    `json:"menuItem,omitempty"`
	MenuItemOptions  *MenuItemOptions  `json:"menuItemOptions,omitempty"`
	MenuItemPosition *int              `json:"menuItemPosition,omitempty"`
	MenuPopupOptions *MenuPopupOptions `json:"menuPopupOptions,omitempty"`
	Message          *EventMessage     `json:"message,omitempty"`
	URL              string            `json:"url,omitempty"`
	WindowID         string            `json:"windowId,omitempty"`
	WindowOptions    *WindowOptions    `json:"windowOptions,omitempty"`
}

Event represents an event

type EventDisplays added in v0.2.0 

type EventDisplays struct {
	All     []*DisplayOptions `json:"all,omitempty"`
	Primary *DisplayOptions   `json:"primary,omitempty"`
}

EventDisplays represents events displays

type EventMenu added in v0.2.0 

type EventMenu struct {
	*EventSubMenu
}

EventMenu represents an event menu

type EventMenuItem added in v0.2.0 

type EventMenuItem struct {
	ID      string           `json:"id"`
	Options *MenuItemOptions `json:"options,omitempty"`
	RootID  string           `json:"rootId"`
	SubMenu *EventSubMenu    `json:"submenu,omitempty"`
}

EventMenuItem represents an event menu item

type EventMessage 

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

EventMessage represents an event message

func (*EventMessage) MarshalJSON 

func (p *EventMessage) MarshalJSON() ([]byte, error)

MarshalJSON implements the JSONMarshaler interface

func (*EventMessage) Unmarshal 

func (p *EventMessage) Unmarshal(i interface{}) error

Unmarshal unmarshals the payload into the given interface

func (*EventMessage) UnmarshalJSON 

func (p *EventMessage) UnmarshalJSON(i []byte) error

UnmarshalJSON implements the JSONUnmarshaler interface

type EventSubMenu added in v0.2.0 

type EventSubMenu struct {
	ID     string           `json:"id"`
	Items  []*EventMenuItem `json:"items,omitempty"`
	RootID string           `json:"rootId"`
}

EventSubMenu represents a sub menu event

type Listener 

type Listener func(e Event) (deleteListener bool)

Listener represents a listener executed when an event is dispatched 

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

Menu represents a menu https://github.com/electron/electron/blob/v1.6.5/docs/api/menu.md 

func (m Menu) Append(i *MenuItem) (err error)

Append appends a menu item into the sub menu 

func (m Menu) ClosePopup() error

ClosePopup close the context menu in the focused window 

func (m Menu) ClosePopupInWindow(w *Window) (err error)

ClosePopupInWindow close the context menu in the specified window 

func (m *Menu) Create() (err error)

Create creates the menu 

func (m *Menu) Destroy() (err error)

Destroy destroys the menu 

func (m Menu) Insert(pos int, i *MenuItem) (err error)

Insert inserts a menu item to the position of the sub menu 

func (m Menu) Item(indexes ...int) (mi *MenuItem, err error)

Item returns the item at the specified indexes 

func (m Menu) NewItem(o *MenuItemOptions) *MenuItem

NewItem returns a new menu item 

func (m Menu) Popup(o *MenuPopupOptions) error

Popup pops up the menu as a context menu in the focused window 

func (m Menu) PopupInWindow(w *Window, o *MenuPopupOptions) (err error)

PopupInWindow pops up the menu as a context menu in the specified window 

func (m Menu) SubMenu(indexes ...int) (s *SubMenu, err error)

SubMenu returns the sub menu at the specified indexes 

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

MenuItem represents a menu item 

func (o MenuItem) IsDestroyed() bool

IsDestroyed checks whether the window has been destroyed 

func (o MenuItem) On(eventName string, l Listener)

On implements the Listenable interface 

func (i *MenuItem) SetChecked(checked bool) (err error)

SetChecked sets the checked attribute 

func (i *MenuItem) SetEnabled(enabled bool) (err error)

SetEnabled sets the enabled attribute 

func (i *MenuItem) SetLabel(label string) (err error)

SetLabel sets the label attribute 

func (i *MenuItem) SetVisible(visible bool) (err error)

SetVisible sets the visible attribute 

func (i *MenuItem) SubMenu() *SubMenu

SubMenu returns the menu item sub menu 

type MenuItemOptions struct {
	// TODO Accelerator *string `json:"label,omitempty"`
	Checked  *bool              `json:"checked,omitempty"`
	Enabled  *bool              `json:"enabled,omitempty"`
	Icon     *string            `json:"icon,omitempty"`
	Label    *string            `json:"label,omitempty"`
	Position *string            `json:"position,omitempty"`
	Role     *string            `json:"role,omitempty"`
	SubLabel *string            `json:"sublabel,omitempty"`
	SubMenu  []*MenuItemOptions `json:"-"`
	Type     *string            `json:"type,omitempty"`
	Visible  *bool              `json:"visible,omitempty"`
}

MenuItemOptions represents menu item options We must use pointers since GO doesn't handle optional fields whereas NodeJS does. Use PtrBool, PtrInt or PtrStr to fill the struct https://github.com/electron/electron/blob/v1.6.5/docs/api/menu-item.md 

type MenuPopupOptions struct {
	PositionOptions
	PositioningItem *int `json:"positioningItem,omitempty"`
}

MenuPopupOptions represents menu pop options

type Options 

type Options struct {
	AppName            string
	AppIconDarwinPath  string // Darwin systems requires a specific .icns file
	AppIconDefaultPath string
	BaseDirectoryPath  string
}

Options represents Astilectron options

type Paths 

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

Paths represents the set of paths needed by Astilectron

func (*Paths) AppExecutable added in v0.2.0 

func (p *Paths) AppExecutable() string

AppExecutable returns the app executable path

func (*Paths) AppIconDarwinSrc added in v0.2.0 

func (p *Paths) AppIconDarwinSrc() string

AppIconDarwinSrc returns the darwin app icon path

func (*Paths) AstilectronApplication 

func (p *Paths) AstilectronApplication() string

AstilectronApplication returns the astilectron application path

func (*Paths) AstilectronDirectory 

func (p *Paths) AstilectronDirectory() string

AstilectronDirectory returns the astilectron directory path

func (*Paths) AstilectronDownloadDst 

func (p *Paths) AstilectronDownloadDst() string

AstilectronDownloadDst returns the astilectron download destination path

func (*Paths) AstilectronDownloadSrc 

func (p *Paths) AstilectronDownloadSrc() string

AstilectronDownloadSrc returns the astilectron download source path

func (*Paths) AstilectronUnzipSrc 

func (p *Paths) AstilectronUnzipSrc() string

AstilectronUnzipSrc returns the astilectron unzip source path

func (*Paths) BaseDirectory 

func (p *Paths) BaseDirectory() string

BaseDirectory returns the base directory path

func (*Paths) ElectronDirectory 

func (p *Paths) ElectronDirectory() string

ElectronDirectory returns the electron directory path

func (*Paths) ElectronDownloadDst 

func (p *Paths) ElectronDownloadDst() string

ElectronDownloadDst returns the electron download destination path

func (*Paths) ElectronDownloadSrc 

func (p *Paths) ElectronDownloadSrc() string

ElectronDownloadSrc returns the electron download source path

func (*Paths) ElectronUnzipSrc 

func (p *Paths) ElectronUnzipSrc() string

ElectronUnzipSrc returns the electron unzip source path

func (*Paths) ProvisionStatus added in v0.2.0 

func (p *Paths) ProvisionStatus() string

ProvisionStatus returns the provision status path

func (*Paths) VendorDirectory 

func (p *Paths) VendorDirectory() string

VendorDirectory returns the vendor directory path

type Position added in v0.2.0 

type Position struct {
	X, Y int
}

Position represents a position

type PositionOptions added in v0.2.0 

type PositionOptions struct {
	X *int `json:"x,omitempty"`
	Y *int `json:"y,omitempty"`
}

PositionOptions represents position options

type ProvisionStatus added in v0.2.0 

type ProvisionStatus struct {
	Astilectron *ProvisionStatusPackage `json:"astilectron,omitempty"`
	Electron    *ProvisionStatusPackage `json:"electron,omitempty"`
}

ProvisionStatus represents the provision status

type ProvisionStatusPackage added in v0.2.0 

type ProvisionStatusPackage struct {
	Version string `json:"version"`
}

ProvisionStatusPackage represents the provision status of a package

type Provisioner 

type Provisioner interface {
	Provision(ctx context.Context, d Dispatcher, appName, os string, p Paths) error
}

Provisioner represents an object capable of provisioning Astilectron

func NewDisembedderProvisioner added in v0.2.0 

func NewDisembedderProvisioner(d Disembedder, pathAstilectron, pathElectron string) Provisioner

NewDisembedderProvisioner creates a provisioner that can provision based on embedded data

type Rectangle added in v0.2.0 

type Rectangle struct {
	Position
	Size
}

Rectangle represents a rectangle

type RectangleOptions added in v0.2.0 

type RectangleOptions struct {
	PositionOptions
	SizeOptions
}

RectangleOptions represents rectangle options

type Size added in v0.2.0 

type Size struct {
	Height, Width int
}

Size represents a size

type SizeOptions added in v0.2.0 

type SizeOptions struct {
	Height *int `json:"height,omitempty"`
	Width  *int `json:"width,omitempty"`
}

SizeOptions represents size options 

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

SubMenu represents an exported sub menu 

func (m SubMenu) Append(i *MenuItem) (err error)

Append appends a menu item into the sub menu 

func (m SubMenu) ClosePopup() error

ClosePopup close the context menu in the focused window 

func (m SubMenu) ClosePopupInWindow(w *Window) (err error)

ClosePopupInWindow close the context menu in the specified window 

func (m SubMenu) Insert(pos int, i *MenuItem) (err error)

Insert inserts a menu item to the position of the sub menu 

func (m SubMenu) Item(indexes ...int) (mi *MenuItem, err error)

Item returns the item at the specified indexes 

func (m SubMenu) NewItem(o *MenuItemOptions) *MenuItem

NewItem returns a new menu item 

func (m SubMenu) Popup(o *MenuPopupOptions) error

Popup pops up the menu as a context menu in the focused window 

func (m SubMenu) PopupInWindow(w *Window, o *MenuPopupOptions) (err error)

PopupInWindow pops up the menu as a context menu in the specified window 

func (m SubMenu) SubMenu(indexes ...int) (s *SubMenu, err error)

SubMenu returns the sub menu at the specified indexes

type Window 

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

Window represents a window TODO Add missing window options TODO Add missing window methods TODO Add missing window events

func (*Window) Blur 

func (w *Window) Blur() (err error)

Blur blurs the window

func (*Window) Center 

func (w *Window) Center() (err error)

Center centers the window

func (*Window) Close 

func (w *Window) Close() (err error)

Close closes the window

func (*Window) CloseDevTools 

func (w *Window) CloseDevTools() (err error)

CloseDevTools closes the dev tools

func (*Window) Create 

func (w *Window) Create() (err error)

Create creates the window We wait for EventNameWindowEventDidFinishLoad since we need the web content to be fully loaded before being able to send messages to it

func (*Window) Destroy 

func (w *Window) Destroy() (err error)

Destroy destroys the window

func (*Window) Focus 

func (w *Window) Focus() (err error)

Focus focuses on the window

func (*Window) Hide 

func (w *Window) Hide() (err error)

Hide hides the window

func (Window) IsDestroyed added in v0.2.0 

func (o Window) IsDestroyed() bool

IsDestroyed checks whether the window has been destroyed

func (*Window) Maximize 

func (w *Window) Maximize() (err error)

Maximize maximizes the window

func (*Window) Minimize 

func (w *Window) Minimize() (err error)

Minimize minimizes the window

func (*Window) Move 

func (w *Window) Move(x, y int) (err error)

Move moves the window

func (*Window) MoveInDisplay added in v0.2.0 

func (w *Window) MoveInDisplay(d *Display, x, y int) error

MoveInDisplay moves the window in the proper display

func (*Window) NewMenu added in v0.2.0 

func (w *Window) NewMenu(i []*MenuItemOptions) *Menu

NewMenu creates a new window menu

func (Window) On 

func (o Window) On(eventName string, l Listener)

On implements the Listenable interface

func (*Window) OpenDevTools 

func (w *Window) OpenDevTools() (err error)

OpenDevTools opens the dev tools

func (*Window) Resize 

func (w *Window) Resize(width, height int) (err error)

Resize resizes the window

func (*Window) Restore 

func (w *Window) Restore() (err error)

Restore restores the window

func (*Window) Send 

func (w *Window) Send(message interface{}) (err error)

Send sends a message to the inner JS of the Web content of the window

func (*Window) Show 

func (w *Window) Show() (err error)

Show shows the window

func (*Window) Unmaximize 

func (w *Window) Unmaximize() (err error)

Unmaximize unmaximize the window

type WindowOptions 

type WindowOptions struct {
	AcceptFirstMouse       *bool   `json:"acceptFirstMouse,omitempty"`
	AlwaysOnTop            *bool   `json:"alwaysOnTop,omitempty"`
	AutoHideMenuBar        *bool   `json:"autoHideMenuBar,omitempty"`
	BackgroundColor        *string `json:"backgroundColor,omitempty"`
	Center                 *bool   `json:"center,omitempty"`
	Closable               *bool   `json:"closable,omitempty"`
	DisableAutoHideCursor  *bool   `json:"disableAutoHideCursor,omitempty"`
	EnableLargerThanScreen *bool   `json:"enableLargerThanScreen,omitempty"`
	Focusable              *bool   `json:"focusable,omitempty"`
	Frame                  *bool   `json:"frame,omitempty"`
	Fullscreen             *bool   `json:"fullscreen,omitempty"`
	Fullscreenable         *bool   `json:"fullscreenable,omitempty"`
	HasShadow              *bool   `json:"hasShadow,omitempty"`
	Height                 *int    `json:"height,omitempty"`
	Icon                   *string `json:"icon,omitempty"`
	Kiosk                  *bool   `json:"kiosk,omitempty"`
	MaxHeight              *int    `json:"maxHeight,omitempty"`
	Maximizable            *bool   `json:"maximizable,omitempty"`
	MaxWidth               *int    `json:"maxWidth,omitempty"`
	MinHeight              *int    `json:"minHeight,omitempty"`
	Minimizable            *bool   `json:"minimizable,omitempty"`
	MinWidth               *int    `json:"minWidth,omitempty"`
	Modal                  *bool   `json:"modal,omitempty"`
	Movable                *bool   `json:"movable,omitempty"`
	Resizable              *bool   `json:"resizable,omitempty"`
	Show                   *bool   `json:"show,omitempty"`
	SkipTaskbar            *bool   `json:"skipTaskbar,omitempty"`
	Title                  *string `json:"title,omitempty"`
	TitleBarStyle          *string `json:"titleBarStyle,omitempty"`
	Transparent            *bool   `json:"transparent,omitempty"`
	UseContentSize         *bool   `json:"useContentSize,omitempty"`
	Width                  *int    `json:"width,omitempty"`
	X                      *int    `json:"x,omitempty"`
	Y                      *int    `json:"y,omitempty"`
}

WindowOptions represents window options We must use pointers since GO doesn't handle optional fields whereas NodeJS does. Use PtrBool, PtrInt or PtrStr to fill the struct https://github.com/electron/electron/blob/v1.6.5/docs/api/browser-window.md

Source Files

View all Source files

Directories

Path Synopsis
examples
1.basic_window
2.basic_window_events
3.webserver_app
4.remote_messaging
5.single_binary_distribution
6.screens_and_displays
7.menus
8.loader
9.bootstrap

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.