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


Tkabber 1.0

Abstract

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



Table of Contents

1.  Features
2.  Requirements
3.  Download, install and run
4.  Upgrading from version 0.11.0 or 0.11.1
    4.1.  External plugins
    4.2.  Configuration options
5.  Upgrading from version 0.10.0
    5.1.  Configuration options
        5.1.1.  Proxy servers
        5.1.2.  Resources to control fonts
        5.1.3.  Keep-alives and dead link detection
        5.1.4.  Resources to control appearance of balloon windows
        5.1.5.  Support for external XML parser
    5.2.  User interface
        5.2.1.  System tray icon mouse gestures
        5.2.2.  New tab management widget
        5.2.3.  Window splitters
6.  Upgrading from version 0.9.9
7.  Configuration
    7.1.  Pre-load
        7.1.1.  Tabbed Interface
        7.1.2.  Fonts and colors
        7.1.3.  Cryptography by default
        7.1.4.  Debugging Output
        7.1.5.  Splash window
        7.1.6.  I18n/L10n
        7.1.7.  Browse URL
        7.1.8.  Searching
    7.2.  Post-load
        7.2.1.  Look-and-Feel
        7.2.2.  The system tray icon (for Unix)
        7.2.3.  The Autoaway Module
        7.2.4.  The Avatar Module
        7.2.5.  The Chat Module
        7.2.6.  The Clientinfo Module
        7.2.7.  The Conferenceinfo Module
        7.2.8.  The Cryptographic Module
        7.2.9.  The Emoticons Module
        7.2.10.  The File Transfer Module
        7.2.11.  The Groupchat Module
        7.2.12.  The Ispell Module
        7.2.13.  The Stream Initiation Module
        7.2.14.  The Logger Module
        7.2.15.  The Proxy Module
        7.2.16.  The Login Module
        7.2.17.  The Message Module
        7.2.18.  The Raw XML Input Module
        7.2.19.  The Roster Module
        7.2.20.  The Sound Module
    7.3.  Menu-load
        7.3.1.  The Avatar Module
        7.3.2.  The Browser Module
        7.3.3.  The Groupchat Module
        7.3.4.  The Login Module
        7.3.5.  The Message Module
        7.3.6.  The Presence Module
        7.3.7.  Miscellany
    7.4.  Final-Load
8.  Extensibility
    8.1.  Message Hooks
    8.2.  Chat Hooks
    8.3.  Login Hooks
    8.4.  Presence Hooks
    8.5.  Info/Query Hook
    8.6.  Roster Hooks
    8.7.  Miscellaneous Hooks
9.  User Interface basics
    9.1.  Searching
Appendix A.  Releases History
    A.1.  Main changes in 1.0
    A.2.  Main changes in 0.11.1
    A.3.  Main changes in 0.11.0
    A.4.  Main changes in 0.10.0
    A.5.  Main changes in 0.9.9
    A.6.  Main changes in 0.9.8
    A.7.  Main changes in 0.9.7beta
    A.8.  Main changes in 0.9.6beta
    A.9.  Main changes in 0.9.5beta
Appendix B.  Tk option database resources
Appendix C.  Documentation TODO
Appendix D.  Acknowledgements
Appendix E.  Copyrights
§  Authors' Addresses




 TOC 

1.  Features

Tkabber provides a Tcl/Tk interface to the Jabber/XMPP 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:

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
messages:
  • privacy rules
  • signed/encrypted messages (if you install an optional extension)
  • 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
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



 TOC 

2.  Requirements

You should already have installed:

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

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!



 TOC 

3.  Download, install and run

Latest stable version is 1.0 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:

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

From the shell, you can invoke Tkabber as:

% tkabber.tcl

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

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

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

Tkabber will automatically know that it's running under tkcon and 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. For this you need to set hanler for application/xmpp+xml MIME type in your browser to something like this:

tkabber -mime %s


 TOC 

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.



 TOC 

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.0 then you'll have to disable or remove that plugin.



 TOC 

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' (The Proxy Module) 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) ""

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' (The Proxy Module) below.



 TOC 

5.  Upgrading from version 0.10.0

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



 TOC 

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.



 TOC 

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 (Configuration options), 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:



 TOC 

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



 TOC 

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:

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



 TOC 

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:



 TOC 

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.



 TOC 

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.



 TOC 

5.2.1.  System tray icon mouse gestures

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

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.



 TOC 

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



 TOC 

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.



 TOC 

6.  Upgrading from version 0.9.9

When upgrading Tkabber from version 0.9.9 or earlier read the above section (Upgrading from version 0.10.0) and also note the following:



 TOC 

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:

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:

Let's look at each, in turn.



 TOC 

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"


 TOC 

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.



 TOC 

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.

The corresponding Tk's option 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 (Tk option database resources) for a list of all the resources that you can set to control Tkabber's look-and-feel.

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:

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.



 TOC 

7.1.3.  Cryptography by default

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

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



 TOC 

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

set debug_lvls {}


 TOC 

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


 TOC 

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


 TOC 

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

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"


 TOC 

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



 TOC 

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

# 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


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

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

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



 TOC 

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:

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


 TOC 

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.

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.



 TOC 

7.2.3.  The Autoaway Module

This module is presently available only if either:

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.



 TOC 

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:



 TOC 

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


 TOC 

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


 TOC 

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.



 TOC 

7.2.8.  The Cryptographic Module

Earlier (Pre-load) 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


 TOC 

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

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


 TOC 

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"


 TOC 

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.



 TOC 

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:

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



 TOC 

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


 TOC 

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


 TOC 

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

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.



 TOC 

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:

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



 TOC 

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.



 TOC 

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.



 TOC 

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



 TOC 

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:

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


 TOC 

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

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.


 TOC 

7.3.1.  The Avatar Module

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



 TOC 

7.3.2.  The Browser Module

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



 TOC 

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.



 TOC 

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.



 TOC 

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.



 TOC 

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:

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


 TOC 

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.



 TOC 

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.



 TOC 

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

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.



 TOC 

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

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.



 TOC 

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.

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.

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.



 TOC 

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



 TOC 

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:

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.

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



 TOC 

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



 TOC 

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.

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.



 TOC 

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

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.



 TOC 

9.  User Interface basics



 TOC 

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:

Searching may be customized using the settings located under the Plugins → Search group of the Customize window. These setings are:



 TOC 

Appendix A.  Releases History



 TOC 

A.1.  Main changes in 1.0



 TOC 

A.2.  Main changes in 0.11.1



 TOC 

A.3.  Main changes in 0.11.0



 TOC 

A.4.  Main changes in 0.10.0



 TOC 

A.5.  Main changes in 0.9.9



 TOC 

A.6.  Main changes in 0.9.8



 TOC 

A.7.  Main changes in 0.9.7beta



 TOC 

A.8.  Main changes in 0.9.6beta



 TOC 

A.9.  Main changes in 0.9.5beta



 TOC 

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.
*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.
*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
*Roster.chatforeground
Colors of item name for different presences.



 TOC 

Appendix C.  Documentation TODO

The next revision of this documentation should discuss:



 TOC 

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



 TOC 

Appendix E.  Copyrights

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



 TOC 

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