1 Plouf's Java IRC Client Applet
2 ------------------------------
10 Thank you for using PJIRC! You'll find in this document all information you
11 might need in order to understand what is PJIRC, how it works and how to
12 install it. Please read it before asking questions on forums or even
13 directly to the author.
15 PJIRC is an IRC client, just like Opera is a HTTP client. PJIRC is just
16 another front-end for the well-known IRC network. You're supposed to be
17 familiar with the IRC concepts. If not, you should try to find more
18 information about it before going further in this document and trying
19 to install and use PJIRC.
21 PJIRC has two distinct parts : the IRC engine and the GUI. The IRC engine
22 handles all the boring and uninteresting stuff such as managing the
23 connection, formatting messages and so on. You might think of it as being
24 the "kernel". On the other hand, the GUI is responsible for displaying
25 the result with a nice layout using plenty of CPU-consuming graphical
28 There are several PJIRC GUI's, and you can choose the one you prefer. You
29 might think of them as "skins", but they are much more than that. The
30 standard PJIRC package comes with a default GUI, the "Pixx GUI". You should
31 find its specific documentation within this package. This document will
32 only describe the IRC engine part.
37 The following files are part of the IRC engine :
38 IRCApplet.class : Main Applet class file.
39 irc.jar : IRC Engine for non-IE VM, signed mode.
40 irc.cab : IRC Engine for IE VM, both mode.
41 securedirc.cab : IRC Signed specific part engine for IE VM, signed mode.
42 irc-unsigned.jar : IRC Engine for non-IE VM, unsigned mode.
44 The cab files are only recognized by Internet Explorer. jar files
45 are recognized by other Browsers or Java Virtual Machines. The class
46 file is some kind of "executable file", think of it as being the
47 "file that you execute" when you launch PJIRC.
49 PJIRC can works in the modes : the "signed" mode and the "unsigned" mode.
50 It is recommanded that you use the "signed" mode unless you have
51 specific reasons to switch to unsigned mode. The mode PJIRC uses depends
52 of the file you will tell it to use in the HTML Applet Fragment (see
58 The unsigned IRC Engine can be built using the following javac compiler
60 javac -nowarn -g:none -O -target 1.1 IRCApplet.java
61 javac -nowarn -g:none -O -target 1.1 irc\style\*.java
62 javac -nowarn -g:none -O -target 1.1 irc\tree\*.java
63 javac -nowarn -g:none -O -target 1.1 irc\dcc\prv\*.java
64 javac -nowarn -g:none -O -target 1.1 irc\gui\prv\*.java
65 javac -nowarn -g:none -O -target 1.1 irc\gui\common\*.java
66 javac -nowarn -g:none -O -target 1.1 irc\ident\prv\*.java
67 javac -nowarn -g:none -O -target 1.1 irc\gui\prv\*.java
71 Just upload the files you need, in regard to the mode (signed or unsigned)
72 you want. Upload any extra files, such as language files or images and
77 Using signed mode and the Pixx GUI, the following minimal applet fragment
78 should work just fine :
80 <applet code=IRCApplet.class archive="irc.jar,pixx.jar" width=640 height=400>
81 <param name="CABINETS" value="irc.cab,securedirc.cab,pixx.cab">
82 <param name="nick" value="Anonymous">
83 <param name="name" value="PJIRC User">
84 <param name="host" value="irc.diboo.net">
85 <param name="gui" value="pixx">
90 A test tool is available at http://www.pjirc.com/check.
91 This tool will detect common errors and mistakes.
95 A server is any entity the client (PJIRC) connects to. There
96 are three types of servers :
97 - IRC server : usually referred as "the server", this is
98 the server PJIRC was designed to connect to.
100 - DCC server : a DCC (for Direct Client to Client) is a
101 special server for handling direct
102 connections to other clients.
104 - Null server : the Null server is a ghost server,
105 physically connected to nothing.
109 The term "source" will be used throughout the remaining of this
110 document. In short, a "source" stands for any "window" that can
111 receive or send text or data to or from a server. A Channel is a
112 Source, bound to an IRC server. A DCCChat is also a source, but
113 bound to a DCC server. Here is the list of all known sources :
115 - Default : not bound to anything (bound to the Null server),
116 the Default source is used to handle any
117 server-independent operations. This source
118 cannot be left. It is only present if multiserver
121 - Status : bound to an IRC server, the Status is used for
122 any IRC server-specific operations or notifications.
123 Leaving this source will lead to the server
124 disconnection and eventually to all any sources
125 related to this server. This source is unique and
126 cannot be left is multiserver support is disabled.
128 - Query : bound to an IRC server, the Query is a private
129 chat between two clients, via the IRC server. This
130 source can be left at any time.
132 - Channel : bound to an IRC server, the Channel is a
133 public room where many clients can chat, via
134 the IRC server. This source can be left at
135 any time, provided it is not restricted to do
136 so by the application configuration. Leaving
137 this source may sometimes take several seconds
138 since a feedback from the server is required.
140 - ChanList : bound to an IRC server, the ChanList enumerates
141 the listing of all available Channels on the
142 IRC server. This source can be left at any time.
144 - DCCChat : bound to a DCC server, the DCCChat is a private
145 chat between two clients, via the DCC server. This
146 source can be left at any time. Leaving this
147 source will lead to the DCC server disconnection.
149 - DCCFile : bound to a DCC server, the DCCFile is a special
150 source used for transmitting files from a client
151 to another, via the DCC server. This source can
152 be left at any time. Leaving this source will
153 lead to the DCC server disconnection.
157 parameters are passed to the applet via the following syntax :
158 <param name="name" value="value">
163 nick : default nick to be used. '?' characters will be replaced by random
166 <param name="nick" value="Guest??"> will tell the applet to use nicks
169 name : "real" user name, sent to IRC server.
171 <param name="name" value="UserName">
173 host : IRC server host.
175 <param name="host" value="irc.server.net">
177 gui : PJIRC graphical user interface.
179 <param name="gui" value="pixx">
185 port : IRC server port. By default, the port is 6667.
189 <param name="port" value="6667">
191 commandX, with X a figure : Tells the applet to execute this command once
192 -------- connected to the server.
194 The first command MUST be command1, and there can
195 be no "gap" in the numbers : the command14 MUST be
196 after command13, and NOT after command12.
198 If the command is not prefixed by /, then the
199 string is passed as it to the server. Otherwise,
200 it is sent through the status window interpretor.
203 <param name="command1" value="/nickserv identify password">
204 <param name="command2" value="/join #channel">
206 language : sets the langage to be used. The name corresponds to a langage file
207 -------- that must be accessible from the applet. For example, if there is
208 a file lang/mylang.lng, then you may enter value="lang/mylang".
209 By default, the langage is english.
212 <param name="language" value="french">
214 quitmessage : sets the quit message. By default, this message is empty.
218 <param name="quitmessage" value="PJIRC forever!">
220 asl : enable or disable asl handling. Asl (for age, sex and localtion) is
221 --- parsed from the full user name. Other parts of the software may behave
222 differently provided the nick is male or female, its age, and so on...
223 The full name format is expected to be "age sex localtion", for instance
224 "22 m Belgium". By default, asl is disabled.
227 <param name="asl" value="true">
229 aslmale : set the string corresponding to the male gender in the full name for
230 ------- asl parsing. Default value is "m".
233 <param name="aslmale" value="m">
235 aslfemale : set the string corresponding to the female gender in the full name
236 --------- for asl parsing. Default value is "f".
239 <param name="aslfemale" value="f">
241 aslunknown : set the string corresponding to the unknown gender in the full name
242 ---------- for asl parsing. Default value is "x".
245 <param name="aslunknown" value="x">
247 useinfo : replace the status window by the info window. The info window acts
248 ------- exactly as the status window, but only shows motd and welcome
249 messages. Since whois etc... results are no more shown, popup
250 commands such as whois, finger, etc... are disabled. By default,
251 the info window is disabled.
254 <param name="useinfo" value="false">
256 soundbeep : set the beep sound. The beep sound is the sound played when the
257 --------- /beep command is used. The file must be in .au format.
260 <param name="soundbeep" value="snd/bell2.au">
262 soundquery : set the incoming private sound. The sound is played when a new
263 ---------- private source is opened.
266 <param name="soundquery" value="snd/ding.au">
268 password : set the server password on connection.
272 <param name="password" value="mysecretpassword">
274 alternatenick : set the alternate nickname, to be used if primary nickname is
275 ------------- already used on the server.
278 <param name="alternatenick" value="someothernick">
280 languageencoding : set the language file encoding to be used. If not
281 ---------------- specified, default encoding will be used.
284 <param name="languageencoding" value="UnicodeLittle">
286 authorizedjoinlist : set the list of channels the user is authorized to join.
287 ------------------ Syntax is "all-#channel1-#channel2-..." or
288 "none+#channel1+#channel2+...". By default, authorized
292 <param name="authorizedjoinlist" value="none+#mychannel">
294 authorizedleavelist : set the list of channels the user is authorized to
295 ------------------- leave. Syntax is "all-#channel1-#channel2-..." or
296 "none+#channel1+#channel2+...". By default, authorized
300 <param name="authorizedleavelist" value="all-#mychannel">
302 authorizedcommandlist : set the list of command the user is athorized to do.
303 --------------------- Syntax is "all-command1-command2-..." or
304 "none+command1+command2+...". By default, authorized
305 command list is "all". Don't prefix the command with
308 <param name="authorizedcommandlist" value="none+me">
311 coding : specify what encoding algorithm should be used for sending the text
312 ------ to the irc server. By default, encoding 1 is used. Values are :
313 0 : strict ascii, MSB is dropped, shouldn't be used.
314 1 : pjirc unicode to ascii protocol, charcode is sent as it if
315 below than \u0x00ff. Should be used if pjirc is used with
316 other non UTF-8 compatible clients.
318 3 : local charset coding, should be avoided when possible for
319 compatibility reasons
322 <param name="coding" value="2">
324 lngextension : modify the default lng file extension. By default, lng
325 ------------ extension is "lng".
328 <param name="lngextension" value="txt">
330 userid : set the userid. The user id will be used for ident id and for
331 ------ user name at connect-time. If the id is empty, then full name
332 will be used for id, and nickname will be used as username
333 at connect time. By default, userid is empty.
336 <param name="userid" value="myname">
338 autoconnection : set whether the applet should try to trigger connection
339 -------------- as soon at it is launched. By default, the applet will
343 <param name="autoconnection" value="false">
345 useidentserver : enable or disable the ident server. By default, the
346 -------------- server is enabled.
349 <param name="useidentserver" value="false">
351 mutliserver : enable or disable the multiserver support. By default,
352 ----------- multiserver is disabled.
355 <param name="multiserver" value="true">
357 alternateserverI : set the Ith alternate server. Syntax is
358 ---------------- "host port" or "host port password".
361 <param name="alternateserver1" value="irc.secondhost.com 6667">
363 serveralias : set the default server alias. By default, server alias
364 ----------- is empty string.
367 <param name="serveralias" value="Alias">
369 noasldisplayprefix : set the "no display asl" full name prefix. If the
370 ------------------ user's full name begins with this prefix, then
371 the floating asl window won't be displayed. An
372 empty string disables this feature. By default,
375 <param name="noasldisplayprefix" value="true">
377 pluginX : set the Xth plugin to be loaded at startup.
381 <param name="plugin1" value="MyPlugin">
383 soundwordX : set the Xth sound configuration. Syntax is "word sound". When
384 ---------- "word" is detected in a message, then "sound" is played.
387 <param name="soundword1" value="lol snd/lol.au">
389 fingerreply : set the finger reply.
393 <param name="fingerreply" value="A lucky Plouf's IRC user">
395 userinforeply : set the user info reply.
399 <param name="userinforeply" value="A lucky Plouf's IRC user">
401 fileparameter : URL to the file containing all PJIRC parameters.
402 ------------- The configuration file format is the same as the
403 pjirc.cfg file. If other parameters are specified
404 using the html tags, they will be mixed.
407 <param name="fileparameter" value="pjirc.cfg">
409 aslseparatorstring : set the asl separator string. When the ASL parser
410 ------------------ reach this string, the parsing stops and any text
411 being found after this string (including the
412 separator) will be ignored.
415 <param name="aslseparatorstring" value="|">
417 allowdccchat : set whether dcc chat is allowed. By default, this is
421 <param name="allowdccchat" value="false">
423 allowdccfile : set whether dcc file is allowed. By default, this is
427 <param name="allowdccfile" value="false">
429 disablequeries : disable all queries. By default, this is not enabled.
433 <param name="disablequeries" value="true">
439 'Style' is the name of the library used inside PJIRC for text display. Even
440 if this display has nothing to do with the actual irc engine, a majority
441 of all GUI's are likely to use it. As a consequence, 'Style' is included in
442 the engine package. All 'Style' parameters are prefixed by 'style:'.
445 righttoleft : set right-to-left display, instead of left-to-right default
449 <param name="style:righttoleft" value="true">
451 sourcecolorruleN : set the Nth source color rule. Rule syntax is
452 ---------------- "type name index1=color1 index2=color2 ...".
455 <param name="style:sourcecolorrule1" value="none+Channel all 0=00ff00">
456 <param name="style:sourcecolorrule2" value="none+Query none+some_nick 0=000000 1=ffffff">
458 sourcefontruleN : set the Nth source font rule. Rule syntax is
459 ---------------- "type name fontname fontsize".
462 <param name="style:sourcefontrule1" value="none+Channel all Arial 12">
465 backgroundimage : toggle master background image switch. If this flag is
466 --------------- turned off, all background images will be ignored. By
467 default, background images are disabled.
470 <param name="style:backgroundimage" value="true">
472 backgroundimageX : background image configuration number X. Syntax is
473 ---------------- "sourcetype sourcename tiling image" with sourcetype and
474 sourcename the target source type and name, tiling a
475 figure and image the image file name. Valid source types
476 are DCCChat, Channel, Query, Status, ChanList and Default.
477 As for the command parameter, there can't be any gap in the
480 Possible tiling values are:
490 <param name="style:backgroundimage1" value="none+channel none+#happy 1 img/content.gif">
491 <param name="style:backgroundimage2" value="none+Query all 2 img/soleil.gif">
493 bitmapsmileys : enable or disable bitmap smileys. Once enabled, bitmaps are
494 ------------- defined via the smiley parameter. By default, bitmap smileys
498 <param name="style:bitmapsmileys" value="true">
500 smileyX : set the Xnth smiley. A smiley is a pair of text->image. Each time
501 ------- the text is found on a line, it will be replaced by the
502 corresponding image. As for the command parameter, the first smiley
503 must be smiley1 and there must'nt be any gap. The format of the
504 parameter is "text image", where image is any URL the applet can
508 <param name="style:smiley1" value=":) img/smile.gif">
509 <param name="style:smiley2" value=":( img/sad.gif">
511 floatingasl : activate "mouseover" floating asl information. By default,
512 ----------- floating asl is disabled. "asl" parameter may be also activated,
513 but this is not mandatory.
516 <param name="style:floatingasl" value="true">
518 floatingaslalpha : set the floating asl alpha transparency value. Between 0
519 ---------------- and 255, 0 is invisible and 255 fully opaque. By default,
520 alpha value is 170. This parameter may be ignored if the
521 java virtual machine doens't support transparency.
524 <param name="style:floatingaslalpha" value="150">
526 linespacing : set the additional space that will be used between two lines
527 ----------- of text. Default value is zero. Unit is pixel.
530 <param name="style:linespacing" value="10">
532 maximumlinecount : set the maximum line count in the history buffer. This
533 ---------------- can save memory for very long chats. Default value is
537 <param name="style:maximumlinecount" value="256">
539 highlightlinks : highlight links when mouse moves over them. By default,
540 -------------- this is not enabled.
543 <param name="style:highlightlinks" value="true">
547 The Pixx's GUI documentation is available in a separate file in the default
548 package. All GUI parameters begins with 'gui:', where gui is the name of the
549 gui. For instance, any Pixx GUI specific parameter will begin by 'pixx:'.
554 PJIRC is designed to support events from the "outside". The applet supports
555 the following methods :
557 void sendString(String str) : send the given string to the server, through
558 the current source interpretor. For instance,
559 you can bring the channel list window by
560 calling sendString("/list")
562 void setFieldText(String txt) : set the textfield content.
564 String getFieldText() : get the textfield content. setFieldText and
565 getFieldText can be combined to append text for the
566 user. For instance, adding a smiley can be done using
567 setFieldText(getFieldText()+':)')
569 void validateText() : validate the current textfield content, as if the user
570 pressed the return key.
572 void requestSourceFocus() : request the active source to gain focus.
574 void sendPluginEvent(String pluginName,Object event) : send the given event
578 Object getPluginValue(String pluginName,Object valueName) : Get the plugin
583 Minimal html fragment
584 ---------------------
586 <applet code=IRCApplet.class archive="irc.jar,securedirc.jar" width=640 height=400>
587 <param name="CABINETS" value="irc.cab,securedirc.cab">
589 <param name="nick" value="Anonymous???">
590 <param name="name" value="Java User">
591 <param name="host" value="irc.dal.net">
592 <param name="gui" value="pixx">
599 A runtime command is any text prefixed by the / character. If the so-called
600 interpretor recognize a command, it will parse and handle it. If not, the
601 command will be sent as it (but without the initial / character) to the
604 Here are the list of all recognized commands.
606 ame %message : send an action to all active channels
607 amsg %message : send a message to all active channels
608 away [%message] : configure the away status
609 beep : send a beep to the speakers
610 clear : clear the window
611 ctcp %command [%parameters] : send a ctcp request to the given nick
612 dcc %nick : send a dcc request to the given nick
613 disconnect : disconnect from the server
614 echo %message : echo the specified text to the active source
615 hop : leave and rejoin the active channel
616 ignore %nick : ignore the specified nick
617 j %channel [%password] : join the given channel
618 join %channel [%password] : same as j
619 kick %nick : kick the given nick
620 leave : leave the active source
621 load %plugin : load the given plugin
622 me %message : send an action to the active source
623 msg %target %message : send a message to the given target
624 newserver %alias %host [%port [%password]] : create a new server status
625 notice %target %message : send a notice to the given target
626 onotice %target %message : send a notice to all operators at the given target
628 ping : ping the given nickname
629 play %sound : play the given sound, only on the local client
630 query %nick : query the given nickname
631 quit [%message] : same as disconnect, but with the given message
632 raw %command : send a raw command to the server
633 server %host [%port [%password]] : connect to the given server
634 sound %soundfile : play the given sound on the client and all other clients on the source
635 sleep %millis : freeze the interpretor for the given amount of milliseconds
636 topic %channel %topic : change the given channel's topic
637 unignore %nick : unignore the specified nick
638 unload %plugin : unload the specified plugin
639 url %url [%target] : open the given url on a new browser window
644 PJIRC is developped by Plouf - plouf@pjirc.com
645 Have a look at http://www.pjirc.com/ for news about PJIRC.
646 PJIRC has an official italian website on http://www.pjirc.it
647 PJIRC has a CVS repository at SourceForge - http://sourceforge.net/projects/pjirc