XChat 1.2

XChat 1.2 Peter Zelezny and Adam Langley July 1st, 1999 This document attempts to document XChat and introduce IRC generally. Large parts of the first section are taken from the alt.irc FAQ, thanks and credit goto the authors of it. IRC What is XChat?

XChat is a graphical IRC client that runs on UNIX like systems. It uses the GTK+ toolkit for graphical abstraction. It if GPL'ed software (free software). It is known to run on these systems:

Linux (primary development platform) FreeBSD OpenBSD NetBSD Solaris AIX IRIX SunOS OS/2

Introduction to IRC

IRC stands for &dquot;Internet Relay Chat&dquot;. It was originally written by Jarkko Oikarinen (jto@tolsun.oulu.fi) in 1988. Since starting in Finland, it has been used in over 60 countries around the world. It was designed as a replacement for the &dquot;talk&dquot; program but has become much much more than that. IRC is a multi-user chat system, where people convene on &dquot;channels&dquot; (a virtual place, usually with a topic of conversation) to talk in groups, or privately. IRC is constantly evolving, so the way things to work one week may not be the way they work the next. Read the MOTD (message of the day) every time you use IRC to keep up on any new happenings or server updates.

IRC gained international fame during the 1991 Persian Gulf War, where updates from around the world came across the wire, and most irc users who were online at the time gathered on a single channel to hear these reports. IRC had similar uses during the coup against Boris Yeltsin in September 1993, where IRC users from Moscow were giving live reports about the unstable situation there.

The user runs a &dquot;client&dquot; program which connects to the IRC network via another program called a &dquot;server&dquot;, which runs on another computer. Servers exist to pass messages from user to user over the IRC network.

