README

trayhost

Package trayhost is a cross-platform Go library to place an icon in the host operating system's taskbar.

Platform Support

• macOS - Fully implemented and supported by @dmitshur.
• Linux - Partially implemented, but unsupported (needs an owner/maintainer).
• Windows - Partially implemented, but unsupported (needs an owner/maintainer).

Notes

On macOS, for Notification Center user notifications to work, your Go binary that uses trayhost must be a part of a standard macOS app bundle.

Most other functionality of trayhost will be available if the binary is not a part of app bundle, but you will get a terminal pop up, and you will not be able to configure some aspects of the app.

Here's a minimal layout of an app bundle:

$ tree "Trayhost Example.app"
Trayhost\ Example.app
└── Contents
    ├── Info.plist
    ├── MacOS
    │   └── example
    └── Resources
        └── Icon.icns

Here's a minimal Info.plist file as reference (only the entries that are needed, nothing extra):

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>CFBundleExecutable</key>
	<string>example</string>
	<key>CFBundleIconFile</key>
	<string>Icon</string>
	<key>CFBundleIdentifier</key>
	<string>ExampleApp</string>
	<key>NSHighResolutionCapable</key>
	<true/>
	<key>LSUIElement</key>
	<string>1</string>
</dict>
</plist>

• CFBundleIdentifier needs to be set to some value for Notification Center to work.
• The binary must be inside Contents/MacOS directory for Notification Center to work.
• NSHighResolutionCapable to enable Retina mode.
• LSUIElement is needed to make the app not appear in Cmd+Tab list and the dock while still being able to show a tooltip in the menu bar.

On macOS, when you run an app bundle, the working directory of the executed process is the root directory (/), not the app bundle's Contents/Resources directory. Change directory to Resources if you need to load resources from there.

ep, err := os.Executable()
if err != nil {
	log.Fatalln("os.Executable:", err)
}
err = os.Chdir(filepath.Join(filepath.Dir(ep), "..", "Resources"))
if err != nil {
	log.Fatalln("os.Chdir:", err)
}

Installation

go get -u github.com/shurcooL/trayhost

Documentation

Overview

Package trayhost is a cross-platform Go library to place an icon in the host operating system's taskbar.

Platform Support

- macOS - Fully implemented and supported by @dmitshur.

- Linux - Partially implemented, but unsupported (needs an owner/maintainer).

- Windows - Partially implemented, but unsupported (needs an owner/maintainer).

Notes

On macOS, for Notification Center user notifications to work, your Go binary that uses trayhost must be a part of a standard macOS app bundle.

Most other functionality of trayhost will be available if the binary is not a part of app bundle, but you will get a terminal pop up, and you will not be able to configure some aspects of the app.

Here's a minimal layout of an app bundle:

$ tree "Trayhost Example.app"
Trayhost\ Example.app
└── Contents
    ├── Info.plist
    ├── MacOS
    │   └── example
    └── Resources
        └── Icon.icns

Here's a minimal Info.plist file as reference (only the entries that are needed, nothing extra):

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>CFBundleExecutable</key>
	<string>example</string>
	<key>CFBundleIconFile</key>
	<string>Icon</string>
	<key>CFBundleIdentifier</key>
	<string>ExampleApp</string>
	<key>NSHighResolutionCapable</key>
	<true/>
	<key>LSUIElement</key>
	<string>1</string>
</dict>
</plist>

- CFBundleIdentifier needs to be set to some value for Notification Center to work.

- The binary must be inside Contents/MacOS directory for Notification Center to work.

- NSHighResolutionCapable to enable Retina mode.

- LSUIElement is needed to make the app not appear in Cmd+Tab list and the dock while still being able to show a tooltip in the menu bar.

On macOS, when you run an app bundle, the working directory of the executed process is the root directory (/), not the app bundle's Contents/Resources directory. Change directory to Resources if you need to load resources from there.

ep, err := os.Executable()
if err != nil {
	log.Fatalln("os.Executable:", err)
}
err = os.Chdir(filepath.Join(filepath.Dir(ep), "..", "Resources"))
if err != nil {
	log.Fatalln("os.Chdir:", err)
}

Example

