chat/readme.txt

   1 Plouf's Java IRC Client Applet
   2 ------------------------------
   3
   4 Webmaster's manual
   5 ------------------
   6
   7 Concepts
   8 --------
   9
  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.
  14
  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.
  20
  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
  26   stuff and so on.
  27
  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.
  33
  34 Files
  35 -----
  36
  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.
  43
  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.
  48
  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
  53     below).
  54
  55
  56 Build
  57 -----
  58         The unsigned IRC Engine can be built using the following javac compiler
  59         commands :
  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
  68
  69 Installation
  70 ------------
  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
  73         sound.
  74
  75 Applet html fragment
  76 --------------------
  77         Using signed mode and the Pixx GUI, the following minimal applet fragment
  78         should work just fine :
  79
  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">
  86         </applet>
  87
  88 Test your applet
  89 ----------------
  90         A test tool is available at http://www.pjirc.com/check.
  91         This tool will detect common errors and mistakes.
  92
  93 What is a server?
  94 -----------------
  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.
  99
 100     - DCC server : a DCC (for Direct Client to Client) is a
 101                    special server for handling direct
 102                    connections to other clients.
 103
 104     - Null server : the Null server is a ghost server,
 105                     physically connected to nothing.
 106
 107 What is a source?
 108 -----------------
 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 :
 114
 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
 119                 support is enabled.
 120
 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.
 127
 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.
 131
 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.
 139
 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.
 143
 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.
 148
 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.
 154
 155 Parameters
 156 ----------
 157   parameters are passed to the applet via the following syntax :
 158     <param name="name" value="value">
 159
 160 Mandatory parameters
 161 --------------------
 162
 163   nick : default nick to be used. '?' characters will be replaced by random
 164          numbers.
 165     Example :
 166       <param name="nick" value="Guest??">   will tell the applet to use nicks
 167                                             such as Guest47
 168
 169   name : "real" user name, sent to IRC server.
 170     Example :
 171       <param name="name" value="UserName">
 172
 173   host : IRC server host.
 174     Example :
 175       <param name="host" value="irc.server.net">
 176
 177   gui : PJIRC graphical user interface.
 178     Example :
 179       <param name="gui" value="pixx">
 180
 181
 182 Optional parameters
 183 -------------------
 184
 185   port : IRC server port. By default, the port is 6667.
 186   ----
 187
 188     Example :
 189       <param name="port" value="6667">
 190
 191   commandX, with X a figure : Tells the applet to execute this command once
 192   --------                    connected to the server.
 193
 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.
 197
 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.
 201
 202     Example :
 203       <param name="command1" value="/nickserv identify password">
 204       <param name="command2" value="/join #channel">
 205
 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.
 210
 211     Example :
 212       <param name="language" value="french">
 213
 214   quitmessage : sets the quit message. By default, this message is empty.
 215   -----------
 216
 217     Example :
 218       <param name="quitmessage" value="PJIRC forever!">
 219
 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.
 225
 226     Example :
 227       <param name="asl" value="true">
 228
 229   aslmale : set the string corresponding to the male gender in the full name for
 230   -------   asl parsing. Default value is "m".
 231
 232     Example :
 233       <param name="aslmale" value="m">
 234
 235   aslfemale : set the string corresponding to the female gender in the full name
 236   ---------   for asl parsing. Default value is "f".
 237
 238     Example :
 239       <param name="aslfemale" value="f">
 240
 241   aslunknown : set the string corresponding to the unknown gender in the full name
 242   ----------   for asl parsing. Default value is "x".
 243
 244     Example :
 245       <param name="aslunknown" value="x">
 246
 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.
 252
 253     Example :
 254       <param name="useinfo" value="false">
 255
 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.
 258
 259     Example :
 260       <param name="soundbeep" value="snd/bell2.au">
 261
 262   soundquery : set the incoming private sound. The sound is played when a new
 263   ----------   private source is opened.
 264
 265     Example :
 266       <param name="soundquery" value="snd/ding.au">
 267
 268   password : set the server password on connection.
 269   --------
 270
 271     Example :
 272       <param name="password" value="mysecretpassword">
 273
 274   alternatenick : set the alternate nickname, to be used if primary nickname is
 275   -------------   already used on the server.
 276
 277     Example :
 278       <param name="alternatenick" value="someothernick">
 279
 280   languageencoding : set the language file encoding to be used. If not
 281   ----------------   specified, default encoding will be used.
 282
 283     Example :
 284       <param name="languageencoding" value="UnicodeLittle">
 285
 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
 289                        join list is "all".
 290
 291     Example :
 292       <param name="authorizedjoinlist" value="none+#mychannel">
 293
 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
 297                         leave list is "all".
 298
 299     Example :
 300       <param name="authorizedleavelist" value="all-#mychannel">
 301
 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
 306                           the / character.
 307     Example :
 308       <param name="authorizedcommandlist" value="none+me">
 309
 310
 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.
 317              2 : UTF-8
 318              3 : local charset coding, should be avoided when possible for
 319                  compatibility reasons
 320
 321     Example :
 322       <param name="coding" value="2">
 323
 324   lngextension : modify the default lng file extension. By default, lng
 325   ------------   extension is "lng".
 326
 327     Example :
 328       <param name="lngextension" value="txt">
 329
 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.
 334
 335     Example :
 336       <param name="userid" value="myname">
 337
 338   autoconnection : set whether the applet should try to trigger connection
 339   --------------   as soon at it is launched. By default, the applet will
 340                    try to connect.
 341
 342     Example :
 343       <param name="autoconnection" value="false">
 344
 345   useidentserver : enable or disable the ident server. By default, the
 346   --------------   server is enabled.
 347
 348     Example :
 349       <param name="useidentserver" value="false">
 350
 351   mutliserver : enable or disable the multiserver support. By default,
 352   -----------   multiserver is disabled.
 353
 354     Example :
 355       <param name="multiserver" value="true">
 356
 357   alternateserverI : set the Ith alternate server. Syntax is
 358   ----------------   "host port" or "host port password".
 359
 360     Example :
 361       <param name="alternateserver1" value="irc.secondhost.com 6667">
 362
 363   serveralias : set the default server alias. By default, server alias
 364   -----------   is empty string.
 365
 366     Example :
 367       <param name="serveralias" value="Alias">
 368
 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,
 373                        prefix is disabled.
 374     Example :
 375       <param name="noasldisplayprefix" value="true">
 376
 377   pluginX : set the Xth plugin to be loaded at startup.
 378   -------
 379
 380     Example :
 381       <param name="plugin1" value="MyPlugin">
 382
 383   soundwordX : set the Xth sound configuration. Syntax is "word sound". When
 384   ----------   "word" is detected in a message, then "sound" is played.
 385
 386     Example :
 387       <param name="soundword1" value="lol snd/lol.au">
 388
 389   fingerreply : set the finger reply.
 390   -----------
 391
 392     Example :
 393       <param name="fingerreply" value="A lucky Plouf's IRC user">
 394
 395   userinforeply : set the user info reply.
 396   -------------
 397
 398     Example :
 399       <param name="userinforeply" value="A lucky Plouf's IRC user">
 400
 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.
 405
 406     Example :
 407       <param name="fileparameter" value="pjirc.cfg">
 408
 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.
 413
 414     Example :
 415       <param name="aslseparatorstring" value="|">
 416
 417   allowdccchat : set whether dcc chat is allowed. By default, this is
 418   ------------   true.
 419
 420     Example :
 421       <param name="allowdccchat" value="false">
 422
 423   allowdccfile : set whether dcc file is allowed. By default, this is
 424   ------------   true.
 425
 426     Example :
 427       <param name="allowdccfile" value="false">
 428
 429   disablequeries : disable all queries. By default, this is not enabled.
 430   --------------
 431
 432     Example
 433       <param name="disablequeries" value="true">
 434
 435
 436 Style parameters
 437 ----------------
 438
 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:'.
 443
 444
 445   righttoleft : set right-to-left display, instead of left-to-right default
 446   -----------   display.
 447
 448     Example :
 449       <param name="style:righttoleft" value="true">
 450
 451   sourcecolorruleN : set the Nth source color rule. Rule syntax is
 452   ----------------   "type name index1=color1 index2=color2 ...".
 453
 454     Example :
 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">
 457
 458   sourcefontruleN : set the Nth source font rule. Rule syntax is
 459   ----------------   "type name fontname fontsize".
 460
 461     Example :
 462       <param name="style:sourcefontrule1" value="none+Channel all Arial 12">
 463
 464
 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.
 468
 469     Example :
 470       <param name="style:backgroundimage" value="true">
 471
 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
 478                      X indexes.
 479
 480                      Possible tiling values are:
 481                        0 : Center
 482                        1 : Stretch
 483                        2 : Tiling
 484                        3 : Top left
 485                      259 : Top right
 486                      515 : Bottom left
 487                      771 : Bottom right
 488
 489     Example :
 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">
 492
 493   bitmapsmileys : enable or disable bitmap smileys. Once enabled, bitmaps are
 494   -------------   defined via the smiley parameter. By default, bitmap smileys
 495                   are disabled.
 496
 497     Example :
 498       <param name="style:bitmapsmileys" value="true">
 499
 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
 505             access.
 506
 507     Example :
 508       <param name="style:smiley1" value=":) img/smile.gif">
 509       <param name="style:smiley2" value=":( img/sad.gif">
 510
 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.
 514
 515     Example :
 516       <param name="style:floatingasl" value="true">
 517
 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.
 522
 523     Example :
 524       <param name="style:floatingaslalpha" value="150">
 525
 526   linespacing : set the additional space that will be used between two lines
 527   -----------   of text. Default value is zero. Unit is pixel.
 528
 529     Example :
 530       <param name="style:linespacing" value="10">
 531
 532   maximumlinecount : set the maximum line count in the history buffer. This
 533   ----------------   can save memory for very long chats. Default value is
 534                      1024.
 535
 536     Example
 537       <param name="style:maximumlinecount" value="256">
 538
 539   highlightlinks : highlight links when mouse moves over them. By default,
 540   --------------   this is not enabled.
 541
 542     Example
 543       <param name="style:highlightlinks" value="true">
 544
 545 GUI parameters
 546 --------------
 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:'.
 550
 551 JavaScript support
 552 ------------------
 553
 554   PJIRC is designed to support events from the "outside". The applet supports
 555   the following methods :
 556
 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")
 561
 562   void setFieldText(String txt) : set the textfield content.
 563
 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()+':)')
 568
 569   void validateText() : validate the current textfield content, as if the user
 570                         pressed the return key.
 571
 572   void requestSourceFocus() : request the active source to gain focus.
 573
 574   void sendPluginEvent(String pluginName,Object event) : send the given event
 575                                                          value to the given
 576                                                          plugin.
 577
 578   Object getPluginValue(String pluginName,Object valueName) : Get the plugin
 579                                                               value from the
 580                                                               given plugin
 581                                                               name.
 582
 583 Minimal html fragment
 584 ---------------------
 585
 586 <applet code=IRCApplet.class archive="irc.jar,securedirc.jar" width=640 height=400>
 587 <param name="CABINETS" value="irc.cab,securedirc.cab">
 588
 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">
 593
 594 </applet>
 595
 596 Runtime commands
 597 ----------------
 598
 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
 602 server.
 603
 604 Here are the list of all recognized commands.
 605
 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
 627 part : same as leave
 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
 640
 641 Contacts
 642 --------
 643
 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