tktray(n)                           tktray                           tktray(n)



______________________________________________________________________________

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




tktray                                1.0                            tktray(n)
