tktray(3tk)

📦 version 1.3.9, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 tktray — bestie, it's the tktray(3tk) page 💖

okay so. you opened the tktray(3tk) man page and I'm here to walk you through it like we're texting at 2am. it's giving "System Tray Icon Support for Tk on X11" and honestly? iconic. let's go 🌸

✨ NAME ✨

tktray — System Tray Icon Support for Tk on X11 🫶

✨ SYNOPSIS ✨

package require Tcl  8.4

package require tktray  ?1.0?

tktray::icon pathName ?options?

pathName balloon message ?msec_timeout?

pathName cancel message_handle

pathName bbox

pathName cget option

pathName configure ?options?

pathName docked

pathName orientation

like yes bestie, package require Tcl 8.4 is the floor, we do not go lower 💅

✨ DESCRIPTION ✨

so tktray is an extension that's able to create system tray icons. that's the whole vibe. it follows http://www.freedesktop.org specifications when it's looking up the system tray manager — iykyk. this protocol is supported by modern versions of KDE and Gnome panels, plus some other panel-like applications that decided to show up. 🦋

✨ COMMANDS ✨

🎀 tktray::icon pathName ?options?

Create a new icon for the system tray, periodt. The application managing the system tray gets notified about your new icon, and normally that results in the icon being added to the tray. ✨

but listen — if there's no system tray at the time you create the icon, the icon will be invisible. and then when a new system tray shows up? boom, your icon gets added to it. no cap. and since tktray 1.3, if the tray crashes and destroys your icon, it will be recreated on a new system tray when one's available. she's resilient like that 💪

and here are her options, one by one, no skipping, we don't do that here:

  • -class — WM_CLASS attribute for icon window. The tray manager may use the class name to remember the icon's position or other attributes. This name may be used for event binding as well. Okay so for now: the real icon window is distinct from the user-specified widget — it may be recreated and destroyed several times during the icon's lifetime, whenever a system tray crashes, terminates, disappears or appears 😭. However, tktray tries to forward click and motion events from this inner window to the user widget, so event bindings on the widget name should work as they used to. This option applies to the real icon window, not to a user-visible widget, so don't rely on it to set widget defaults from an option database — the standard "TrayIcon" class name is used for it.
  • -docked — boolean indicating whether the real icon window should be embedded into a tray when it exists. Think of it as a heavier version of the -visible option: there's a guarantee that no place for the icon will be reserved on any tray. 💅
  • -image — image to show in the system tray. Since tktray 1.3, image type "photo" is not mandatory anymore 🎉. The icon will be automatically redrawn on any image modifications. For Tk, deleting an image and creating an image with the same name later counts as a kind of image modification, and tktray follows this convention. Photo image operations that modify existing image content are another example of events that trigger redisplay. The requested size for the icon is set according to the image's width and height — but whether the tray obeys (or disobeys) that request is left entirely up to the tray. 🙈
  • -shape — used to put a nonrectangular shape on an icon window. Ignored for compatibility. that's it. that's the note. 💀
  • -visible — boolean value indicating whether the icon must be visible. The system tray manager keeps managing the icon whether it's visible or not. So when an invisible icon becomes visible, its position on the system tray is likely to remain the same. Tktray currently tries to find a tray and embed into it as soon as possible, whether -visible is true or not. The _XEMBED_INFO property is set for the embedded window: a tray should show or hide an icon depending on this property. But — and I need you to hear this — there may be, and indeed are, incomplete tray implementations ignoring _XEMBED_INFO (ex. docker). Gnome-panel "unmaps" an icon by making it one pixel wide, and that might be what you expect. For those implementations, the place for an icon will be reserved but no image will be displayed: tktray takes care of it. Tktray also blocks mouse event forwarding for invisible icons, so you may be confident that no <Button> bindings will be invoked at that time. 🫶

🎀 pathName balloon message ?msec_timeout?

Post a message that any decent tray implementation would show alongside the icon (or the place allocated for it). The message disappears automatically after $msec_timeout milliseconds. 🕐

unfortunately, there is absolutely no way to know if the tray supports this feature, so don't rely on it for any critical information to be delivered. fr fr.

When no timeout or a zero timeout is given, the message should not be hidden without user action (usually a mouse click). The return value is an integer — a message handle you can use for cancelling the message before the timeout expires, or zero if there's currently no system tray to handle the request. 😭

🎀 pathName cancel message_handle

Cancel an earlier-posted balloon message. A zero message_handle is silently ignored. If there's no message with this handle, or its timeout has expired, or it was posted to another system tray and is unknown to the current one — nothing bad should happen (but that depends on the tray implementation, bestie, we can't promise the tray is chill). 🍓

🎀 pathName bbox

Get the list of left, top, right and bottom coordinates of the icon relative to the root window of the icon's screen. 📐

Use this command in preference to winfo rootx and winfo rooty to get the icon location, though the latter may seem to work on your system. Bounding box information is updated asynchronously — so don't rely on its correctness on script startup, just after icon creation. 👑

This command is for event handlers: on <ButtonPress-3> you'd like to have a popup menu, but where should it be posted? Use %W bbox to determine it right at the moment when a click happened. ✨

🎀 pathName cget option

Retrieve current option value as set by the caller. simple. clean. 💅

🎀 pathName configure ?options?

Modify the icon's options after it was created. glow-up support, we love to see it 💖

🎀 pathName docked

Query the icon to find out if it's currently embedded into some system tray. Invisible icons may be docked too (and tktray strives for it ✨). If this method returns false, the icon is not visible to anyone, and there's no chance to get balloon messages displayed. 💀

🎀 pathName orientation

Query the orientation of the system tray that's currently embedding the icon. 🧭

✨ WINDOW MANAGEMENT ✨

okay so the current implementation of tktray is designed to present an interface of a usual toplevel window — but there are some important differences (and some of them may come up later, no promises 👀).

The System Tray specification is based on XEMBED protocol, and the latter has a problem: when the embedder crashes, nothing can prevent embedded windows from destruction. 😭

Since tktray 1.3, no explicit icon recreation code is required on the Tcl level. The widget was split in two: one represented by a caller-specified name, and another (currently $path.inner) that exists only when a tray is available (and dies and comes back and so on, main character energy honestly). 🌈

This solution has some disadvantages as well. The user-created widget is not mapped at all, thus it can't be used any more as a parent for other widgets, showing them instead of an image. A temporal inner window, however, may contain widgets. 🦋

This version introduces three virtual events: <<IconCreate>>, <<IconConfigure>> and <<IconDestroy>>.

  • <<IconCreate>> is generated when docking is requesting for an icon. ✨
  • <<IconConfigure>> is generated when an icon window is resized or changed in some other way. 💅
  • <<IconDestroy>> is generated when an icon is destroyed due to panel crash or undocked with unsetting the -docked option. 😭

✨ AUTHORS ✨

Anton Kovalenko — See http://www.sw4me.com/wiki/Tktray. 👑

✨ KEYWORDS ✨

icons, system tray, taskbar 🎀

Copyright (c) 2005, Anton Kovalenko

and that's the whole page bestie!! this was version 1.0 of tktray, living in the tktray(3tk) manual, and you read the entire thing like the icon you are 💖✨🦋 go forth and dock responsibly 🫶

📦 where this page comes from