A. Shchepin
                                                             Process-One
                                                                 M. Rose
                                            Dover Beach Consulting, Inc.
                                                              S. Golovan
                                                     New Economic School
                                                               M. Litvak
                                                  Information Centre ISP
                                                                May 2006


                             Tkabber v0.9.9


Abstract

   _Tkabber_ is an open source Jabber client, written in _Tcl/Tk_.  This
   memo describes the installation, configuration, and extension of
   _Tkabber_.
































Shchepin, et al.                                                [Page 1]

                             Tkabber v0.9.9                     May 2006


Table of Contents

   1.  Features . . . . . . . . . . . . . . . . . . . . . . . . . . .  4
   2.  Requirements . . . . . . . . . . . . . . . . . . . . . . . . .  7
   3.  Download, install and run  . . . . . . . . . . . . . . . . . . 10
   4.  Configuration  . . . . . . . . . . . . . . . . . . . . . . . . 12
     4.1.  Pre-load . . . . . . . . . . . . . . . . . . . . . . . . . 12
       4.1.1.  Tabbed Interface . . . . . . . . . . . . . . . . . . . 13
       4.1.2.  Primary Look-and-Feel  . . . . . . . . . . . . . . . . 14
       4.1.3.  Cryptography by default  . . . . . . . . . . . . . . . 14
       4.1.4.  Using of external TclXML library . . . . . . . . . . . 15
       4.1.5.  Use ispell to check spelling . . . . . . . . . . . . . 15
       4.1.6.  Debugging Output . . . . . . . . . . . . . . . . . . . 15
       4.1.7.  Splash window  . . . . . . . . . . . . . . . . . . . . 16
       4.1.8.  Periodically send empty string to server . . . . . . . 16
       4.1.9.  I18n/L10n  . . . . . . . . . . . . . . . . . . . . . . 16
     4.2.  Post-load  . . . . . . . . . . . . . . . . . . . . . . . . 16
       4.2.1.  Look-and-Feel  . . . . . . . . . . . . . . . . . . . . 20
       4.2.2.  The Autoaway Module  . . . . . . . . . . . . . . . . . 21
       4.2.3.  The Avatar Module  . . . . . . . . . . . . . . . . . . 21
       4.2.4.  The Chat Module  . . . . . . . . . . . . . . . . . . . 22
       4.2.5.  The Clientinfo Module  . . . . . . . . . . . . . . . . 22
       4.2.6.  The Conferenceinfo Module  . . . . . . . . . . . . . . 22
       4.2.7.  The Cryptographic Module . . . . . . . . . . . . . . . 23
       4.2.8.  The Emoticons Module . . . . . . . . . . . . . . . . . 23
       4.2.9.  The File Transfer Module . . . . . . . . . . . . . . . 23
       4.2.10. The Groupchat Module . . . . . . . . . . . . . . . . . 23
       4.2.11. The Ispell Module  . . . . . . . . . . . . . . . . . . 24
       4.2.12. The Stream Initiation Module . . . . . . . . . . . . . 24
       4.2.13. The Jidlink Module . . . . . . . . . . . . . . . . . . 25
       4.2.14. The Logger Module  . . . . . . . . . . . . . . . . . . 25
       4.2.15. The Login Module . . . . . . . . . . . . . . . . . . . 26
       4.2.16. The Message Module . . . . . . . . . . . . . . . . . . 26
       4.2.17. The Raw XML Input Module . . . . . . . . . . . . . . . 26
       4.2.18. The Roster Module  . . . . . . . . . . . . . . . . . . 26
       4.2.19. The Sound Module . . . . . . . . . . . . . . . . . . . 27
     4.3.  Menu-load  . . . . . . . . . . . . . . . . . . . . . . . . 28
       4.3.1.  The Avatar Module  . . . . . . . . . . . . . . . . . . 29
       4.3.2.  The Browser Module . . . . . . . . . . . . . . . . . . 29
       4.3.3.  The Groupchat Module . . . . . . . . . . . . . . . . . 29
       4.3.4.  The Login Module . . . . . . . . . . . . . . . . . . . 29
       4.3.5.  The Message Module . . . . . . . . . . . . . . . . . . 30
       4.3.6.  The Presence Module  . . . . . . . . . . . . . . . . . 30
       4.3.7.  Miscellany . . . . . . . . . . . . . . . . . . . . . . 31
     4.4.  Final-Load . . . . . . . . . . . . . . . . . . . . . . . . 31
   5.  Extensibility  . . . . . . . . . . . . . . . . . . . . . . . . 32
     5.1.  Chat Hooks . . . . . . . . . . . . . . . . . . . . . . . . 33
     5.2.  Login Hooks  . . . . . . . . . . . . . . . . . . . . . . . 35



Shchepin, et al.                                                [Page 2]

                             Tkabber v0.9.9                     May 2006


     5.3.  Presence Hooks . . . . . . . . . . . . . . . . . . . . . . 35
     5.4.  Roster Hooks . . . . . . . . . . . . . . . . . . . . . . . 36
     5.5.  Miscellaneous Hooks  . . . . . . . . . . . . . . . . . . . 37
   Appendix A.  Releases History  . . . . . . . . . . . . . . . . . . 38
     A.1.  Main changes in 0.9.9  . . . . . . . . . . . . . . . . . . 38
     A.2.  Main changes in 0.9.8  . . . . . . . . . . . . . . . . . . 38
     A.3.  Main changes in 0.9.7beta  . . . . . . . . . . . . . . . . 38
     A.4.  Main changes in 0.9.6beta  . . . . . . . . . . . . . . . . 39
     A.5.  Main changes in 0.9.5beta  . . . . . . . . . . . . . . . . 39
   Appendix B.  XRDB  . . . . . . . . . . . . . . . . . . . . . . . . 40
   Appendix C.  Documentation TODO  . . . . . . . . . . . . . . . . . 43
   Appendix D.  Acknowledgements  . . . . . . . . . . . . . . . . . . 44
   Appendix E.  Copyrights  . . . . . . . . . . . . . . . . . . . . . 45
   Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 46





































Shchepin, et al.                                                [Page 3]

                             Tkabber v0.9.9                     May 2006


