

                                                             A. Shchepin
                                        Innovation Center of Information
                                                   Technologies (Sevcom)
                                                                 M. Rose
                                            Dover Beach Consulting, Inc.
                                                              S. Golovan
                                                     New Economic School
                                                               M. Litvak
                                                  Information Centre ISP
                                                       December 15, 2002


                          Tkabber v0.9 (beta)


Abstract

   'Tkabber' is an open source Jabber client, written in 'Tcl/Tk'.  This
   memo describes the installation, configuration, and extension of
   'Tkabber'.
































Shchepin, et al.                                                [Page 1]

                          Tkabber v0.9 (beta)              December 2002


Table of Contents

   1.     SYNOPSIS . . . . . . . . . . . . . . . . . . . . . . . . .   4
   1.1    Getting Started  . . . . . . . . . . . . . . . . . . . . .   5
   1.2    Requirements . . . . . . . . . . . . . . . . . . . . . . .   6
   1.3    Installation . . . . . . . . . . . . . . . . . . . . . . .   8
   1.4    Invocation . . . . . . . . . . . . . . . . . . . . . . . .   8
   2.     Configuration  . . . . . . . . . . . . . . . . . . . . . .   9
   2.1    Pre-load . . . . . . . . . . . . . . . . . . . . . . . . .   9
   2.1.1  Tabbed Interface . . . . . . . . . . . . . . . . . . . . .  10
   2.1.2  Primary Look-and-Feel  . . . . . . . . . . . . . . . . . .  10
   2.1.3  Cryptography by default  . . . . . . . . . . . . . . . . .  11
   2.1.4  Use ispell to check spelling . . . . . . . . . . . . . . .  12
   2.1.5  Debugging Output . . . . . . . . . . . . . . . . . . . . .  12
   2.1.6  Splash window  . . . . . . . . . . . . . . . . . . . . . .  13
   2.1.7  Periodically send empty string to server . . . . . . . . .  13
   2.1.8  I18n/L10n  . . . . . . . . . . . . . . . . . . . . . . . .  13
   2.2    Post-load  . . . . . . . . . . . . . . . . . . . . . . . .  13
   2.2.1  Look-and-Feel  . . . . . . . . . . . . . . . . . . . . . .  16
   2.2.2  The Autoaway Module  . . . . . . . . . . . . . . . . . . .  17
   2.2.3  The Avatar Module  . . . . . . . . . . . . . . . . . . . .  17
   2.2.4  The Chat Module  . . . . . . . . . . . . . . . . . . . . .  17
   2.2.5  The Clientinfo Module  . . . . . . . . . . . . . . . . . .  18
   2.2.6  The Conferenceinfo Module  . . . . . . . . . . . . . . . .  18
   2.2.7  The Cryptographic Module . . . . . . . . . . . . . . . . .  18
   2.2.8  The Emoticons Module . . . . . . . . . . . . . . . . . . .  18
   2.2.9  The Groupchat Module . . . . . . . . . . . . . . . . . . .  19
   2.2.10 The Ispell Module  . . . . . . . . . . . . . . . . . . . .  19
   2.2.11 The Jidlink Module . . . . . . . . . . . . . . . . . . . .  20
   2.2.12 The Login Module . . . . . . . . . . . . . . . . . . . . .  20
   2.2.13 The Message Module . . . . . . . . . . . . . . . . . . . .  21
   2.2.14 The Roster Module  . . . . . . . . . . . . . . . . . . . .  21
   2.2.15 The Sound Module . . . . . . . . . . . . . . . . . . . . .  21
   2.3    Menu-load  . . . . . . . . . . . . . . . . . . . . . . . .  22
   2.3.1  The Avatar Module  . . . . . . . . . . . . . . . . . . . .  22
   2.3.2  The Browser Module . . . . . . . . . . . . . . . . . . . .  23
   2.3.3  The Groupchat Module . . . . . . . . . . . . . . . . . . .  23
   2.3.4  The Login Module . . . . . . . . . . . . . . . . . . . . .  23
   2.3.5  The Message Module . . . . . . . . . . . . . . . . . . . .  23
   2.3.6  The Presence Module  . . . . . . . . . . . . . . . . . . .  23
   2.3.7  Miscellany . . . . . . . . . . . . . . . . . . . . . . . .  24
   2.4    Final-Load . . . . . . . . . . . . . . . . . . . . . . . .  24
   3.     Extensibility  . . . . . . . . . . . . . . . . . . . . . .  25
   3.1    Chat Hooks . . . . . . . . . . . . . . . . . . . . . . . .  26
   3.2    Login Hooks  . . . . . . . . . . . . . . . . . . . . . . .  27
   3.3    Presence Hooks . . . . . . . . . . . . . . . . . . . . . .  27
   3.4    Roster Hooks . . . . . . . . . . . . . . . . . . . . . . .  28
   3.5    Miscellaneous Hooks  . . . . . . . . . . . . . . . . . . .  29



