1. API
  2. tray

API

Methods for interacting with a ToDesktop application's tray icon.

Remarks

This package exposes a number of methods for interacting with a ToDesktop application's tray icon.

The tray icon is a part of the operating systems UI, located:

  • at the right of the Menu Bar on macOS; - in the System Tray on Windows.

Functions

Function Description
closeContextMenu(｛ ref ｝) Closes an open context menu, as set by tray.setContextMenu(). MacOS and Windows only.
create(args) Creates a new Tray.
destroy() Remove the app's tray item.
destroy(options)
displayBalloon(｛ ref, ...options ｝) Displays a tray balloon on windows.
focus(｛ ref ｝) Returns focus to the taskbar notification area. Windows only.
getBounds(｛ ref ｝) The bounds of this tray icon as Object. MacOS and Windows only.
getIgnoreDoubleClickEvents(｛ ref ｝) Whether double click events will be ignored.
getTitle(｛ ref ｝) Gets the title displayed next to the tray icon in the status bar.
isDestroyed(｛ ref ｝) Whether the tray icon is destroyed.
popUpContextMenu(｛ ref, ...options ｝) Pops up the context menu of the tray icon. When menu is passed, the menu will be shown instead of the tray icon's context menu. MacOS and Windows only.
removeBalloon(｛ ref ｝) Removes a tray balloon.
setContextMenu(｛ ref, ...options ｝) Sets the context menu for this icon.
setIgnoreDoubleClickEvents(｛ ref, ignore, ｝) Sets the option to ignore double click events. Ignoring these events allows you to detect every individual click of the tray icon.
setImage(｛ ref, image, ｝) Sets the image associated with this tray icon.
setPressedImage(｛ ref, image, ｝) Sets the image associated with this tray icon when pressed on macOS.
setTitle(title) Set the title of the app's tray item.
setTitle(options)
setToolTip(｛ ref, tooltip, ｝) Sets the hover text for this tray icon.

closeContextMenu()

Closes an open context menu, as set by tray.setContextMenu(). MacOS and Windows only.

Signature:

        import { tray } from "@todesktop/client-core"
tray.closeContextMenu({ ref }: {
    ref: Ref;
}): Promise<void>;
Parameters
Parameter Type Description
｛ ref ｝ ｛ ref: Ref; ｝

Returns:

Promise<void>

create()

Creates a new Tray.

Signature:

        import { tray } from "@todesktop/client-core"
tray.create(...args: [image: string | InstanceRefObject, guid?: string | undefined]): Promise<Ref>;
Parameters
Parameter Type Description
args [image: string | InstanceRefObject, guid?: string | undefined]

Returns:

Promise<Ref>

Identifier for the newly created Tray.

destroy()

Remove the app's tray item.

Signature:

        import { tray } from "@todesktop/client-core"
tray.destroy(): Promise<void>;

Returns:

Promise<void>

destroy()

Signature:

        import { tray } from "@todesktop/client-core"
tray.destroy(options: {
    ref: Ref;
}): Promise<void>;
Parameters
Parameter Type Description
options ｛ ref: Ref; ｝

Returns:

Promise<void>

displayBalloon()

Displays a tray balloon on windows.

Signature:

        import { tray } from "@todesktop/client-core"
tray.displayBalloon({ ref, ...options }: {
    ref: Ref;
} & DisplayBalloonOptions): Promise<void>;
Parameters
Parameter Type Description
｛ ref, ...options ｝ ｛ ref: Ref; ｝ & DisplayBalloonOptions

Returns:

Promise<void>

focus()

Returns focus to the taskbar notification area. Windows only.

Signature:

        import { tray } from "@todesktop/client-core"
tray.focus({ ref }: {
    ref: Ref;
}): Promise<void>;
Parameters
Parameter Type Description
｛ ref ｝ ｛ ref: Ref; ｝

Returns:

Promise<void>

