> For the complete documentation index, see [llms.txt](https://docs.sacruda.nl/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sacruda.nl/developers/sacruda-apis/tray-icons.md).

# Tray icons

Sacruda has a system tray which is in many ways comparable to Windows. Any given app can add an icon to this tray by sending it to the `trayHost`, which is a system service responsible for managing tray icons; everything from creating, deleting and rendering is handled there.

### The Tray Process

Sacruda has a process type built-in called the `TrayIconProcess`, which inherits from the main `Process` class. If your tray icon has a popup, this class will render it. It's got a bunch of properties, as well as a couple functions that make the tray icon work.

#### Creating a `TrayIconProcess`

{% hint style="danger" %}
Helper processes might be implemented into the CLI in the future to automatically create tray icon processes.
{% endhint %}

First of all, I'll create a file called `tray.js` in which I'll create a class that inherits off of the TrayIconProcess class, and super its parent by adding a constructor, like so:

```javascript
class TrayIcon extends TrayIconProcess {
	constructor(handler, pid, parentPid, data) {
		super(handler, pid, parentPid, data);
	}
}
```

Next, I'll add a `renderPopup` function to this process, which gives the body of the popup as well as the parent process:

<pre class="language-javascript"><code class="lang-javascript">class TrayIcon extends TrayIconProcess {
	constructor(handler, pid, parentPid, data) {
		super(handler, pid, parentPid, data);
	}
	
<strong>	async renderPopup(body, target) {
</strong><strong>	  // Do something cool here
</strong><strong>	}
</strong>}
</code></pre>

Finally, I'll add a return statement at the bottom of the file to "export" the newly created tray icon process:

<pre class="language-javascript"><code class="lang-javascript">  // . . .
	async renderPopup(body, target) {
	  // Do something cool here
	}
}

<strong>return { TrayIcon };
</strong></code></pre>

#### Making the actual tray icon

Now that you have the tray icon process, import it in the file where your main app process is located:

```javascript
const { TrayIcon } = await load("tray.js");
```

Then, in the `render` or `start` methods, create the tray icon by accessing the shell:

```javascript
// Just getting a PNG file to use as the actual image
const icon = await fs.direct(util.join(workingDirectory, "tray.png"));

daemon.getShell()?.trayHost.createTrayIcon(this.pid, "icon_id_goes_here", {
  icon,
  popup: { // Popup dimensions are fixed and cannot be scaled dynamically.
    width: 320,
    height: 240
  }
}, TrayIcon);
```

{% hint style="warning" %}
`popup` is optional: omit it to not have a tray popup at all. Additionally, if you don't want a popup, you can safely omit the `renderPopup` method in the tray icon process. However, if you don't have a popup, it *is* recommended to add an action.
{% endhint %}

### Tray icon action

A tray icon action is the action that is performed when the icon is clicked. This can either be to toggle something or to focus a minimized window, you can see it as a basic javascript event listener. The action is a callback with one argument: the process from which the tray icon was created, being your app's main process. Here's an example:

```javascript
// Just getting a PNG file to use as the actual image
const icon = await this.fs.direct(util.join(workingDirectory, "tray.png"));

daemon.getShell()?.trayHost.createTrayIcon(this.pid, "TrayIcon", {
  icon,
  action: (proc) => {
    stack.renderer?.focusPid(proc.pid); // This focuses a window by its pid
  }
}, GooseTray);
```

### Removing tray icons

A tray icon is set to destroy itself if the parent process is terminated. That said, you can also manually remove a tray icon, or even all tray icons of a process.

If you want to:

* Remove all tray icons of the process:

  ```javascript
  daemon.getShell()?.trayHost?.disposeProcessTrayIcons(this.pid);
  ```
* Remove just a single tray icon:

  ```javascript
  daemon.getShell()?.trayHost?.disposeTrayIcon(this.pid, "TrayIcon");
  ```

{% hint style="info" %}
Sacruda will automatically dispose the tray icons you create when your main process is terminated.
{% endhint %}

### Changing a tray icon's image dynamically

{% hint style="danger" %}
This functionality is quite unrefined and may cause problems with the tray host if incorrectly applied. Read the instructions carefully before proceeding.
{% endhint %}

From Sacruda 7.0.10 onwards, it's really easy to change the icon displayed in the tray dynamically. First, you'll need to know a couple things: the identifier you used to create the tray icon, and the new icon you wish to use. Next, call `ITrayHostService.changeIcon`:

{% code lineNumbers="true" %}

```javascript
const newIcon = "WarningIcon";
const identifier = "icon_id_goes_here";

daemon.getShell()?.trayHost?.changeIcon(this.pid, identifier, newIcon);
```

{% endcode %}

### Styling a tray popup

Just like your app's window, you can simply just use the ID of your tray icon as the selectors for your CSS, as long as the ID of your tray icon **is original enough** not to interfere with anything else. If your tray popup is called `MineSweeperTray`, you can select it and anything inside of it as such:

```css
#MineSweeperTray {
  /* Do stuff here */
}
```

Ofcourse you're welcome to seperate this tray popup CSS from your main CSS file by creating a second one and adding it to your HTML using a `<link>`.

{% hint style="danger" %}
If you're using `ThirdPartyProcess` instead of `ThirdPartyAppProcess`, loading CSS for your tray works a little differently. You have to call `IThirdPartyProcess.loadCSS`, passing in the relative ArcOS file path of the CSS file you want to load:

{% code lineNumbers="true" %}

```javascript
const cssFile = "./popup.css";
await this.loadCSS(cssFile);
```

{% endcode %}

**NOTE**: the loadCSS method **can throw an error** if the file can't be read. Be sure to employ proper [Error handling](https://docs.sacruda.nl/developers/your-apps-code/error-handling.md).
{% endhint %}