Shchepin, et al.                                                [Page 2]

                          Tkabber v0.9 (beta)              December 2002


          Authors' Addresses . . . . . . . . . . . . . . . . . . . .  30
   A.     XRDB . . . . . . . . . . . . . . . . . . . . . . . . . . .  32
   B.     Documentation TODO . . . . . . . . . . . . . . . . . . . .  35
   C.     Acknowledgements . . . . . . . . . . . . . . . . . . . . .  36
   D.     Copyrights . . . . . . . . . . . . . . . . . . . . . . . .  37














































Shchepin, et al.                                                [Page 3]

                          Tkabber v0.9 (beta)              December 2002


1. SYNOPSIS

       % tkabber.tcl

   Tkabber [1] provides a 'Tcl/Tk' interface to the Jabber [2] instant
   messaging and presence service.

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

   o  it is portable: once you install a 'Tcl/Tk' interpreter on your
      system, the 'Tkabber' script "just runs" -- without having to
      compile anything;

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

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

   Although relatively new software, 'Tkabber' is fully-featured:

   sessions:

      *  hashed passwords

      *  encrypted sessions (if you install an optional extension)

      *  login via HTTP proxy

      *  user-defined hooks for connection establishment and release

   messages:

      *  emoticons

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

      *  file transfers (HTTP, DTCP and IBB transports)

      *  filters

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




Shchepin, et al.                                                [Page 4]

                          Tkabber v0.9 (beta)              December 2002


      *  headline messages

      *  message events

      *  completions of nick and commands

      *  hyperlinks

      *  user-defined hooks for chat window events

   presence:

      *  avatars

      *  browsing

      *  groupchat and roster invitations

      *  signed presence (if you install an optional extension)

      *  vCards

      *  user-defined hooks for presence changes

   windowing:

      *  configurable look-and-feel via a resources database

      *  unicode

      *  tabbed/non-tabbed interface

      *  sound notifications

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

      *  for Windows: auto-away, and taskbar icons


1.1 Getting Started

   For many readers, this documentation is simply overkill.  It tries to
   document everything that you might want to know.  If you want to use
   'Tkabber' just 'cause it's portable, then all you really need to do
   is this:

   1.  Install 'Tck/Tk' and the two mandatory libraries discussed in the



Shchepin, et al.                                                [Page 5]

                          Tkabber v0.9 (beta)              December 2002


       next section (Section 1.2).  The easiest way to do this is to get
       the free ActiveTcl [3] binary release.

   2.  Copy the 'Tkabber' distribution to your system (e.g., somewhere
       in your home directory).

   3.  Put that directory in your search path or make a symlink/shortcut
       to the file "tkabber.tcl" in that directory.

   4.  Invoke it by running/clicking "tkabber.tcl" from the shell or
       your desktop.

   If you'd like to read about the details, the options, and so on, keep
   reading -- otherwise, we're done!