package main import ( "fmt" "io/ioutil" "log" "os" "path/filepath" "time" "github.com/shurcooL/trayhost" ) func main() { menuItems := []trayhost.MenuItem{ { Title: "Example Item", Handler: func() { fmt.Println("do stuff") }, }, { Title: "Get Clipboard Content", Handler: func() { cc, err := trayhost.GetClipboardContent() if err != nil { fmt.Printf("GetClipboardContent() error: %v\n", err) return } fmt.Printf("Text: %q\n", cc.Text) fmt.Printf("Image: %v len(%v)\n", cc.Image.Kind, len(cc.Image.Bytes)) fmt.Printf("Files: len(%v) %v\n", len(cc.Files), cc.Files) }, }, { Title: "Set Clipboard Text", Handler: func() { const text = "this text gets copied" trayhost.SetClipboardText(text) fmt.Printf("Text %q got copied into your clipboard.\n", text) }, }, { // Displaying notifications requires a proper app bundle and won't work without one. // See https://godoc.org/github.com/shurcooL/trayhost#hdr-Notes. Title: "Display Notification", Handler: func() { notification := trayhost.Notification{ Title: "Example Notification", Body: "Notification body text is here.", Timeout: 3 * time.Second, Handler: func() { fmt.Println("do stuff when notification is clicked") }, } if cc, err := trayhost.GetClipboardContent(); err == nil && cc.Image.Kind != "" { // Use image from clipboard as notification image. notification.Image = cc.Image } notification.Display() }, }, trayhost.SeparatorMenuItem(), { Title: "Quit", Handler: trayhost.Exit, }, } // On macOS, when you run an app bundle, the working directory of the executed process // is the root directory (/), not the app bundle's Contents/Resources directory. // Change directory to Resources so that we can load resources from there. ep, err := os.Executable() if err != nil { log.Fatalln("os.Executable:", err) } err = os.Chdir(filepath.Join(filepath.Dir(ep), "..", "Resources")) if err != nil { log.Fatalln("os.Chdir:", err) } // Load tray icon. iconData, err := ioutil.ReadFile("icon@2x.png") if err != nil { log.Fatalln(err) } trayhost.Initialize("Example App", iconData, menuItems) trayhost.EnterLoop() }

Index

• func EnterLoop()
• func Exit()
• func Initialize(title string, imageData []byte, items []MenuItem)
• func SetClipboardText(text string)
• func UpdateMenu(newMenu []MenuItem)
• type ClipboardContent
  • func GetClipboardContent() (ClipboardContent, error)
• type Image
• type ImageKind
• type MenuItem
  • func SeparatorMenuItem() MenuItem
• type Notification
  • func (n Notification) Display()

Examples

• Package

Constants

This section is empty.

Variables

This section is empty.

Functions

func EnterLoop

func EnterLoop()

EnterLoop enters main loop.

func Exit

func Exit()

Exit exits the application. It can be called from a MenuItem handler.

func Initialize

func Initialize(title string, imageData []byte, items []MenuItem)

Initialize sets up the application properties. imageData is the icon image in PNG format.

func SetClipboardText

func SetClipboardText(text string)

SetClipboardText sets the system clipboard to the specified UTF-8 encoded string.

This function may only be called from the main thread.

func UpdateMenu

func UpdateMenu(newMenu []MenuItem)

UpdateMenu removes all current menu items, and adds new menu items.

Types

type ClipboardContent

type ClipboardContent struct {
	Text  string
	Image Image
	Files []string
}

ClipboardContent holds the contents of system clipboard.

func GetClipboardContent

func GetClipboardContent() (ClipboardContent, error)

GetClipboardContent returns the contents of the system clipboard, if it contains or is convertible to a UTF-8 encoded string, image, and/or files.

This function may only be called from the main thread.

type Image

type Image struct {
	Kind  ImageKind
	Bytes []byte
}

Image is an encoded image of certain kind.

type ImageKind

type ImageKind string

ImageKind is a file extension in lower case: "png", "jpg", "tiff", etc. Empty string means no image.

type MenuItem

type MenuItem struct {
	// Title is the title of menu item.
	//
	// If empty, it acts as a separator. SeparatorMenuItem can be used
	// to create such separator menu items.
	Title string

	// Enabled can optionally control if this menu item is enabled or disabled.
	//
	// nil means always enabled.
	Enabled func() bool

	// Handler is triggered when the item is activated. nil means no handler.
	Handler func()
}

MenuItem is a menu item.

func SeparatorMenuItem

func SeparatorMenuItem() MenuItem

SeparatorMenuItem creates a separator MenuItem.

type Notification

type Notification struct {
	Title string // Title of user notification.
	Body  string // Body of user notification.
	Image Image  // Image shown in the content of user notification.

	// Timeout specifies time after which the notification is cleared.
	//
	// A Timeout of zero means no timeout.
	Timeout time.Duration

	// Activation (click) handler.
	//
	// nil means no handler.
	Handler func()
}

Notification represents a user notification.

func (Notification) Display

func (n Notification) Display()

Display displays the user notification.