1 Plouf's Java IRC Client Applet
\r
2 ------------------------------
\r
10 Thank you for using PJIRC! You'll find in this document all information you
\r
11 might need in order to understand what is PJIRC, how it works and how to
\r
12 install it. Please read it before asking questions on forums or even
\r
13 directly to the author.
\r
15 PJIRC is an IRC client, just like Opera is a HTTP client. PJIRC is just
\r
16 another front-end for the well-known IRC network. You're supposed to be
\r
17 familiar with the IRC concepts. If not, you should try to find more
\r
18 information about it before going further in this document and trying
\r
19 to install and use PJIRC.
\r
21 PJIRC has two distinct parts : the IRC engine and the GUI. The IRC engine
\r
22 handles all the boring and uninteresting stuff such as managing the
\r
23 connection, formatting messages and so on. You might think of it as being
\r
24 the "kernel". On the other hand, the GUI is responsible for displaying
\r
25 the result with a nice layout using plenty of CPU-consuming graphical
\r
28 There are several PJIRC GUI's, and you can choose the one you prefer. You
\r
29 might think of them as "skins", but they are much more than that. The
\r
30 standard PJIRC package comes with a default GUI, the "Pixx GUI". You should
\r
31 find its specific documentation within this package. This document will
\r
32 only describe the IRC engine part.
\r
37 The following files are part of the IRC engine :
\r
38 IRCApplet.class : Main Applet class file.
\r
39 irc.jar : IRC Engine for non-IE VM, signed mode.
\r
40 irc.cab : IRC Engine for IE VM, both mode.
\r
41 securedirc.cab : IRC Signed specific part engine for IE VM, signed mode.
\r
42 irc-unsigned.jar : IRC Engine for non-IE VM, unsigned mode.
\r
44 The cab files are only recognized by Internet Explorer. jar files
\r
45 are recognized by other Browsers or Java Virtual Machines. The class
\r
46 file is some kind of "executable file", think of it as being the
\r
47 "file that you execute" when you launch PJIRC.
\r
49 PJIRC can works in the modes : the "signed" mode and the "unsigned" mode.
\r
50 It is recommanded that you use the "signed" mode unless you have
\r
51 specific reasons to switch to unsigned mode. The mode PJIRC uses depends
\r
52 of the file you will tell it to use in the HTML Applet Fragment (see
\r
58 The unsigned IRC Engine can be built using the following javac compiler
\r
60 javac -nowarn -g:none -O -target 1.1 IRCApplet.java
\r
61 javac -nowarn -g:none -O -target 1.1 irc\style\*.java
\r
62 javac -nowarn -g:none -O -target 1.1 irc\tree\*.java
\r
63 javac -nowarn -g:none -O -target 1.1 irc\dcc\prv\*.java
\r
64 javac -nowarn -g:none -O -target 1.1 irc\gui\prv\*.java
\r
65 javac -nowarn -g:none -O -target 1.1 irc\gui\common\*.java
\r
66 javac -nowarn -g:none -O -target 1.1 irc\ident\prv\*.java
\r
67 javac -nowarn -g:none -O -target 1.1 irc\gui\prv\*.java
\r
71 Just upload the files you need, in regard to the mode (signed or unsigned)
\r
72 you want. Upload any extra files, such as language files or images and
\r
75 Applet html fragment
\r
76 --------------------
\r
77 Using signed mode and the Pixx GUI, the following minimal applet fragment
\r
78 should work just fine :
\r
80 <applet code=IRCApplet.class archive="irc.jar,pixx.jar" width=640
\r
82 <param name="CABINETS" value="irc.cab,securedirc.cab,pixx.cab">
\r
83 <param name="nick" value="Anonymous">
\r
84 <param name="fullname" value="PJIRC User">
\r
85 <param name="host" value="irc.diboo.net">
\r
86 <param name="gui" value="pixx">
\r
91 A test tool is available at http://www.pjirc.com/check.
\r
92 This tool will detect common errors and mistakes.
\r
96 A server is any entity the client (PJIRC) connects to. There
\r
97 are three types of servers :
\r
98 - IRC server : usually referred as "the server", this is
\r
99 the server PJIRC was designed to connect to.
\r
101 - DCC server : a DCC (for Direct Client to Client) is a
\r
102 special server for handling direct
\r
103 connections to other clients.
\r
105 - Null server : the Null server is a ghost server,
\r
106 physically connected to nothing.
\r
110 The term "source" will be used throughout the remaining of this
\r
111 document. In short, a "source" stands for any "window" that can
\r
112 receive or send text or data to or from a server. A Channel is a
\r
113 Source, bound to an IRC server. A DCCChat is also a source, but
\r
114 bound to a DCC server. Here is the list of all known sources :
\r
116 - Default : not bound to anything (bound to the Null server),
\r
117 the Default source is used to handle any
\r
118 server-independent operations. This source
\r
119 cannot be left. It is only present if multiserver
\r
120 support is enabled.
\r
122 - Status : bound to an IRC server, the Status is used for
\r
123 any IRC server-specific operations or notifications.
\r
124 Leaving this source will lead to the server
\r
125 disconnection and eventually to all any sources
\r
126 related to this server. This source is unique and
\r
127 cannot be left is multiserver support is disabled.
\r
129 - Query : bound to an IRC server, the Query is a private
\r
130 chat between two clients, via the IRC server. This
\r
131 source can be left at any time.
\r
133 - Channel : bound to an IRC server, the Channel is a
\r
134 public room where many clients can chat, via
\r
135 the IRC server. This source can be left at
\r
136 any time, provided it is not restricted to do
\r
137 so by the application configuration. Leaving
\r
138 this source may sometimes take several seconds
\r
139 since a feedback from the server is required.
\r
141 - ChanList : bound to an IRC server, the ChanList enumerates
\r
142 the listing of all available Channels on the
\r
143 IRC server. This source can be left at any time.
\r
145 - DCCChat : bound to a DCC server, the DCCChat is a private
\r
146 chat between two clients, via the DCC server. This
\r
147 source can be left at any time. Leaving this
\r
148 source will lead to the DCC server disconnection.
\r
150 - DCCFile : bound to a DCC server, the DCCFile is a special
\r
151 source used for transmitting files from a client
\r
152 to another, via the DCC server. This source can
\r
153 be left at any time. Leaving this source will
\r
154 lead to the DCC server disconnection.
\r
158 parameters are passed to the applet via the following syntax :
\r
159 <param name="name" value="value">
\r
161 Mandatory parameters
\r
162 --------------------
\r
164 nick : default nick to be used. '?' characters will be replaced by random
\r
167 <param name="nick" value="Guest??"> will tell the applet to use nicks
\r
170 fullname : "real" user name, sent to IRC server.
\r
172 <param name="fullname" value="UserName">
\r
174 host : IRC server host.
\r
176 <param name="host" value="irc.server.net">
\r
178 gui : PJIRC graphical user interface.
\r
180 <param name="gui" value="pixx">
\r
183 Optional parameters
\r
184 -------------------
\r
186 port : IRC server port. By default, the port is 6667.
\r
190 <param name="port" value="6667">
\r
192 commandX, with X a figure : Tells the applet to execute this command once
\r
193 -------- connected to the server.
\r
195 The first command MUST be command1, and there can
\r
196 be no "gap" in the numbers : the command14 MUST be
\r
197 after command13, and NOT after command12.
\r
199 If the command is not prefixed by /, then the
\r
200 string is passed as it to the server. Otherwise,
\r
201 it is sent through the status window interpretor.
\r
204 <param name="command1" value="/nickserv identify password">
\r
205 <param name="command2" value="/join #channel">
\r
207 language : sets the langage to be used. The name corresponds to a langage file
\r
208 -------- that must be accessible from the applet. For example, if there is
\r
209 a file lang/mylang.lng, then you may enter value="lang/mylang".
\r
210 By default, the langage is english.
\r
213 <param name="language" value="french">
\r
215 quitmessage : sets the quit message. By default, this message is empty.
\r
219 <param name="quitmessage" value="PJIRC forever!">
\r
221 asl : enable or disable asl handling. Asl (for age, sex and localtion) is
\r
222 --- parsed from the full user name. Other parts of the software may behave
\r
223 differently provided the nick is male or female, its age, and so on...
\r
224 The full name format is expected to be "age sex localtion", for instance
\r
225 "22 m Belgium". By default, asl is disabled.
\r
228 <param name="asl" value="true">
\r
230 aslmale : set the string corresponding to the male gender in the full name for
\r
231 ------- asl parsing. Default value is "m".
\r
234 <param name="aslmale" value="m">
\r
236 aslfemale : set the string corresponding to the female gender in the full name
\r
237 --------- for asl parsing. Default value is "f".
\r
240 <param name="aslfemale" value="f">
\r
242 aslunknown : set the string corresponding to the unknown gender in the full
\r
243 ---------- name for asl parsing. Default value is "x".
\r
246 <param name="aslunknown" value="x">
\r
248 useinfo : replace the status window by the info window. The info window acts
\r
249 ------- exactly as the status window, but only shows motd and welcome
\r
250 messages. Since whois etc... results are no more shown, popup
\r
251 commands such as whois, finger, etc... are disabled. By default,
\r
252 the info window is disabled.
\r
255 <param name="useinfo" value="false">
\r
257 soundbeep : set the beep sound. The beep sound is the sound played when the
\r
258 --------- /beep command is used. The file must be in .au format.
\r
261 <param name="soundbeep" value="snd/bell2.au">
\r
263 soundquery : set the incoming private sound. The sound is played when a new
\r
264 ---------- private source is opened.
\r
267 <param name="soundquery" value="snd/ding.au">
\r
269 password : set the server password on connection.
\r
273 <param name="password" value="mysecretpassword">
\r
275 alternatenick : set the alternate nickname, to be used if primary nickname is
\r
276 ------------- already used on the server.
\r
279 <param name="alternatenick" value="someothernick">
\r
281 languageencoding : set the language file encoding to be used. If not
\r
282 ---------------- specified, default encoding will be used.
\r
285 <param name="languageencoding" value="UnicodeLittle">
\r
287 authorizedjoinlist : set the list of channels the user is authorized to join.
\r
288 ------------------ Syntax is "all-#channel1-#channel2-..." or
\r
289 "none+#channel1+#channel2+...". By default, authorized
\r
290 join list is "all".
\r
293 <param name="authorizedjoinlist" value="none+#mychannel">
\r
295 authorizedleavelist : set the list of channels the user is authorized to
\r
296 ------------------- leave. Syntax is "all-#channel1-#channel2-..." or
\r
297 "none+#channel1+#channel2+...". By default, authorized
\r
298 leave list is "all".
\r
301 <param name="authorizedleavelist" value="all-#mychannel">
\r
303 authorizedcommandlist : set the list of command the user is athorized to do.
\r
304 --------------------- Syntax is "all-command1-command2-..." or
\r
305 "none+command1+command2+...". By default, authorized
\r
306 command list is "all". Don't prefix the command with
\r
309 <param name="authorizedcommandlist" value="none+me">
\r
312 coding : specify what encoding algorithm should be used for sending the text
\r
313 ------ to the irc server. By default, encoding 1 is used. Values are :
\r
314 0 : strict ascii, MSB is dropped, shouldn't be used.
\r
315 1 : pjirc unicode to ascii protocol, charcode is sent as it if
\r
316 below than \u0x00ff. Should be used if pjirc is used with
\r
317 other non UTF-8 compatible clients.
\r
319 3 : local charset coding, should be avoided when possible for
\r
320 compatibility reasons
\r
323 <param name="coding" value="2">
\r
325 lngextension : modify the default lng file extension. By default, lng
\r
326 ------------ extension is "lng".
\r
329 <param name="lngextension" value="txt">
\r
331 userid : set the userid. The user id will be used for ident id and for
\r
332 ------ user name at connect-time. If the id is empty, then full name
\r
333 will be used for id, and nickname will be used as username
\r
334 at connect time. By default, userid is empty.
\r
337 <param name="userid" value="myname">
\r
339 autoconnection : set whether the applet should try to trigger connection
\r
340 -------------- as soon at it is launched. By default, the applet will
\r
344 <param name="autoconnection" value="false">
\r
346 useidentserver : enable or disable the ident server. By default, the
\r
347 -------------- server is enabled.
\r
350 <param name="useidentserver" value="false">
\r
352 mutliserver : enable or disable the multiserver support. By default,
\r
353 ----------- multiserver is disabled.
\r
356 <param name="multiserver" value="true">
\r
358 alternateserverI : set the Ith alternate server. Syntax is
\r
359 ---------------- "host port" or "host port password".
\r
362 <param name="alternateserver1" value="irc.secondhost.com 6667">
\r
364 serveralias : set the default server alias. By default, server alias
\r
365 ----------- is empty string.
\r
368 <param name="serveralias" value="Alias">
\r
370 noasldisplayprefix : set the "no display asl" full name prefix. If the
\r
371 ------------------ user's full name begins with this prefix, then
\r
372 the floating asl window won't be displayed. An
\r
373 empty string disables this feature. By default,
\r
374 prefix is disabled.
\r
376 <param name="noasldisplayprefix" value="true">
\r
378 pluginX : set the Xth plugin to be loaded at startup.
\r
382 <param name="plugin1" value="MyPlugin">
\r
384 soundwordX : set the Xth sound configuration. Syntax is "word sound". When
\r
385 ---------- "word" is detected in a message, then "sound" is played.
\r
388 <param name="soundword1" value="lol snd/lol.au">
\r
390 fingerreply : set the finger reply.
\r
394 <param name="fingerreply" value="A lucky Plouf's IRC user">
\r
396 userinforeply : set the user info reply.
\r
400 <param name="userinforeply" value="A lucky Plouf's IRC user">
\r
402 fileparameter : URL to the file containing all PJIRC parameters.
\r
403 ------------- The configuration file format is the same as the
\r
404 pjirc.cfg file. If other parameters are specified
\r
405 using the html tags, they will be mixed.
\r
408 <param name="fileparameter" value="pjirc.cfg">
\r
410 aslseparatorstring : set the asl separator string. When the ASL parser
\r
411 ------------------ reach this string, the parsing stops and any text
\r
412 being found after this string (including the
\r
413 separator) will be ignored.
\r
416 <param name="aslseparatorstring" value="|">
\r
418 allowdccchat : set whether dcc chat is allowed. By default, this is
\r
422 <param name="allowdccchat" value="false">
\r
424 allowdccfile : set whether dcc file is allowed. By default, this is
\r
428 <param name="allowdccfile" value="false">
\r
430 disablequeries : disable all queries. By default, this is not enabled.
\r
434 <param name="disablequeries" value="true">
\r
436 autorejoin : enables the automatic channel rejoin when kicked out. By default,
\r
437 ---------- autorejoin is disabled.
\r
440 <param name="autorejoin" value="true">
\r
442 initX : set the Xth initial command to be executed when the applet starts
\r
443 ----- up. This is usefull when several servers needs to be automatically
\r
447 <param name="init1" value="/newserver Undernet eu.undernet.org">
\r
452 'Style' is the name of the library used inside PJIRC for text display. Even
\r
453 if this display has nothing to do with the actual irc engine, a majority
\r
454 of all GUI's are likely to use it. As a consequence, 'Style' is included in
\r
455 the engine package. All 'Style' parameters are prefixed by 'style:'.
\r
458 righttoleft : set right-to-left display, instead of left-to-right default
\r
459 ----------- display.
\r
462 <param name="style:righttoleft" value="true">
\r
464 sourcecolorruleN : set the Nth source color rule. Rule syntax is
\r
465 ---------------- "type name index1=color1 index2=color2 ...".
\r
468 <param name="style:sourcecolorrule1" value="none+Channel all 0=00ff00">
\r
469 <param name="style:sourcecolorrule2" value="none+Query none+some_nick
\r
470 0=000000 1=ffffff">
\r
472 sourcefontruleN : set the Nth source font rule. Rule syntax is
\r
473 ---------------- "type name fontname fontsize".
\r
476 <param name="style:sourcefontrule1" value="none+Channel all Arial 12">
\r
479 backgroundimage : toggle master background image switch. If this flag is
\r
480 --------------- turned off, all background images will be ignored. By
\r
481 default, background images are disabled.
\r
484 <param name="style:backgroundimage" value="true">
\r
486 backgroundimageX : background image configuration number X. Syntax is
\r
487 ---------------- "sourcetype sourcename tiling image" with sourcetype and
\r
488 sourcename the target source type and name, tiling a
\r
489 figure and image the image file name. Valid source types
\r
490 are DCCChat, Channel, Query, Status, ChanList and Default.
\r
491 As for the command parameter, there can't be any gap in the
\r
494 Possible tiling values are:
\r
504 <param name="style:backgroundimage1" value="none+channel none+#happy 1
\r
506 <param name="style:backgroundimage2" value="none+Query all 2
\r
509 bitmapsmileys : enable or disable bitmap smileys. Once enabled, bitmaps are
\r
510 ------------- defined via the smiley parameter. By default, bitmap smileys
\r
514 <param name="style:bitmapsmileys" value="true">
\r
516 smileyX : set the Xnth smiley. A smiley is a pair of text->image. Each time
\r
517 ------- the text is found on a line, it will be replaced by the
\r
518 corresponding image. As for the command parameter, the first smiley
\r
519 must be smiley1 and there must'nt be any gap. The format of the
\r
520 parameter is "text image", where image is any URL the applet can
\r
524 <param name="style:smiley1" value=":) img/smile.gif">
\r
525 <param name="style:smiley2" value=":( img/sad.gif">
\r
527 floatingasl : activate "mouseover" floating asl information. By default,
\r
528 ----------- floating asl is disabled. "asl" parameter may be also activated,
\r
529 but this is not mandatory.
\r
532 <param name="style:floatingasl" value="true">
\r
534 floatingaslalpha : set the floating asl alpha transparency value. Between 0
\r
535 ---------------- and 255, 0 is invisible and 255 fully opaque. By default,
\r
536 alpha value is 170. This parameter may be ignored if the
\r
537 java virtual machine doens't support transparency.
\r
540 <param name="style:floatingaslalpha" value="150">
\r
542 linespacing : set the additional space that will be used between two lines
\r
543 ----------- of text. Default value is zero. Unit is pixel.
\r
546 <param name="style:linespacing" value="10">
\r
548 maximumlinecount : set the maximum line count in the history buffer. This
\r
549 ---------------- can save memory for very long chats. Default value is
\r
553 <param name="style:maximumlinecount" value="256">
\r
555 highlightlinks : highlight links when mouse moves over them. By default,
\r
556 -------------- this is not enabled.
\r
559 <param name="style:highlightlinks" value="true">
\r
563 The Pixx's GUI documentation is available in a separate file in the default
\r
564 package. All GUI parameters begins with 'gui:', where gui is the name of the
\r
565 gui. For instance, any Pixx GUI specific parameter will begin by 'pixx:'.
\r
570 PJIRC is designed to support events from the "outside". The applet supports
\r
571 the following methods :
\r
573 void sendString(String str) :
\r
574 send the given string to the server, through the current source
\r
575 interpretor. For instance, you can bring the channel list window by
\r
576 calling sendString("/list")
\r
578 void setFieldText(String txt) :
\r
579 set the textfield content.
\r
581 String getFieldText() :
\r
582 get the textfield content. setFieldText and getFieldText can be combined
\r
583 to append text for the user. For instance, adding a smiley can be done
\r
584 using setFieldText(getFieldText()+':)')
\r
586 void validateText() :
\r
587 validate the current textfield content, as if the user pressed the return
\r
590 void requestSourceFocus() :
\r
591 request the active source to gain focus.
\r
593 void sendPluginEvent(String pluginName,Object event) :
\r
594 send the given event value to the given plugin.
\r
596 Object getPluginValue(String pluginName,Object valueName) :
\r
597 Get the plugin value from the given plugin name.
\r
599 void requestSourceFocus(String serverName,String type,String name) :
\r
600 request the given source to gain focus. If serverName is empty, the first
\r
601 source matching the type and name will receive focus regardless of its
\r
604 void sendString(String serverName,String type,String name,String cmd) :
\r
605 send the given string to the server, through the given source
\r
606 interpretor. If serverName is empty, the first source matching the type
\r
607 and name will receive the string, regardless of its server.
\r
609 IRCApplication getIRCApplication() :
\r
610 get the IRCApplication. For advanced use only.
\r
612 Minimal html fragment
\r
613 ---------------------
\r
615 <applet code=IRCApplet.class archive="irc.jar,securedirc.jar" width=640
\r
617 <param name="CABINETS" value="irc.cab,securedirc.cab">
\r
619 <param name="nick" value="Anonymous???">
\r
620 <param name="name" value="Java User">
\r
621 <param name="host" value="irc.dal.net">
\r
622 <param name="gui" value="pixx">
\r
629 A runtime command is any text prefixed by the / character. If the so-called
\r
630 interpretor recognize a command, it will parse and handle it. If not, the
\r
631 command will be sent as it (but without the initial / character) to the
\r
634 Here are the list of all recognized commands.
\r
636 ame %message : send an action to all active channels
\r
637 amsg %message : send a message to all active channels
\r
638 away [%message] : configure the away status
\r
639 beep : send a beep to the speakers
\r
640 clear : clear the window
\r
641 ctcp %command [%parameters] : send a ctcp request to the given nick
\r
642 dcc %nick : send a dcc request to the given nick
\r
643 disconnect : disconnect from the server
\r
644 echo %message : echo the specified text to the active source
\r
645 hop : leave and rejoin the active channel
\r
646 ignore %nick : ignore the specified nick
\r
647 j %channel [%password] : join the given channel
\r
648 join %channel [%password] : same as j
\r
649 kick %nick : kick the given nick
\r
650 leave : leave the active source
\r
651 load %plugin : load the given plugin
\r
652 me %message : send an action to the active source
\r
653 msg %target %message : send a message to the given target
\r
654 newserver %alias %host [%port [%password]] : create a new server status
\r
655 notice %target %message : send a notice to the given target
\r
656 onotice %target %message : send a notice to all operators at the given target
\r
657 part : same as leave
\r
658 ping : ping the given nickname
\r
659 play %sound : play the given sound, only on the local client
\r
660 query %nick : query the given nickname
\r
661 quit [%message] : same as disconnect, but with the given message
\r
662 raw %command : send a raw command to the server
\r
663 server %host [%port [%password]] : connect to the given server
\r
664 sound %soundfile : play the given sound on the client and all other clients on
\r
666 sleep %millis : freeze the interpretor for the given amount of milliseconds
\r
667 topic %channel %topic : change the given channel's topic
\r
668 unignore %nick : unignore the specified nick
\r
669 unload %plugin : unload the specified plugin
\r
670 url %url [%target] : open the given url on a new browser window
\r
671 onserver %server command : execute the following command only if the source
\r
672 server matches the specified one. This is usefull when used with the
\r
673 commandX parameters.
\r
678 PJIRC is developped by Plouf - plouf@pjirc.com
\r
679 Have a look at http://www.pjirc.com/ for news about PJIRC.
\r
680 PJIRC has an official italian website on http://www.pjirc.it
\r
681 PJIRC has a CVS repository at SourceForge :
\r
682 http://sourceforge.net/projects/pjirc
\r