| TOC |
|
Tkabber is an open source Jabber client, written in Tcl/Tk. This memo describes the installation, configuration, and extension of Tkabber.
1.
Features
2.
Requirements
3.
Download, install and run
4.
Configuration
4.1.
Pre-load
4.1.1.
Tabbed Interface
4.1.2.
Primary Look-and-Feel
4.1.3.
Cryptography by default
4.1.4.
Using of external TclXML library
4.1.5.
Use ispell to check spelling
4.1.6.
Debugging Output
4.1.7.
Splash window
4.1.8.
Periodically send empty string to server
4.1.9.
I18n/L10n
4.2.
Post-load
4.2.1.
Look-and-Feel
4.2.2.
The Autoaway Module
4.2.3.
The Avatar Module
4.2.4.
The Chat Module
4.2.5.
The Clientinfo Module
4.2.6.
The Conferenceinfo Module
4.2.7.
The Cryptographic Module
4.2.8.
The Emoticons Module
4.2.9.
The File Transfer Module
4.2.10.
The Groupchat Module
4.2.11.
The Ispell Module
4.2.12.
The Stream Initiation Module
4.2.13.
The Jidlink Module
4.2.14.
The Logger Module
4.2.15.
The Login Module
4.2.16.
The Message Module
4.2.17.
The Raw XML Input Module
4.2.18.
The Roster Module
4.2.19.
The Sound Module
4.3.
Menu-load
4.3.1.
The Avatar Module
4.3.2.
The Browser Module
4.3.3.
The Groupchat Module
4.3.4.
The Login Module
4.3.5.
The Message Module
4.3.6.
The Presence Module
4.3.7.
Miscellany
4.4.
Final-Load
5.
Extensibility
5.1.
Chat Hooks
5.2.
Login Hooks
5.3.
Presence Hooks
5.4.
Roster Hooks
5.5.
Miscellaneous Hooks
Appendix A.
Releases History
A.1.
Main changes in 0.9.9
A.2.
Main changes in 0.9.8
A.3.
Main changes in 0.9.7beta
A.4.
Main changes in 0.9.6beta
A.5.
Main changes in 0.9.5beta
Appendix B.
XRDB
Appendix C.
Documentation TODO
Appendix D.
Acknowledgements
Appendix E.
Copyrights
§
Authors' Addresses
| TOC |
Tkabber provides a Tcl/Tk interface to the Jabber 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 and HTTP-polling session transports
- XMPP SRV and TXT DNS-records handling
- hashed passwords
- SASL authentication
- encrypted sessions (if you install an optional extension)
- compressed sessions (if you install an optional extension)
- login via HTTP proxy
- user-defined hooks for connection establishment and release
- XMPP/Jabber MIME type
- messages:
- privacy rules
- signed/encrypted messages (if you install an optional extension)
- file transfers (HTTP, SOCKS bytestream, DTCP and IBB transports)
- groupchat (GroupChat-1.0 and Multi-User Chat conferencing protocols)
- headline messages
- message events
- completions of nick and commands
- hyperlinks
- emoticons
- user-defined hooks for chat window events
- presence:
- signed presence (if you install an optional extension)
- avatars
- browsing
- groupchat and roster invitations
- conference room bookmarks
- annotations about roster items
- vCards
- user-defined hooks for presence changes
- windowing:
- configurable look-and-feel via a resources database
- unicode
- tabbed/non-tabbed interface
- sound notifications
- nested roster groups
- for Unix: auto-away, spell checking, KDE or freedesktop docking, and WMaker icons
- for Windows: auto-away, and taskbar icons
| TOC |
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 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:
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 |
Latest stable version is 0.9.9.
You can always find the latest development version via CVS. Do following steps:
If you use the Debian GNU/Linux distribution, you may want to get all required packages by using apt. Just execute apt-get install tk tcllib bwidget or apt-get install tkabber to get the latest stable version.
No real installation is required, simply copy the tkabber/ directory to a commonly-available area, and then either:
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 Help menu to find the checkbutton to show the console.
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 |
One of the first thing that Tkabber does is read a file in your home directory called ".tkabber/config.tcl". This is a Tcl source file, so obviously, it's a lot easier to maintain this file if you know the Tcl programming language. If you're not familiar with it, that's okay — most things you'll need to do are pretty simple! (In fact, if you don't have your own configuration file, you'll get the vanilla Tkabber, which hopefully you'll find quite usable.)
Note that almost all Tkabber options can be cofigured using graphical interface (menu Tkabber->Customize), so editing configuration file is not strictly necessary.
Tkabber is configured in four stages:
Let's look at each, in turn.
| TOC |
There are a few things that you may let Tkabber know immediately. These are:
# tabbed interface
set ifacetk::options(use_tabbar) 1
# primary look-and-feel
set load_default_xrdb 1
set font "-monotype-arial-medium-r-normal-*-13-*-*-*-*-*-iso10646-1"
option add *font \
"-monotype-arial-medium-r-normal-*-13-*-*-*-*-*-iso10646-1" \
userDefault
# cryptography by default
set ssj::options(sign-traffic) 0
set ssj::options(encrypt-traffic) 0
# using of external tclxml library
set use_external_tclxml 0
# use ispell to check spelling
set use_ispell 0
# debugging output
set debug_lvls {jlib warning}
# splash window
set show_splash_window 0
# periodically send empty string to server
set keep_alive 0
set keep_alive_interval 10
# force english labels instead of native language
::msgcat::mclocale en
| TOC |
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 |
All of the windows, dialogs, etc., used by Tkabber are called "widgets". Each widget determines most of its "look" from an "resource" database. On Unix, try man palette to see what the primary "look-and-feel" options are, and man option to see how to modify them. (On Windows, from the Start menu, select Tcl and then Tcl Help, and then enter either "palette" or "option".)
Most folks who want to define a new look-and-feel put all their options in an "xrdb" file, and then reference it this way:
set load_default_xrdb 0
option readfile ~/.tkabber/newlook.xrdb userDefault
The first line tells Tkabber not to load its default "xrdb" file, whilst the second line tells Tkabber the file to load instead.
See Appendix B (XRDB) for a list of all the resources that you can set to control Tkabber's look-and-feel.
Directory "examples" contains several examples of resource database files "*.xrdb".
Alternatively, if you're a Tcl "old timer", you can always do:
set load_default_xrdb 0
tk_bisque
to set the palette to a pleasing color scheme.
Other look-and-feel options which you may want to set are font options:
set font "-monotype-arial-medium-r-normal-*-13-*-*-*-*-*-iso10646-1"
option add *font \
"-monotype-arial-medium-r-normal-*-13-*-*-*-*-*-iso10646-1" \
userDefault
Obviously, you may chose the most suitable fonts for you.
| TOC |
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 |
By default Tkabber use version of TclXML library that come with it distribution. This version is pure-Tcl, and it performance can be not suitable. Then you can install TclXML with built-in expat support and set variable use_external_tclxml:
set use_external_tclxml 0
| TOC |
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
| TOC |
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 |
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 |
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
| TOC |
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 |
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 raise_new_tab 1
# the autoaway module
set plugins::autoaway::options(awaytime) 5
set plugins::autoaway::options(xatime) 15
set plugins::autoaway::options(status) "Automatically away due to idle"
set plugins::autoaway::options(drop_priority) 1
# the avatar module
set avatar::options(announce) 0
set avatar::options(share) 0
# the chat module
set chat::options(default_message_type) chat
set chat::options(stop_scroll) 0
set plugins::options(timestamp_format) {[%R]}
# the clientinfo module
set plugins::clientinfo::options(autoask) 0
# the conferenceinfo module
set plugins::conferenceinfo::options(autoask) 0
set plugins::conferenceinfo::options(interval) 1
set plugins::conferenceinfo::options(err_interval) 60
# the cryptographic module
set ssj::options(encrypt,fred@example.com) 1
# the emoticon module
emoteicons::load_dir ~/.tkabber/emoticons/rythmbox
# the file transfer module
set ft::options(download_dir) "/tmp"
# the groupchat module
global gra_group gra_server
global gr_nick gr_group gr_server
global defaultnick
set defaultnick(adhoc@conference.example.com) publius
set defaultnick(*@conference.example.com) cicerone
# the ispell module
set plugins::ispell::options(executable) /usr/bin/ispell
set plugins::ispell::options(dictionary) russian
set plugins::ispell::options(dictionary_encoding) koi8-r
set plugins::ispell::options(check_every_symbol) 1
# the stream initiation module
set si::transport(allowed,http://jabber.org/protocol/bytestreams) 0
set si::transport(allowed,http://jabber.org/protocol/ibb) 1
# the jidlink module
set jidlink::transport(allowed,dtcp-passive) 0
# the logger module
set logger::options(logdir) ~/.tkabber/logs
set logger::options(log_chat) 1
set logger::options(log_groupchat) 1
# the login module
global loginconf loginconf1 loginconf2 autologin
set loginconf(user) ""
set loginconf(password) ""
set loginconf(server) example.com
set loginconf(resource) tkabber
set loginconf(priority) 16
set loginconf(usealtserver) 0
set loginconf(altserver) ""
set loginconf(altport) 5422
set loginconf(stream_options) plaintext
set loginconf(useproxy) 0
set loginconf(usesasl) 1
set loginconf(allowauthplain) 0
set loginconf(httpproxy) localhost
set loginconf(httpproxyport) 3128
set loginconf(httplogin) ""
set loginconf(httppassword) ""
# The following variables are useful when your jabber-server
# (example.com) does not have SRV or A-record in DNS
set loginconf(usealtserver) 1
set loginconf(altserver) "jabber.example.com"
set loginconf1(profile) "Default Account"
set loginconf1(user) mrose
set loginconf2(profile) "Test Account"
set loginconf2(user) test
array set loginconf [array get loginconf1]
set autologin 0
# the message module
set message::options(headlines,cache) 1
set message::options(headlines,multiple) 1
# the raw xml input module
set plugins::rawxml::set options(pretty_print) 0
set plugins::rawxml::set options(indent) 2
# 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 |
Tkabber is shameless in borrowing icons from other Jabber clients. By setting pixmaps::options(pixmaps_theme), you can select a family of related icons. Besides "Default", you can choose one of "Gabber", "JAJC", "Jarl", "Psi", "ICQ", or a few other themes.
If you want, you can have Tkabber use a different theme by putting custom theme subdirectory to ~/.tkabber/pixmaps/ directory (tilde means home directory). Tkabber knows that it is a theme directory by looking for icondef.xml file in the directory. To find out the structure of icon definition file, look through JEP-0038 and go to where you installed Tkabber and take a look at the directory called "pixmaps/default/".
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 tab has new activity, it is automatically raised. If you don't like this behavior, add this line:
set raise_new_tab 0
| TOC |
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 |
There are two variables that you can set to control whether Tkabber will allow others to see your avatar:
| TOC |
Most instant messaging users prefer to see all the back-and-forth communication in a single window. If you prefer to see each line sent back-and-forth in a separate window, here's what to put in your postload:
set chat::options(default_message_type) normal
The variable named chat::options(stop_scroll) determines whether a chat window should automatically scroll down to the bottom whenever something new comes in.
You can also set format of time stamp that displayed in beginning of each chat message. Refer to Tcl documentation for description of format. E.g., to display it in "dd:mm:ss" format, add this line:
set plugins::options(timestamp_format) {[%T]}
| TOC |
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 |
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 |
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 |
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.)
If you have just a few icons, and you don't want to create a directory and a textual mapping, you can use the procedure called emoteicons::add, e.g.,
emoteicons::add ":beer:" \
[image create photo -file ~/.tkabber/beer.gif]
If you want to disable all emoticons, you can use the following trick. Put in postload function
array unset emoteicons::emoteicons
| TOC |
You can set directory in which files will be saved by default:
set ft::options(download_dir) "/tmp"
| TOC |
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 |
If you enabled this module earlier (Use ispell to check spelling), then you can 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 |
Stream initiation profile is defined in JEP-0095 with two transports (JEP-0047 - IBB, JEP-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 |
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
| TOC |
You can set directory to store logs:
set logger::options(logdir) ~/.tkabber/logs
Also you can allow or disallow storing of private and group chats logs:
set logger::options(log_chat) 1
set logger::options(log_groupchat) 1
| TOC |
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 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 JEP-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 |
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 |
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 |
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 |
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:
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 |
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:
| TOC |
The procedure called avatar::store_on_server stores your avatar on the server.
| TOC |
The procedure called browser::open opens a new browser window.
| TOC |
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 |
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 |
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 |
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 |
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 |
Finally, right before Tkabber goes to display the login dialog, it invokes a procedure called finload, which does whatever you want it to.
| TOC |
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 muc::set_message_timestamp 15 hook::add draw_message_hook ...::add_number_of_messages_to_title 18 hook::add draw_message_hook ...::chat_message_notify19 hook::add draw_message_hook ...::handle_server_message 20 hook::add draw_message_hook ...::roster::update_chat_activity 50 hook::add draw_message_hook ...::check_nick 60 hook::add draw_message_hook ::wmdock::msg_recv 70 hook::add draw_message_hook ...::handle_last_nick 79 hook::add draw_message_hook ...::::add_bookmark 80 hook::add draw_message_hook ...::handle_me 83 hook::add draw_message_hook ...::xhtml::draw_xhtml_message 85 hook::add draw_message_hook ...::draw_normal_message 87
Many of these procedures look at the incoming chat message and operate on only certain kinds of messages. Some of these procedures may return "stop", e.g., handle_me which handles chat bodies that start with "/me" and draw_xhtml_message which visualizes XHTML formatted messages. (In this example, the actual namespaces were replaced with "...:" to make it more readable).
Now let's look at the different kind of hooks that Tkabber knows about.
| TOC |
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 ID using chat::get_connid routines); and, and the type of chat (either "chat" or "groupchat").
Similarly, when Tkabber encounters activity on a tabbed window, a hook is run:
raise_chat_tab_hook $path $chatid
The hook is given two parameters: the path of the Tk widget for the tabbed window; and, the chatid of the chat or conference room window.
When you want to send a chat message, a hook is run:
chat_send_message_hook $chatid $user $body $type
The hook is given four parameters: the chatid of the recipient; the localpart of your login identity; the body of the message; and, the type of chat.
draw_message_hook $chatid $from $type $body $extras
The hook is given five parameters: the chatid of the sender window (JID includes a resource); the JID of the sender (without the resource); the type of chat; the body of the message; and, a nested-list of additional payload elements. (This last parameter isn't documented in this version of the documentation.)
Chat windows have menubuttons, and two hooks is used to add items in menu:
chat_create_user_menu_hook $path $connid $jid chat_create_conference_menu_hook $path $connid $jid
The first is used in user chat windows, and second in groupchat ones. Hooks is given three parameters: the path of the Tk menu widget; connection ID; and, the JID of user or conference.
In groupchat windows possible to complete participant's nicks or commands by pressing TAB key. List of completions is generated by running this hook:
generate_completions_hook $chatid $compsvar $wordstart $line
The hook is given four parameters: the chatid of conference window; name of global variable, in which stored current list of possible completions; index of position where completion must be inserted; and, content of text widget where completion is requested.
When someone enters/exits conference, next hooks called:
chat_user_enter $group $nick chat_user_exit $group $nick
The hook is given two parameters: chatid of conference and nick participant.
| TOC |
Two hooks are invoked whenever a session is connected or disconnected:
connected_hook $connid disconnected_hook $connid
Both hook is given one parameter: connection ID (Tkabber allows several connections at once).
| TOC |
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 $connid $from $type $x $args
The hook is given four parameters: connection ID, who send this presence, type of presence (e.g., "error", "unavailable"), list of extended subtags and parameters of this presence (e.g., "-show xa -status online").
| TOC |
When an item is added to the roster window, one of the three hooks is run to add stuff to the menu associated with that item:
roster_conference_popup_menu_hook $path $connid $jid roster_service_popup_menu_hook $path $connid $jid roster_jid_popup_menu_hook $path $connid $jid
The hook is given three parameters: the path of the Tk menu widget; the connection ID; and, a JID for which presence information is available.
Also next hook is run to add stuff to the menu in groupchats:
roster_create_groupchat_user_menu_hook $path $connid $jid
The hook is given three parameters: the path of the Tk menu widget; the connection ID; and, a JID of user.
Next hook is run to add stuff to the popup balloon for each roster item:
roster_user_popup_info_hook $varname $connid $jid
The hook is given three parameters: the variable name in which current popup text is stored, the connection ID, and the JID of the roster item.
| TOC |
There are three "obvious" hooks:
postload_hook finload_hook quit_hook
The first two, by default, run the postload and finload procedures, respectively. postload_hook is run after all code loaded and before initializing main Tkabber window. After that finload_hook is run. The final hooks is called just before Tkabber terminates (cf., Section 4.3.7 (Miscellany)).
You can add custom pages to userinfo window using
userinfo_hook $path $connid $jid $editable
| TOC |
| TOC |
| TOC |
| TOC |
| TOC |
| TOC |
| TOC |
Here is list of most Tkabber-specific XRDB resources that you need to change look:
- Tkabber.geometry
- Geometry of main window.
- *Chat.chatgeometry
- *Chat.groupchatgeometry
- *Customize.geometry
- *RawXML.geometry
- *Stats.geometry
- *Messages.geometry
- *JBrowser.geometry
- *JDisco.geometry
- Geometry of various windows (when not using tabs).
- *Chat.inputheight
- *RawXML.inputheight
- Height of input windows in chat and raw XML windows.
- *Balloon.background
- *Balloon.foreground
- Background and foreground colors of popup balloon.
- *Balloon.style
- Behaviour of popup balloon: can be delay (balloon appeared after some time) and follow (balloon appeared immediately and follows mouse).
- *JBrowser.fill
- Color of browser item name.
- *JBrowser.nscolor
- Color of NS browser item.
- *JBrowser*Tree*background
- Background of browser.
- *Chat.meforeground
- Color of user's messages in chat windows.
- *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 |
The next revision of this documentation should discuss:
| TOC |
Rebecca Malamud was kind enough to design the "enlightened feather" motif used in the Tkabber look-and-feel.
| TOC |
Copyright (c) 2002-2006 Alexey Shchepin
Tkabber is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
Tkabber is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
| TOC |
| Alexey Yurievich Shchepin | |
| Process-One | |
| Email: | alexey@sevcom.net |
| Marshall T. Rose | |
| Dover Beach Consulting, Inc. | |
| POB 255268 | |
| Sacramento, CA 95865-5268 | |
| US | |
| Phone: | +1 916 483 8878 |
| Fax: | +1 916 483 8848 |
| Email: | mrose@dbc.mtview.ca.us |
| Sergei Vitalyevich Golovan | |
| New Economic School | |
| Email: | sgolovan@nes.ru |
| Michail Yurievich Litvak | |
| Information Centre ISP | |
| Email: | mci@al.lg.ua |