1.2 Requirements

   You should already have installed:

   o  Tcl/Tk version 8.3.3 [4] (or later)

   o  tcllib version 1.2 [5] (or later)

   o  BWidget 1.3 [6] (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 [7] distribution contains all three packages (along
   with the 'Img' package mentioned next); so, you may want to use that
   instead of three separate downloads.

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

   o  'Tcl/Tk' supports only a small number of image formats (i.e.,
      bitmaps, GIFs and portable pixmaps).  If presence information
      contains avatars, these may be in other formats (e.g., PNGs or
      JPGs).

      Accordingly, you may want to install Img version 1.2 [8] (or



Shchepin, et al.                                                [Page 6]

                          Tkabber v0.9 (beta)              December 2002


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

   o  By default, communications between the server and client take
      place over a plaintext connection.  While this may not be a
      problem in some local, wired environments, if your server is
      distant or your client is wireless, then you may want to encrypt
      all the client/server traffic.

      Accordingly, you may to install tls version 1.4.1 [9] (or later).
      This package works on both Unix and Windows.  Note that if you're
      using Unix, then you'll also need to have 'OpenSSL' installed.
      Fortunately, this comes preinstalled on many Unix systems.  If
      it's not on your system, check here [10].  (The Windows
      distribution of 'tls' comes with all the necessary DLLs.)

   o  By default, end-to-end communications between two or more Jabber
      clients is plaintext.  Depending on your environment, this may not
      be a problem for you.  Alternatively, you may want to digitally-
      sign all of your outgoing messages, and allow others to encrypt
      their messages to you.

      Accordingly, you may want to install the 'gpgme' package, which,
      at present, works only on Unix.  Depending on what's already
      installed on your system, you may have to download upto three
      files:

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

      *  GPGME version 0.3.11 [12] (or later); and,

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

   o  If you're running Unix or Windows, then you may want 'Tkabber' to
      automatically mark you as away after a priod of inactivity.

      Accordingly, on Unix, you may want to install Tk Xwin version 1.0
      [14] (or later), whilst on WIndows, you may want to install Tcl
      Winidle version 0.1 [15] (or later).

   o  If you're running 'KDE', then you may want 'Tkabber' to use the
      docking tray.

      Accordingly, you may want to install Tk Theme version 1.20 [16]
      (or later).

   o  If you're running Windows, then you may want 'Tkabber' to use the
      system tray.




Shchepin, et al.                                                [Page 7]

                          Tkabber v0.9 (beta)              December 2002


      Accordingly, you may want to install Winico version 0.3 [17] (or
      later).

   o  If you're a Tcl/Tk guru, then you may want to access the Tk
      console to debug things.

      Accordingly, you may want to install tkcon version 2.3 [18] (or
      later).

   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!

1.3 Installation

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

1.4 Invocation

   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 "Help"
   menu to find the checkbutton to show the console.







Shchepin, et al.                                                [Page 8]

                          Tkabber v0.9 (beta)              December 2002


2. Configuration

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

   'Tkabber' is configured in four stages:

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

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

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

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

   Let's look at each, in turn.

2.1 Pre-load

   There are a few things that 'Tkabber' needs to know immediately.
   These are:

   # tabbed interface

   set usetabbar 1


   # primary look-and-feel

   set pixmaps_theme default

   set load_default_xrdb 1


   # cryptography by default

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




Shchepin, et al.                                                [Page 9]

                          Tkabber v0.9 (beta)              December 2002


   # use ispell to check spelling

   set use_ispell 0


   # debugging output

   set debug_lvls {jlib warning}


   # splash window

   set show_splash_window 0


   # periodically send empty string to server

   set keep_alive           0
   set keep_alive_interval 10


   # force english labels instead of native language

   # ::msgcat::mclocale en


2.1.1 Tabbed Interface

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

   set usetabbar 0

   Although tkabber is tolerant of a lot of configuration changes, the
   only time you're allowed to change "usetabbar" is at the beginning of
   your configuration file.  After that, it must not be changed!

2.1.2 Primary Look-and-Feel

   'Tkabber' is shameless in borrowing icons from other Jabber clients.
   By setting "pixmaps_theme", you can select a family of related icons.
   Besides "default", you can choose one of "gabber", "jajc", "jarl",
   "psi", or "icq".







Shchepin, et al.                                               [Page 10]

                          Tkabber v0.9 (beta)              December 2002


   If you want, you can have 'Tkabber' use a different theme by setting
   "pixmaps_theme" to a string that ends in "/", e.g.,

   set pixmaps_theme ~/.tkabber/pixmaps/

   The theme directory should have four directories named "browser",
   "roster", "services", and, "tkabber".  Each of these directories
   contains the icons that make up the theme.  To find out the names of
   the icons that go in each directory, go to where you installed
   'Tkabber' and take a look at the directory called "pixmaps/default/".

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

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

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

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

   See Appendix A for a list of all the resources that you can set to
   control 'Tkabber's' look-and-feel.

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

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

       set load_default_xrdb 0
       tk_bisque

   to set the palette to a pleasing color scheme.

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



Shchepin, et al.                                               [Page 11]

                          Tkabber v0.9 (beta)              December 2002


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

2.1.4 Use ispell to check spelling

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

   set use_ispell 1


2.1.5 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
   configuration file:

   set debug_lvls {}










Shchepin, et al.                                               [Page 12]

                          Tkabber v0.9 (beta)              December 2002


2.1.6 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


2.1.7 Periodically send empty string to server

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

   set keep_alive 1
   set keep_alive_interval 10


2.1.8 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


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

       global alert colors alert_lvls




Shchepin, et al.                                               [Page 13]

                          Tkabber v0.9 (beta)              December 2002


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

       set raise_new_tab            1


   # the autoaway module

       set plugins::autoaway::options(awaytime) [expr  5*60*1000]
       set plugins::autoaway::options(xatime)   [expr 15*60*1000]


   # the avatar module

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


   # the chat module

       set chat::options(default_message_type) chat
       set chat::options(stop_scroll)          0


   # the clientinfo module

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


   # the conferenceinfo module

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


   # the cryptographic module

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


   # the emoticon module

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




Shchepin, et al.                                               [Page 14]

                          Tkabber v0.9 (beta)              December 2002


   # the groupchat module

       global gra_group gra_server
       global gr_nick gr_group gr_server gr_v2
       global defaultnick

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


   # the ispell module

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


   # the jidlink module

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


   # the login module

       global loginconf loginconf1 loginconf2 autologin

       set loginconf(user)          ""
       set loginconf(password)      ""
       set loginconf(resource)      tkabber
       set loginconf(server)        example.com
       set loginconf(port)          5222
       set loginconf(priority)      8
       set loginconf(usessl)        1
       set loginconf(sslport)       5223
       set loginconf(useproxy)      0
       set loginconf(httpproxy)     localhost
       set loginconf(httpproxyport) 3128
       set loginconf(httplogin)     ""
       set loginconf(httppassword)  ""

       # The following variables are useful when your jabber-server
       # (example.com) does not have 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 15]

                          Tkabber v0.9 (beta)              December 2002


       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 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(sound)                 1
       set sound::options(external_play_program) /usr/bin/play
   }

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

