Class TrayItem

Tray Item

Represents a single StatusNotifierItem (system tray icon) with its properties and actions.

Lifecycle:

Construction - Connect to StatusNotifierItem D-Bus proxy
Ready - Monitor item properties and icon changes
Disposal - Disconnect proxy and cleanup menu

Fires

removed - Emitted when item disappears from bus (busName: string)

Fires

ready - Emitted when item proxy is ready

Fires

changed - Emitted when item properties change

Hierarchy (View Summary)

default
- TrayItem

Implements

Disposable

Index

Accessors

icon

get icon(): string | Pixbuf
The icon as a name string, GdkPixbuf, or fallback "image-missing". Uses attention icon when "NeedsAttention".

Returns string | Pixbuf
- Defined in src/service/systemtray.ts:178

id

get id(): string
The unique application identifier for this tray item.

Returns string
- Defined in src/service/systemtray.ts:140

is_menu

get is_menu(): boolean
Whether the item only supports menu activation (no primary activate).

Returns boolean
- Defined in src/service/systemtray.ts:160

isDisposed

get isDisposed(): boolean
Check if service has been disposed

Returns boolean
Inherited from Service.isDisposed
- Defined in src/service.ts:411

status

get status(): string
The current status: "Passive", "Active", or "NeedsAttention".

Returns string
- Defined in src/service/systemtray.ts:150

title

get title(): string
The display title of the tray item.

Returns string
- Defined in src/service/systemtray.ts:145

get tooltip_markup(): string
Markup string from the item's tooltip, combining title and description.

Returns string
- Defined in src/service/systemtray.ts:165

window_id

get window_id(): number
The X11 window ID associated with this tray item, or 0.

Returns number
- Defined in src/service/systemtray.ts:155

Constructors

constructor

new TrayItem(busName: string, objectPath: string): TrayItem
Parameters
- busName: string
- objectPath: string
Returns TrayItem
Overrides default.constructor
- Defined in src/service/systemtray.ts:77

Methods

`Readonly`activate

activate(event: Event): void
Sends an Activate request to the tray item at the event's coordinates.
Parameters
- event: Event
  The GDK event providing root coordinates
Returns void
- Defined in src/service/systemtray.ts:97

bind

bind<
    Prop extends
        | "isDisposed"
        | "$signals"
        | "id"
        | "title"
        | "category"
        | "menu"
        | "status"
        | "window_id"
        | "is_menu"
        | "tooltip_markup"
        | "icon"
        | undefined,
>(
    prop: Prop,
): Binding<TrayItem, Prop, TrayItem[Prop]>
Creates a Binding for a property on this service.
Type Parameters
- Prop extends
      | "isDisposed"
      | "$signals"
      | "id"
      | "title"
      | "category"
      | "menu"
      | "status"
      | "window_id"
      | "is_menu"
      | "tooltip_markup"
      | "icon"
      | undefined
Parameters
- prop: Prop
  The property to bind
Returns Binding<TrayItem, Prop, TrayItem[Prop]>
A Binding that can be used in widget constructors
Example
```
const label = Widget.Label({
    label: audio.bind('volume').as(v => `${Math.round(v * 100)}%`),
});
```
Inherited from default.bind
- Defined in src/service.ts:348

changed

changed(property: string): void
Notifies listeners that a property changed and emits the 'changed' signal.
Parameters
- property: string
  The property name that changed
Returns void
Inherited from default.changed
- Defined in src/service.ts:330

connect

connect(signal?: string, callback: (_: this, ...args: any[]) => void): number
Connects a callback to a signal on this service.
Parameters
- signal: string = 'changed'
  The signal name (defaults to 'changed')
- callback: (_: this, ...args: any[]) => void
  The callback to invoke when the signal is emitted
Returns number
The signal connection ID
Inherited from default.connect
- Defined in src/service.ts:272

diffBind

diffBind<
    Item,
    Prop extends

            | "isDisposed"
            | "$signals"
            | "id"
            | "title"
            | "category"
            | "menu"
            | "status"
            | "window_id"
            | "is_menu"
            | "tooltip_markup"
            | "icon"
            | undefined,
>(
    prop: Prop,
    opts: {
        create: (item: Item) => Widget;
        key: (item: Item) => string | number;
        update?: (widget: Widget, item: Item) => void;
    },
): Binding<TrayItem, Prop, Widget[]>
Creates an incremental list binding that reuses existing widgets.

Instead of recreating all widgets on every update, this method caches widgets by a key function and only creates new widgets for new items, destroying widgets for removed items.
Type Parameters
- Item
- Prop extends
      | "isDisposed"
      | "$signals"
      | "id"
      | "title"
      | "category"
      | "menu"
      | "status"
      | "window_id"
      | "is_menu"
      | "tooltip_markup"
      | "icon"
      | undefined
Parameters
- prop: Prop
  The property containing the item array
- opts: {
      create: (item: Item) => Widget;
      key: (item: Item) => string | number;
      update?: (widget: Widget, item: Item) => void;
  }
  Key extractor, widget factory, and optional update callback
Returns Binding<TrayItem, Prop, Widget[]>
A Binding that produces an array of widgets
Example
```
const children = audio.diffBind('speakers', {
    key: (s) => s.name,
    create: (s) => Widget.Label({ label: s.description }),
    update: (w, s) => { w.label = s.description; },
});
```
Inherited from default.diffBind
- Defined in src/service.ts:472

`Protected`disconnectAll

disconnectAll(): void
Clean up all tracked signal connections Call this in service-specific dispose implementations

Returns void
Inherited from default.disconnectAll
- Defined in src/service.ts:380

dispose

dispose(): void
Dispose of service resources Override in subclasses to add specific cleanup