getBounds()

The bounds of this tray icon as Object. MacOS and Windows only.

Signature:

        import { tray } from "@todesktop/client-core"
tray.getBounds({ ref }: {
    ref: Ref;
}): Promise<Electron.Rectangle>;
Parameters
Parameter Type Description
｛ ref ｝ ｛ ref: Ref; ｝

Returns:

Promise<Electron.Rectangle>

getIgnoreDoubleClickEvents()

Whether double click events will be ignored.

Signature:

        import { tray } from "@todesktop/client-core"
tray.getIgnoreDoubleClickEvents({ ref }: {
    ref: Ref;
}): Promise<boolean>;
Parameters
Parameter Type Description
｛ ref ｝ ｛ ref: Ref; ｝

Returns:

Promise<boolean>

getTitle()

Gets the title displayed next to the tray icon in the status bar.

Signature:

        import { tray } from "@todesktop/client-core"
tray.getTitle({ ref }: {
    ref: Ref;
}): Promise<string>;
Parameters
Parameter Type Description
｛ ref ｝ ｛ ref: Ref; ｝

Returns:

Promise<string>

isDestroyed()

Whether the tray icon is destroyed.

Signature:

        import { tray } from "@todesktop/client-core"
tray.isDestroyed({ ref }: {
    ref: Ref;
}): Promise<boolean>;
Parameters
Parameter Type Description
｛ ref ｝ ｛ ref: Ref; ｝

Returns:

Promise<boolean>

popUpContextMenu()

Pops up the context menu of the tray icon. When menu is passed, the menu will be shown instead of the tray icon's context menu. MacOS and Windows only.

Signature:

        import { tray } from "@todesktop/client-core"
tray.popUpContextMenu({ ref, ...options }: {
    ref: Ref;
    menu?: InstanceRefObject | undefined;
    position?: Electron.Point | undefined;
}): Promise<void>;
Parameters
Parameter Type Description
｛ ref, ...options ｝ ｛ ref: Ref; menu?: InstanceRefObject | undefined; position?: Electron.Point | undefined; ｝

Returns:

Promise<void>

removeBalloon()

Removes a tray balloon.

Signature:

        import { tray } from "@todesktop/client-core"
tray.removeBalloon({ ref }: {
    ref: Ref;
}): Promise<void>;
Parameters
Parameter Type Description
｛ ref ｝ ｛ ref: Ref; ｝

Returns:

Promise<void>

setContextMenu()

Sets the context menu for this icon.

Signature:

        import { tray } from "@todesktop/client-core"
tray.setContextMenu({ ref, ...options }: {
    ref: Ref;
    menu?: InstanceRefObject | undefined;
}): Promise<void>;
Parameters
Parameter Type Description
｛ ref, ...options ｝ ｛ ref: Ref; menu?: InstanceRefObject | undefined; ｝

Returns:

Promise<void>

setIgnoreDoubleClickEvents()

Sets the option to ignore double click events. Ignoring these events allows you to detect every individual click of the tray icon.

Signature:

        import { tray } from "@todesktop/client-core"
tray.setIgnoreDoubleClickEvents({ ref, ignore, }: {
    ref: Ref;
    ignore: boolean;
}): Promise<void>;
Parameters
Parameter Type Description
｛ ref, ignore, ｝ ｛ ref: Ref; ignore: boolean; ｝

Returns:

Promise<void>

setImage()

Sets the image associated with this tray icon.

Signature:

        import { tray } from "@todesktop/client-core"
tray.setImage({ ref, image, }: {
    ref: Ref;
    image: string | InstanceRefObject;
}): Promise<void>;
Parameters
Parameter Type Description
｛ ref, image, ｝ ｛ ref: Ref; image: string | InstanceRefObject; ｝

Returns:

Promise<void>

setPressedImage()

Sets the image associated with this tray icon when pressed on macOS.

Signature:

        import { tray } from "@todesktop/client-core"
