Ubuntu Manpage: tktray - System Tray Icon Support for Tk on X11

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

DESCRIPTION

       Tktray  is  an extension that is able to create system tray icons.  It follows http://www.freedesktop.org
       specifications when looking up the system tray manager. This protocol is supported by modern versions  of
       KDE and Gnome panels, and by some other panel-like application.

COMMANDS

tktray::icon pathName ?options?
Create a new icon for the system tray. The application managing the system tray is notified about
the new icon. It normally results in the icon being added to the tray. If there is no system
tray at the icon creation time, the icon will be invisible. When a new system tray appears, the
icon will be added to it. Since tktray 1.3, if the tray crashes and destroys your icon, it will be
recreated on a new system tray when it's available.

-class WM_CLASS attribute for icon window. Tray manager may use class name to remember icon
position or other attributes. This name may be used for event binding as well. For now,
real icon window is distinct from the user-specified widget: it may be recreated and
destroyed several times during icon lifetime, when a system tray crashes, terminates,
disappears or appears. However, tktray tries to forward click and motion events from this
inner window to user widget, so event bindings on widget name should work as they used to.
This option applies to a 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 -visible option: there is a guarantee that no
place for 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. Icon will be automatically redrawn on any image modifications. For Tk, deleting
an image and creating an image with the same name later is a kind of image modification,
and tktray follows this convention. Photo image operations that modify existing image
content are another example of events triggering redisplay. Requested size for icon is set
according to the image's width and height, but obeying (or disobeying) this request is left
for the tray.

-shape used to put a nonrectangular shape on an icon window. Ignored for compatibility.

-visible
boolean value indicating whether the icon must be visible. The system tray manager
continues to manage the icon whether it is visible or not. Thus when 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. _XEMBED_INFO property is set for embedded window: a tray should show or hide
an icon depending on this property. 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, that might to 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 this time.

pathName balloon message ?msec_timeout?
Post a message that any decent tray implementation would show alongside the icon (or a place
allocated for it). The message will disappear 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. When no timeout or 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 that may be used for cancelling the message before timeout expiration,
or zero if there is currently no system tray to handle the request.

pathName cancel message_handle
Cancel an earlier-posted balloon message. Zero message_handle is silently ignored. If there is no
message with this handle, or its timeout has expired, or it was posted to another system tray and
is unknow to the current one, nothing bad should happen (but it depends on the tray
implementation).

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. This command should be used in preference to winfo rootx and winfo rooty to
get icon location, though the latter may seem to work on your system. Bounding box information is
updated asynchronously. 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
it should 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.

pathName configure ?options?
Modify icon's options after it was created.

pathName docked
Query icon 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
no chance to get balloon messages displayed.

pathName orientation
Query orientation of a system tray that is currently embedding the icon.

WINDOW MANAGEMENT

       Current  implementation  of  tktray  is  designed to present an interface of a usual toplevel window, but
       there are some important differences (some of them may come up later). System Tray specification is based
       on  XEMBED protocol, and the later 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  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).   This
       solution has some disadvantages as well.  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 -docked option.

AUTHORS

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

KEYWORDS

       icons, system tray, taskbar

COPYRIGHT

       Copyright (c) 2005, Anton Kovalenko