


                                                             A. Shchepin
                                                             Process-One
                                                                 M. Rose
                                            Dover Beach Consulting, Inc.
                                                              S. Golovan
                                                     New Economic School
                                                               M. Litvak
                                                           Colocall Ltd.
                                                            K. Khomoutov
                                                             Service 007
                                                       February 14, 2014


                              Tkabber 1.1

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 1.1                 February 2014


Table of Contents

   1.  Features . . . . . . . . . . . . . . . . . . . . . . . . . . .  4
   2.  Requirements . . . . . . . . . . . . . . . . . . . . . . . . .  7
   3.  Download, install and run  . . . . . . . . . . . . . . . . . . 10
   4.  Upgrading from version 0.11.0 or 0.11.1  . . . . . . . . . . . 12
     4.1.  External plugins . . . . . . . . . . . . . . . . . . . . . 12
     4.2.  Configuration options  . . . . . . . . . . . . . . . . . . 12
   5.  Upgrading from version 0.10.0  . . . . . . . . . . . . . . . . 14
     5.1.  Configuration options  . . . . . . . . . . . . . . . . . . 14
       5.1.1.  Proxy servers  . . . . . . . . . . . . . . . . . . . . 14
       5.1.2.  Resources to control fonts . . . . . . . . . . . . . . 14
       5.1.3.  Keep-alives and dead link detection  . . . . . . . . . 15
       5.1.4.  Resources to control appearance of balloon windows . . 16
       5.1.5.  Support for external XML parser  . . . . . . . . . . . 16
     5.2.  User interface . . . . . . . . . . . . . . . . . . . . . . 16
       5.2.1.  System tray icon mouse gestures  . . . . . . . . . . . 16
       5.2.2.  New tab management widget  . . . . . . . . . . . . . . 16
       5.2.3.  Window splitters . . . . . . . . . . . . . . . . . . . 17
   6.  Upgrading from version 0.9.9 . . . . . . . . . . . . . . . . . 18
   7.  Configuration  . . . . . . . . . . . . . . . . . . . . . . . . 19
     7.1.  Pre-load . . . . . . . . . . . . . . . . . . . . . . . . . 21
       7.1.1.  Tabbed Interface . . . . . . . . . . . . . . . . . . . 22
       7.1.2.  Fonts and colors . . . . . . . . . . . . . . . . . . . 22
       7.1.3.  Cryptography by default  . . . . . . . . . . . . . . . 24
       7.1.4.  Debugging Output . . . . . . . . . . . . . . . . . . . 24
       7.1.5.  Splash window  . . . . . . . . . . . . . . . . . . . . 25
       7.1.6.  I18n/L10n  . . . . . . . . . . . . . . . . . . . . . . 25
       7.1.7.  Browse URL . . . . . . . . . . . . . . . . . . . . . . 25
       7.1.8.  Searching  . . . . . . . . . . . . . . . . . . . . . . 26
     7.2.  Post-load  . . . . . . . . . . . . . . . . . . . . . . . . 26
       7.2.1.  Look-and-Feel  . . . . . . . . . . . . . . . . . . . . 31
       7.2.2.  The system tray icon (for Unix)  . . . . . . . . . . . 31
       7.2.3.  The Autoaway Module  . . . . . . . . . . . . . . . . . 32
       7.2.4.  The Avatar Module  . . . . . . . . . . . . . . . . . . 32
       7.2.5.  The Chat Module  . . . . . . . . . . . . . . . . . . . 32
       7.2.6.  The Clientinfo Module  . . . . . . . . . . . . . . . . 33
       7.2.7.  The Conferenceinfo Module  . . . . . . . . . . . . . . 33
       7.2.8.  The Cryptographic Module . . . . . . . . . . . . . . . 33
       7.2.9.  The Emoticons Module . . . . . . . . . . . . . . . . . 33
       7.2.10. The File Transfer Module . . . . . . . . . . . . . . . 34
       7.2.11. The Groupchat Module . . . . . . . . . . . . . . . . . 34
       7.2.12. The Ispell Module  . . . . . . . . . . . . . . . . . . 35
       7.2.13. The Stream Initiation Module . . . . . . . . . . . . . 35
       7.2.14. The Logger Module  . . . . . . . . . . . . . . . . . . 36
       7.2.15. The Proxy Module . . . . . . . . . . . . . . . . . . . 36
       7.2.16. The Login Module . . . . . . . . . . . . . . . . . . . 38
       7.2.17. The Message Module . . . . . . . . . . . . . . . . . . 39



Shchepin, et al.                                                [Page 2]

                               Tkabber 1.1                 February 2014


       7.2.18. The Raw XML Input Module . . . . . . . . . . . . . . . 39
       7.2.19. The Roster Module  . . . . . . . . . . . . . . . . . . 39
       7.2.20. The Sound Module . . . . . . . . . . . . . . . . . . . 40
     7.3.  Menu-load  . . . . . . . . . . . . . . . . . . . . . . . . 41
       7.3.1.  The Avatar Module  . . . . . . . . . . . . . . . . . . 42
       7.3.2.  The Browser Module . . . . . . . . . . . . . . . . . . 42
       7.3.3.  The Groupchat Module . . . . . . . . . . . . . . . . . 42
       7.3.4.  The Login Module . . . . . . . . . . . . . . . . . . . 42
       7.3.5.  The Message Module . . . . . . . . . . . . . . . . . . 43
       7.3.6.  The Presence Module  . . . . . . . . . . . . . . . . . 43
       7.3.7.  Miscellany . . . . . . . . . . . . . . . . . . . . . . 44
     7.4.  Final-Load . . . . . . . . . . . . . . . . . . . . . . . . 44
   8.  Extensibility  . . . . . . . . . . . . . . . . . . . . . . . . 45
     8.1.  Message Hooks  . . . . . . . . . . . . . . . . . . . . . . 46
     8.2.  Chat Hooks . . . . . . . . . . . . . . . . . . . . . . . . 47
     8.3.  Login Hooks  . . . . . . . . . . . . . . . . . . . . . . . 49
     8.4.  Presence Hooks . . . . . . . . . . . . . . . . . . . . . . 49
     8.5.  Info/Query Hook  . . . . . . . . . . . . . . . . . . . . . 50
     8.6.  Roster Hooks . . . . . . . . . . . . . . . . . . . . . . . 50
     8.7.  Miscellaneous Hooks  . . . . . . . . . . . . . . . . . . . 51
   9.  User Interface basics  . . . . . . . . . . . . . . . . . . . . 52
     9.1.  Searching  . . . . . . . . . . . . . . . . . . . . . . . . 52
   Appendix A.  Releases History  . . . . . . . . . . . . . . . . . . 56
     A.1.  Main changes in 1.1  . . . . . . . . . . . . . . . . . . . 56
     A.2.  Main changes in 1.0  . . . . . . . . . . . . . . . . . . . 56
     A.3.  Main changes in 0.11.1 . . . . . . . . . . . . . . . . . . 57
     A.4.  Main changes in 0.11.0 . . . . . . . . . . . . . . . . . . 57
     A.5.  Main changes in 0.10.0 . . . . . . . . . . . . . . . . . . 58
     A.6.  Main changes in 0.9.9  . . . . . . . . . . . . . . . . . . 59
     A.7.  Main changes in 0.9.8  . . . . . . . . . . . . . . . . . . 59
     A.8.  Main changes in 0.9.7beta  . . . . . . . . . . . . . . . . 59
     A.9.  Main changes in 0.9.6beta  . . . . . . . . . . . . . . . . 60
     A.10. Main changes in 0.9.5beta  . . . . . . . . . . . . . . . . 60
   Appendix B.  Tk option database resources  . . . . . . . . . . . . 61
   Appendix C.  Documentation TODO  . . . . . . . . . . . . . . . . . 65
   Appendix D.  Acknowledgements  . . . . . . . . . . . . . . . . . . 66
   Appendix E.  Copyrights  . . . . . . . . . . . . . . . . . . . . . 67
   Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 68













