xchat.sgml

The major functionality added in this release includes: - Rootless mode in X11 - Widget Templt

  <item>Hide Version - When set VERSION requests are ignored
  <item>Sound Dir - The directory to look for sounds
  <item>Play Command - The command used to play sounds
 </itemize></p>
 <sect>Windows
 <p>These windows can be accessed from the Windows menu
 </p>
 <sect1>Channel List
 <p>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.
 </p>
 <p>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.
 </p>
 <sect1>DCC Send and DCC Receive
 <p>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.
 </p>
 <p>The &dquot;Abort&dquot; button kills the send or receive while &dquot;Info&dquot;
 gives some extra information about the transaction.
 </p>
 <p>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. 
 </p>
 <p>The text of items in the DCC windows is now color coded with the state
 of the transaction.
 </p>
 <sect1>DCC Chat
 <p>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.
 </p>
 <sect1>Raw Log
 <p>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;&lt;&lt;&dquot; or &dquot;&gt;&gt;&dquot;.
 A &dquot;&lt;&lt;&dquot; means the rest of the line (after the space) was data
 to from XChat to the server, &dquot;&gt;&gt;&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
 </p>
 <sect1>URL Grabber
 <p>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.
 </p>
 <sect1>Notify List
 <p>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.
 </p>
 <sect1>Lastlog
 <p>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.
 </p>
 <sect1>Ignore
 <p>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:
 </p>
 <p>
 <itemize>
  <item>CTCP - All CTCP messages (DCC Send, CTCP Ping etc)
  <item>Private - All /msg's from them
  <item>Channel - All channel messages from them
  <item>Notice - All /notice messages from them
  <item>Invite - All invite messages from them
  <item>Unignore - Inverts the mask so you can ban *!*@*.aol.com then unignore.
 </itemize></p>
 <p>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:
 </p>
 <p>
 <code>/ignore *!*@*.aol.com ALL /ignore myfriend!myfriend@*.aol.com ALL UNIGNORE (Would ignore everyone on AOL except myfriend).
 </code></p>
 <sect>How to help XChat
 <sect1>Navigating the Code
 <p>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:
 </p>
 <p>
 <itemize>
  <item>xchat.c - Main program file, contains main()
  <item>xchat.h - Main header file, contains most of the major struct's used in
 XChat
  <item>editlist.c - Generic code for handling editable lists (like the Userlist
 Buttons list)
  <item>fkeys.c - Handles function keys
  <item>gtkutil.c - Wrappers round GTK
  <item>outbound.c - Code for handling commands
  <item>inbound.c - Code for handling data from the server
  <item>text.c - Code for text handling and logging
  <item>plugin.c - All the plugin code
 </itemize></p>
 <p>Most of the other files are easy to guess.
 </p>
 <sect1>Writing Scripts
 <p>Dagmar d'Surreal has written the documentation for writing scripts, in
 xchatdox2.html
 </p>
 <sect1>Writing Plugins
 <p>There should be a sample module under the sample directory, this gives
 a general overview of writing a module.
 </p>
 <p>Firstly you must &num;define USE_PLUGIN before any &num;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
 </p>
 <p>
 <itemize>
  <item>0 = success
  <item>1 = fail 
 </itemize></p>
 <p>The name and desc parts of the module structure must be filled out with
 strings.
 </p>
 <p>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.
 </p>
 <p>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:
 </p>
 <p>
 <itemize>
  <item>signal - one of the XP_* defines in plugin.h
  <item>callback - a pointer to a callback function passed 5 void *'s and a char.
 Use the XP_CALLBACK() define in plugin.h around it
  <item>naddr - a pointer to a pointer (yes, double indirect) to a callback function
 (see last item)
  <item>mod - your module handle, passed to you in module_init
 </itemize></p>
 <p>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&lsqb;_ANDSET&rsqb; expand to include a return, so these must be
 at the end of the execution paths of your handler.
 </p>
 <p>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.
 </p>
 <p>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:
 </p>
 <p>
 <itemize>
  <item>mod - the module handle passed to module_init 
  <item>cmds - a pointer to an array of struct commands (see below)
 </itemize></p>
 <p>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.
 </p>
 <p>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.
 </p>
 <p>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:
 </p>
 <p>
 <itemize>
  <item>PrintText (struct session *sess, char *text) - Prints &dquot;text&dquot;
 to the session &dquot;sess&dquot;
  <item>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
 </itemize></p>
 <p>I have also written a much more complete (and working) example of a plugin,
 it's called auto and is on the the <url url="http://xchat.linuxpower.org" name="XChat homepage">.
 </p>
 <sect2>Signals
 <p>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
 </p>
 <sect>I18n
 <p>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:
 </p>
 <p>
 <verb>export LANG=xx
 </verb></p>
 <p>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.
 </p>
 <sect>Authors
 <p>Many, many people have helped XChat, too many to list. You know who you
 are, thank you.
 </p>
 <p>
 <itemize>
  <item>Peter Zelezny [e-mail] (Most of X-Chat) 
  <item>Erik Scrafford [e-mail] (perl.c, lastlog.c, color.c) 
  <item>Adam Langley [e-mail] (plugins, this documentation, TextEvents,
 ...)
  <item>Dagmar d'Surreal [e-mail] (rfc1459 string compare util.c, see
 comments)
  <item>Matthias Urlichs [e-mail] (Perl text events)
  <item>David Herdeamn [e-mail] (Ignore GUI, Tree serverlist, submenus in
 popups)
  <item>Scott James Remnant [e-mail] (Highlight notifies, Prefs GUI,
 IP settings)
 </itemize></p>
 <p>Many others helped with other changes. If you submitted a patch and want
 your name included here, let [e-mail] know
 </p>
 <sect1>Maintainers
 <p>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 [e-mail].
 </p>
 <p>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,&num;linux) are not 'real' releases and are not always
 stable.
 </p>
 <p>Other people chip in code and ideas from time to time, mostly to zed, on
 Elitenet,&num;linux.
 </p>
 <p>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,&num;linux - but beware the people on &num;linux are
 not support staff, they may just laugh at you ;)
 </p>
 <sect>Change Log
 <p>This lists the changes in each version of XChat. Please note that the ChangeLog
 file is the definitive reference.
 </p>


 </article>