1.  Features

   Tkabber [1] provides a _Tcl/Tk_ interface to the Jabber [2] instant
   messaging and presence service.

   _Tcl/Tk_ is a graphical scripting language that runs on the Unix,
   Windows, and Macintosh platforms.  The choice of _Tcl/Tk_ for a
   Jabber client is three-fold:

   o  it is portable: once you install a _Tcl/Tk_ interpreter on your
      system, the _Tkabber_ script "just runs" -- without having to
      compile anything;

   o  it is customizable: _Tkabber_ reads a configuration file when it
      starts that tells it the settings of various parameters; and,

   o  it is extensible: the configuration file is actually a _Tcl_
      script, so you can replace or augment entire portions of _Tkabber_
      (if you're so inclined).

   _Tkabber_ is fully-featured:

   sessions:

      *  TCP and HTTP-polling session transports

      *  XMPP SRV and TXT DNS-records handling

      *  hashed passwords

      *  SASL authentication

      *  encrypted sessions (if you install an optional extension)

      *  compressed sessions (if you install an optional extension)

      *  login via HTTP proxy

      *  user-defined hooks for connection establishment and release

      *  XMPP/Jabber MIME type

   messages:

      *  privacy rules

      *  signed/encrypted messages (if you install an optional
         extension)



Shchepin, et al.                                                [Page 4]

                             Tkabber v0.9.9                     May 2006


      *  file transfers (HTTP, SOCKS bytestream, DTCP and IBB
         transports)

      *  groupchat (GroupChat-1.0 and Multi-User Chat conferencing
         protocols)

      *  headline messages

      *  message events

      *  completions of nick and commands

      *  hyperlinks

      *  emoticons

      *  user-defined hooks for chat window events

   presence:

      *  signed presence (if you install an optional extension)

      *  avatars

      *  browsing

      *  groupchat and roster invitations

      *  conference room bookmarks

      *  annotations about roster items

      *  vCards

      *  user-defined hooks for presence changes

   windowing:

      *  configurable look-and-feel via a resources database

      *  unicode

      *  tabbed/non-tabbed interface

      *  sound notifications

      *  nested roster groups




Shchepin, et al.                                                [Page 5]

                             Tkabber v0.9.9                     May 2006


      *  for Unix: auto-away, spell checking, KDE or freedesktop
         docking, and WMaker icons

      *  for Windows: auto-away, and taskbar icons















































Shchepin, et al.                                                [Page 6]

                             Tkabber v0.9.9                     May 2006


2.  Requirements

   You should already have installed:

   o  Tcl/Tk version 8.3.3 [3] (or later, Tcl/Tk 8.4.9 or later is
      recommended)

   o  tcllib version 1.2 [4] (or later, tcllib 1.8 or later is required
      for SRV and TXT DNS-records support).

   o  BWidget 1.3 [4] (or later)

   Most systems already come with these packages pre-installed.  If not,
   various Unix systems have them available as ready-made packages.
   Otherwise, go to the URLs above and click on the appropriate download
   link for your system.  Both _tcllib_ and _BWidget_ are script
   libraries -- no compiling is necessary.  In the case of _Tcl/Tk_,
   there are many ready-made binary packages available on the download
   site.

   The ActiveTcl [5] distribution contains all three packages (along
   with the _Img_ package mentioned next); so, you may want to use that
   instead of three separate downloads.

   At your discretion, there are several optional packages that you may
   also install. _Tkabber_ will run just fine without them, but if
   they're available _Tkabber_ will make additional features available
   to you.  So, here's the list:

   o  _Tcl/Tk_ supports only a small number of image formats (i.e.,
      bitmaps, GIFs and portable pixmaps).  If presence information
      contains avatars, these may be in other formats (e.g., PNGs or
      JPGs).
      Accordingly, you may want to install Img version 1.2 [6] (or
      later).  This package works on both Unix and Windows.


   o  By default, communications between the server and client take
      place over a plaintext connection.  While this may not be a
      problem in some local, wired environments, if your server is
      distant or your client is wireless, then you may want to encrypt
      all the client/server traffic.
      Accordingly, you may to install tls version 1.4.1 [7] (or later).
      This package works on both Unix and Windows.  Note that if you're
      using Unix, then you'll also need to have _OpenSSL_ installed.
      Fortunately, this comes preinstalled on many Unix systems.  If
      it's not on your system, check here [8].  (The Windows
      distribution of _tls_ comes with all the necessary DLLs.)



Shchepin, et al.                                                [Page 7]

                             Tkabber v0.9.9                     May 2006


   o  Another option in Unix is to compress connection between client
      and server (it currently disables encryption).
      If you want to compress traffic you should install ZTcl version
      1.0b4 [9] (or later) and Tclmore version 0.7b1 [9] (or later).


   o  By default, end-to-end communications between two or more Jabber
      clients is plaintext.  Depending on your environment, this may not
      be a problem for you.  Alternatively, you may want to digitally-
      sign all of your outgoing messages, and allow others to encrypt
      their messages to you.
      Accordingly, you may want to install the _gpgme_ package, which,
      at present, works only on Unix.  Depending on what's already
      installed on your system, you may have to download upto three
      files:

      *  Tcl GPGME version 1.0 [10] (or later);

      *  GPGME version 0.3.11 [11] (or later but only 0.3.x); and,

      *  GPG version 1.0.7 [12] (or later).


   o  If you're running Unix or Windows, then you may want _Tkabber_ to
      automatically mark you as away after a priod of inactivity.
      Accordingly, on Unix, you may want to install Tk Xwin version
      1.0 [13] (or later), whilst on WIndows, you may want to install
      Tcl Winidle version 0.1 [14] (or later).


   o  If you're running Unix, then you may want _Tkabber_ to use the
      docking tray.
      Accordingly, you may want to install Tk Theme version 1.20 [15]
      (or later) for _KDE_ icon, or tktray version 1.1 [16] (or later)
      for freedesktop icon (supported by modern _KDE_ and _GNOME_).


   o  If you're running Windows, then you may want _Tkabber_ to use the
      system tray.
      Accordingly, you may want to install Winico version 0.6 [17] (or
      later).


   o  If you're a Tcl/Tk guru, then you may want to access the Tk
      console to debug things.
      Accordingly, you may want to install tkcon version 2.3 [18] (or
      later).




Shchepin, et al.                                                [Page 8]

                             Tkabber v0.9.9                     May 2006


   Please keep in mind that these are all "optional extras" -- if
   they're not right for you or your environment, don't bother with
   them!
















































Shchepin, et al.                                                [Page 9]

                             Tkabber v0.9.9                     May 2006


3.  Download, install and run

   Latest stable version is 0.9.9 [19].

   You can always find the latest development version via CVS.  Do
   following steps:

   o  export CVSROOT=:pserver:anonymous@cvs.jabberstudio.org:/home/cvs

   o  cvs login

   o  Enter empty password

   o  cvs -z3 co tkabber/tkabber

   o  And if you want to test some plugins, then do cvs -z3 co tkabber/
      tkabber-plugins

   If you use the Debian GNU/Linux distribution, you may want to get all
   required packages by using _apt_.  Just execute apt-get install tk
   tcllib bwidget or apt-get install tkabber to get the latest stable
   version.

   No real installation is required, simply copy the "tkabber/"
   directory to a commonly-available area, and then either:

   o  put this directory in your search-path; or,

   o  make a calling script/shortcut to the file "tkabber.tcl" in that
      directory.

   Although _Tkabber_ comes with a Makefile, there's really not much to
   do -- most folks prefer to simply copy the distribution directory to
   somewhere in their home directory.

   From the shell, you can invoke _Tkabber_ as:

   % tkabber.tcl

   whilst on a windowing system, simply double-click on that file or a
   short-cut to it.

   If you're a Tcl/Tk guru and have installed _tkcon_, then you may want
   to invoke _Tkabber_ as:

   % tkcon.tcl -exec "" -root .tkconn -main "source tkabber.tcl"

   _Tkabber_ will automatically know that it's running under _tkcon_ and



Shchepin, et al.                                               [Page 10]

                             Tkabber v0.9.9                     May 2006


   will start by hiding the _Tk_ console window.  Look under the "Help"
   menu to find the checkbutton to show the console.

   Also you can setup _Tkabber_ as handler for XMPP/Jabber MIME
   Type [20].  For this you need to set hanler for
   "application/xmpp+xml" MIME type in your browser to something like
   this:

   tkabber -mime %s










































Shchepin, et al.                                               [Page 11]

                             Tkabber v0.9.9                     May 2006


