tray

package module
v0.1.10 Latest Latest
Warning

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

 Go to latest Published: Nov 24, 2025 License: MIT Imports: 20 Imported by: 1

README

tray

Go Reference

tray is a very simple implementation of the StatusNotifierItem protocol for system tray icons on Linux.

Documentation

Overview

Package tray is an implementation of StatusNotifierItem.

Package tray provides a pure Go implementation of the StatusNotifierItem D-Bus interface. This can be used to create system tray icons and menus in most Linux desktop environments.

Index

Constants

This section is empty.

Variables

View Source 
var ARGB32Model color.Model = color.ModelFunc(argb32Model)

ARGB32Model is the color.Model implementation used by Pixmap.

Functions

This section is empty.

Types

type ARGB32 added in v0.1.7 

type ARGB32 uint32

ARGB32 is the color.Color implementation used by Pixmap.

func (ARGB32) RGBA added in v0.1.7 

func (c ARGB32) RGBA() (r, g, b, a uint32)

type ActivateHandler 

type ActivateHandler func(x, y int) error

ActiveHandler is a convenience type for the common case of only needing to implement the Activate method of Handler. It calls itself when Activate is called and does nothing for all other methods.

func (ActivateHandler) Activate 

func (h ActivateHandler) Activate(x, y int) error

func (ActivateHandler) ContextMenu 

func (h ActivateHandler) ContextMenu(x, y int) error

func (ActivateHandler) Scroll 

func (h ActivateHandler) Scroll(delta int, orientation Orientation) error

func (ActivateHandler) SecondaryActivate 

func (h ActivateHandler) SecondaryActivate(x, y int) error

type Category 

type Category string

Category is the possible values of the Category Item property. 

const (
	ApplicationStatus Category = "ApplicationStatus"
	Communications    Category = "Communications"
	SystemServices    Category = "SystemServices"
	Hardware          Category = "Hardware"
)

type Handler 

type Handler interface {
	ContextMenu(x, y int) error
	Activate(x, y int) error
	SecondaryActivate(x, y int) error
	Scroll(delta int, orientation Orientation) error
}

Handler specifies behavior for incoming events for a StatusNotifierItem. In most cases, Activate is the only method of interest, as that's the one that's called when an icon is clicked or double-clicked. For that common case, see ActivateHandler.

Errors returned by the methods of a Handler are sent over D-Bus as a response to the call that resulted in the Handler being invoked in the first place. In a lot of cases, this won't do much besides possibly showing up in a log somewhere, so it's probably best in those cases to handle it locally some other way, if appropriate, and then just return nil regardless.

type Item 

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

Item is a single StatusNotifierItem. Each item roughly corresponds to a single icon in the system tray.

func New 

func New(props ...ItemProp) (*Item, error)

New creates a new Item configured with the given props. It is recommended to at least set the ID and Icon properties, though these can be set later if preferred. The icon's behavior without them set will likely not be useful, however, if it isn't completely broken depending on the desktop environment.

func (*Item) AttentionIconName 

func (item *Item) AttentionIconName() string

AttentionIconName returns the current value of the AttentionIconName property.

func (*Item) AttentionIconPixmap 

func (item *Item) AttentionIconPixmap() []image.Image

AttentionIconPixmap returns the current value of the AttentionIconPixmap property.

func (*Item) AttentionMovieName 

func (item *Item) AttentionMovieName() string

AttentionMovieName returns the current value of the AttentionMovieName property.

func (*Item) Category 

func (item *Item) Category() Category

Category returns the current value of the Category property.

func (*Item) Close 

func (item *Item) Close() error

Close closes the underlying D-Bus connection, removing the item from the tray. The behavior of any calls to any methods either on this Item or on any associated Menu or MenuItem instances after calling this is undefined.

func (*Item) Handler 

func (item *Item) Handler() Handler

Handler returns the Handler that is used to handle events triggered by the desktop environment.

func (*Item) ID 

func (item *Item) ID() string

ID returns the current value of the Id property.

func (*Item) IconAccessibleDesc 

func (item *Item) IconAccessibleDesc() string

IconAccessibleDesc returns the current value of the IconAccessibleDesc property.

func (*Item) IconName 

func (item *Item) IconName() string

IconName returns the current value of the IconName property.

func (*Item) IconPixmap 

func (item *Item) IconPixmap() []image.Image

IconPixmap returns the current value of the IconPixmap property.

func (*Item) IsMenu 

func (item *Item) IsMenu() bool

IsMenu returns the current value of the ItemIsMenu property.

func (*Item) Menu 

func (item *Item) Menu() *Menu

Menu returns the Menu instance associated with the Item.

func (*Item) OverlayIconName 