tray.setPressedImage({ ref, image, }: {
    ref: Ref;
    image: string | InstanceRefObject;
}): Promise<void>;
Parameters
Parameter Type Description
｛ ref, image, ｝ ｛ ref: Ref; image: string | InstanceRefObject; ｝

Returns:

Promise<void>

setTitle()

Set the title of the app's tray item.

Signature:

        import { tray } from "@todesktop/client-core"
tray.setTitle(title: string): Promise<void>;
Parameters
Parameter Type Description
title string

Returns:

Promise<void>

setTitle()

Signature:

        import { tray } from "@todesktop/client-core"
tray.setTitle(options: SetTitleOptions): Promise<void>;
Parameters
Parameter Type Description
options SetTitleOptions

Returns:

Promise<void>

setToolTip()

Sets the hover text for this tray icon.

Signature:

        import { tray } from "@todesktop/client-core"
tray.setToolTip({ ref, tooltip, }: {
    ref: Ref;
    tooltip: string;
}): Promise<void>;
Parameters
Parameter Type Description
｛ ref, tooltip, ｝ ｛ ref: Ref; tooltip: string; ｝

Returns:

Promise<void>

Variables

Variable Description
on Subcribes to an event on a tray object.
removeAllListeners Unsubscribes all tray objects from the event name.

on

Subcribes to an event on a tray object.

Signature:

        on: <E extends "click" | "balloon-click" | "balloon-closed" | "balloon-show" | "double-click" | "drag-end" | "drag-enter" | "drag-leave" | "drop" | "drop-files" | "drop-text" | "mouse-down" | "mouse-enter" | "mouse-leave" | "mouse-move" | "mouse-up" | "right-click">(eventName: E, callback: NamespaceEvents<{
    "balloon-click": () => void;
    "balloon-closed": () => void;
    "balloon-show": () => void;
    click: () => void;
    "double-click": () => void;
    "drag-end": () => void;
    "drag-enter": () => void;
    "drag-leave": () => void;
    drop: () => void;
    "drop-files": (files: string[]) => void;
    "drop-text": (text: string) => void;
    "mouse-down": (position: Point) => void;
    "mouse-enter": (position: Point) => void;
    "mouse-leave": (position: Point) => void;
    "mouse-move": (position: Point) => void;
    "mouse-up": (position: Point) => void;
    "right-click": () => void;
}>[E], { ref, preventDefault }?: {
    ref?: InstanceRefObject;
    preventDefault?: boolean;
}) => Promise<() => Promise<void>>

removeAllListeners

Unsubscribes all tray objects from the event name.

Signature:

        removeAllListeners: <E extends "click" | "balloon-click" | "balloon-closed" | "balloon-show" | "double-click" | "drag-end" | "drag-enter" | "drag-leave" | "drop" | "drop-files" | "drop-text" | "mouse-down" | "mouse-enter" | "mouse-leave" | "mouse-move" | "mouse-up" | "right-click">(eventName: E, { ref, }?: {
    ref?: InstanceRefObject;
}) => Promise<void>

Type Aliases

TrayEvents

Signature:

        export declare type TrayEvents = NamespaceEvents<{
    "balloon-click": () => void;
    "balloon-closed": () => void;
    "balloon-show": () => void;
    click: () => void;
    "double-click": () => void;
    "drag-end": () => void;
    "drag-enter": () => void;
    "drag-leave": () => void;
    drop: () => void;
    "drop-files": (files: string[]) => void;
    "drop-text": (text: string) => void;
    "mouse-down": (position: Point) => void;
    "mouse-enter": (position: Point) => void;
    "mouse-leave": (position: Point) => void;
    "mouse-move": (position: Point) => void;
    "mouse-up": (position: Point) => void;
    "right-click": () => void;
}>;
Type Alias Description
TrayEvents
Previous <- systemPreferences
Next views ->