4.  Configuration

   One of the first thing that _Tkabber_ does is read a file in your
   home directory called "".tkabber/config.tcl"".  This is a _Tcl_
   source file, so obviously, it's a lot easier to maintain this file if
   you know the Tcl programming language.  If you're not familiar with
   it, that's okay -- most things you'll need to do are pretty simple!
   (In fact, if you don't have your own configuration file, you'll get
   the vanilla _Tkabber_, which hopefully you'll find quite usable.)

   Note that almost all _Tkabber_ options can be cofigured using
   graphical interface (menu Tkabber->Customize), so editing
   configuration file is not strictly necessary.

   _Tkabber_ is configured in four stages:

   o  in the pre-load stage, configuration options which guide the
      loading process are set;

   o  in the post-load stage, configuration options for each module are
      set;

   o  in the menu-load stage, the user is given an option to re-arrange
      _Tkabber's_ menu bar; and,

   o  the final-load stage allows any last changes to be made before the
      "login" dialog window is displayed to the user.

   Let's look at each, in turn.

4.1.  Pre-load

   There are a few things that you may let _Tkabber_ know immediately.
   These are:

   # tabbed interface

   set ifacetk::options(use_tabbar) 1


   # primary look-and-feel

   set load_default_xrdb 1

   set font "-monotype-arial-medium-r-normal-*-13-*-*-*-*-*-iso10646-1"
   option add *font \
          "-monotype-arial-medium-r-normal-*-13-*-*-*-*-*-iso10646-1" \
          userDefault



Shchepin, et al.                                               [Page 12]

                             Tkabber v0.9.9                     May 2006


   # cryptography by default

   set ssj::options(sign-traffic)    0
   set ssj::options(encrypt-traffic) 0


   # using of external tclxml library

   set use_external_tclxml 0


   # use ispell to check spelling

   set use_ispell 0


   # debugging output

   set debug_lvls {jlib warning}


   # splash window

   set show_splash_window 0


   # periodically send empty string to server

   set keep_alive           0
   set keep_alive_interval 10


   # force english labels instead of native language

   ::msgcat::mclocale en

4.1.1.  Tabbed Interface

   The first of these options, "ifacetk::options(use_tabbar)", tells
   _Tkabber_ whether you want a tabbed interface or not.  If not, here's
   what to put in your configuration file:

   set ifacetk::options(use_tabbar) 0

   Although _Tkabber_ immediately applies most of its configuration
   changes, in order to apply changed option
   "ifacetk::options(use_tabbar)" you have to restart _Tkabber_.  So,
   basically you have two options: set "ifacetk::options(use_tabbar)" at



Shchepin, et al.                                               [Page 13]

                             Tkabber v0.9.9                     May 2006


   the beginning of your configuration file, or using graphical
   interface save the option and restart _Tkabber_.

4.1.2.  Primary Look-and-Feel

   All of the windows, dialogs, etc., used by _Tkabber_ are called
   "widgets".  Each widget determines most of its "look" from an
   "resource" database.  On Unix, try "man palette" to see what the
   primary "look-and-feel" options are, and "man option" to see how to
   modify them.  (On Windows, from the _Start_ menu, select _Tcl_ and
   then _Tcl Help_, and then enter either ""palette"" or ""option"".)

   Most folks who want to define a new look-and-feel put all their
   options in an "xrdb" file, and then reference it this way:

       set load_default_xrdb 0
       option readfile ~/.tkabber/newlook.xrdb userDefault

   The first line tells _Tkabber_ not to load its default "xrdb" file,
   whilst the second line tells _Tkabber_ the file to load instead.

   See Appendix B for a list of all the resources that you can set to
   control _Tkabber's_ look-and-feel.

   Directory ""examples"" contains several examples of resource database
   files ""*.xrdb"".

   Alternatively, if you're a Tcl "old timer", you can always do:

       set load_default_xrdb 0
       tk_bisque

   to set the palette to a pleasing color scheme.

   Other look-and-feel options which you may want to set are font
   options:

       set font "-monotype-arial-medium-r-normal-*-13-*-*-*-*-*-iso10646-1"
       option add *font \
              "-monotype-arial-medium-r-normal-*-13-*-*-*-*-*-iso10646-1" \
              userDefault

   Obviously, you may chose the most suitable fonts for you.

4.1.3.  Cryptography by default

   Next, you may want to _Tkabber_ to use cryptography by default.
   There are two options:



Shchepin, et al.                                               [Page 14]

                             Tkabber v0.9.9                     May 2006


   o  whether the traffic you send should be digitally-signed; and,

   o  if you have cryptographic information for someone, should the
      default action be to encipher your traffic for them.

   (By defining these options early on, _Tkabber_ will complain
   immediately if it isn't able to load its cryptographic module;
   otherwise, the default behavior is to proceed without any
   cryptographic buttons, menus, and so on.)

4.1.4.  Using of external TclXML library

   By default _Tkabber_ use version of _TclXML_ library that come with
   it distribution.  This version is pure-Tcl, and it performance can be
   not suitable.  Then you can install _TclXML_ with built-in _expat_
   support and set variable "use_external_tclxml":

   set use_external_tclxml 0

4.1.5.  Use ispell to check spelling

   On Unix, _Tkabber_ can check spelling of what you entered by calling
   an external program _ispell_.  To enable this feature, add following
   line:

   set use_ispell 1

4.1.6.  Debugging Output

   _Tkabber_ has a lot of debugging output.  By default, it gets printed
   to the standard output by a Tcl procedure called "debugmsg".
   However, only information about those modules listed in a variable
   called "debug_lvls" will be printed.

   If you know how to program Tcl, then this will seem rather obvious:

   set debug_lvls [list message presence ssj warning]

   # if you want a different behavior,
   #     define your own...

   proc debugmsg {module msg} {
   #    ...
   }







Shchepin, et al.                                               [Page 15]

                             Tkabber v0.9.9                     May 2006


   Most users won't care about "debugmsg" because they're running
   _Tkabber_ under an application launcher so the standard output is
   never seen.  However, if this isn't the case for you, and you just
   don't want to see any of this stuff, put this one line in your
   configuration file:

   set debug_lvls {}

4.1.7.  Splash window

   By default, when _Tkabber_ startup, it show loading process in splash
   window.  To disable this feature, put this in your configuration
   file:

   set show_splash_window 0

4.1.8.  Periodically send empty string to server

   If you're using a proxy to talk to a Jabber server, after a period of
   inactivity, the proxy may decide to disconnect you.  To avoid this,
   you can tell _Tkabber_ to send an empty string to the server every
   _keep_alive_interval_ minutes:

   set keep_alive 1
   set keep_alive_interval 10

4.1.9.  I18n/L10n

   _Tkabber_ can show all messages in user's native language.  This is
   done by using Tcl's built-in _msgcat_ package which looks for a
   directory called "msgs/" wherever you installed _Tkabber_, and then
   uses the "LC_MESSAGES" environment variable (or "LANG" if
   "LC_MESSAGES" not set) to select the appropriate file.  If you wish,
   you can force use of a particular language by putting a line like
   this in your configuration file:

   ::msgcat::mclocale en

4.2.  Post-load

   After _Tkabber_ reads your configuration file, it loads all of its
   own modules, it then invokes a procedure called "postload".  This
   procedure is supposed to perform module-specific configuration.

   The default version of this procedure doesn't do anything.  If you
   want to configure one more module modules, then you need to define
   the procedure in your configuration file, e.g.,




Shchepin, et al.                                               [Page 16]

                             Tkabber v0.9.9                     May 2006


   proc postload {} {
   # look-and-feel

       set pixmaps::options(pixmaps_theme) Default

       global alert colors alert_lvls

       set alert_lvls(error)        1
       set alert_lvls(server)       1
       set alert_lvls(message)      2
       set alert_lvls(mesg_to_user) 3
       set alert_colors             {Black DarkBlue Blue Red}

       set raise_new_tab            1


   # the autoaway module

       set plugins::autoaway::options(awaytime)  5
       set plugins::autoaway::options(xatime)   15
       set plugins::autoaway::options(status) "Automatically away due to idle"
       set plugins::autoaway::options(drop_priority) 1


   # the avatar module

       set avatar::options(announce) 0
       set avatar::options(share)    0


   # the chat module

       set chat::options(default_message_type) chat
       set chat::options(stop_scroll)          0
       set plugins::options(timestamp_format)  {[%R]}


   # the clientinfo module

       set plugins::clientinfo::options(autoask) 0


   # the conferenceinfo module

       set plugins::conferenceinfo::options(autoask)        0
       set plugins::conferenceinfo::options(interval)       1
       set plugins::conferenceinfo::options(err_interval)  60




Shchepin, et al.                                               [Page 17]

                             Tkabber v0.9.9                     May 2006


   # the cryptographic module

       set ssj::options(encrypt,fred@example.com) 1


   # the emoticon module

       emoteicons::load_dir ~/.tkabber/emoticons/rythmbox


   # the file transfer module

       set ft::options(download_dir) "/tmp"


   # the groupchat module

       global gra_group gra_server
       global gr_nick gr_group gr_server
       global defaultnick

       set defaultnick(adhoc@conference.example.com) publius
       set defaultnick(*@conference.example.com) cicerone


   # the ispell module

       set plugins::ispell::options(executable)          /usr/bin/ispell
       set plugins::ispell::options(dictionary)          russian
       set plugins::ispell::options(dictionary_encoding) koi8-r
       set plugins::ispell::options(check_every_symbol)  1

   # the stream initiation module

       set si::transport(allowed,http://jabber.org/protocol/bytestreams) 0
       set si::transport(allowed,http://jabber.org/protocol/ibb) 1

   # the jidlink module

       set jidlink::transport(allowed,dtcp-passive) 0


   # the logger module

       set logger::options(logdir)        ~/.tkabber/logs
       set logger::options(log_chat)      1
       set logger::options(log_groupchat) 1




Shchepin, et al.                                               [Page 18]

                             Tkabber v0.9.9                     May 2006


   # the login module

       global loginconf loginconf1 loginconf2 autologin

       set loginconf(user)           ""
       set loginconf(password)       ""
       set loginconf(server)         example.com
       set loginconf(resource)       tkabber
       set loginconf(priority)       16
       set loginconf(usealtserver)   0
       set loginconf(altserver)      ""
       set loginconf(altport)        5422
       set loginconf(stream_options) plaintext
       set loginconf(useproxy)       0
       set loginconf(usesasl)        1
       set loginconf(allowauthplain) 0
       set loginconf(httpproxy)      localhost
       set loginconf(httpproxyport)  3128
       set loginconf(httplogin)     ""
       set loginconf(httppassword)  ""

       # The following variables are useful when your jabber-server
       # (example.com) does not have SRV or A-record in DNS
       set loginconf(usealtserver)  1
       set loginconf(altserver)     "jabber.example.com"

       set loginconf1(profile)      "Default Account"
       set loginconf1(user)         mrose

       set loginconf2(profile)      "Test Account"
       set loginconf2(user)         test

       array set loginconf          [array get loginconf1]

       set autologin 0


   # the message module

       set message::options(headlines,cache)    1
       set message::options(headlines,multiple) 1


   # the raw xml input module

       set plugins::rawxml::set options(pretty_print) 0
       set plugins::rawxml::set options(indent)       2




Shchepin, et al.                                               [Page 19]

                             Tkabber v0.9.9                     May 2006


   # the roster module

       set roster::show_only_online            1
       set roster::roster(collapsed,RSS)       1
       set roster::roster(collapsed,Undefined) 1

       set roster::aliases(friend@some.host) \
           {friend@other.host friend@another.host}
       set roster::use_aliases                 1


   # the sound module

       set sound::options(mute)                   0
       set sound::options(mute_if_focus)          0
       set sound::options(notify_online)          0
       set sound::options(mute_groupchat_delayed) 1
       set sound::options(mute_chat_delayed)      0
       set sound::options(external_play_program) /usr/bin/aplay
       set sound::options(external_play_program_options) -q
       set sound::options(delay)

       set sound::options(connected_sound)                     ""
       set sound::options(presence_available_sound)            ""
       set sound::options(presence_unavailable_sound)          ""
       set sound::options(groupchat_server_message_sound)      ""
       set sound::options(groupchat_their_message_to_me_sound) ""
   }

   This isn't nearly as complicated as it seems.  Let's break it down by
   individual module

4.2.1.  Look-and-Feel

   _Tkabber_ is shameless in borrowing icons from other Jabber clients.
   By setting "pixmaps::options(pixmaps_theme)", you can select a family
   of related icons.  Besides ""Default"", you can choose one of
   ""Gabber"", ""JAJC"", ""Jarl"", ""Psi"", ""ICQ"", or a few other
   themes.

   If you want, you can have _Tkabber_ use a different theme by putting
   custom theme subdirectory to "~/.tkabber/pixmaps/" directory (tilde
   means home directory). _Tkabber_ knows that it is a theme directory
   by looking for "icondef.xml" file in the directory.  To find out the
   structure of icon definition file, look through _JEP-0038_ and go to
   where you installed _Tkabber_ and take a look at the directory called
   ""pixmaps/default/"".




Shchepin, et al.                                               [Page 20]

                             Tkabber v0.9.9                     May 2006


   If you're using the tabbed window interface, _Tkabber_ needs a way of
   telling you that something has changed in a window that's not on top.
   This is where the an array called _alert_lvls_ and a list called
   _alert_colors_ come in.  The array maps an incoming message to a
   priority number from zero to three.  The list, which is indexed
   starting at _zero_, indicates what color the tab should use to let
   you know that something's changed.  So, the way to read the example
   is that receiving:

   o  an error or server message will cause the tab of a lowered window
      to go dark blue;

   o  a groupchat or headline message will cause the tab to go blue;
      and,

   o  a chat message addressed directly to you will cause the tab to go
      red.

   By default, whenever a tab has new activity, it is automatically
   raised.  If you don't like this behavior, add this line:
   set raise_new_tab 0

4.2.2.  The Autoaway Module

   This module is presently available only if either:

   o  on UNIX, if you have the _Tk Xwin_ extension installed; or,

   o  On Windows, if you have the _Tcl Winidle_ extension installed.

   There are two variables that control when _Tkabber_ automatically
   marks you as away: "plugins::autoaway::options(awaytime)" and
   "plugins::autoaway::options(xatime)".  Both define the idle threshold
   in minutes (the number does not have to be integer).

   If variable "plugins::autoaway::options(drop_priority)" is set in 1
   then _Tkabber_ will set priority to 0 when moving in extended away
   state.

   Variable "plugins::autoaway::options(status)" allows to specify text
   status, which is set when _Tkabber_ is moving in away state.

4.2.3.  The Avatar Module

   There are two variables that you can set to control whether _Tkabber_
   will allow others to see your avatar:





Shchepin, et al.                                               [Page 21]

                             Tkabber v0.9.9                     May 2006


   o  "avatar::options(announce)" determines whether your presence
      information indicates that you have an avatar; and,

   o  "avatar::options(share)" determines whether requests for your
      avatar will be honored.

4.2.4.  The Chat Module

   Most instant messaging users prefer to see all the back-and-forth
   communication in a single window.  If you prefer to see each line
   sent back-and-forth in a separate window, here's what to put in your
   "postload":

   set chat::options(default_message_type) normal

   The variable named "chat::options(stop_scroll)" determines whether a
   chat window should automatically scroll down to the bottom whenever
   something new comes in.

   You can also set format of time stamp that displayed in beginning of
   each chat message.  Refer to _Tcl_ documentation for description of
   format.  E.g., to display it in ""dd:mm:ss"" format, add this line:

   set plugins::options(timestamp_format) {[%T]}

4.2.5.  The Clientinfo Module

   This module shows in popup balloons information of used by this user
   client name, version, and OS.  You can allow or deny automatic asking
   of this info from users by setting this variable to 1 or 0:
   set plugins::clientinfo::options(autoask) 1

4.2.6.  The Conferenceinfo Module

   After you join a conference that's listed in your roster, then
   whenever you mouse over that roster entry, you'll see a popup listing
   the conference's participants.  If you want to see this popup,
   regardless of whether you are currently joined with the conference,
   add this line to your post-load:
   set plugins::conferenceinfo::options(autoask) 1

   You can also set interval between these requests with these two
   variables:

   set plugins::conferenceinfo::options(interval)       1
   set plugins::conferenceinfo::options(err_interval)  60

   The second variable defines how many minutes to wait after receiving



Shchepin, et al.                                               [Page 22]

                             Tkabber v0.9.9                     May 2006


   an error reply before trying again.  (Usually an error reply
   indicates that the server hosting the conference doesn't support
   browsing, so it makes sense not to try that often.

4.2.7.  The Cryptographic Module

   Earlier (Section 4.1) we saw an example where the "ssj::options"
   array from the cryptographic module was set during the preload.

   In addition to "signed-traffic" and "encrypt-traffic", you can also
   tell _Tkabber_ whether to encrypt for a particular JID, e.g.,

       set ssj::options(encrypt,fred@example.com) 1

4.2.8.  The Emoticons Module

   The procedure called _emoteicons::load_dir_ is used to load emoticon
   definitions from a directory.  The directory contains a file called
   ""icondef.xml"", which defines the mapping between each image and its
   textual emoticon (To find out what this file looks like, go to where
   you installed _Tkabber_ and take a look at the file called
   ""emoticons-tkabber/icondef.xml"" or read JEP-0038 [21].)

   If you have just a few icons, and you don't want to create a
   directory and a textual mapping, you can use the procedure called
   "emoteicons::add", e.g.,

       emoteicons::add ":beer:" \
                       [image create photo -file ~/.tkabber/beer.gif]

   If you want to disable all emoticons, you can use the following
   trick.  Put in postload function

       array unset emoteicons::emoteicons

4.2.9.  The File Transfer Module

   You can set directory in which files will be saved by default:

       set ft::options(download_dir) "/tmp"

4.2.10.  The Groupchat Module

   There are several variables that set the dialog window defaults for
   adding a groupchat to your roster, or joining a groupchat:






Shchepin, et al.                                               [Page 23]

                             Tkabber v0.9.9                     May 2006


   add to roster dialog window: "gra_group" and "gra_server" specify the
      default room and conference server, repectively; and,

   join dialog window: "gr_nick", "gr_group" and "gr_server" specify the
      default nickname, room, and conference server, respectively.

   Note that variables "gra_server", "gr_nick" and "gr_server" overriden
   in login procedure, so better place for changing them is in
   "connected_hook" (see below).

   You may want to have different nicknames for different groupchats.
   Accordingly, the array called _defaultnick_ is used to set the
   default nickname for when you enter a conference.  The array is
   indexed by the JID of the room, e.g.,

       set defaultnick(adhoc@conference.example.com) publius

   Another possibility is to put pattern in parentheses.  The following
   example shows how to specify default nickname for all conferences at
   _conference.example.com_:

       set defaultnick(*@conference.example.com) ciceroni

   Exact JID's take the higher precedence than patterns.

4.2.11.  The Ispell Module

   If you enabled this module earlier (Section 4.1.5), then you can
   define:

   o  the path to the _ispell_ executable by setting
      "plugins::ispell::options(executable)"

   o  the path to the dictionary by setting
      "plugins::ispell::options(dictionary)"; and,

   o  the encoding of the output by setting
      "plugins::ispell::options(dictionary_encoding)".

   If you don't care about putting a large load on your process, then
   you can also set "plugins::ispell::options(check_every_symbol)" to 1
   to check correctness of current word after every entered symbol.
   (Usually you don't need to set this option.)

4.2.12.  The Stream Initiation Module

   Stream initiation profile is defined in _JEP-0095_ with two
   transports (_JEP-0047_ - IBB, _JEP-0065_ - SOCKS5 bytestreams).  With



Shchepin, et al.                                               [Page 24]

                             Tkabber v0.9.9                     May 2006


   it you can specify what transports you can use, and via negotiation
   choose more appropriate one. _Tkabber_ comes with two transport
   implementations:

   bytestreams: that allows you to connect to any node that supports
      "bytestreams" transport (mediated connection is not supported
      yet);

   ibb: that uses your "Jabber" connection to transmit the data (which
      may slowdown other traffic to you).

   If your machine is behind a NAT, then you can't use the "bytestreams"
   transport, so you should disable it:

       set si::transport(allowed,http://jabber.org/protocol/bytestreams) 0

4.2.13.  The Jidlink Module

   Jidlink is a simple negotiation protocol for setting up a bytestream
   between two JIDs.  With it you can specify what transports you can
   use, and via negotiation choose more appropriate one. _Tkabber_ comes
   with three transport implementations:

   dtcp-active: that allows you to connect to any node that supports
      "dtcp-passive";

   dtcp-passive: that allows any node that supports "dtcp-active" to
      connect to you; and,

   inband-bytestream: that uses your "Jabber" connection to transmit the
      data (which may slowdown other traffic to you).

   If your machine is behind a firewall, then you can't use the
   "dtcp-passive" transport, so you should disable it:

       set jidlink::transport(allowed,dtcp-passive) 0

4.2.14.  The Logger Module

   You can set directory to store logs:

       set logger::options(logdir) ~/.tkabber/logs

   Also you can allow or disallow storing of private and group chats
   logs:

       set logger::options(log_chat)      1
       set logger::options(log_groupchat) 1



Shchepin, et al.                                               [Page 25]

                             Tkabber v0.9.9                     May 2006


4.2.15.  The Login Module

   The first task is to initialize the configuration defaults for the
   _login_ module.  As you can see above, the global array "loginconf"
   has a whole bunch of elements, e.g., "user", "password", and so on.
   This collection of elements, which is termed a login profile, is what
   populates the dialog window you'll see when _Tkabber_ wants to
   connect to the server.

   It turns out that _Tkabber_ lets you have as many different login
   profiles as you want.  If you want more than just one, they're named
   "loginconf1", "loginconf2", and so on.

   What the example above shows is the default values for all profiles
   being set in "loginconf", and then two profiles, one called ""Default
   Account"" and the other called ""Test Account"" being created.

   If you want to automatically login to server, then you can set the
   "autologin" variable to "1".

   If you set the "autologin" variable to "-1", then _Tkabber_ will not
   automatically login and will not show login dialog.

   Default value for "autologin" is "0".  In this case _Tkabber_ shows
   login dialog.

4.2.16.  The Message Module

   By default, when you restart _Tkabber_ it won't remember the
   headlines you received.  If you want _Tkabber_ to remember headlines
   whenever you run it, set "message::options(headlines,cache)" to "1".

   By default, _Tkabber_ will put all headline messages into a single
   window.  If you want _Tkabber_ to use a seperate window for each
   headline source, set "message::options(headlines,multiple)" to "1".

4.2.17.  The Raw XML Input Module

   With this module you can monitor incoming/outgoing traffic from
   connection to server and send custom XML stanzas.  Also you can
   switch on "pretty print" option to see incoming and outgoing XML
   stanzas pretty printed.  Note, that with this option they may be
   drawed incorrectly, e.g. for XHTML tags.  Also you can set
   indentation level via "indent" option.

4.2.18.  The Roster Module

   By default, your entire roster is shown, even those items that aren't



Shchepin, et al.                                               [Page 26]

                             Tkabber v0.9.9                     May 2006


   online.  The variable called "roster::show_only_online" controls
   this.

   Similarly by default, each item in every category is shown in the
   roster.  If you want to hide the items in a given category, the array
   called "roster::roster" lets you do this.  In the example, we see
   that two groups (""RSS"" and ""Undefined"") start with their items
   hidden.

   Some peoples use several JIDs. _Tkabber_ lets you specify an alias
   for people like these, so it will show only one entry in the roster.
   In the example, we see that user "friend@some.host" have aliases
   "friend@other.host" and "friend@another.host".  You can also disable
   all aliases by setting "roster::use_aliases" to "0".

4.2.19.  The Sound Module

   _Tkabber_ can play sounds on some events.  It can use for this
   _snack_ library or external program that can play _WAV_ files.  Sound
   notifications is enabled when _Tkabber_ starts.

   If you want to start _Tkabber_ with sound muted add the following
   line:
   set sound::options(mute) 1

   If you want _Tkabber_ to stop notifying you when you are not online
   (in away or dnd state) add the following line:
   set sound::options(notify_online) 1

   If you want _Tkabber_ to mute sound when it is focued (and you are
   paying enough attention to it) add the following line:
   set sound::options(mute_if_focus) 1

   You can also mute sounds of delayed groupchat messages and delayed
   personal chat messages:

   set sound::options(mute_groupchat_delayed) 1
   set sound::options(mute_chat_delayed)      0

   If you want to use external program for playing sounds and possibly
   this program's options, then also add something like this (these
   options are suitable for Linux users with ALSA installed):

   set sound::options(external_play_program) /usr/bin/aplay
   set sound::options(external_play_program_options) -q






Shchepin, et al.                                               [Page 27]

                             Tkabber v0.9.9                     May 2006


   You can also set minimal interval (in milliseconds) between playing
   different sounds.
   set sound::options(delay) 200

   _Tkabber_ allows you to specify the filename it will play notifying
   about some more or less important events.  These are:

   o  "sound::options(connected_sound)" -- sound playing when _Tkabber_
      is connected to the server;

   o  "sound::options(presence_available_sound)" -- sound playing when
      available presence is coming;

   o  "sound::options(presence_unavailable_sound)" -- sound playing when
      unavailable presence is coming;

   o  "sound::options(chat_my_message_sound)" -- sound playing when you
      send one-to-one chat message;

   o  "sound::options(chat_their_message_sound)" -- sound playing when
      you receive one-to-one chat message;

   o  "sound::options(groupchat_server_message_sound)" -- sound playing
      when you receive groupchat message from server;

   o  "sound::options(groupchat_my_message_sound)" -- sound playing when
      you receive groupchat message from server;

   o  "sound::options(groupchat_their_message_sound)" -- sound playing
      when you receive groupchat message from another user;

   o  "sound::options(groupchat_their_message_to_me_sound)" -- sound
      playing when you receive highlighted (usually personally
      addressed) groupchat message from another user.

   If you want to disable sound notification for some of the events,
   then you can add line like this:

   set sound::options(connected_sound)                     ""
   set sound::options(presence_available_sound)            ""
   set sound::options(presence_unavailable_sound)          ""
   set sound::options(groupchat_server_message_sound)      ""
   set sound::options(groupchat_their_message_to_me_sound) ""

4.3.  Menu-load

   After _Tkabber_ invokes your "postload" procedure, it starts building
   the GUI.  One of the most important things it does is build up a list



Shchepin, et al.                                               [Page 28]

                             Tkabber v0.9.9                     May 2006


   that specifies its menu bar.  It then invokes a procedure called
   "menuload", which is allowed to modify that specification before
   _Tkabber_ uses it.

   The default version of this procedure is the identity function,
   i.e..,

   proc menuload {description} { return $description }

   If you _really_ want to change the menubar specification, then here's
   how to get started:

   1.  Go to where you installed the _BWidget_ library and take a look
       at the file called ""BWman/MainFrame.html"".  The documentation
       for the ""-menu"" option explains the syntax of the
       specification.

   2.  Go to where you installed _Tkabber_ and take a look at the file
       called ""iface.tcl"".  Look for the line that starts with ""set
       descmenu"".  This will show you the specification given to your
       "menuload" procedure.

   3.  Go to where you installed _Tkabber_ and take a look at the file
       called ""examples/mtr-config.tcl"".  Look at the "menuload"
       procedure defined there.  It lays out _Tkabber's_ menu bar
       similar to _Gabber's_.

   4.  Finally, study the procedures listed here.

4.3.1.  The Avatar Module

   The procedure called "avatar::store_on_server" stores your avatar on
   the server.

4.3.2.  The Browser Module

   The procedure called "browser::open" opens a new browser window.

4.3.3.  The Groupchat Module

   The procedure called "add_group_dialog" displays a dialog window when
   you want to add a groupchat to your roster.  Similarly, the procedure
   called "join_group_dialog" displays a dialog window when you want to
   join a groupchat.

4.3.4.  The Login Module

   The procedure called "show_login_dialog" displays a dialog window



Shchepin, et al.                                               [Page 29]

                             Tkabber v0.9.9                     May 2006


   when you want to login to the server.  (Prior to attempting to login,
   if necessary it will logout).  Naturally, the procedure called
   "logout" does just that; however, if you want get a dialog window for
   confirmation, use "show_logout_dialog" instead.

4.3.5.  The Message Module

   If you want to send a message to someone, the procedure called
   "message::send_dialog" will put up a dialog window.  It takes upto
   three optional arguments: the recipient JID, the subject, and the
   thread.

   If you want to get added to someone's roster, the procedure called
   "message::send_subscribe_dialog" will put up a dialog window.  It
   takes one optional argument: the recipient JID.

   If you want to adjust your message filters, the procecure called
   "filters::open" will put up a dialog window.

4.3.6.  The Presence Module

   If you want to display information about a user, the procecure called
   "userinfo::open" will put up a dialog window.  It takes two optional
   arguments: the user's JID; and, whether or not the dialog window
   should be editable.

   Obviously, the second argument makes sense only if it's your own
   information, i.e.,

       global loginconf

       userinfo::open \
           ${loginconf(user)}@$loginconf(server)/$loginconf(resource) 1

   There are also two variables that you can use to set your own
   presence: "userstatus" and "textstatus".  The first variable takes
   one of five values:

   o  available;

   o  chat;

   o  away;

   o  xa;

   o  dnd; or,




Shchepin, et al.                                               [Page 30]

                             Tkabber v0.9.9                     May 2006


   o  invisible.

   The second variable takes any textual value.

   Changes to your presence information are propagated only when
   "userstatus" is changed.  Accordingly, if you make a change to
   "textstatus", be sure to write "userstatus" immediately afterwards,
   even if it's a no-op, e.g.,

       global userstatus textstatus

       set textstatus "Out to lunch"
       set userstatus $userstatus

4.3.7.  Miscellany

   Finally, you can use the procedure named "help_window" to display
   some textual help.  This procedure takes two arguments: the title for
   the window; and, the text to display.

   Also, instead of calling "exit" to terminate _Tkabber_, please use
   the "quit" procedure instead.

4.4.  Final-Load

   Finally, right before _Tkabber_ goes to display the login dialog, it
   invokes a procedure called "finload", which does whatever you want it
   to.























Shchepin, et al.                                               [Page 31]

                             Tkabber v0.9.9                     May 2006


5.  Extensibility

   In addition to various configuration mechanisms, _Tkabber_ lets you
   define procedures, termed "hooks" that get run when certain events
   happen.

   Here's an example.  When _Tkabber_ receives a chat message, how does
   it know what to process and what to draw?  The short answer is that
   it doesn't need to know anything, all it does is:

   hook::run draw_message_hook $chatid $from $type $body $extras

   The "hook::run" procedure invokes whatever hooks have been defined
   for "draw_message_hook".  In fact, more than ten procedures may get
   invoked to satisfy this hook!

   Here's how it works: _Tkabber_ comes with a number of plugins, which
   get loaded automatically.  Each plugin makes one or more calls that
   look like this:

   hook::add draw_message_hook [namespace current]::my_draw_hook $prio

   where the last two parameters are: the name of a procedure to run;
   and, a relative integer priority.

   When "hook::run" is invoked for "draw_message_hook", each of these
   procedures is called, in the priority order (from smallest to
   largest).  If one of the procedures wants to prevent the later
   procedures from being called, it returns the string ""stop"".






















Shchepin, et al.                                               [Page 32]

                             Tkabber v0.9.9                     May 2006


   To continue with the example, in between the pre-load and post-load
   stages of configuration, the following calls get made by different
   plugins:

   hook::add draw_message_hook [list ...::events::process_x 0] 0
   hook::add draw_message_hook ...::chatstate::process_x 1
   hook::add draw_message_hook ...::check_draw_empty_body 4
   hook::add draw_message_hook ...::chat_open_window 5
   hook::add draw_message_hook [list ...::events::process_x 1] 6
   hook::add draw_message_hook ...::draw_signed 6
   hook::add draw_message_hook ...::draw_encrypted 7
   hook::add draw_message_hook ...::handle_error 10
   hook::add draw_message_hook ...::handle_info 10
   hook::add draw_message_hook ...::draw_timestamp 15
   hook::add draw_message_hook    ::logger::log_message 15
   hook::add draw_message_hook      muc::set_message_timestamp 15
   hook::add draw_message_hook ...::add_number_of_messages_to_title 18
   hook::add draw_message_hook ...::chat_message_notify19
   hook::add draw_message_hook ...::handle_server_message 20
   hook::add draw_message_hook ...::roster::update_chat_activity 50
   hook::add draw_message_hook ...::check_nick 60
   hook::add draw_message_hook    ::wmdock::msg_recv 70
   hook::add draw_message_hook ...::handle_last_nick 79
   hook::add draw_message_hook ...::::add_bookmark 80
   hook::add draw_message_hook ...::handle_me 83
   hook::add draw_message_hook ...::xhtml::draw_xhtml_message 85
   hook::add draw_message_hook ...::draw_normal_message 87

   Many of these procedures look at the incoming chat message and
   operate on only certain kinds of messages.  Some of these procedures
   may return ""stop"", e.g., "handle_me" which handles chat bodies that
   start with ""/me"" and draw_xhtml_message which visualizes _XHTML_
   formatted messages.  (In this example, the actual namespaces were
   replaced with ""...:"" to make it more readable).

   Now let's look at the different kind of hooks that _Tkabber_ knows
   about.

5.1.  Chat Hooks

   When _Tkabber_ decides that it needs to open a (tabbed) window for a
   chat or groupchat, two hooks are run:

   open_chat_pre_hook  $chatid $type
   open_chat_post_hook $chatid $type

   Both hooks are given two parameters: the chatid (ID of the chat or
   conference room window, you always can obtain JID using



Shchepin, et al.                                               [Page 33]

                             Tkabber v0.9.9                     May 2006


   "chat::get_jid" and connection ID using "chat::get_connid" routines);
   and, and the type of chat (either ""chat"" or ""groupchat"").

   Similarly, when _Tkabber_ encounters activity on a tabbed window, a
   hook is run:

   raise_chat_tab_hook $path $chatid

   The hook is given two parameters: the path of the _Tk_ widget for the
   tabbed window; and, the chatid of the chat or conference room window.

   When you want to send a chat message, a hook is run:

   chat_send_message_hook $chatid $user $body $type

   The hook is given four parameters: the chatid of the recipient; the
   localpart of your login identity; the body of the message; and, the
   type of chat.

   draw_message_hook $chatid $from $type $body $extras

   The hook is given five parameters: the chatid of the sender window
   (JID includes a resource); the JID of the sender (without the
   resource); the type of chat; the body of the message; and, a nested-
   list of additional payload elements.  (This last parameter isn't
   documented in this version of the documentation.)

   Chat windows have menubuttons, and two hooks is used to add items in
   menu:

   chat_create_user_menu_hook $path $connid $jid
   chat_create_conference_menu_hook $path $connid $jid

   The first is used in user chat windows, and second in groupchat ones.
   Hooks is given three parameters: the path of the _Tk_ menu widget;
   connection ID; and, the JID of user or conference.

   In groupchat windows possible to complete participant's nicks or
   commands by pressing TAB key.  List of completions is generated by
   running this hook:

   generate_completions_hook $chatid $compsvar $wordstart $line

   The hook is given four parameters: the chatid of conference window;
   name of global variable, in which stored current list of possible
   completions; index of position where completion must be inserted;
   and, content of text widget where completion is requested.




Shchepin, et al.                                               [Page 34]

                             Tkabber v0.9.9                     May 2006


   When someone enters/exits conference, next hooks called:

   chat_user_enter $group $nick
   chat_user_exit  $group $nick

   The hook is given two parameters: chatid of conference and nick
   participant.

5.2.  Login Hooks

   Two hooks are invoked whenever a session is connected or
   disconnected:

   connected_hook $connid

   disconnected_hook $connid

   Both hook is given one parameter: connection ID (_Tkabber_ allows
   several connections at once).

5.3.  Presence Hooks

   When our presence status changes, a hook is run:

   change_our_presence_post_hook $status

   The hook is given one parameter: the new presence status value, i.e.,
   one of:

   o  available;

   o  chat;

   o  away;

   o  xa;

   o  dnd; or

   o  unavailable.

   Similarly, when someone else's presence changes, a hook is run:

   on_change_user_presence_hook $label $status

   The hook is given two parameters: the label associated with the JID
   (e.g., "fred") or the JID itself (e.g., "fred@example.com") if no
   label exists in the roster; and, the user's new status.



Shchepin, et al.                                               [Page 35]

                             Tkabber v0.9.9                     May 2006


   And for all received presence packets, a hook is run:

   client_presence_hook $connid $from $type $x $args

   The hook is given four parameters: connection ID, who send this
   presence, type of presence (e.g., "error", "unavailable"), list of
   extended subtags and parameters of this presence (e.g., "-show xa
   -status online").

5.4.  Roster Hooks

   When an item is added to the roster window, one of the three hooks is
   run to add stuff to the menu associated with that item:

   roster_conference_popup_menu_hook $path $connid $jid

   roster_service_popup_menu_hook $path $connid $jid

   roster_jid_popup_menu_hook $path $connid $jid

   The hook is given three parameters: the path of the _Tk_ menu widget;
   the connection ID; and, a JID for which presence information is
   available.

   Also next hook is run to add stuff to the menu in groupchats:

   roster_create_groupchat_user_menu_hook $path $connid $jid

   The hook is given three parameters: the path of the _Tk_ menu widget;
   the connection ID; and, a JID of user.

   Next hook is run to add stuff to the popup balloon for each roster
   item:

   roster_user_popup_info_hook $varname $connid $jid

   The hook is given three parameters: the variable name in which
   current popup text is stored, the connection ID, and the JID of the
   roster item.












Shchepin, et al.                                               [Page 36]

                             Tkabber v0.9.9                     May 2006


5.5.  Miscellaneous Hooks

   There are three "obvious" hooks:

   postload_hook

   finload_hook

   quit_hook

   The first two, by default, run the "postload" and "finload"
   procedures, respectively. _postload_hook_ is run after all code
   loaded and before initializing main _Tkabber_ window.  After that
   _finload_hook_ is run.  The final hooks is called just before
   _Tkabber_ terminates (cf., Section 4.3.7).

   You can add custom pages to userinfo window using

   userinfo_hook $path $connid $jid $editable
































Shchepin, et al.                                               [Page 37]

                             Tkabber v0.9.9                     May 2006


Appendix A.  Releases History

A.1.  Main changes in 0.9.9

   o  Improved privacy lists interface

   o  Support for stream compression (JEP-0138)

   o  Support for SRV DNS-records

   o  Support for TXT DNS-records (JEP-0156)

   o  Support for ad-hoc commands (JEP-0050)

   o  Improved headlines support

   o  Chat state notification support (JEP-0085)

   o  Many fixes and enhancements

A.2.  Main changes in 0.9.8

   o  Support for STARTTLS

   o  Reorganized menu

   o  Support for searching in chat window

   o  Support for annotations about roster items (JEP-0145)

   o  Support for conference rooms bookmarks (JEP-0048)

   o  Added multilogin support for GPGME

   o  Better support for xml:lang

   o  Support for service discovery extensions (JEP-0128)

   o  Support for NTLM authentication

   o  Many fixes and enhancements

A.3.  Main changes in 0.9.7beta

   o  Updated support for file transfer (JEP-0095, JEP-0096, JEP-0047,
      JEP-0065)





Shchepin, et al.                                               [Page 38]

                             Tkabber v0.9.9                     May 2006


   o  Support for colored nicks and messages in conference

   o  Better multiple logins support

   o  Updated support for xml:lang

   o  Support for IDNA (RFC3490)

   o  Many fixes and enhancements

A.4.  Main changes in 0.9.6beta

   o  Multiple logins support

   o  History now splitted by month

   o  Animated emoteicons support

   o  Many user interface improvements

   o  More XMPP support

   o  More translations

   o  Bugfixes

A.5.  Main changes in 0.9.5beta

   o  Nested roster groups

   o  Messages emphasizing

   o  User interface improvements

   o  Support for XMPP/Jabber MIME Type

   o  Bugfixes














Shchepin, et al.                                               [Page 39]

                             Tkabber v0.9.9                     May 2006


Appendix B.  XRDB

   Here is list of most _Tkabber_-specific _XRDB_ resources that you
   need to change look:

   Tkabber.geometry Geometry of main window.

   *Chat.chatgeometry

   *Chat.groupchatgeometry

   *Customize.geometry

   *RawXML.geometry

   *Stats.geometry

   *Messages.geometry

   *JBrowser.geometry

   *JDisco.geometry Geometry of various windows (when not using tabs).

   *Chat.inputheight

   *RawXML.inputheight Height of input windows in chat and raw XML
      windows.

   *Balloon.background

   *Balloon.foreground Background and foreground colors of popup
      balloon.

   *Balloon.style Behaviour of popup balloon: can be "delay" (balloon
      appeared after some time) and "follow" (balloon appeared
      immediately and follows mouse).

   *JBrowser.fill Color of browser item name.

   *JBrowser.nscolor Color of NS browser item.

   *JBrowser*Tree*background Background of browser.

   *Chat.meforeground Color of user's messages in chat windows.







Shchepin, et al.                                               [Page 40]

                             Tkabber v0.9.9                     May 2006


   *Chat.theyforeground Color of other peoples messages in chat windows.

   *Chat.serverlabelforeground Color of label before server message.

   *Chat.serverforeground Color of server messages in chat windows.

   *Chat.errforeground Color of error messages in chat windows.

   *Chat.urlforeground Color of URLs in chat windows.

   *Chat.urlactiveforeground Color of mouse highlighted URLs in chat
      windows.

   *JDisco.fill Default color of items in Service Discovery Browser.

   *JDisco.featurecolor Default color of feature items in Service
      Discovery Browser.

   *JDisco.identitycolor Default color of identity items in Service
      Discovery Browser.

   *JDisco.optioncolor Default color of option items in Service
      Discovery Browser.

   *JDisco*Tree*background Default color of background in Service
      Discovery Browser.

   *NoteBook.alertColor0

   *NoteBook.alertColor1

   *NoteBook.alertColor2

   *NoteBook.alertColor3 Tabs alert colors.

   *Roster.cbackground Roster background color.

   *Roster.groupindent Indentation for group title.

   *Roster.groupiconindent Indentation for group icon.

   *Roster.jidindent Indentation for item name.

   *Roster.jidmultindent Indentation for item with multiple resources.







Shchepin, et al.                                               [Page 41]

                             Tkabber v0.9.9                     May 2006


   *Roster.subjidindent Indentation for item resource.

   *Roster.iconindent Indentation for item icon.

   *Roster.subitemtype

   *Roster.subiconindent Indentation for resource icon.

   *Roster.textuppad Top pad for item's names.

   *Roster.textdownpad Bottom pad for item's names.

   *Roster.linepad Vertical distance between items.

   *Roster.foreground Color of item's names.

   *Roster.jidfill Background of roster item.

   *Roster.jidhlfill Background of roster item when mouse is over.

   *Roster.jidborder Color of item's border.

   *Roster.groupfill

   *Roster.grouphlfill

   *Roster.groupborder The same to roster groups.

   *Roster.groupcfill Background color of collapsed group.

   *Roster.stalkerforeground

   *Roster.unavailableforeground

   *Roster.dndforeground

   *Roster.xaforeground

   *Roster.awayforeground

   *Roster.availableforeground

   *Roster.chatforeground Colors of item name for different presences.








Shchepin, et al.                                               [Page 42]

                             Tkabber v0.9.9                     May 2006


Appendix C.  Documentation TODO

   The next revision of this documentation should discuss:

   o  Pre-load:

      *  "browseurl"

   o  Post-load:

      *  "chat_height" and "chat_width" (appear to be no-ops).

   o  Menu-load:

      *  "change_password_dialog"

      *  "conference::create_room_dialog"

      *  "disco::browser::open_win"

      *  "message::send_msg"

      *  "privacy::request_lists"

      *  "rawxml::open_window"

      *  "userinfo::show_info_dialog"

   o  Hooks: the additional payload format.






















Shchepin, et al.                                               [Page 43]

                             Tkabber v0.9.9                     May 2006


Appendix D.  Acknowledgements

   Rebecca Malamud was kind enough to design the "enlightened feather"
   motif used in the _Tkabber_ look-and-feel.















































Shchepin, et al.                                               [Page 44]

                             Tkabber v0.9.9                     May 2006


Appendix E.  Copyrights

   Copyright (c) 2002-2006 Alexey Shchepin

   _Tkabber_ is free software; you can redistribute it and/or modify it
   under the terms of the GNU General Public License as published by the
   Free Software Foundation; either version 2 of the License, or (at
   your option) any later version.

   _Tkabber_ is distributed in the hope that it will be useful, but
   WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
   General Public License for more details.






































Shchepin, et al.                                               [Page 45]

                             Tkabber v0.9.9                     May 2006


Authors' Addresses

   Alexey Yurievich Shchepin
   Process-One

   Email: alexey@sevcom.net


   Marshall T. Rose
   Dover Beach Consulting, Inc.
   POB 255268
   Sacramento, CA  95865-5268
   US

   Phone: +1 916 483 8878
   Fax:   +1 916 483 8848
   Email: mrose@dbc.mtview.ca.us


   Sergei Vitalyevich Golovan
   New Economic School

   Email: sgolovan@nes.ru


   Michail Yurievich Litvak
   Information Centre ISP

   Email: mci@al.lg.ua






















Shchepin, et al.                                               [Page 46]