1tktray(n)                           tktray                           tktray(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       tktray - System Tray Icon Support for Tk on X11
9

SYNOPSIS

11       package require Tcl  8.4
12
13       package require tktray  ?1.0?
14
15       tktray::icon pathName ?options?
16
17       pathName balloon message ?msec_timeout?
18
19       pathName cancel message_handle
20
21       pathName bbox
22
23       pathName cget option
24
25       pathName configure ?options?
26
27       pathName docked
28
29       pathName orientation
30
31_________________________________________________________________
32

DESCRIPTION

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

COMMANDS

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
50              -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
64              -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
70              -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
81              -shape used  to  put  a  nonrectangular shape on an icon window.
82                     Ignored for compatibility.
83
84              -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
103       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
116       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
123       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
135       pathName cget option
136              Retrieve current option value as set by the caller.
137
138       pathName configure ?options?
139              Modify icon's options after it was created.
140
141       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
147       pathName orientation
148              Query orientation of a system tray that is  currently  embedding
149              the icon.
150

WINDOW MANAGEMENT

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
166       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

AUTHORS

174       Anton Kovalenko See http://www.sw4me.com/wiki/Tktray.
175

KEYWORDS

177       icons, system tray, taskbar
178
180       Copyright (c) 2005, Anton Kovalenko
181
182
183
184
185tktray                                1.0                            tktray(n)
Impressum