2.2.1 Look-and-Feel

   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;




Shchepin, et al.                                               [Page 16]

                          Tkabber v0.9 (beta)              December 2002


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

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

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

2.2.2 The Autoaway Module

   This module is presently available only if either:

   o  on UNIX, if you have the 'Tk Xwin' extension installed; or,

   o  On Windows, if you have the 'Tcl Winidle' extension installed.

   There are two variables that control when 'Tkabber' automatically
   marks you as away: "plugins::autoaway::options(awaytime)" and
   "plugins::autoaway::options(xatime)".  Both define the idle threshold
   in milli-seconds.

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


2.2.4 The Chat Module

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

   set chat::options(default_message_type) normal

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




Shchepin, et al.                                               [Page 17]

                          Tkabber v0.9 (beta)              December 2002


2.2.5 The Clientinfo Module

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

2.2.6 The Conferenceinfo Module

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

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

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

   The second variable defines how many seconds 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.

2.2.7 The Cryptographic Module

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


2.2.8 The Emoticons Module

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





Shchepin, et al.                                               [Page 18]

                          Tkabber v0.9 (beta)              December 2002


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

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


2.2.9 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,
      whilst "gr_v2" indicates whether the version 2 protocol should be
      used.

   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


2.2.10 The Ispell Module

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

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

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

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

   If you don't care about putting a large load on your process, then
   you can also set "plugins::ispell::options(check_every_symbol)" to 1