func (item *Item) OverlayIconName() string

OverlayIconName returns the current value of the OverlayIconName property.

func (*Item) OverlayIconPixmap 

func (item *Item) OverlayIconPixmap() []image.Image

OverlayIconPixmap returns the current value of the OverlayIconPixmap property.

func (*Item) SetProps 

func (item *Item) SetProps(props ...ItemProp) error

SetProps sets the given properties for the item, emits any necessary signals after setting all of them, and then returns any errors that happened. A non-nil error return does not necessarily indicate complete failure.

func (*Item) Status 

func (item *Item) Status() Status

Status returns the current value of the Status property.

func (*Item) Title 

func (item *Item) Title() string

Title returns the current value of the Title property.

func (*Item) ToolTip 

func (item *Item) ToolTip() (iconName string, iconPixmap []image.Image, title, description string)

ToolTip returns the current values of the ToolTip property.

func (*Item) WindowID 

func (item *Item) WindowID() uint32

WindowID returns the current value of the WindowId property.

type ItemProp 

type ItemProp func(*itemProps)

ItemProp is a function that modifies the properties of an Item.

func ItemAttentionIconName 

func ItemAttentionIconName(name string) ItemProp

ItemAttentionIconName sets the AttentionIconName property to the given value.

func ItemAttentionIconPixmap 

func ItemAttentionIconPixmap(images ...image.Image) ItemProp

ItemAttentionIconPixmap sets the AttentionIconPixmap property to the given value.

func ItemAttentionMovieName 

func ItemAttentionMovieName(name string) ItemProp

ItemAttentionMovieName sets the AttentionMovieName property to the given value.

func ItemCategory 

func ItemCategory(category Category) ItemProp

ItemCategory sets the Category property to the given value.

func ItemHandler 

func ItemHandler(handler Handler) ItemProp

ItemHandler sets the Item's handler.

func ItemID 

func ItemID(id string) ItemProp

ItemID sets the Id property to the given value.

func ItemIconAccessibleDesc 

func ItemIconAccessibleDesc(desc string) ItemProp

ItemIconAccessibleDesc sets the IconAccessibleDesc property to the given value.

func ItemIconName 

func ItemIconName(name string) ItemProp

ItemIconName sets the IconName property to the given value.

func ItemIconPixmap 

func ItemIconPixmap(images ...image.Image) ItemProp

ItemIconPixmap sets the IconPixmap property to the given value.

func ItemIsMenu 

func ItemIsMenu(itemIsMenu bool) ItemProp

ItemIsMenu sets the ItemIsMenu property to the given value.

func ItemMenuHandler 

func ItemMenuHandler(handler MenuEventHandler) ItemProp

ItemMenuHandler sets the MenuEventHandler that is called when the menu receives incoming events. Generally speaking, clients will probably want to set handlers on MenuItem, not on the Menu itself.

func ItemMenuIconThemePath 

func ItemMenuIconThemePath(path []string) ItemProp

ItemMenuIconThemePath sets the item's associated menu's IconThemePath property.

func ItemMenuStatus 

func ItemMenuStatus(status MenuStatus) ItemProp

ItemMenuStatus sets the item's associated menu's Status property.

func ItemMenuTextDirection 

func ItemMenuTextDirection(direction TextDirection) ItemProp

ItemMenuTextDirection sets the item's associated menu's TextDirection property.

func ItemOverlayIconName 

func ItemOverlayIconName(name string) ItemProp

ItemOverlayIconName sets the OverlayIconName property to the given value.

func ItemOverlayIconPixmap 

func ItemOverlayIconPixmap(images ...image.Image) ItemProp

ItemOverlayIconPixmap sets the OverlayIconPixmap property to the given value.

func ItemStatus 

func ItemStatus(status Status) ItemProp

ItemStatus sets the Status property to the given value.

func ItemTitle 

func ItemTitle(title string) ItemProp

ItemTitle sets the Title property to the given value.

func ItemToolTip 

func ItemToolTip(iconName string, iconPixmap []image.Image, title, description string) ItemProp

ItemToolTip sets the ToolTip property to the given values.

func ItemWindowID 

func ItemWindowID(id uint32) ItemProp

ItemWindowID sets the WindowId property to the given value. 

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

Menu is the menu for a StatusNotifierItem as specififed by the dbusmenu interface. An instance of it is available via Item.Menu. 

func (menu *Menu) AddChild(props ...MenuItemProp) (*MenuItem, error)

AddChild creates a new MenuItem with the given properties and appends it as the last child of the root of the menu hierarchy. 

func (menu *Menu) AppendChild(child *MenuItem) error

