Provided by: tk-tktray_1.3.9-2_amd64 bug

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