$Id: README 524 2012-08-23 13:33:45Z sergei $
"Green" -- plugin for Tkabber.


I. The Idea

This plugin introduces special processing of the system's "power
management events" in Tkabber: disconnecting all active
connections to the server when the system is suspending and
(optional) restoring of these connections after the system
resumes its normal operation.

This plugin is primarily targeted to the users of laptops who
want to gracefully handle periods of hibernation.


II. Usage

The usage of this plugin heavily depends on the power management
facilities the underlying OS provides. Currently this plugin
supports Windows 2000 and above through the usage of external
Tcl/Tk extension and X Window-based systems (namely, Linux)
through the usage of DBus based notifications or a special
"activator script".

In any case, this plugin should be installed as any other
Tkabber plugin first.

When the system reports it's about to suspend, Tkabber remembers
the current connections then tears them down.

When the system reports it resumed its normal operation, Tkabber
consults the options(resume_sessions) flag (see below) -- if
it's on, Tkabber waits for options(resume_delay) seconds to
allow the network to come up, then attempts to restore the
remembered connections.

Tkabber waits this timeout in a non-blocking manner, so you can
manually re-establish the connections you need -- Tkabber won't
try to re-establish them again. On the other hand, there's
currently no way to abort scheduled reconnection attempt.

See the "Configuration" section below for additional details.


II.1. Usage in Windows

You have to install the "winpm" Tcl/Tk extension [1] for this
plugin to be able to track Windows power management broadcasts.

Winpm should be installed in one of the standard places Tcl
searches for packages. With a standard installation of
ActiveTcl [2] this is usually the "C:\Tcl\lib" directory.
You can get the idea of where Tcl looks for its packages by
issuing the
set auto_path
command in the Tkabber's console (main menu, "Help" -> "Show
Console").


II.2. Usage in X Window System

Since X Window doesn have any notion of power broadcasts, each
X-based system uses its own way of delivering the information
about power state changes to the running applications. It can be
done either via DBus notification mechanism, which is used by
many desktop environments (GNOME, KDE, XFCE etc.), or via some
specific shell scripts.

II.2.1 DBus notifications

If the dbus-tcl Tcl extension is available then this plugin
installs callbacks on two DBus signals:
org.freedesktop.UPower.Sleeping and
org.freedesktop.UPower.Resuming. If the system uses these
notification signals then the user isn't required to
do any additional setup, and the plugin will be fully
functional.

II.2.2 Shell scripts

To handle this kind of setup this plugin provides one special
"activator script" which uses the ability of Tcl/Tk programs
running on the same X display to communicate by sending Tcl
scripts to each other.

This script is called "swsusp-tkabber.tcl" and is placed in
the plugin directory. It's not required by the plugin itself and
can be freely relocated, if needed.

The activator script accepts one mandatory command-line parameter
which specifies the power management event to report; its
acceptable values are "suspend" or "resume", which are
self-explanatory.  It is up to the user to arrange for this
script to be run in the right time with a suitable command-line
parameter.

You have to observe several factors when setting this up:

* This script is written in Tcl and requires presence of
  both Tcl and Tk in the system (Tk-based tclkit will also
  work, just run it directly with this script, like
  "tclkit /path/to/swsusp-tkabber.tcl").

* For Tk to initialize and be able to find Tcl interpreters
  controlling the running instances of Tkabber, this script has
  to be run on the same X display to which Tkabber instances
  of interest are connected. This means that if the script
  is started by some kind of a daemon (which will probably be
  the case) you have to let the script know which display to
  connect to by exporting the properly set DISPLAY environment
  variable. For example, provided you have just one display on
  the localhost (the usual case), you can run:

  DISPLAY=:0
  export DISPLAY
  /path/to/swsusp-tkabber.tcl

  or even (in bash):
  DISPLAY=:0 /path/to/swsusp-tkabber.tcl

* Since a Tk application can connect to just one display at a
  time, if you have several displays with running instances of
  Tkabber you will need to arrange for the activator script to
  run several times -- one per display -- each time with
  appropriate environment settings (see above).

* Tcl interpreters running instances of Tkabber are identified
  by "Tk application names" they register on the display.
  The activator script contacts those interpreters whose names
  match the "tkabber*" glob-style pattern. Usually this is
  exactly what is needed but if the script appears to work but
  its actions remain unnoticed by some instance of Tkabber,
  check the application name of its interpreter by issuing the
  tk appname
  command in its console. If it for some reason doesn't match
  the "tkabber*" pattern, either fix the Tkabber startup script
  (via the "-name Tkabber" command line parameter to the wish
  Tcl/Tk shell, for instance) or adjust the pattern in the
  activator script.

* Do not rename (or symlink) the activator script so that its
  new name matches the "tkabber*" glob-style pattern -- this
  will cause the activator script to count itself as a running
  instance of Tkabber which, in turn, will force it to try to
  inform itself about the power management event being reported;
  this will fail with an error.


III. Configuration

This plugin can be configured via the Customize interface of
Tkabber -- open its window via the "Tkabber" -> "Customize"
main menu entry, then navigate to the "Plugins" -> "Green"
group of settings.

Currently there are two options to tweak:

* options(resume_sessions) -- when set, on system resume Tkabber
  will attempt to restore the connections it teared down when
  the system was suspending.  It is on by default.

* options(resume_delay) -- specifies the number of seconds to
  wait before attempting to re-establish the connectons when
  resuming. This is intended to allow the network to come up.

NOTE that due to currently present limitations of Tkabber, if
you're using multi-login, you must provide "loginconf" array for
each connection you're using, complete enough so that this
plugin is able to connect without user intervention. This means
providing at least the user, server and password fields.
See [3] and [4] for details on specifying those loginconf
arrays.  Their numbering doesn't matter for this plugin -- it
picks the correct one based on the user/server couple.


IV. Limitations

* Support for restoring multiple connections is clunky.

* There's no way to cancel the scheduled reconnection attempt.

* Reconnection attempt isn't cancelled when processing suspend
  event. This may provoke strange behaviour.


V. Links

1. http://tkwinpm.googlecode.com
2. http://www.activestate.com
3. http://tkabber.jabber.ru/files/doc/tkabber.html#s.postload-login
4. http://tkabber.jabber.ru/node/192


# vim:tw=64:noet