Shchepin, et al.                                                [Page 3]

                               Tkabber 1.1                 February 2014


1.  Features

   Tkabber [1] provides a _Tcl/Tk_ interface to the Jabber/XMPP [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, BOSH 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 SOCKS4a, SOCKS5 or HTTPS proxy

      *  IPv6 support (from Tcl/Tk 8.6)

      *  user-defined hooks for connection establishment and release

      *  XMPP/Jabber MIME type








Shchepin, et al.                                                [Page 4]

                               Tkabber 1.1                 February 2014


   messages:

      *  privacy rules

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

      *  Off-the-record (OTR [3]) messaging

      *  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 messages arriving and 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







Shchepin, et al.                                                [Page 5]

                               Tkabber 1.1                 February 2014


   windowing:

      *  configurable look-and-feel via a resources database

      *  unicode

      *  tabbed/non-tabbed interface

      *  sound notifications

      *  nested roster groups

      *  roster metacontacts

      *  auto-away

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

      *  for Windows: taskbar icons































Shchepin, et al.                                                [Page 6]

                               Tkabber 1.1                 February 2014


2.  Requirements

   You should already have installed:

   o  Tcl/Tk version 8.4.9 [4] (or later, Tcl/Tk 8.5.9 or later is
      recommended).  Note, that if you want to use Tkabber in IPv6
      environment, you'll have to install Tcl/Tk 8.6beta2 or later.

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

   o  BWidget 1.3 [5] (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 [6] distribution contains all three packages (along
   with the _tls_ and _Img_ package mentioned below); 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  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 OpenSSL source page [8].  (The
      Windows distribution of _tls_ comes with all the necessary DLLs.)


   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 [9] (or



Shchepin, et al.                                                [Page 7]

                               Tkabber 1.1                 February 2014


      later).  This package works on both Unix and Windows.


   o  Tkabber comes bundled with pure-Tcl XML parser.  If its
      performance is insufficient, you may want to install tDOM version
      0.8.0 [10] (or later) and use expat based XML parser.


   o  Another option in Unix is to compress connection between client
      and server (it currently disables encryption).
      There's no special requirements for traffic compression in Tcl/Tk
      8.6, but if you're using Tcl/Tk 8.4 or 8.5 and want to compress
      traffic you should install ZTcl version 1.0b4 [11] (or later) and
      Tclmore version 0.7b1 [11] (or later).
      (At the time of 0.11.0 release _ZTcl_ and _Tclmore_ home page were
      unavailable, so you may grab them from a mirror [12].)


   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 _TclGPG_ package.
      Depending on what's already installed on your system, you may have
      to download upto two software bits:

      *  TclGPG [13] (available only in SVN at present);

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

      Another alternative is to use Off-the-record messaging
      protocol [3], if your contact supports it.  The OTR plugin is
      included into _Tkabber plugins collection_ starting from version
      1.1 and requires _Tcl/Tk_ 8.5 or newer, due to its arbitrary
      precision integer arithmetics, and a few packages from _Tcllib_,
      namely the _aes_, _asn_, _base64_, _math::bignum_, _sha1_,
      _sha256_ packages.  Also, if you're using Windows, the
      Memchan [15] extension has to be installed to run the OTR plugin.


   o  If you're running Unix or Windows, then you may want _Tkabber_ to
      play predefined sounds when message or presence arrives.
      Accordingly, you may want to install Snack version 2.10 [16] (or
      later).






Shchepin, et al.                                                [Page 8]

                               Tkabber 1.1                 February 2014


   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 (if you're using _Tcl/Tk_ 8.4), on Unix, you may want
      to install Tk Xwin version 1.0 [17] (or later), whilst on WIndows,
      you may want to install Tcl Winidle version 0.1 [18] (or later).

   o  Users of _Tcl/Tk_ 8.5 or newer don't have to use external packages
      to measure their idle time.


   o  If you're running Unix, then you may want _Tkabber_ to use the
      docking tray.
      Accordingly, you may want to install tktray version 1.3 [19] (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 [20] (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 [21] (or
      later).

   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 1.1                 February 2014


3.  Download, install and run

   Latest stable version is 1.1 and available at
   http://tkabber.jabber.ru/download.

   Older versions can be found at http://files.jabber.ru/tkabber/.

   You can always find the latest development version via SVN.  Execute
   the following command:

   svn co https://svn.xmpp.ru/repos/tkabber/trunk/tkabber

   And if you want to test some plugins, then do

   svn co https://svn.xmpp.ru/repos/tkabber/trunk/tkabber-plugins

   And if you want to try unofficial plugins, then execute

   svn co https://svn.xmpp.ru/repos/tkabber-3rd-party/trunk/plugins

   They usually include short readme with info on what they do and how
   to use them.

   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 version included into Debian repository.

   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.






Shchepin, et al.                                               [Page 10]

                               Tkabber 1.1                 February 2014


   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
   will start by hiding the _Tk_ console window.  Look under the
   "Services->Debug tools" menu to find the checkbutton to show the
   console.  Note that if _Tkcon_ is installed as a Tcl/Tk package then
   _Tkabber_ will add corresponding menu item under _Services->Debug
   tools_ automatically.

   Also you can setup _Tkabber_ as handler for XMPP/Jabber MIME
   Type [22].  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 1.1                 February 2014


4.  Upgrading from version 0.11.0 or 0.11.1

   When upgrading _Tkabber_ from version 0.11.1 or earlier note that its
   plugin interface and several configuration options have been changed.

4.1.  External plugins

   There are incompatible changes in Tkabber internals, which break the
   old plugins.  So, you'll have to upgrade them as well.  If a plugin
   author hasn't released a version compatible with _Tkabber_ 1.1 then
   you'll have to disable or remove that plugin.

4.2.  Configuration options

   There are notable changes in specifying a set of proxy servers.  If
   you define proxy server in the global "loginconf" array then you'll
   have to do the following: In case if you use the _Customize_
   interface, you may open the _Manage proxy servers_ dialog window and
   add your proxy server there.  Note that if you're using the HTTPS
   proxy then you'll have to add it twice (one in the _Tunnel proxies_
   tab and the other in the _HTTP proxies_ tab, see section 'The proxy
   module' (Section 7.2.15) below).  If you define proxy server in the
   _Tkabber_ config file then you have lines similar to the following in
   the config:

   set loginconf(proxy) https
   set loginconf(proxyhost) proxy.example.com
   set loginconf(proxyport) 3128
   set loginconf(proxyusername) ""
   set loginconf(proxypassword) ""





















Shchepin, et al.                                               [Page 12]

                               Tkabber 1.1                 February 2014


   Replace them by the following:

   set proxy1(type) https
   set proxy1(host) proxy.example.com
   set proxy1(port) 3128
   set proxy1(username) ""
   set proxy1(password) ""
   set proxy1(match) *
   set proxy1(exclude) "localhost* 127.0.0.* 172.* 192.168.* 10.*"

   set proxy2(type) http
   set proxy2(host) proxy.example.com
   set proxy2(port) 3128
   set proxy2(username) ""
   set proxy2(password) ""
   set proxy2(match) *
   set proxy2(exclude) "localhost* 127.0.0.* 172.* 192.168.* 10.*"

   set proxyconf(profile) Proxies
   set proxyconf(tunnel) {proxy1}
   set proxyconf(http) {proxy2}

   which will instruct _Tkabber_ to use these proxies for all
   connections.  If you need more complicated setup with several proxy
   profiles, read section 'The proxy module' (Section 7.2.15) below.


























Shchepin, et al.                                               [Page 13]

                               Tkabber 1.1                 February 2014


5.  Upgrading from version 0.10.0

   When upgrading _Tkabber_ from version 0.10.0 or earlier read the
   above section on plugins (Section 4.1) and also note that several
   configuration options and user interface elements have been changed.

5.1.  Configuration options

   There are notable changes in handling connection through proxy
   servers, managing fonts and balloon colors, and detecting breaks in
   underlying TCP connection to a server.

5.1.1.  Proxy servers

   Since SOCKS4 and SOCKS5 proxy types were implemented in addition to
   HTTP proxy type, the whole set of connection options regarding proxy
   servers has been changed.  This means that after upgrade the old
   values stored using the Customize mechanism will be lost and the same
   values in "loginconf" arrays will not be recognized any longer.

   To learn how to adapt your current proxy settins to the current
   _Tkabber_ version, read section above (Section 4.2), but remember
   that variables in the "loginconf" array mentioned there have been
   changed between 0.10.0 and 0.11.0.  Use the map below as a reference
   which variable should actually be used:

   o  Variable "httpproxy"in 0.10.0 became "proxyhost" in 0.11.0.

   o  Variable "httpport" became "proxyport".

   o  Variable "httplogin" became "proxyusername".

   o  Variable "httppassword" became "proxypassword".

5.1.2.  Resources to control fonts

   Fonts handling has been partially reworked: the global variable
   "font" that controls chat and roster fonts has been removed and now
   _Tkabber_ relies on _Tk_ option database to manage these settings.
   You can override roster and chat fonts independently of each other.
   To do that on systems not based on X Window use _Customize_ options
   described below.

   The main consequence of this change is that now the fonts are taken
   from _Tk_ option database and if it contains sane values you don't
   need to touch anything (until the update you had to tweak the "font"
   variable because it was set to font "fixed" by default).  The
   variable "font" does not have any special meaning starting from



Shchepin, et al.                                               [Page 14]

                               Tkabber 1.1                 February 2014


   0.11.0 release.

   The second consequence is that you are now able to set fonts for chat
   and roster windows separately from each other using this list as a
   reference:

   o  "*font" _Tk_ option database resource sets default font for all
      widgets used in _Tkabber_.

   o  "*Chat*Text.font" _Tk_ option database resource can be used to
      override font used for chat windows.  This resource can be
      overridden by the "::ifacetk::options(font)" option from the "Main
      Interface" group of _Customize_ settings.

   o  "*Roster*font" _Tk_ option database resource can be used to
      override font used for roster windows.  This resource can be
      overridden by the "::ifacetk::options(roster_font)" option from
      the "Main Interface" group of _Customize_ settings.

5.1.3.  Keep-alives and dead link detection

   Keep-alive mechanism that was used to keep NATP devices from
   disconnecting idle XMPP sessions was accompanied in 0.10.0 with "XMPP
   ping" mechanism which also implemented dead link detection with
   support for disconnecting upon detection of network outage.

   In version 0.11.0, the old keep-alive mechanism has been dropped, so
   the following two global options have no effect now:

   o  "keep_alive"

   o  "keep_alive_interval"

   In order to get the same functionality, enable XMPP ping using these
   options in the "IQ" group of Customize settings:

   o  Enabling "::plugins::ping::options(ping)" will make _Tkabber_
      periodically send xmpp:ping IQ request to the server.

   o  Set "::plugins::ping::options(timeout)" option to a number of
      seconds _Tkabber_ should wait for either a xmpp:ping reply or an
      error to arrive from the server; if there is no answer from the
      server during this timeout, the socket for this connection will be
      forcibly disconnected.







Shchepin, et al.                                               [Page 15]

                               Tkabber 1.1                 February 2014


5.1.4.  Resources to control appearance of balloon windows

   Resources controlling the appearance of balloon windows have been
   made more generic.  If you use custom _Tk_ option database settings
   for balloon windows, change the relevant resources using this map:

   o  Change references to "*Balloon.background" and
      "*Balloon.foreground" resources to "*Balloon*background" and
      "*Balloon*foreground", respectively.

   o  Change references to "*Balloon*padX" and "*Balloon*padY" resources
      to "*Balloon.text.padX" and "*Balloon.text.padY", respectively.

5.1.5.  Support for external XML parser

   Support for _TclXML_ as an external XML parser has been removed
   (since _TclXML_ has anyway been unable to support partial XML
   processing) along with the global variable "use_external_tclxml"
   which controlled the loading of _TclXML_.

   Now expat-based _Tcl_ package _tDOM_ is supported as an external XML
   parser.  It is enabled by default if it is installed.

5.2.  User interface

   There are notable changes in systray mouse gestures, appearance of a
   main tabbed window, and in behavior of paned window splitters.

5.2.1.  System tray icon mouse gestures

   Mouse gestures bound to system tray (system notification area) icon
   have been reworked:

   o  Single click on it with the left mouse button now unconditionally
      brings the main _Tkabber_ window to front, possibly deiconifying
      it first.

   o  Single click with the middle mouse button now unconditionally
      iconifies the main _Tkabber_ window.

   This differs from the previois behaviour where single click with the
   left mouse button on _Tkabber_'s system tray icon toggled the
   iconified/visible state of the main _Tkabber_ window.

5.2.2.  New tab management widget

   The _notebook_ widget which was used to render tabs in tabbed
   interface mode has been replaced with a new custom widget providing



Shchepin, et al.                                               [Page 16]

                               Tkabber 1.1                 February 2014


   the ability for multi-row placement of tabs and docking them to the
   left or right sides of the chat window (in addition to top or bottom
   docking available in 0.10.0 version and earlier).

   If you adjusted any specific _Tk_ option database resources
   pertaining to that _notebook_ widget, you have to change them keeping
   in mind that the new widget is just a bunch of _Tk_ buttons (class
   "Button") placed in a frame (called ".nb" as before).  The class name
   for the new widget is "ButtonBar".

   So if you explicitly set, say "*Notebook*font" option, you have to
   change it to "*ButtonBar*font" and so on.

5.2.3.  Window splitters

   Window splitters (thin vertical and horizontal windows used to change
   relative sizes of windows between which a splitter is placed) have
   been changed to "Windows" style.  This differs from previous "Motif"
   style which implemented explicit "grip box" on each splitter which
   was the only "active point" of a splitter.































Shchepin, et al.                                               [Page 17]

                               Tkabber 1.1                 February 2014


6.  Upgrading from version 0.9.9

   When upgrading _Tkabber_ from version 0.9.9 or earlier read the above
   section (Section 5) and also note the following:

   o  On Macintosh or Microsoft Windows _Tkabber_ will copy it's
      configuration directory to a new location (see the next section
      (Section 7) for details).  If the transfer of the config directory
      goes smoothly you may delete old ""~/.tkabber"" directory and
      replace its name in your config file by "$::configdir".

   o  Also, _Tkabber_ will convert chatlogs directory to a new format.

   o  Also, _Tkabber_ changed the way it works with emoticons.  Instead
      of loading them in config file you may put you faivorite emoticons
      directory into "$::configdir/plugins" directory, restart Tkabber
      and then choose emoticons set using Customize GUI.


































Shchepin, et al.                                               [Page 18]

                               Tkabber 1.1                 February 2014


7.  Configuration

   _Tkabber_ maintains its configuration using a set of files placed in
   a special configuration directory which location depends on the
   operating system _Tkabber_ runs on.  These locations are:

   o  Unix systems: ""~/.tkabber"";

   o  Macintosh: ""~/Library/Application Support/Tkabber"";

   o  Under Microsoft Windows this location is governed by the policy of
      the particular flavor of this OS, but the general rule is that the
      _Tkabber_ configuration directory is named ""Tkabber"" and is
      located in the special system folder for storing application-
      specific data.  For example, under Windows XP this will be
      something like ""C:\Documents and Settings\USERNAME\Application
      Data\Tkabber"", where ""USERNAME"" is the login name of a
      particular operating system's user.

   _Tkabber_ also honors the value of the ""TKABBER_HOME"" environment
   variable -- if it exists the whole OS-based guessing of the
   configuration directory location is cancelled and the value of this
   environment variable is used instead.

   Once the pathname of the _Tkabber_ configuration directory is known,
   its value is assigned to the ""configdir"" global Tcl variable which
   can be accessed from within the main _Tkabber_ configuration file
   (see below).

   One of the first things that _Tkabber_ does when it's starting up is
   reading a file located in its configuration directory under the name
   ""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;





Shchepin, et al.                                               [Page 19]

                               Tkabber 1.1                 February 2014


   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.









































Shchepin, et al.                                               [Page 20]

                               Tkabber 1.1                 February 2014


7.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

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


   # cryptography by default

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


   # debugging output

   set debug_lvls {xmpp warning}


   # splash window

   set show_splash_window 0


   # force english labels instead of native language

   ::msgcat::mclocale en

   # use mozilla firefox to open web urls in text

   set webbrowser "firefox -new-tab %s"









Shchepin, et al.                                               [Page 21]

                               Tkabber 1.1                 February 2014


7.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
   the beginning of your configuration file, or using graphical
   interface save the option and restart _Tkabber_.

7.1.2.  Fonts and colors

   Many aspects of the _Tkabber_'s visual appearance such as fonts,
   colors and geometry of windows can be configured using the Tk option
   database. [23]

   The corresponding _Tk_'s option [24] command can be used in the
   _Tkabber_'s configuration file in any acceptable way: from small
   tweaks to reading files containing elaborate sets of configuration
   commands; ready-to-use examples of such files are included in the
   distribution and are located under the "examples/xrdb" directory.

   The _Tk_ toolkit is able to initialize its option database from the
   _XRDB_ (X Resource Database) if its availability is detected at run
   time.  This means that any settings described here can be tuned via
   the standard XRDB mechanism (see "man xrdb").

   Beware though that the _Tk_'s semantics of matching option
   specifications against the option database differ in some subtle
   details from that of the _Xt_ toolkit.  The most notable one is the
   priority of options: _Tk_ prefers the latest option it sees, while
   _Xt_ prefers "the most specific" one.

   When specifying _Tkabber_-specific options in your _XRDB_ file use
   the "Tkabber" class as the root element of the options.

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








Shchepin, et al.                                               [Page 22]

                               Tkabber 1.1                 February 2014


   Probably the most commonly used way to configure _Tkabber_'s visual
   appearance (especially on Windows platforms which lack _XRDB_
   mechanism) is to put all the necessary settings in some file and then
   ask _Tk_ to update its option database from it, like this:

       set load_default_xrdb 0
       option readfile $::configdir/newlook.xrdb userDefault

   The first line tells _Tkabber_ not to load its default "xrdb" file,
   whilst the second line tells _Tkabber_ which file to load instead.
   Look at the provided example "xrdb" files to get the idea about how
   they are organised.  Of course, you can use any of that files as a
   template.  And of course, you can simply specify any of the example
   files instead of your own to the "option readfile" command to get the
   provided "theme".

   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.  Read more about this
   in "man palette".

   You can also customize the fonts _Tkabber_ uses to render its user
   interface:

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

   The above setting (operating on the Tk option database) selects the
   font used for all UI elements like buttons and labels and roster and
   conversation windows.  Obviously, you should choose fonts that suit
   your taste.

   If you want to specify another font for roster labels use the
   following option:

       option add *Roster*font \
              "-misc-fixed-medium-r-normal-*-12-*-*-*-*-*-iso10646-1" \
              userDefault

   When picking fonts, observe these rules:

   o  Under X, encoding (charset) of fonts must match that of your
      locale.




Shchepin, et al.                                               [Page 23]

                               Tkabber 1.1                 February 2014


   o  Ensure that the specified font exists, since if it's not, _Tk_
      will try hard to pick the most suitable one which often yields not
      what you want.  (The best bet is to first pick the font using some
      tool like "xfontsel".)

   Note that when specifying settings using the _Tkabber_'s
   configuration files (i.e. not using _XRDB_ directly) you are not
   forced to use "X-style" (XLFD) font descriptions and may instead
   specify fonts using sometimes more convenient _Tk_ features described
   in Tk font manual page.

7.1.3.  Cryptography by default

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

   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.)

7.1.4.  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} {
   #    ...
   }

   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



Shchepin, et al.                                               [Page 24]

                               Tkabber 1.1                 February 2014


   configuration file:

   set debug_lvls {}

7.1.5.  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

7.1.6.  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

7.1.7.  Browse URL

   _Tkabber_ executes a browser when you click on a URL in chat windows,
   or in user info window, or in headlines window etc.  It uses some
   heuristics to find which browsers are installed in the system and
   invokes the first browser it finds.

   If _Tkabber_'s decision on which browser to use is suboptimal to you,
   or if you want to add some options to the browser command line (open
   URL in a new tab, or in a new window etc.) you may set the varable
   "webbrowser" like the following:

   set webbrowser "firefox -new-tab %s"

   Note, that the "%s" in the string (it doesn't have to be at the end)
   will be replaced by an actual URL when the command will be run.
   Also, if your favorite browser's path contains spaces, enclose it in
   braces.

   The following figures shows some examples of setting this variable







Shchepin, et al.                                               [Page 25]

                               Tkabber 1.1                 February 2014


   for Windows:

   set webbrowser "{C:/Program Files/Opera/opera.exe} %s"

   set webbrowser \
       "{C:/Program Files/Mozilla Firefox/firefox.exe} -new-window %s"

   set webbrowser "{C:/Program Files/Internet Explorer/iexplore.exe} %s"

   for Unix:

   set webbrowser "iceweasel -new-tab %s"

   set webbrowser "chromium-browser %s"

7.1.8.  Searching

   _Tkabber_ allows the user to perform textual searching in certain
   classes of its windows.  This searching is controlled by several
   settings which can be specified in this section.

   These settings are described in detail in Section 9.1.

7.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.,

 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 ifacetk::options(raise_new_tab) 1




Shchepin, et al.                                               [Page 26]

                               Tkabber 1.1                 February 2014


 # tray icon

     set ::plugins::tktray::options(enable) 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(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


 # the cryptographic module

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


 # the emoticon module

     set plugins::emoticons::options(theme) \
                 $::configdir/emoticons/rythmbox





Shchepin, et al.                                               [Page 27]

                               Tkabber 1.1                 February 2014


 # 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(enable)              1
     set plugins::ispell::options(executable)          /usr/bin/ispell
     set plugins::ispell::options(command_line)        -C -d 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 logger module

     set logger::options(logdir)        [file join $::configdir logs]
     set logger::options(log_chat)      1
     set logger::options(log_groupchat) 1

 # the proxy module

     global proxy1 proxy2 proxy3 proxyconf1 proxyconf2 proxyconf

     set proxy1(type)     https
     set proxy1(host)     proxy.example.com
     set proxy1(port)     3128
     set proxy1(username) ""
     set proxy1(password) ""
     set proxy1(match)    *
     set proxy1(exclude)  "localhost* 127.0.0.* 172.* 192.168.* 10.*"

     set proxy2(type)     http



Shchepin, et al.                                               [Page 28]

                               Tkabber 1.1                 February 2014


     set proxy2(host)     proxy.example.com
     set proxy2(port)     3128
     set proxy2(username) ""
     set proxy2(password) ""
     set proxy2(match)    *
     set proxy2(exclude)  "localhost* 127.0.0.* 172.* 192.168.* 10.*"

     set proxy3(type)     socks5
     set proxy3(host)     proxy.example.com
     set proxy3(port)     1080
     set proxy3(username) ""
     set proxy3(password) ""
     set proxy3(match)    *
     set proxy3(exclude)  "localhost* 127.0.0.* 172.* 192.168.* 10.*"

     set proxyconf1(profile) Home
     set proxyconf1(tunnel)  {}
     set proxyconf1(http)    {}

     set proxyconf2(profile) Work
     set proxyconf2(tunnel)  {proxy1 proxy3}
     set proxyconf2(http)    {proxy2}

     array set proxyconf [array get proxyconf2]

 # 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(usesasl)        1
     set loginconf(allowauthplain) 0

     # 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



Shchepin, et al.                                               [Page 29]

                               Tkabber 1.1                 February 2014


     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


 # 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) ""
 }



Shchepin, et al.                                               [Page 30]

                               Tkabber 1.1                 February 2014


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

7.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 "$::configdir/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 _XEP-0038_ and go to
   where you installed _Tkabber_ and take a look at the directory called
   ""pixmaps/default/"".

   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 new tab is created, it is automatically
   raised.  If you don't like this behavior, add this line:
   set ifacetk::options(raise_new_tab) 0

7.2.2.  The system tray icon (for Unix)

   This module is presently available only for Unix

   To enable the system tray icon you have to install _tktray_ extension
   and set the config variable "plugins::tktray::options(enable)" to 1.




Shchepin, et al.                                               [Page 31]

                               Tkabber 1.1                 February 2014


   If you want to control the tray icon appearance and/or position,
   consult the documentation for your desktop environment or window
   manager.  Note, that the Tkabber's tray icon has WM class
   _TkabberIcon_.

7.2.3.  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.

7.2.4.  The Avatar Module

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

   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.

7.2.5.  The Chat Module

   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]}




Shchepin, et al.                                               [Page 32]

                               Tkabber 1.1                 February 2014


7.2.6.  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

7.2.7.  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
   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.

7.2.8.  The Cryptographic Module

   Earlier (Section 7.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

7.2.9.  The Emoticons Module

   The procedure called _plugins::emoticons::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/default/icondef.xml"" or read XEP-0038 [25].)






Shchepin, et al.                                               [Page 33]

                               Tkabber 1.1                 February 2014


   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
   "plugins::emoticons::add", e.g.,

       plugins::emoticons::add ":beer:" \
           [image create photo -file $::configdir/emoticons/beer.gif]

   If you want to disable all emoticons, you can simply load empty
   directory.  Put in postload function

       plugins::emoticons::load_dir ""

7.2.10.  The File Transfer Module

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

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

7.2.11.  The Groupchat Module

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

   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.




Shchepin, et al.                                               [Page 34]

                               Tkabber 1.1                 February 2014


7.2.12.  The Ispell Module

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

   set plugins::ispell::options(enable) 1

   If you enabled this module, then you can also define:

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

   o  the _ispell_ command line options by setting
      "plugins::ispell::options(command_line)"; 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.)

7.2.13.  The Stream Initiation Module

   Stream initiation profile is defined in _XEP-0095_ with two
   transports (_XEP-0047_ - IBB, _XEP-0065_ - SOCKS5 bytestreams).  With
   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








Shchepin, et al.                                               [Page 35]

                               Tkabber 1.1                 February 2014


7.2.14.  The Logger Module

   You can set directory to store logs:

       set logger::options(logdir) [file join $::configdir 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

7.2.15.  The Proxy Module

   Starting from version 1.0 _Tkabber_ does not keep proxy settings in
   the "loginconf" array.  It uses proxy profiles defined in separate
   arrays.

   First, you may want to specify a set of proxy servers.  You can have
   multiple proxy servers defined in the config file (to use in
   different environments, or if in your company different proxies are
   used to connect to different hosts).  To do so, define global arrays
   (their names could be arbitrary, but "proxy<number>" looks natural):

       set proxy1(type)     https
       set proxy1(host)     proxy.example.com
       set proxy1(port)     3128
       set proxy1(username) ""
       set proxy1(password) ""
       set proxy1(match)    *
       set proxy1(exclude)  "localhost* 127.0.0.* 172.* 192.168.* 10.*"

       set proxy2(type)     http
       set proxy2(host)     proxy.example.com
       set proxy2(port)     3128
       set proxy2(username) ""
       set proxy2(password) ""
       set proxy2(match)    *
       set proxy2(exclude)  "localhost* 127.0.0.* 172.* 192.168.* 10.*"

       set proxy3(type)     socks5
       set proxy3(host)     proxy.example.com
       set proxy3(port)     1080
       set proxy3(username) ""
       set proxy3(password) ""
       set proxy3(match)    *
       set proxy3(exclude)  "localhost* 127.0.0.* 172.* 192.168.* 10.*"




Shchepin, et al.                                               [Page 36]

                               Tkabber 1.1                 February 2014


   Field "type" is one of the following: _"socks4"_, _"socks5"_,
   _"https"_, _"http"_.  The firat three types are tunnelling proxies.
   If you enable them, _Tkabber_ will use them to tunnel its TCP
   connections (in case of _"https"_ this means using _CONNECT_ method
   for HTTP proxy).  The other one is used when _Tkabber_ needs to fetch
   some data via _GET_ or _POST_ method of the HTTP protocol (e.g., when
   utilizing BOSH or HTTP-poll connection).

   Fields "host", "port", "username" and "password" are selfexplanatory.

   There are two fields which need some explanation: "match" and
   "exclude".  When Tkabber needs to connect to a certain _host_ or to
   get an HTTP document it searches proxies in order they appear in the
   corresponding proxyconf list (see below) and uses the first proxy for
   which the _host_ matches one of the patterns from the "match" field
   but doesn't match any of the patterns from the "exclude" field.  The
   matching uses patterns convention from the "string match" _Tcl_
   command.

   Second, you may want to define proxy profiles, and switch between
   them when the environment changes (it's useful for portable
   computers).  To do so, you may define global arrays named
   "proxyconf<number>" where numbers must start from 1 and be
   consecutive, otherwise _Tkabber_ GUI wouldn't be able to switch to
   them:

       set proxyconf1(profile) Home
       set proxyconf1(tunnel)  {}
       set proxyconf1(http)    {}

       set proxyconf2(profile) Work
       set proxyconf2(tunnel)  {proxy1 proxy3}
       set proxyconf2(http)    {proxy2}

       array set proxyconf [array get proxyconf2]

   Here, two proxy profiles are defined.  The first one instructs
   _Tkabber_ not to use any proxies and directly connect to any host.
   The second one defines two tunnel proxies and one HTTP proxy.  Note
   that HTTPS and HTTP proxy are the same, but they should appear in
   both "tunnel" and "http" fields anyway.  The last line chooses the
   default proxy profile, which is _Work_ in the example above.

   Also, you can edit proxy settings using _Tkabber_ GUI under
   _Tkabber->Manage proxy servers_ menu item.






Shchepin, et al.                                               [Page 37]

                               Tkabber 1.1                 February 2014


7.2.16.  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.

   Elements "loginconf(user)" and "loginconf(password)"specify username
   and password to authenticate at your _Jabber_ server.

   Element "loginconf(server)" must be set to _Jabber_ server name (the
   part of you _JID_ after "@".

   Element "loginconf(stream_options)" is set to one of the following
   values:

   o  plaintext -- use plaintext connection;

   o  encrypted -- use encrypted (via STARTTLS mechanism) connection
      (this option requires tls extension to be installed);

   o  ssl -- use encrypted (via legacy SSL mechanism) connection (this
      option requires tls extension to be installed);

   o  compressed -- use compressed connection (this option requires Ztcl
      extension to be installed).

   _Tkabber_ tries to resolve _Jabber_ server name using _SRV_ first and
   usual _A_ records in _DNS_.  If the resolution fails (for example if
   you are in LAN environment without _DNS_) you can force _Tkabber_ to
   connect to the server using "loginconf(altserver)" and
   "loginconf(altport)" options (do not forget to set
   "loginconf(usealtserver)" to "1").

   Another option is to use _BOSH_ (XEP-0124 and XEP-0206) connect
   method (if your server supports it) and tunnel _XMPP_ traffic through
   _HTTP_.  To enable _BOSH_ set "loginconf(usebosh)" to "1". _Tkabber_
   then tries to find connect _URL_ using _TXT_ record in _DNS_ (see
   XEP-0156).  You can specify _URL_ manually by setting
   "loginconf(boshurl)".

   And another option is to use _HTTP_-polling connect method (if your
   server supports it) and tunnel _XMPP_ traffic through _HTTP_.  To
   enable _HTTP_-polling set "loginconf(usehttppoll)" to "1". _Tkabber_
   then tries to find connect _URL_ using _TXT_ record in _DNS_ (see
   XEP-0156).  You can specify _URL_ manually by setting
   "loginconf(pollurl)".

   This collection of elements, which is termed a login profile, is what



Shchepin, et al.                                               [Page 38]

                               Tkabber 1.1                 February 2014


   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.

7.2.17.  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".

7.2.18.  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.

7.2.19.  The Roster Module

   By default, your entire roster is shown, even those items that aren't
   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



Shchepin, et al.                                               [Page 39]

                               Tkabber 1.1                 February 2014


   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".

7.2.20.  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

   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:





Shchepin, et al.                                               [Page 40]

                               Tkabber 1.1                 February 2014


   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) ""

7.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
   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..,




Shchepin, et al.                                               [Page 41]

                               Tkabber 1.1                 February 2014


   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.

7.3.1.  The Avatar Module

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

7.3.2.  The Browser Module

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

7.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.

7.3.4.  The Login Module

   The procedure called "show_login_dialog" displays a dialog window
   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.






Shchepin, et al.                                               [Page 42]

                               Tkabber 1.1                 February 2014


7.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.

7.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,

   o  invisible.

   The second variable takes any textual value.





Shchepin, et al.                                               [Page 43]

                               Tkabber 1.1                 February 2014


   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

7.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.

7.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 44]

                               Tkabber 1.1                 February 2014


8.  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 45]

                               Tkabber 1.1                 February 2014


   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 ...::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.

