1tktray(n) tktray tktray(n)
2______________________________________________________________________________
6
8 tktray - System Tray Icon Support for Tk on X11
9
11 package require Tcl 8.4
12 package require tktray ?1.0?
14 tktray::icon pathName ?options?
16 pathName balloon message ?msec_timeout?
18 pathName cancel message_handle
20 pathName bbox
22 pathName cget option
24 pathName configure ?options?
26 pathName docked
28 pathName orientation
30_________________________________________________________________
32
34 Tktray is an extension that is able to create system tray icons. It
35 follows http://www.freedesktop.org specifications when looking up the
36 system tray manager. This protocol is supported by modern versions of
37 KDE and Gnome panels, and by some other panel-like application.
38
40 tktray::icon pathName ?options?
41 Create a new icon for the system tray. The application managing
42 the system tray is notified about the new icon. It normally
43 results in the icon being added to the tray. If there is no
44 system tray at the icon creation time, the icon will be invisi‐
45 ble. When a new system tray appears, the icon will be added to
46 it. Since tktray 1.3, if the tray crashes and destroys your
47 icon, it will be recreated on a new system tray when it's avail‐
48 able.
49 -class WM_CLASS attribute for icon window. Tray manager may use
51 class name to remember icon position or other attributes.
52 This name may be used for event binding as well. For
53 now, real icon window is distinct from the user-specified
54 widget: it may be recreated and destroyed several times
55 during icon lifetime, when a system tray crashes, termi‐
56 nates, disappears or appears. However, tktray tries to
57 forward click and motion events from this inner window to
58 user widget, so event bindings on widget name should work
59 as they used to. This option applies to a real icon win‐
60 dow, not to a user-visible widget, so don't rely on it to
61 set widget defaults from an option database: the standard
62 "TrayIcon" class name is used for it.
63 -docked
65 boolean indicating whether the real icon window should be
66 embedded into a tray when it exists. Think of it as a
67 heavier version of -visible option: there is a guarantee
68 that no place for icon will be reserved on any tray.
69 -image image to show in the system tray. Since tktray 1.3, image
71 type "photo" is not mandatory anymore. Icon will be
72 automatically redrawn on any image modifications. For Tk,
73 deleting an image and creating an image with the same
74 name later is a kind of image modification, and tktray
75 follows this convention. Photo image operations that
76 modify existing image content are another example of
77 events triggering redisplay. Requested size for icon is
78 set according to the image's width and height, but obey‐
79 ing (or disobeying) this request is left for the tray.
80 -shape used to put a nonrectangular shape on an icon window.
82 Ignored for compatibility.
83 -visible
85 boolean value indicating whether the icon must be visi‐
86 ble. The system tray manager continues to manage the
87 icon whether it is visible or not. Thus when invisible
88 icon becomes visible, its position on the system tray is
89 likely to remain the same. Tktray currently tries to
90 find a tray and embed into it as soon as possible,
91 whether -visible is true or not. _XEMBED_INFO property is
92 set for embedded window: a tray should show or hide an
93 icon depending on this property. There may be, and indeed
94 are, incomplete tray implementations ignoring _XEM‐
95 BED_INFO (ex. docker). Gnome-panel "unmaps" an icon by
96 making it one pixel wide, that might to be what you
97 expect. For those implementations, the place for an icon
98 will be reserved but no image will be displayed: tktray
99 takes care of it. Tktray also blocks mouse event forward‐
100 ing for invisible icons, so you may be confident that no
101 <Button> bindings will be invoked at this time.
102 pathName balloon message ?msec_timeout?
104 Post a message that any decent tray implementation would show
105 alongside the icon (or a place allocated for it). The message
106 will disappear automatically after $msec_timeout milliseconds.
107 Unfortunately, there is absolutely no way to know if the tray
108 supports this feature, so don't rely on it for any critical
109 information to be delivered. When no timeout or zero timeout is
110 given, the message should not be hidden without user action
111 (usually a mouse click). The return value is an integer, a mes‐
112 sage handle that may be used for cancelling the message before
113 timeout expiration, or zero if there is currently no system tray
114 to handle the request.
115 pathName cancel message_handle
117 Cancel an earlier-posted balloon message. Zero message_handle is
118 silently ignored. If there is no message with this handle, or
119 its timeout has expired, or it was posted to another system tray
120 and is unknow to the current one, nothing bad should happen (but
121 it depends on the tray implementation).
122 pathName bbox
124 Get the list of left, top, right and bottom coordinates of the
125 icon relative to the root window of the icon's screen. This
126 command should be used in preference to winfo rootx and winfo
127 rooty to get icon location, though the latter may seem to work
128 on your system. Bounding box information is updated asyn‐
129 chronously. Don't rely on its correctness on script startup,
130 just after icon creation. This command is for event handlers:
131 on <ButtonPress-3> you'd like to have a popup menu, but where it
132 should be posted? Use %W bbox to determine it right at the
133 moment when a click happened.
134 pathName cget option
136 Retrieve current option value as set by the caller.
137 pathName configure ?options?
139 Modify icon's options after it was created.
140 pathName docked
142 Query icon if it's currently embedded into some system tray.
143 Invisible icons may be docked too (and tktray strives for it).
144 If this method returns false, the icon is not visible to anyone,
145 and no chance to get balloon messages displayed.
146 pathName orientation
148 Query orientation of a system tray that is currently embedding
149 the icon.
150
152 Current implementation of tktray is designed to present an interface of
153 a usual toplevel window, but there are some important differences (some
154 of them may come up later). System Tray specification is based on XEM‐
155 BED protocol, and the later has a problem: when the embedder crashes,
156 nothing can prevent embedded windows from destruction. Since tktray
157 1.3, no explicit icon recreation code is required on Tcl level. The
158 widget was split in two: one represented by a caller-specified name,
159 and another (currently $path.inner) that exists only when a tray is
160 available (and dies and comes back and so on). This solution has some
161 disadvantages as well. User-created widget is not mapped at all, thus
162 it can't be used any more as a parent for other widgets, showing them
163 instead of an image. A temporal inner window, however, may contain wid‐
164 gets.
165 This version introduces three virtual events: <<IconCreate>> <<IconCon‐
167 figure>> and <<IconDestroy>>. <<IconCreate>> is generated when docking
168 is requesting for an icon. <<IconConfigure>> is generated when an icon
169 window is resized or changed in some other way. <<IconDestroy>> is
170 generated when an icon is destroyed due to panel crash or undocked with
171 unsetting -docked option.
172
174 Anton Kovalenko See http://www.sw4me.com/wiki/Tktray.
175
177 icons, system tray, taskbar
178
180 Copyright (c) 2005, Anton Kovalenko
181tktray 1.0 tktray(n)