Shchepin, et al.                                               [Page 19]

                          Tkabber v0.9 (beta)              December 2002


   to check correctness of current word after every entered symbol.
   (Usually you don't need to set this option.)

2.2.11 The Jidlink Module

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

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

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

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

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

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


2.2.12 The Login Module

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

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

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

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

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




Shchepin, et al.                                               [Page 20]

                          Tkabber v0.9 (beta)              December 2002


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

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

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

2.2.15 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.  To
   enable sound notifications, you can add following line:
   set sound::options(sound) 1

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

    If you want to use external program for playing sounds, then also
   add something like this:

   set sound::options(external_play_program) /usr/bin/play





Shchepin, et al.                                               [Page 21]

                          Tkabber v0.9 (beta)              December 2002


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

    If you want to use another sound theme, then you can add line like
   this:
   set sound::options(theme) "sound_theme"
   Then 'Tkabber' load sound files from directory called "tkabber/
   sounds/sound_theme" if theme name not started with "/" or "~", else
   it consider theme name as path to theme directory.

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

   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.


2.3.1 The Avatar Module

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



Shchepin, et al.                                               [Page 22]

                          Tkabber v0.9 (beta)              December 2002


2.3.2 The Browser Module

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

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

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

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

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




Shchepin, et al.                                               [Page 23]

                          Tkabber v0.9 (beta)              December 2002


   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.

   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


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

2.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 24]

                          Tkabber v0.9 (beta)              December 2002


3. 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 $jid $from $type $body $extras

   The "hook::run" procedure invokes whatever hooks have been defined
   for "draw_message_hook".  In fact, upto 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, an 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".

   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 ...::draw_signed            6
   hook::add draw_message_hook ...::draw_encrypted         7
   hook::add draw_message_hook ...::handle_error          10
   hook::add draw_message_hook ...::draw_timestamp        15
   hook::add draw_message_hook ...::logger::log_message   15
   hook::add draw_message_hook ...::handle_server_message 20
   hook::add draw_message_hook ...::handle_me             50
   hook::add draw_message_hook    ::wmdock::msg_recv      70
   hook::add draw_message_hook ...::draw_normal_message   80

   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".  (In this example, the actual namespaces were



Shchepin, et al.                                               [Page 25]

                          Tkabber v0.9 (beta)              December 2002


   replaced with "...:" to make it more readable).

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

3.1 Chat Hooks

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

   open_chat_pre_hook  $jid $type
   open_chat_post_hook $jid $type

   Both hooks are given two parameters: the JID of the user (or
   conference room); 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 $jid

   The hook is given two parameters: the path of the 'Tk' widget for the
   tabbed window; and, the JID of the user (or conference room).

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

   chat_send_message_hook $jid $user $body $type

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

   draw_message_hook $jid $from $type $body $extras

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

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

   chat_create_user_menu_hook $path $jid
   chat_create_conference_menu_hook $path $jid

   The first is used in user chat windows, and second in groupchat ones.



Shchepin, et al.                                               [Page 26]

                          Tkabber v0.9 (beta)              December 2002


   Hooks is given two parameters: the path of the 'Tk' menu widget; and,
   the JID of user or conference.

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

   generate_completions_hook $jid $compsvar $wordstart $line

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

    When someone enters/exits conference, next hooks called:

   hook::run chat_user_enter $group $nick
   hook::run chat_user_exit  $group $nick

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

3.2 Login Hooks

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

   connected_hook

   disconnected_hook

   Neither hook is given any parameters.

3.3 Presence Hooks

   When our presence status changes, a hook is run:

   change_our_presence_post_hook $status

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

   o  available;

   o  chat;

   o  away;




Shchepin, et al.                                               [Page 27]

                          Tkabber v0.9 (beta)              December 2002


   o  xa;

   o  dnd;

   o  invisible; or,

   o  unavailable.

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

   on_change_user_presence_hook $jid $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.

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

   client_presence_hook $from $type $x $args

   The hook is given three parameters: 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").

3.4 Roster Hooks

    When a user is added to the roster window, a hook is run to add
   stuff to the menu associated with that user:
   roster_create_user_menu_hook $path $jids
   The hook is given two parameters: the path of the 'Tk' menu widget;
   and, a list of JIDs for which presence information is available.

    Also next hook is run to add stuff to the menu in groupchats:
   roster_create_groupchat_user_menu_hook $path $jid
   The hook is given two parameters: the path of the 'Tk' menu widget;
   and, a JID of user.

    Next hook is run to add stuff to the popup balloon for each roster
   item:
   roster_user_popup_info_hook $varname $jid
   The hook is given two parameters: the variable name in which current
   popup text is stored, and the JID of the roster item.