8.1.  Message Hooks

   When _Tkabber_ receives a message stanza it calls two hooks:

   rewrite_message_hook \
       xlib from id type is_subject subject body err thread priority x
   process_message_hook \
       $xlib $from $id $type $is_subject $subject $body $err $thread \
       $priority $x




Shchepin, et al.                                               [Page 46]

                               Tkabber 1.1                 February 2014


   The first hook takes eleven variable names as arguments, so the
   calling procedures can rewrite them.  This means that a procedure in
   this hook should call "upvar 2 $varbody body" and use the "body"
   variable to change the actual message body.  For example, this allows
   _Tkabber_ to put decrypted message into the "body" variable if it is
   encrypted.

   The second hook does the job of showing message to the user (or doing
   something else with it if it's a special message like part of an in-
   band file transfer.

8.2.  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
   "chat::get_jid" and connection token using "chat::get_xlib"
   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.

   When you are aboutn to send a chat or normal message to the wire, a
   hook is run:

 rewrite_outgoing_message_hook xlib to id type subject body err thread x

   The first hook takes nine variable names as arguments, so the calling
   procedures can rewrite them.  This means that a procedure in this



Shchepin, et al.                                               [Page 47]

                               Tkabber 1.1                 February 2014


   hook should call "upvar 2 $varbody body" and use the "body" variable
   to change the actual message body.  For example, this allows
   _Tkabber_ to encrypt message and put the encrypted message into the
   "body" variable to send.  This hook is introduced in _Tkabber_ 1.1,
   and is used by the OTR plugin, so the latter will not work in
   _Tkabber_ 1.0 and older.

   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 are used to add items in
   menu:

   chat_create_user_menu_hook $path $xlib $jid
   chat_create_conference_menu_hook $path $xlib $jid

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

   In groupchat windows it is possible to complete participants' 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 current list of possible
   completions is stored; index of position where completion must be
   inserted; and content of text widget where completion is requested.

   When someone enters/exits conference, the following hooks are called:

   chat_user_enter $group $nick
   chat_user_exit  $group $nick

   The hooks are given two parameters: chatid of conference and nick of
   participant.








Shchepin, et al.                                               [Page 48]

                               Tkabber 1.1                 February 2014


   When someone changes his/her nickname in a conference room, the
   following hook is called:

   room_nickname_changed_hook $chatid $nick $new_nick

   The hook is given three parameters: chatid of conference old nickname
   and the new nickname of participant.

8.3.  Login Hooks

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

   connected_hook $xlib

   disconnected_hook $xlib

   Both hooks are given one parameter: connection token (_Tkabber_
   allows several connections at once).

8.4.  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 49]

                               Tkabber 1.1                 February 2014


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

   client_presence_hook $xlib $from $type $x $args

   The hook is given four parameters: connection token, 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").