AppendChild makes child the last child of the root of the menu hiearchy, moving it from wherever it currently is. The same rules about sub-menu conversion apply as they do in both [AddChild] and [Remove]. 

func (menu *Menu) IconThemePath() []string

IconThemePath returns the current value of the menu's IconThemePath property. 

func (menu *Menu) Status() MenuStatus

Status returns the current value of the menu's Status property. 

func (menu *Menu) TextDirection() TextDirection

TextDirection returns the current value of the menu's TextDirection property. 

type MenuEventHandler func(eventID MenuEventID, data any, timestamp uint32) error

MenuEventHandler is a function that is called in response to events on both the Menu and on MenuItem. It is given a MenuEventID that identifies the type of event, such as Clicked, arbitrary data that is associated with the event, and a timestamp. The timestamp corresponds to an internal time value of the sender and is not a specific absolute point in time.

The error returned by the handler is sent as a response to the D-Bus call that triggered it, so in a lot of cases it is more useful to handle an error locally in some way and then return nil from the handler regardless.

For the simple common case of handling specifically Clicked events, see ClickedHandler.

func ClickedHandler 

func ClickedHandler(handler func(data any, timestamp uint32) error) MenuEventHandler

ClickedHandler is a convenience function that returns a MenuEventHandler that calls handler if and only if the event ID is Clicked. 

type MenuEventID string

MenuEventID is an identifier for the type of event that is being sent to a menu's event handler. The values defined in this package are not the only possible values. In particular, the spec defines a format for vendor-specific custom values. These can be parsed with the [ParseVendor] method. 

const (
	Clicked MenuEventID = "clicked"
	Hovered MenuEventID = "hovered"
	Opened  MenuEventID = "opened"
	Closed  MenuEventID = "closed"
)
func (id MenuEventID) ParseVendor() (vendor, event string, ok bool)

ParseVendor parses a vendor-specific custom event ID. If id contains such a value, it returns the vendor and event names as parsed from it. If it does not contain such a value, the returned bool will be false. 

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

MenuItem is a single item in the menu of the tray item. The item can be a regular single item or can be a sub-menu containing more items, recursively.

MenuItems are created by calling the AddChild method on either the Menu or on another MenuItem. 

func (item *MenuItem) AddChild(props ...MenuItemProp) (*MenuItem, error)

AddChild creates a new MenuItem with the given properties and append it as the last child of the MenuItem that it is called on. If the receiver MenuItem has no children before this, it will automatically be converted into a sub-menu MenuItem. 

func (item *MenuItem) AppendChild(child *MenuItem) error

AppendChild makes child the last child of item, moving it from wherever it currently is. The same rules about sub-menu conversion apply as they do in both [AddChild] and [Remove]. 

func (item *MenuItem) Enabled() bool

Enabled returns the current value of the item's "enabled" property. 

func (item *MenuItem) IconData() (image.Image, error)

IconData returns the current value of the item's "icon-data" property. This is one of two properties that determine what icon should be displayed in the menu by the environment, the other being "icon-name". 

func (item *MenuItem) IconName() string

IconName returns the current value of the item's "icon-name" property. This is one of two properties that determine what icon should be displayed in the menu by the environment, the other being "icon-data". 

func (item *MenuItem) Label() string

Label returns the current value of the item's "label" property. This is the text that should be displayed by the environment for the item in the menu. 

func (item *MenuItem) MoveBefore(sibling *MenuItem) error

MoveBefore makes item the previous sibling of sibling. If necessary, this method will transfer item from its current parent to sibling's parent. 

func (item *MenuItem) Remove() error

Remove removes item from the menu hierarchy completely. If its parent is another MenuItem and item is its only child, the parent is converted from a sub-menu item back into a regular one. 

func (item *MenuItem) RequestActivation(timestamp uint32) error

RequestActivation sends a request to the environment that item be activated. What exactly this means is dependent on the environment and situation. 

func (item *MenuItem) SetProps(props ...MenuItemProp) error

SetProps sets all of the given properties on the item. 

func (item *MenuItem) Shortcut() [][]string

Shortcut returns the current value of the item's "shortcut" property. This is used by the environment to determine keyboard shortcuts and is of the form 

[][]string{
	[]string{"Control", "Alt", "e"},
}

func (item *MenuItem) ToggleState() MenuToggleState

ToggleState returns the current value of the item's "toggle-state" property. 

func (item *MenuItem) ToggleType() MenuToggleType

ToggleType returns the current value of the item's "toggle-type" property. 

func (item *MenuItem) Type() MenuType

Type returns the current value of the item's "type" property, 

func (item *MenuItem) VendorProp(vendor, prop string) (any, bool)

VendorProp returns the current value of the vendor-specific custom property with the given vendor and property name. It returns false as its second return if no such property exists. 