Returns void
Implementation of Disposable.dispose
Overrides default.dispose
- Defined in src/service/systemtray.ts:312

emit

emit(signal: string, ...args: any[]): void
Emits a signal, warning if the signal was not registered via Service.register.

The warning is cheap (a Set lookup per emit) and helps catch typos and missing signal declarations that silently break .bind().
Parameters
- signal: string
- ...args: any[]
Returns void
Inherited from default.emit
- Defined in src/service.ts:283

`Readonly`openMenu

openMenu(event: Event): void
Opens the context menu for this tray item, using DbusmenuGtk3 if available.
Parameters
- event: Event
  The GDK event for popup positioning
Returns void
- Defined in src/service/systemtray.ts:128

`Protected`retryWithBackoff

retryWithBackoff<T>(
    operation: () => Promise<T>,
    maxRetries?: number,
    baseDelay?: number,
): Promise<T>
Retry a DBus operation with exponential backoff
Type Parameters
- T
Parameters
- operation: () => Promise<T>
- maxRetries: number = 3
- baseDelay: number = 100
Returns Promise<T>
Inherited from default.retryWithBackoff
- Defined in src/service.ts:418

`Readonly`scroll

scroll(event: EventScroll): void
Sends a Scroll event to the tray item.
Parameters
- event: EventScroll
  The GDK scroll event with direction and delta
Returns void
- Defined in src/service/systemtray.ts:115

`Readonly`secondaryActivate

secondaryActivate(event: Event): void
Sends a SecondaryActivate (middle-click) request to the tray item.
Parameters
- event: Event
  The GDK event providing root coordinates
Returns void
- Defined in src/service/systemtray.ts:106

`Protected`trackConnection

trackConnection(emitter: Object, id: number): void
Track a signal connection for automatic cleanup
Parameters
- emitter: Object
  The object the signal is connected to (defaults to this)
- id: number
  The signal connection ID
Returns void
Inherited from default.trackConnection
- Defined in src/service.ts:361
trackConnection(id: number): void
Track a signal connection for automatic cleanup
Parameters
- id: number
  The signal connection ID
Returns void
Inherited from default.trackConnection
- Defined in src/service.ts:362

updateProperty

updateProperty(prop: string, value: unknown): void
Updates a property value and emits a notify signal if the value changed.

Performs a deep equality check via JSON serialization to avoid unnecessary notifications.
Parameters
- prop: string
  The property name in kebab-case
- value: unknown
  The new value
Returns void
Inherited from default.updateProperty
- Defined in src/service.ts:315

`Static`import

import<S extends keyof Services>(service: S): Promise<Services[S]>
Dynamically imports a built-in service by name.
Type Parameters
- S extends keyof Services
Parameters
- service: S
  The service name to import
Returns Promise<Services[S]>
The default export of the service module
Example
```
const Audio = await Service.import('audio');
const Battery = await Service.import('battery');
```
Inherited from default.import
- Defined in src/service.ts:234

`Static`pspec

pspec(name: string, type?: PspecType, handle?: PspecFlag): ParamSpec<unknown>
Creates a GObject property specification.
Parameters
- name: string
  The property name in kebab-case
- type: PspecType = 'jsobject'
  The property type (defaults to 'jsobject')
- handle: PspecFlag = 'r'
  The access flag: 'r', 'w', or 'rw' (defaults to 'r')
Returns ParamSpec<unknown>
A GObject.ParamSpec
Inherited from default.pspec
- Defined in src/service.ts:246

`Static`register

register(
    service: new (...args: any[]) => Object,
    signals?: { [signal: string]: PspecType[] },
    properties?: { [prop: string]: [type?: PspecType, handle?: PspecFlag] },
): void
Registers a GObject subclass with signals and properties.
Parameters
- service: new (...args: any[]) => Object
  The class constructor to register
- Optionalsignals: { [signal: string]: PspecType[] }
  Map of signal names to their parameter types
- Optionalproperties: { [prop: string]: [type?: PspecType, handle?: PspecFlag] }
  Map of property names to [type, accessFlag] tuples
Returns void
Inherited from default.register
- Defined in src/service.ts:257

Properties

`Optional`menu

menu?: Menu

DBusMenu if available

Class TrayItem

Fires

Fires

Fires

Hierarchy (View Summary)

Implements

Index

Accessors

Constructors

Methods

Properties

Accessors

category

Returns string

icon

Returns string | Pixbuf

id

Returns string

is_menu

Returns boolean

isDisposed

Returns boolean

status

Returns string

title

Returns string

tooltip_markup

Returns string

window_id

Returns number

Constructors

constructor

Parameters

Returns TrayItem

Methods

Readonlyactivate

Parameters

Returns void

bind

Type Parameters

Parameters

Returns Binding<TrayItem, Prop, TrayItem[Prop]>

Example

changed

Parameters

Returns void

connect

Parameters

Returns number

diffBind

Type Parameters

Parameters

Returns Binding<TrayItem, Prop, Widget[]>

Example

ProtecteddisconnectAll

Returns void

dispose

Returns void

emit

Parameters

Returns void

ReadonlyopenMenu

Parameters

Returns void

ProtectedretryWithBackoff

Type Parameters

Parameters

Returns Promise<T>

Readonlyscroll

Parameters

Returns void

ReadonlysecondaryActivate

Parameters

Returns void

ProtectedtrackConnection

Parameters

Returns void

Parameters

Returns void

updateProperty

`Readonly`activate

`Protected`disconnectAll

`Readonly`openMenu

`Protected`retryWithBackoff

`Readonly`scroll

`Readonly`secondaryActivate

`Protected`trackConnection

`Static`import

`Static`pspec

`Static`register

`Optional`menu