8.5.  Info/Query Hook

   When an IQ stanza is received, a hook is run:

   client_iq_hook $xlib $from $type $queries $args

   The hook is given four compulsory parameters: connection token, who
   sent this query/response type of stanza (e.g., "get", "set", "result"
   or "error"), list of query subelements (usually it contains only one
   element), list of optional arguments (e.g., "-lang language -to jid
   -id id -x $list_of_other_attributes").

8.6.  Roster Hooks

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

   roster_conference_popup_menu_hook $path $xlib $jid

   roster_service_popup_menu_hook $path $xlib $jid

   roster_jid_popup_menu_hook $path $xlib $jid

   roster_group_popup_menu_hook $path $xlib $name

   When run, each hook is given three parameters: the path of the _Tk_
   menu widget; the connection token; and, a JID of the roster item (or
   the name of the roster group for the last one).

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

   roster_create_groupchat_user_menu_hook $path $xlib $jid

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






Shchepin, et al.                                               [Page 50]

                               Tkabber 1.1                 February 2014


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

   roster_user_popup_info_hook $varname $xlib $jid

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

8.7.  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 has
   been loaded and before initializing main _Tkabber_ window.  After
   that "finload_hook" is run.  The final hook is called just before
   _Tkabber_ terminates (cf., Section 7.3.7).

   You can add custom pages to userinfo window using

   userinfo_hook $path $xlib $jid $editable

   It is run with four arguments: the userinfo notebook widget name; the
   connection token; the JID of the user; and a boolean parameter which
   indicates whether the form is editable.



















Shchepin, et al.                                               [Page 51]

                               Tkabber 1.1                 February 2014


9.  User Interface basics

9.1.  Searching

   Search panel may be invoked in certain classes of _Tkabber_ windows
   using the "<<OpenSearchPanel>>" Tk virtual event which is bound by
   default to the "<Control-S>" keyboard command.

   Search panel can be dismissed by pressing the "<Escape>" key and the
   default search action ("search down") is activated by pressing the
   "<Return>" key while entering the search pattern.

   Search panel is currenlty available in:

   o  Chat and groupchat windows;

   o  Service discovery window;

   o  Chat history logs;

   o  All windows of the "Chats history" tool.

   o  Headlines window.

   o  Raw XML log window.

   o  MUC affiliations and roles lists.

   Searching may be customized using the settings located under the
   _Plugins --> Search_ group of the _Customize_ window.  These setings
   are:

   o  "::plugins::search::options(case)": perform case-sensitive
      searching (_off_ by default);

   o  "::plugins::search::options(mode)": selects searching mode which
      can be one of:

      *  _substring_ -- use simple substring search: the typed search
         string is taken verbatim and then the attempt to locate it is
         performed.  This is the default mode.

      *  _glob_ -- uses "glob-style" (or "shell-style") matching:
         special symbols are recognized and they provide for
         "wildcarding":

         +  _*_ matches zero or more characters;




Shchepin, et al.                                               [Page 52]

                               Tkabber 1.1                 February 2014


         +  _?_ matches exactly one character;

         +  _[_ and _]_ define character classes, e.g., "[A-Z]" will
            match any character in the series "A", "B", ...  "Z".

         The full syntax is described in Tcl string manual page.  That
         is, this search mode can be convenient for those who want more
         general yet simple approach to searching and is familiar with
         the "shell globbing" concept found in Unix shells.

      *  _regexp_ -- provides for searching using full-blown regular
         expressions engine.  The full syntax is described in Tcl
         re_syntax manual page [26].






































Shchepin, et al.                                               [Page 53]

                               Tkabber 1.1                 February 2014


URIs

   [1]   <http://tkabber.jabber.ru/>

   [2]   <http://www.jabber.org/>

   [3]   <https://otr.cypherpunks.ca/>

   [4]   <http://sourceforge.net/project/showfiles.php?group_id=10894>

   [5]   <http://sourceforge.net/project/showfiles.php?group_id=12883>

   [6]   <http://www.activestate.com/Products/ActiveTcl>

   [7]   <http://sourceforge.net/project/showfiles.php?group_id=13248>

   [8]   <http://www.openssl.org/source/>

   [9]   <http://sourceforge.net/projects/tkimg/>

   [10]  <http://www.tdom.org/>

   [11]  <https://gna.org/projects/ztcl/>

   [12]  <http://sgolovan.nes.ru/jabber/ztcl/>

   [13]  <http://code.google.com/p/tclgpg/>

   [14]  <http://www.gnupg.org/download.html>

   [15]  <http://memchan.sourceforge.net/>

   [16]  <http://www.speech.kth.se/snack/download.html>

   [17]  <http://beepcore-tcl.sourceforge.net/tkXwin-1.0.tgz>

   [18]  <http://sgolovan.nes.ru/jabber/tclWinidle/>

   [19]  <http://sw4me.com/wiki/Tktray>

   [20]  <http://sourceforge.net/projects/tktable/>

   [21]  <http://tkcon.sourceforge.net>

   [22]  <http://www.xmpp.org/extensions/xep-0081.html>

   [23]  <http://wiki.tcl.tk/1727>




Shchepin, et al.                                               [Page 54]

                               Tkabber 1.1                 February 2014


   [24]  <http://www.tcl.tk/man/tcl8.4/TkCmd/option.htm>

   [25]  <http://www.xmpp.org/extensions/xep-0038.html>

   [26]  <http://www.tcl.tk/man/tcl8.4/TclCmd/re_syntax.htm>














































Shchepin, et al.                                               [Page 55]

                               Tkabber 1.1                 February 2014


Appendix A.  Releases History

A.1.  Main changes in 1.1

   o  Added new OTR plugin (requires Tcl/Tk 8.5 to operate)

   o  Roster versioning (XEP-0237 and RFC-6121)

   o  Added new Battleship game plugin

   o  A few fixes and enhancements

A.2.  Main changes in 1.0

   o  Completely rewritten Tkabber internals

   o  Dropped Tcl/Tk 8.3 support.  Now Tcl/Tk 8.4 is required

   o  Partial IPv6 support (requires Tcl/Tk 8.6)

   o  Switched from TclGPGME to TclGPG for encryption and signing

   o  Added new connection method BOSH (XEP-0124 and XEP-0206)

   o  Disabled SSLv2 and enabled TLSv1 TLS options

   o  Added user nicknames (XEP-0172) support.

   o  Updated the CAPTCHA forms (XEP-0158) support

   o  Added metacontacts (XEP-0209) support

   o  Implemented multiple proxy profiles

   o  Implemented remote controlling from a locally executed script

   o  Added new plugins: floatingcontact, poker

   o  Rewritten most plugins to support disabling and unloading on the
      fly

   o  A few interface enhancements (search in MUC affiliations lists,
      proxy management)

   o  Many fixes and enhancements






Shchepin, et al.                                               [Page 56]

                               Tkabber 1.1                 February 2014


A.3.  Main changes in 0.11.1

   o  New default sound theme by Serge Yudin

   o  Added new plugins: quotelastmsg, singularity, stripes

   o  Many fixes and enhancements

A.4.  Main changes in 0.11.0

   o  New tabbed user interface.  Tab headers now occupy several rows
      and tab bar can be docked to the left and right sides of chat
      window

   o  Roster filter

   o  Added support for pixmaps (in particular emoticons) JISP archives
      (XEP-0038)

   o  Added support for SOCKS4a and SOCKS5 proxy for the main connection

   o  Added user location support (XEP-0080)

   o  Added user mood support (XEP-0107)

   o  Added user activity support (XEP-0108)

   o  Added user tune support (XEP-0118)

   o  Added entity capabilities (XEP-0115 v.1.5, only reporting) support

   o  Added basic robot challenges support (XEP-0158, v.0.9)

   o  Added partial data forms media element support (XEP-0221, v.0.2,
      URIs and images only)

   o  Roster is now exported to XML instead of Tcl list

   o  Added support for entity time (XEP-0202)

   o  Tkabber version is now reported in disco#info (XEP-0232)

   o  Moved deprecated Jabber Browser (XEP-0011) to an external plugin

   o  Moved Jidlink file transfer to an external plugin

   o  Added several new plugins: attline, ctcomp, custom-urls,
      floatinglog, gmail, openurl, presencecmd, receipts



Shchepin, et al.                                               [Page 57]

                               Tkabber 1.1                 February 2014


   o  Many fixes and enhancements

A.5.  Main changes in 0.10.0

   o  New artwork by Artem Bannikov

   o  Mediated SOCKS5 connection support for file transfer (XEP-0065)

   o  Blocking communicaation with users not in roster (using XEP-0016
      via simple interface)

   o  Translatable outgoing error messages support (based on recipient's
      xml:lang)

   o  Remote controlling clients support (XEP-0146)

   o  Extended stanza addressing support (XEP-0033)

   o  New chats history tool with search over the all chatlog files

   o  Roster item icons are chosen based on Disco queries to item server

   o  Search in Disco, Browser, Headlines, RawXML, and Customize windows

   o  New internal plugins: abbrev allows to abbreviate words in chat
      input windows, postpone stores/restores current input window
      content

   o  New external plugins (aniemoticons, latex, tkabber-khim, traffic,
      renju)

   o  Emoticons theme now can be loaded using GUI

   o  Most Tkabber's tabs can now be stored on exit and restored on
      start

   o  XMPP ping support (XEP-0199).  Reconnecting based on XMPP ping
      replies

   o  Delayed delivery now recognizes XEP-0203 timestamps

   o  Added optional 'My Resources' roster group, which contains other
      connected resources of the same JID

   o  Many fixes and enhancements






Shchepin, et al.                                               [Page 58]

                               Tkabber 1.1                 February 2014


A.6.  Main changes in 0.9.9

   o  Improved privacy lists interface

   o  Support for stream compression (XEP-0138)

   o  Support for SRV DNS-records

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

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

   o  Improved headlines support

   o  Chat state notification support (XEP-0085)

   o  Many fixes and enhancements

A.7.  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 (XEP-0145)

   o  Support for conference rooms bookmarks (XEP-0048)

   o  Added multilogin support for GPGME

   o  Better support for xml:lang

   o  Support for service discovery extensions (XEP-0128)

   o  Support for NTLM authentication

   o  Many fixes and enhancements

A.8.  Main changes in 0.9.7beta

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

   o  Support for colored nicks and messages in conference





Shchepin, et al.                                               [Page 59]

                               Tkabber 1.1                 February 2014


   o  Better multiple logins support

   o  Updated support for xml:lang

   o  Support for IDNA (RFC3490)

   o  Many fixes and enhancements

A.9.  Main changes in 0.9.6beta

   o  Multiple logins support

   o  History now splitted by month

   o  Animated emoticons support

   o  Many user interface improvements

   o  More XMPP support

   o  More translations

   o  Bugfixes

A.10.  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 60]

                               Tkabber 1.1                 February 2014