func (item *MenuItem) Visible() bool

Visible returns the current value of the item's "visible" property. 

type MenuItemProp func(*menuItemProps)
func MenuItemEnabled(enabled bool) MenuItemProp

MenuItemEnabled sets a MenuItem's "enabled" property. See MenuItem.Enabled. 

func MenuItemHandler(handler MenuEventHandler) MenuItemProp

MenuItemHandler sets the event handler for a MenuItem. 

func MenuItemIconData(img image.Image) MenuItemProp

MenuItemIconData sets a MenuItem's "icon-data" property. See MenuItem.IconData. 

func MenuItemIconName(name string) MenuItemProp

MenuItemIconName sets a MenuItem's "icon-name" property. See MenuItem.IconName. 

func MenuItemLabel(label string) MenuItemProp

MenuItemLabel sets a MenuItem's "label" property. See MenuItem.Label. 

func MenuItemShortcut(shortcut [][]string) MenuItemProp

MenuItemShortcut sets a MenuItem's "shortcut" property. See MenuItem.Shortcut. 

func MenuItemToggleState(state MenuToggleState) MenuItemProp

MenuItemToggleState sets a MenuItem's "toggle-state" property. See MenuItem.ToggleState. 

func MenuItemToggleType(t MenuToggleType) MenuItemProp

MenuItemToggleType sets a MenuItem's "toggle-type" property. See MenuItem.ToggleType. 

func MenuItemType(t MenuType) MenuItemProp

MenuItemType sets a MenuItem's "type" property. See MenuItem.Type. 

func MenuItemVendorProp(vendor, prop string, value any) MenuItemProp

MenuItemVendorProp sets a vendor-specific custom property with the given vendor and property name. See MenuItem.VendorProp. 

func MenuItemVisible(visible bool) MenuItemProp

MenuItemVisible sets a MenuItem's "visible" property. See MenuItem.Visible. 

type MenuStatus string

MenuStatus is the possible statuses of a menu. 

const (
	Normal MenuStatus = "normal"
	Notice MenuStatus = "notice"
)
type MenuToggleState int

MenuToggleState is the two main states that a togglable menu item can be in. All values other than On and Off are considered to be indeterminate. 

const (
	Off MenuToggleState = 0
	On  MenuToggleState = 1
)
func (state MenuToggleState) Indeterminate() bool

Indeterminate returns true if state represents an indeterminate state other than On and Off. 

type MenuToggleType string

MenuToggleType is the types of togglability that a menu item can have. 

const (
	NonToggleable MenuToggleType = ""
	Checkmark     MenuToggleType = "checkmark"
	Radio         MenuToggleType = "radio"
)
type MenuType string

MenuType is the possible values of the type of a menu item. 

const (
	Standard  MenuType = "standard"
	Separator MenuType = "separator"
)

type Orientation 

type Orientation string

Orientation is the possible directions of a scroll event. 

const (
	Horizontal Orientation = "horizontal"
	Vertical   Orientation = "vertical"
)

type Pixmap added in v0.1.7 

type Pixmap struct {
	Width, Height int
	Data          []byte
}

Pixmap is the raw wire format of StatusNotifierItem icon data. The Data field is in a big endian ARGB32 format. For convenience, Pixmap implements draw.Image to simplify conversion to and from other formats.

func ToPixmap added in v0.1.7 

func ToPixmap(img image.Image) Pixmap

ToPixmap converts an image.Image into a Pixmap. If an icon is being set to the same image more than once, it is more efficient to convert it to a Pixmap in advance using this function and then pass the result intead of the original image.Image.

func (Pixmap) At added in v0.1.7 

func (p Pixmap) At(x, y int) color.Color

func (Pixmap) Bounds added in v0.1.7 

func (p Pixmap) Bounds() image.Rectangle

func (Pixmap) ColorModel added in v0.1.7 

func (p Pixmap) ColorModel() color.Model

func (Pixmap) Copy added in v0.1.7 

func (p Pixmap) Copy() Pixmap

Copy returns a deep copy of p.

func (*Pixmap) Set added in v0.1.7 

func (p *Pixmap) Set(x, y int, c color.Color)

type Status 

type Status string

Status is the possible values of the Status Item property. 

const (
	Passive        Status = "Passive"
	Active         Status = "Active"
	NeedsAttention Status = "NeedsAttention"
)

type TextDirection 

type TextDirection string

TextDirection represents the possible configurations a menu's text direction. 

const (
	LeftToRight TextDirection = "ltr"
	RightToLeft TextDirection = "rtl"
)

Source Files

View all Source files

Directories

Path Synopsis
internal
set

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.