XChat is a graphical client that runs using GTK(), it is mainly designed to run under UNIX (By this I mean all the UNIX's, like Linux, *BSD etc), but also runs under Win32 systems without some features.

IRC Basics

As mentioned above the channel is the basic unit of collective IRC chatting. Everyone who is &dquot;in&dquot; a channel can see all messages written to the channel and can (usually) write to the channel themselves.

All IRC commands start with a &dquot;/&dquot;, and most are one word. Typing /help will get you help information etc

Once on a server a /join #channel command will join you to the channel #channel in the current window, any further joins while still joined (e.g. before a /part) will open a new window. Once in a channel just type

Channel operators are kings/queens of their channel. This means they can kick you out of their channel for no reason. If you don't like this, you can start your own channel and become a channel operator there.

An IRC operator is someone who maintains the IRC network. They cannot fix channel problems. They cannot kick someone out of a channel for you. They cannot /kill (kick someone out of IRC temporarily) someone just because you gave the offender channel operator privileges and said offender kicked you off.

#hottub and #initgame are almost always teeming with people. #hottub is meant to simulate a hot tub, and #initgame is a non-stop game of &dquot;inits&dquot; (initials). Just join and find out!

To get a list of channels with their names and topics, do /list -min 20 (on ircII) which will show you channels with 20 or more members. You can also do this for smaller numbers.

Many IRC operators are in #Twilight_Zone ... so if you join that channel be prepared for a lot of senseless dribble, more like what you find on the other channels listed above (#hottub). What was once a place of people who could help you has turned into just another place for those who have nothing better to do with themselves than just be there. If you find other documents saying go there to ask questions, ignore them. They should be considered to be out of date.

There are not enough nicknames to have nickname ownership. If someone takes your nickname while you are not on IRC, you can ask for them to give it back, but you can not *demand* it, nor will IRC operators /kill for nickname ownership. If you goto #Twilight_zone, you will find a bunch of people who will refuse to do this for you, yet they will do it for themselves or their friends or use /kill for even less reasonable uses. There are, literally, millions of possible channel names, so if someone is on your usual channel, just go to another. You can /msg them and ask for them to leave, but you can't force them to leave.

Channel operators are the owner(s) of their respective channels. Keep this in mind when giving out channel operator powers (make sure to give them to enough people so that all of the channel operators don't unexpectedly leave and the channel is stuck without a channel operator).

On the other hand, do not give out channel operator to everyone. This causes the possibility of mass-kicking, where the channel would be stuck without any channel operators.

You have one option. You can ask everyone to leave and rejoin the channel. This is a good way to get channel operator back. It doesn't work on large channels or ones with bots, for obvious reasons.

On IRC, you cannot be banned from every single server. Server-banning exists only on a per-server basis (being banned on one server does not mean you are automatically banned from another). &dquot;Ghosts are not allowed on IRC&dquot; means that you are banned from using that server. The banning is in one of three forms:

You are banned specifically, you yourself. Only you can be responsible for this (if you are using a shared account, this obviously does not apply). Thus the responsibility lies completely with you and you have no-one to complain to. Your machine is banned. Chances are it wasn't you who committed the wrongdoing. Try using another machine on campus and seeing if you can use that particular irc server then. Your whole site is banned (where &dquot;site&dquot; == &dquot;school&dquot;, &dquot;company&dquot;, &dquot;country&dquot;). This almost certainly wasn't your fault. And chances are you won't be able to get the server-ban lifted. Try using another server.

The most general answer is "use another server&dquot;, but if it bothers you, try writing to the irc administrator of that site -> /admin server.name.here -- plead your case. It might even get somewhere!

The best, basic, IRC user's manual is the IRC Primer, available in plain text, Postscript, and LaTeX from cs-pub.bu.edu:/irc/support ... Another good place to start might be downloading the .

The IRC protocol is fully documented in

Etiquette

This subsection is by Lea Viljanen, Ari Husa and Helen Rose for irc2.9.5, thank you

Language

The most widely understood and spoken language on IRC is English. However! As IRC is used in many different countries, English is by no means the only language. If you want to speak some other language than English (for example with your friends), go to a separate channel and set the topic to indicate that.

On the other hand, you should check the topic before you move to a channel to see if there are any restrictions about language. On a channel not restricted by a topic, please speak a language everybody can understand. If you want to do otherwise, change channels and set the topic accordingly.

Hello/Goodbye

It's not necessary to greet everybody on a channel personally. Usually one &dquot;Hello&dquot; or equivalent is enough. And don't expect everybody to greet you back. On a channel with 20 people that would mean one screenful of hellos. It's sensible not to greet, in order not to be rude to the rest of the channel. If you must say hello, do it with a private /msg. The same applies to goodbyes.

Discussion

When you come to a new channel it's advised you to listen for a while to get an impression of what's discussed. Please feel free to join in, but do not try to force your topic into the discussion if that doesn't come naturally.

Getting, Building and Running Getting

If you re lazy, or don't want to install any support libraries then Peter Alexandrou has started hosting the

The main distribution point for XChat is , XChat also needs . Optionally XChat can use and .

Building

XChat uses the GNU autoconf system, so building it is quite easy, for most systems the auto detection will work:

./configure ; make ; su ; make install

On some systems gmake might be needed rather than make.

The configure script can be passed some options as well

--disable-perl = Disables Perl support --disable-gnome = Disables GNOME support

Be aware that if you don't have perl or GNOME the configure script will pick this up and you don't need to pass these options, they are only if for when you do have them, but don't want support for them.

If you are having problems with this method you can try the old method:

cp Makefile.gtk Makefile ; make ; su ; make install

Running

The build process makes a binary called xchat. If you installed it typing xchat at the console should run it, if not cd into the XChat directory and type ./xchat

The directory ˜/.xchat should be created for you, XChat uses this directory to store per-user settings and logs.

The GUI

When XChat is first started it brings up a window with 5 main parts:

The menu bar The tool-bar The text box (middle - left) The user-list (middle - right) The input box (bottom)

On startup 1 window is created with no state (it is labeled &dquot;<none>&dquot;), if you join a channel that window then contains all the information from that channel. If someone /msg's you a new window may be created containing all further /msg's from that person

The menu bar

The menu bar has 6 menus in it (the text may change if you have language packs active):

&dquot;X-Chat&dquot; - Major operations, like a &dquot;File&dquot; menu &dquot;Windows&dquot; - Each of the XChat windows can be called from this menu, it also contains operations affecting the buffer &dquot;User Modes&dquot; - All the items in this menu are toggle items changing the state of the IRC user "Settings&dquot; - All the configuration dialogs can be called from here "Scripts & Plugins&dquot; - Operations effecting these &dquot;Help&dquot; - Standard help menu

The tool bar

The tool-bar contains the leafs of each window attached to the main window, these leafs have the name of the channel or nick of the window. Clicking on one of these leafs brings that window to the front. If the text in a currently hidden window changes the text in the leaf goes red

The &dquot;X&dquot; button at the far left closes the currently window. If that is the only window XChat quits. The text box contains the topic of the channel which is currently active in the top window or the address of the nick, if a nick is currently active.

The "^" button (or an up arrow if you use GNOME), next to the "X" button, links or delinks the window. If you have a series of tabs then clicking this will delink the window and make it a separate window. After this, clicking it again will link the window back into the notebook. You cannot delink the only window in a notebook and if you try to link a window when there is no notebook window then one will be created.

The buttons at the right of the tool-bar set the channel modes, and only have effect when the window contains a channel and you are chanop. They stand for:

T - Topic lock N - No outside messages to the channel S - Secret I - Invite only P - Private M - Moderated L - User limit (also has a text box) K - Key (also has a text box)

The far right button, with the arrow, toggles the user-list

The text box

The text box contains the text from the contained object (channel, nick etc) and the output from commands entered into the input box.

It is usually a GTK text box, whose options can be controlled from &dquot;Settings - Setup - Channel Windows&dquot;. However it can also be a ZVT (Gnome only), and this allows extra options like pseudo-transparent backgrounds.

The user-list

The user-list contains every nick in the current channel. Nicks may have a green or yellow dot to the left of the nick. A green dot marks a chanop and a yellow dot shows the nick has a voice (e.g. can post to a moderated channel)

Below the list are a set of buttons, which are controlled from &dquot;Settings - User-list Buttons&dquot;. Clicking on one runs a certain command with reference to the selected nick in the user-list.

Right clicking on a nick brings up a pop-up menu which can be configured from &dquot;Settings - User-list Pop-up. Selecting one runs a certain command with reference to the clicked nick in the user-list.

Multiple nicks can be selected by holding down the Shift key.

The input box

To the left of the input box there is a label, containing your currently active nick, possibly with a yellow or green dot to the left of it see 3.4.

Entering text into the text box and pressing enter will process the entered text. It can be processed in 1 of 2 ways, it is either sent to the contained object (a channel or nick) or if it starts with a &dquot;/&dquot; it is processed as a command.

To the right of the input box is the conference toggle. When set this squashes all join/leave messages so you can have an uninterrupted conversation.

Getting Started

Firstly, if IRC is new to you then read section 1.2.

Startup XChat and select &dquot;Server List&dquot; in the &dquot;X-Chat&dquot; menu. This will display a list of default IRC servers. If you have your own IRC server you like then hit &dquot;New Server&dquot; and enter it's details at the bottom.

Now fill in your personal details at the top.

I will assume you are using a local server (not in the default list) of 127.0.0.1 and my nick of Nebulae. If you ever do use my nick I will NOT be happy, so choose one of your own or open /usr/dict/words and choose one from there.

Press connect and (hopefully) you will connect. The opening text will scroll down the main text-box with the MOTD (Message Of The Day). Once that has stopped click on the input box and type:

/join #dgg5ds

Make 'dgg5ds' anything you like. You should see a line saying <your nick> (<your address>) has joined #channel and your nick should show up in the user-list with a green dot by it showing that you are chanop (since you just created the channel). Since you just created the channel you'll also see a line saying you have given yourself chanop status.

If you type normal text (without a leading /) then you will see it come up in the channel with your nick before it. If anyone else was in the channel they would also see that.

Click in the text box in the tool-bar, type My Topic and hit enter. The topic of the channel is now My Topic, you will see a line telling you so. If you play about with the letter buttons on the tool-bar you can change the channel modes (more on this later).

If you hit too much too quickly you will see XChat &dquot;slow down&dquot;, this is because if you flood (send too much data too quickly) the server will drop the connection so XChat limits the amount of data it will send, this can make it seem slow, but it will always catch up in the end.

Now if you type /msg <your nick> Hello and hit enter in the input box (at the bottom) you send a private message to yourself, saying Hello. You wouldn't normally do this, if you have such bad hand-eye co-ordination that you need to type something and read it, you need to see a doctor, this is just for testing. A new window will be created under the current one, and its leaf will appear in the tool-bar, with the text in red to show that it has changed.

If you click on the new leaf the window will come to the top and you'll see the message Hello from yourself. When you type into the input box in this window the text will goto the object in the window, in this case yourself, in the last case the channel #dgg5ds. If you type anything you will see it echoed back at you. Since you aren't all that interested in messaging yourself (I hope) click the X button on the tool-bar (top - left) and the window will disappear, showing the first window.

Now if you select your nick in the user-list and hit the button marked Whois at the bottom of the user-list your whois information will be shown in the text box. This information comes from the server and can be read by anyone on IRC.

The whois information can also be accessed as a command. In the input box type /whois <your nick> and hit enter. Note the leading / showing it is a command, without this the text would be sent to the channel. The buttons map onto these commands, click the Settings menu and select User-list buttons. A dialog will appear showing each button and the command it runs when pressed, you can add your own. Note that %s in the command is replaced by the nick of the selected entry in the user-list.

Now if you right click your nick in the user-list a number of options come up. These map to commands like the buttons, select User-list Pop-up in the Settings menu.

The CTCP (Client To Client Protocol) options send a private message to the clicked nick which is picked up by their IRC client and dealt as a type of command. Almost always a CTCP message is sent back. These replies can be set in Settings - CTCP Replies. The CTCP VERSION reply is automatic and can be toggled by a /hidever command, but you can still setup a CTCP reply which is run as well as the automatic one.

If you are stuck typing /help -l (thats an lowercase L and a 1) might give you a hint.

Mailing Lists

XChat has two mailing lists which you may want to subscribe to, xchat-discuss and xchat-announce (kindly hosted by nl.linux.org). To subscribe send a message with no subject and this in the body:

subscribe list-name

to majordomo@nl.linux.org where list-name is either xchat-discuss or xchat-announce. You will be asked in a reply to confirm your subscription. xchat-discuss is a general mailing list where you can ask for help, bounce ideas etc off other XChat users. xchat-announce is a moderated list (only zed and I can post to it) where announcements (such as new versions) are posted. *Do not try to post to xchat-announce*.

If you have any queries about the mailing lists just mail me (Adam Langley) at agl@linuxpower.org.

Channel Modes

Each channel can have a series of modes. Only chanop's can change a channels' mode. The modes can either by set by the letter buttons on the right of the tool-bar or by using the /mode command. Modes can also be set by some other commands, like /op, /deop or /ban. The following is a list (which is not complete) of the channel modes.

T - Topic Lock - With this set only chanop's can change the channel topic N - No outside messages - Normally people not in a channel can /msg the channel, with this set only people who have joined the channel can send to it S - Secret - With this set the channel is not listed in the channel list (/list), except if you are in it. This cannot be set with Private (see below) P - Private - With this set the channel name and topic is not listed in the channel list (/list), except if you are in it. This cannot be set with Secret (see above) I - Invite Only - With this set people can't just /join the channel, they have to be /invite'ed by someone in the channel M - Moderated - With this set only chanop's and voice'ed nicks can send to the channel L - User Limit - With this set only a set number of people can join the channel K - Key - With this set anyone who tries the join the channel has to pass this key (also called the password) as argument 2 to the /join command B - Ban - This can be set more than once (with different options). Each person who tries to join the channel has to be outside all the bans. Simply setting a ban stops anyone who matches the bad from joining O - Op - This can be set more than once (with different options). Each nick that is set +o becomes a chanop

Scripts and Plugins

Scripts and Plugins allow you to extend XChat without editing the code. For information about writing them see section 7. Scripts are Perl scripts and to use them you must have Perl already on your system and have built Perl support in when building XChat. Plugins are shared libraries (.so files) that are dynamically linked and unlinked to the XChat process image.

On startup all files ending with .pl in ˜/.xchat are auto loaded. To load a script manually either use the /load command or select &dquot;Load Perl Script&dquot; from the &dquot;Scripts and Plugins&dquot; menu. To unload all scripts either use the /unloadall or select &dquot;Unload All Scripts&dquot; from the &dquot;Scripts and Plugins&dquot; menu.

To load a plugin either use the /loaddll command or select &dquot;Load Plugin&dquot; from the menu. The plugin should then be listed on a /listdll command and in the &dquot;Plugin List&dquot;. You can either remove plugins one by one with the /rmdll command or in the Plugin List, or you can unload all by selecting &dquot;Unload All Plugins&dquot; from the menu.

You don't have to manually unload scripts and plugins before quitting XChat. A list of scripts and plugins for download is on the .

DCC Support

DCC stands for Direct Client Connect. It is a system whereby two clients connect to each other directly, bypassing the IRC server. XChat supports sending 3 types of information across a DCC link:

Files - Text or binary Text -A direct chat link

You can send a file by using the &dquot;/dcc send nick file&dquot; command or by selecting the nick in the user-list and clicking the send button. The DCC send window should then show the status of the transmission. When someone sends a file to you the DCC Receive window will open up allowing you to accept or abort to transfer.

To setup a DCC chat line either use the &dquot;/dcc chat nick&dquot; command or select the nick from the user-list and click chat. Once the DCC connection is accepted any private /msg's to the nick will go across the DCC link instead. When someone offers a DCC chat link with you, you can accept with the command &dquot;/dcc chat offeringnick&dquot;

Customization

If you select Settings - User Commands then you get a dialog listing a set of shortcut commands. When you type any of the words in the left hand column as a command (with a leading /, of course) then the text on the right hand side is executed. Any %n (e.g. %2 or %3) are replaced with the nth argument to the command. Any &n (e.g. &2 or &3) are replaced with the nth argument and all following text, including spaces. %c is the current channel and %n is the current nickname. User commands can be separated with a ; (semicolon), but be careful not to put a space after the ;

The same goes for CTCP Replies, Userlist Buttons, Userlist Popup, but with one exception with Userlist Popup. With this you can create sub-menus by adding lines with a name of SEP and a value of the sub-menu name. To end the sub-menu use a list with a name of ENDSUB and a value of the same name.

Tab Nicks

Say you were in a channel with these nicks:

aaaaaaa aaaaaab Nebulae (yourself) zed

If you wanted to direct a message to zed you would type "zed: <message>" into the input box and hit enter. Rather than do that you can use Tab Nick Complete. Just type "z" and hit tab and XChat will find the first nick in the current channel that matches what you have typed and use that nick. In this case the text in the entry box would become "zed: ". Now if you wanted to direct a message to aaaaaab you would type "a" and hit tab. But that will find the first matching entry, which in this case is aaaaaaa so the input box would hold "aaaaaaa: " - not what you wanted. So hit Shift-Page Down and XChat uses the next entry in the user-list (Shift-Page Up uses the next up), the input box will now hold "aaaaaab: ". Next time you enter "a" and hit tab, however, XChat will select aaaaaab because by using the Shift-Page Down/Up buttons to tell it that it got the wrong nick and XChat will learn.

Replace

Now select Settings - Replace Popup. A list dialog will appear with a series of default entries (assuming you haven't changed them). One of the entries should by "r" and "are", if not add it. Now start typing into any input box and at some point type " r ". The "r" will change to "are".

The replace feature runs every time you hit space in an input box and finds the last word you typed. If that word is in the list it replaces it with its entry. If the word is in ' ' marks like 'r' the word is not replaced. If the word contains an "'" (that's a single quote mark) in it, the part before the quote mark is checked. If that part is found the part is replaced, the quote mark dropped and the part after the quote mark is appended. For example if you have the entry "u" and "you":

u - you u'r - your u''re - you're

Logging

If you go into Settings - Setup - Options and enable logging then each new session this is opened will be logged. Logs are put into ˜/.xchat/xchatlogs and have the format of servername,sessionname.xchatlog. For example, some entries from my logging directory:

us.elitenet.org,#linux.xchatlog irc-2.mint.net,#gimp.xchatlog ircnet.demon.co.uk,#linux.xchatlog

You can also use the No ServerName in Logs option, in which case the filenames of the logs do not have the server name prepended, thus:

#linux.xchatlog #gimp.xchatlog

Note that if you are on two channels with the same name the logs will mix

Panel support

With panel support enabled a new button appears next to the de/link button on the tool bar - it has a down arrow on it. This button panelizes the session. When you first click this a panel applet will appear. The panel applet is a label with "X-Chat" and a series of buttons. The direction of the buttons can be set in Settings->Setup->Options with the "Layout for a vertical panel" option. Note that currently you have to restart XChat to make this option come into effect. Each panelized session appears as a button in the panel applet. If the "Hide session on panelize" option is ticked the session is hidden when panelized. Clicking the button will show the session. The color of the text of the button will change as is normal (red or blue), and will set back when you focus on the session. Right clicking a panel button displays a list of items. At the top are 3 labels with the channel, server and tab state of the session. Under them are a series of buttons:

Close - Closes the session Remove - Removes the panel button Hide - Hides the session Show - Shows the session De/Link - Toggles the link state of the session Move here - Moves the session to the mouse position View - Shows the text box of the session at the mouse, when the mouse leaves the window the text box moves back to the session window

Print Events

As of 0.9.7 you can now change XChat's output strings. Open up Settings - Edit Event Texts to display the current settings.

At the top of the dialog is a list of all the events and the string that is displayed when that event happens. Just below is an edit box for changing the text. Then there is a text box that shows what the event will look like. Under that is a list of the options that is passed to the currently selected event (more on this later).

As an example we'll edit the event text for Join. First select join from the list at the top, it should be a first item. If it wasn't already the text in the edit box will show the Join event text. At first it looks a little complex but it really isn't, it breaks down like this:

%Cxx is a color - %C4 sets red and so on, '%C ' sets the default color (notice the space after it, forget the quote marks) %B toggles bold $x includes the option number x, as described in the bottom list $axxx adds a single byte with value xxx

So delete what is already in the edit box and type this:

%C4*%C *%C4*%C Hey! I can edit the events text! $1 joined $2 (host: $3)

The fist bit is the standard red, white, red stars that XChat uses. After that it's pretty clear. In the main XChat window wait for someone to join a channel you are on (note we changed the Join event *NOT* the You Joining event, so this only works for other people joining) and you will see something like:

*** Hey! I can edit the events text! Adam joined #a (host: ˜Adam@127.0.0.1)

The Sound file entry allows you to enter the name of a sound file that will be played (using the play command setting) each time the selected Event is triggered.

The 5 buttons at the bottom do thus:

Ok - closes and saves the dialog Test All - Shows all the events in the text box Load From - Loads a config file Save As - Saves to a config file Save - Saves to the default config file (loaded on startup) in ˜/.xchat/printevents.conf

Key Bindings

By selecting Settings - Edit Key Bindings you can edit the key bindings XChat uses. The key bindings are sorted by use - so the most recent used are at the top. A key binding is:

A modification (Ctrl, Alt and Shift keys) A keyname An action to perform 2 arguments to the action

To add a new key binding hit "Add new". An event with <none> will appear at the bottom. When you select it (or any binding) the widgets on the right change to reflect that binding. To change the key select the entry labeled key *and press the key*, *do not try to type in the name!*. The action to perform can be selected from the combo at the bottom and help on that action will appear in the text box at the bottom.

Changes in the dialog are always current. When the dialog is closed the key bindings information is written to ˜/.xchat/keybindings.conf

Settings Interface

No Server List On Startup - When set the server is not shown on program startup Auto Save URL List - Save the URL list on exit Double Click Command - The command that is run when a user in the userlist is double clicked. %s in the option is replaced with the nickname of that user before running.

IRC Input/Output

Nick Name Completion - When set text put in will be scanned for incomplete nicknames at the beginning and corrected. Also see tab nickname completion Time Stamp All Text - When set a time is printed at the beginning of every line Tab Nicks - When set nicknames and text are aligned with a tab Colored Nicks - When set nicknames are color coded Strip mIRC Color - When set all color codes in received text are stripped Filter out BEEP's - When set all BEEP codes are stripped Text Buffer Size - The number of lines a text box buffers (0 = all lines) ZVT Buffer Size - The number of lines a ZVT text box buffers

Window Layout

Channel Mode Buttons - When set the mode buttons are displayed on the tool bar User List Buttons - When set the command buttons under the userlist are displayed New Tabs to Front - When set new tabs are set to be the visible tab Channel Tabs - When set new channels are displayed in tabs Private Message Tabs - When set private dialogs are displayed in tabs Tabs at bottom - When set the tabs are put at the bottom of the notebook Use a separate tab/window for server messages - When this is set server messages are treated as a channel and are put in their own tab or window Disable Paned Userlist - When this is set the userlist cannot be paned across to be made bigger and is of fixed size

Mail Window

Left and Top set the initial position of the XChat window Width and Height set the size of the XChat window

Channel Windows & Dialog Windows

These two sections are the same except on what they effect

Normal Font - The font used for normal text Bold Font - The font used for bold text Background Picture - An image used in the background of the text box Use ZVT - When set a ZVT (Zed Virtual Terminal, no connection to zed) widget is used not a GTK text box Transparent Background - (only with ZVT) When set the background of the ZVT is pseudo-transparent Tint Transparency - (only with above) When set the transparent background is tinted

Panel

Hide Session on Panelize - When set the tab/window is hidden when panelized Layout For a Vertical Panel - When set the panel buttons are packed top to bottom

IRC

Raw Mode Display - When set modes are shown in raw IRC mode rather than descriptive texts Beep on Private Messages - When set the internal bell is sounded on a private message Quit Message - The text sent as a reason for you quitting DNS Lookup Program - The name of the program used to lookup IP's Auto ReConnect Delay - The number of seconds to wait before reconnecting to a server

IP Address

Autodetect hostname - When set the hostname is auto probed Autodetect IP address - When set the local IP is auto probed Hostname - If not auto probing this is the hostname IP address - If not auto probing this is the IP Get my IP from Server - (only if auto probing) Gets the IP address from the server

Away

Show away once - When set away messages are only seen once Announce away messages - When set your away message is broadcast Away Reason - The default away message given

Highlighting

Extra Words to Highlight on - Words other than your nickname that will trigger a highlight Hilighted Nick Color - The color set for highlighted nicks

Logging

Logging - When set logs are created in ˜/.xchat/xchatlogs No ServerName in logs - When set the names of the log files do not include the servername so #somechannel on two different servers are treated as the same file

Notification

Highlight Notifies - When set nicks in the userlist are set to a highlight color if they are on your notify list Notified User Color - The color used for the above Notify Check Interval - The number of seconds between checking the status of people on your notify list (0 = do not check)

DCC

Auto * - Automatically open the said window when a request/offer comes in

File Transfer

DCC Offers Timeout - The number of seconds before a DCC offer is removed (0 = disable) DCC Stall Timeout - The number of seconds before a stalled connection is dropped (0 = disable) File permissions - The permissions (in octal) of files created by DCC (0600 is suggested) Directory to save to - The directory in which DCC files are put Save file with Nickname - Prepend the nickname of the sender to the name of the DCC file Fast DCC Send - When set DCC doesn't wait for ACK's before sending the next packet

CTCP

Hide Version - When set VERSION requests are ignored Sound Dir - The directory to look for sounds Play Command - The command used to play sounds

Windows

These windows can be accessed from the Windows menu

Channel List

This window allows you to list all the channels on the server. The channels are filtered to only list channels with at least the number of users given in &dquot;Minimum Users&dquot;. &dquot;Refresh the list&dquot; clears the list and re-runs the search. &dquot;Save the list&dquot; allows you to write the list to a file while &dquot;Join Channel&dquot; joins you to the selected channel in the list.

Be aware that there can be thousands of channels and listing them can flood the connection. The only way to stop a running list is to disconnect.

DCC Send and DCC Receive

These windows show the status of all running DCC sends and receives. &dquot;Status&dquot; shows the status of the file. &dquot;File&dquot; gives the file name. &dquot;Size&dquot; gives the size, in bytes, of the file. &dquot;Position&dquot; gives the number of currently send of received bytes. &dquot;Ack&dquot; (only in Send) gives the number of acknowledged bytes. &dquot;CPS&dquot; gives the number of bytes sent/recv'ed per second. &dquot;From&dquot; gives the nickname of the sending or receiving person. If you have GNOME then you also have a column with the MIME type of the file.

The &dquot;Abort&dquot; button kills the send or receive while &dquot;Info&dquot; gives some extra information about the transaction.

Only in the Receive window are the &dquot;Accept&dquot; and &dquot;Resume&dquot; buttons. &dquot;Accept&dquot; accepts an offered file, while &dquot;Resume&dquot; does the same but continues a broken transaction.

The text of items in the DCC windows is now color coded with the state of the transaction.

DCC Chat

The DCC Chat window list all current DCC chat sessions. &dquot;To/From&dquot; gives the nick of the other peer. &dquot;Recv&dquot; gives the number of bytes received on the DCC link and &dquot;Send&dquot; gives the number of bytes sent. &dquot;StartTime&dquot; gives the time the link was opened.

Raw Log

The Raw Log window lists the raw data sent to, and received from, the server. Each new line of data is prefixed with either &dquot;<<&dquot; or &dquot;>>&dquot;. A &dquot;<<&dquot; means the rest of the line (after the space) was data to from XChat to the server, &dquot;>>&dquot; means the rest of the line (after the space) was data sent from the server to XChat. You can also hit Alt-s to save the rawlog - you will be prompted for a file name

URL Grabber

When an URL (Uniform Resource Locator) is seen in any window, it is placed in the URL Grabber list. This saves cutting and pasting from the window. The &dquot;Clear&dquot; button wipes the list. The &dquot;Lynx&dquot; and &dquot;Netscape&dquot; start lynx or netscape with the selected URL from the list.

Notify List

The notify list uses the ISON command to find any &dquot;friends&dquot; that may be on IRC. You use the /notify command to add and remove people from the list (it's a toggle function), then the notify list shows which of them are on, and which server they are using. The &dquot;Remove&dquot; button removes the currently selected nick form the notify list.

Lastlog

The Lastlog window allows you to search past text in the current window. Type in the search parameters (straight grep) into the text box at the bottom and the data in the current log is searched and all matching lines are written to the text box.

Ignore

This window controls XChat's ignore engine. This (as the name suggests) lets you setup rules to ignore people's messages. These rules are based on a host mask and a mask of what to ignore. The mask is in the format of Nickname!realname@host, so *!*@*.aol.com matches everyone on AOL and LameNick!*@* would match anyone with the nick of LameNick. The row of buttons along the middle gives the MASK of what to ignore:

CTCP - All CTCP messages (DCC Send, CTCP Ping etc) Private - All /msg's from them Channel - All channel messages from them Notice - All /notice messages from them Invite - All invite messages from them Unignore - Inverts the mask so you can ban *!*@*.aol.com then unignore.

The text boxes along the bottom show the number of times a certain type of message has been blocked. The unignore engine can also be accessed from the command line:

/ignore *!*@*.aol.com ALL /ignore myfriend!myfriend@*.aol.com ALL UNIGNORE (Would ignore everyone on AOL except myfriend).

How to help XChat Navigating the Code

The main source of XChat is in the /src directory. In it are all the .c and .h files that make up XChat. If you are looking round the code here's a little map:

xchat.c - Main program file, contains main() xchat.h - Main header file, contains most of the major struct's used in XChat editlist.c - Generic code for handling editable lists (like the Userlist Buttons list) fkeys.c - Handles function keys gtkutil.c - Wrappers round GTK outbound.c - Code for handling commands inbound.c - Code for handling data from the server text.c - Code for text handling and logging plugin.c - All the plugin code

Most of the other files are easy to guess.

Writing Scripts

Dagmar d'Surreal has written the documentation for writing scripts, in xchatdox2.html

Writing Plugins

There should be a sample module under the sample directory, this gives a general overview of writing a module.

Firstly you must #define USE_PLUGIN before any #includes. You must also include xchat.h and plugin.h from the xchat main directory. Every module must export a function called module_init, it is passed the version number (an int), a pointer to the module struct for your module and a pointer to the current session. It returns an int

0 = success 1 = fail

The name and desc parts of the module structure must be filled out with strings.

You must check the version number is what you think it is (currently 2) before referencing anything else, the current version number is defined in plugin.h as MODULE_IFACE_VER.

The basic hook onto XChat, by a plugin, is a signal. At certain places in the code a signal is emitted. A chain of handlers (if any) are then called, each calling the next. If the first handler (and thus the handler that returns to the emitting function) returns TRUE then the emitting function doesn't carry out the default action. In this way a signal handler can over-right XChat's default actions with its own. Any module can hook a signal, using hook_signal and passing a pointer to an xp_signal struct, filling in the &dquot;signal&dquot;, &dquot;callback&dquot;, &dquot;naddr&dquot; and &dquot;mod&dquot; parts. They should be filled in like thus:

signal - one of the XP_* defines in plugin.h callback - a pointer to a callback function passed 5 void *'s and a char. Use the XP_CALLBACK() define in plugin.h around it naddr - a pointer to a pointer (yes, double indirect) to a callback function (see last item) mod - your module handle, passed to you in module_init

At the end of the callback you use XP_CALLNEXT(naddrfunction, a, b, c, d, e, f) to call the next callback, a to f being the arguments you were passed. The plugin code in XChat updates the function pointed to by the &dquot;naddr&dquot; field to point to the next handler, or NULL if you are the last handler. You don't have to worry about that. If you don't want the default action to take place then use XP_CALLNEXT_ANDSET() not XP_CALLNEXT. Only 1 handler in a chain needs to use XP_CALLNEXT_ANDSET to abort the default action. Be aware that XP_CALLNEXT[_ANDSET] expand to include a return, so these must be at the end of the execution paths of your handler.

The signal handlers are passed 5 void *'s and a char (just seemed about enough), by convention the first void * is a pointer to the session or server struct. To cast as a signal callback use the define XP_CALLBACK like a GTK cast.

Most modules call module_add_cmds at some point. This hooks any commands for you without having to hook and parse all the command signals. You pass it a pointer to a struct module_cmd_set, which should be filled in like this:

mod - the module handle passed to module_init cmds - a pointer to an array of struct commands (see below)

See the sample module for an example of the array of struct commands. Be aware that the struct module_cmd_set must be global as XChat uses and changes it.

When the module is removed the module_cleanup function is called, it is passed the module struct and the current session. You do not have to export a module_cleanup as all commands and hooks are removed by XChat.

Plugins call XChat functions directly and thus are more dependent on the XChat code base than scripts. Some of the common XChat functions that are used are listed below:

PrintText (struct session *sess, char *text) - Prints &dquot;text&dquot; to the session &dquot;sess&dquot; handle_command (char *cmd, struct session *sess, int log) - Runs &dquot;cmd&dquot; as if it had been entered in the input box in session &dquot;sess&dquot;. If log == 1 then the command it put in the history

I have also written a much more complete (and working) example of a plugin, it's called auto and is on the the .

Signals

There is a list of all the current signals in plugins/SIGNALS. This may be added to in the future. If you think you have a good place for some more signals e-mail me (I'm Adam, see Authors). NOTE: This doesn't include text event signals, look in text.c for those details

I18n

i18n stands for internationalization (count the number of letters between the i and n). Since 0.9.8 multiple languages are supported. This effort is still continuing and at the moment only the menus are multi-language. To try and select support for your language type:

export LANG=xx

where xx is your two letter language code not country code. If you run a shell other than bash/sh you may need to change this syntax.

Authors

Many, many people have helped XChat, too many to list. You know who you are, thank you.

Peter Zelezny zed@linuxpower.org (Most of X-Chat) Erik Scrafford eriks@chilisoft.com (perl.c, lastlog.c, color.c) Adam Langley agl@linuxpower.org (plugins, this documentation, TextEvents, ...) Dagmar d'Surreal nospam@dsurreal.org (rfc1459 string compare util.c, see comments) Matthias Urlichs smurf@noris.de (Perl text events) David Herdeamn david@2gen.com (Ignore GUI, Tree serverlist, submenus in popups) Scott James Remnant scott@netsplit.com (Highlight notifies, Prefs GUI, IP settings)

Many others helped with other changes. If you submitted a patch and want your name included here, let zed@linuxpower.org know

Maintainers

Peter Zelezny (AKA: zed) puts together all the patches into one (hopefully) complete whole. He controls the web site and all 'real' releases of XChat come from him. He also handles the Freshmeat and GNOME AppList announcements. Anything in the ChangeLog without a name by it is usually his work. His e-mail address is zed@linuxpower.org.

Adam Langley (AKA: Nebulae) (that's me) handles the documentation and chunks of the code, mostly the signals and plugin code. Releases from me (just ask me for them on elitenet,#linux) are not 'real' releases and are not always stable.

Other people chip in code and ideas from time to time, mostly to zed, on Elitenet,#linux.

Patches should be mailed to Peter only unless it's against one of my releases. If you need advice or help on XChat firstly look though this document then ask someone on Elitenet,#linux - but beware the people on #linux are not support staff, they may just laugh at you ;)

Change Log

This lists the changes in each version of XChat. Please note that the ChangeLog file is the definitive reference.