Shchepin, et al.                                               [Page 28]

                          Tkabber v0.9 (beta)              December 2002


3.5 Miscellaneous Hooks

   There are three "obvious" hooks:

   postload_hook

   finload_hook

   quit_hook

   The first two, by default, run the "postload" and "finload"
   procedures, respectively.  The final hooks is called just before
   'Tkabber' terminates (cf., Section 2.3.7).






































Shchepin, et al.                                               [Page 29]

                          Tkabber v0.9 (beta)              December 2002


URIs

   [1]   <http://www.jabber.ru/projects/tkabber/screenshots.html>

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

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

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

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

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

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

   [8]   <http://purl.oclc.com/net/nijtmans/img.html>

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

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

   [11]  <http://beepcore-tcl.sourceforge.net/tclgpgme-1.0.tgz>

   [12]  <ftp://ftp.gnupg.org/gcrypt/alpha/gpgme/>

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

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

   [15]  <http://www.jabber.ru/projects/teo/tclWinidle/>

   [16]  <http://www.xmission.com/~georgeps/Tk_Theme/>

   [17]  <http://ftp.bj-ig.de/pub/tcltk/winico31.zip>

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

   [19]  <http://www.jabber.org/jeps/jep-0038.html>


Authors' Addresses

   Alexey Yurievich Shchepin
   Innovation Center of Information Technologies (Sevcom)

   EMail: alexey@sevcom.net




Shchepin, et al.                                               [Page 30]

                          Tkabber v0.9 (beta)              December 2002


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

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


   Sergei Vitalyevich Golovan
   New Economic School

   EMail: sgolovan@nes.ru


   Michail Yurievich Litvak
   Information Centre ISP

   EMail: mci@al.lg.ua






























Shchepin, et al.                                               [Page 31]

                          Tkabber v0.9 (beta)              December 2002


Appendix A. XRDB

   Here is list of most 'Tkabber'-specific 'XRDB' resources that you
   need to change look:

   *Balloon.background

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

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

   *JBrowser.fill Color of browser item name.

   *JBrowser.nscolor Color of NS browser item.

   *JBrowser*Tree*background Background of browser.

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

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



Shchepin, et al.                                               [Page 32]

                          Tkabber v0.9 (beta)              December 2002


   *NoteBook.alertColor0

   *NoteBook.alertColor1

   *NoteBook.alertColor2

   *NoteBook.alertColor3 Tabs alert colors.

   *Roster.cbackground Roster background color.

   *Roster.groupindent Indentation for group title.

   *Roster.groupiconindent Indentation for group icon.

   *Roster.jidindent Indentation for item name.

   *Roster.jidmultindent Indentation for item with multiple resources.

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




Shchepin, et al.                                               [Page 33]

                          Tkabber v0.9 (beta)              December 2002


   *Roster.stalkerforeground

   *Roster.unavailableforeground

   *Roster.dndforeground

   *Roster.xaforeground

   *Roster.awayforeground

   *Roster.availableforeground

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






































Shchepin, et al.                                               [Page 34]

                          Tkabber v0.9 (beta)              December 2002


Appendix B. Documentation TODO

   The next revision of this documentation should discuss:

   o  Pre-load:

      *  "browseurl"

   o  Post-load:

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

   o  Menu-load:

      *  "change_password_dialog"

      *  "conference::create_room_dialog"

      *  "disco::browser::open_win"

      *  "message::send_msg"

      *  "privacy::request_lists"

      *  "show_rawxml_dialog"

      *  "userinfo::show_info_dialog"

   o  Hooks: the additional payload format.






















Shchepin, et al.                                               [Page 35]

                          Tkabber v0.9 (beta)              December 2002


Appendix C. Acknowledgements

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















































Shchepin, et al.                                               [Page 36]

                          Tkabber v0.9 (beta)              December 2002


Appendix D. Copyrights

   (c) 2002 Alexey Shchepin

   Hold harmless the authors, and any lawful use is allowed.














































Shchepin, et al.                                               [Page 37]