Appendix B.  Tk option database resources

   Here is list of the most essential _Tkabber_-specific _Tk option
   database_ 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

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

   *mainRosterWidth  The width of the main roster window.

   *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).

   *JDisco.fill  Color of service discovery browser item name.

   *JDisco.identitycolor  Color of service discovery browser item
      identity.

   *JDisco.featurecolor  Color of service discovery browser entity
      feature.







Shchepin, et al.                                               [Page 61]

                               Tkabber 1.1                 February 2014


   *JDisco*Tree*background  Background of service discovery browser.

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

   *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.






Shchepin, et al.                                               [Page 62]

                               Tkabber 1.1                 February 2014


   *Roster.jidindent  Indentation for item name.

   *Roster.jidmultindent  Indentation for item with multiple resources.

   *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






Shchepin, et al.                                               [Page 63]

                               Tkabber 1.1                 February 2014


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


















































Shchepin, et al.                                               [Page 64]

                               Tkabber 1.1                 February 2014


Appendix C.  Documentation TODO

   The next revision of this documentation should discuss:

   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 65]

                               Tkabber 1.1                 February 2014


Appendix D.  Acknowledgements

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

   The "new look" appeared in the 0.10.0 release ("golden feather" and
   "blue feather" pixmap themes and the "Earth bulb" logo) was designed
   by Artem Bannikov.

   The new sound theme appeared in 0.11.1 release was created by Serge
   Yudin








































Shchepin, et al.                                               [Page 66]

                               Tkabber 1.1                 February 2014


Appendix E.  Copyrights

   Copyright (C) 2002-2014 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 67]

                               Tkabber 1.1                 February 2014


Authors' Addresses

   Alexey Yurievich Shchepin
   Process-One

   Email: alexey@process-one.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 Golovan
   New Economic School

   Email: sgolovan@nes.ru


   Michail Yurievich Litvak
   Colocall Ltd.

   Email: mci@shadow.in.ua


   Konstantin Khomoutov
   Service 007

   Email: khomoutov@gmail.com
















Shchepin, et al.                                               [Page 68]

