(thing) by N-Wing Fri Jun 16 2000 at 9:26:20

J A V A   C H A T T E R B O X   M A N U A L
updated for version 0.1.10.4* (current version on E2: 0.1.10.2)

This will serve as a manual/guide/FAQ/HOWTO repository metanode for the Java Chatterbox. As this node and/or writeup get large, sections will be moved into their own nodes. The node chatterbox client contains information about other chatterbox clients (duh), and my writeup there is a news-like thing pertaining to the Java chatterbox. Note that some information in this manual may be temporally incorrect - there may be some old information in that no longer applies, and there may be some new information that applies to a newer version of the chatterbox than is on E2.
* note: any version x.y.z.0 is development, so you won't see it here

This guide currently has 3 main sections, divisioned by the target audience:

  • End User - normal users of the Java chatterbox, off one of the Everything websites
  • Web Site - those who want to embed the chatterbox in their own sites
  • Programming - those who want to run the Java chatterbox via appletviewer (or something similar) and/or modifying/viewing the source code

End User Section
(information geared towards the users running the Java chatterbox off the E2 website)

The URL to report bugs to is given in my writeup for chatterbox client.

Explanation of the main window
The main window, or the window that pops-up, off the web page, has 5 parts.

Menus
Chatterbox
This menu contains miscellaneous operations. Login / Cancel Login / Logout allows you to do what it currently says. About displays some information about the Java chatterbox. Quit now will close the Java chatterbox window.
Rooms
This menu provides for some rudimentary room management. There are two history text areas, one for a site's default room (outside on Everything 2), and one for other rooms. Other rooms can only be viewed once a user is logged in, and is in another room.
Selecting the site's default room (indicated with a # in front of it) shows the public messages. Selecting another room (rooms "built into" a site are indicated with a + in front) displays all non-default room messages. However, when an item in the history menu is selected, only the currently selected room's messages are displayed. (If you're confused after reading that, just play around a bit - it is easier to do than explain.).
The last item, Purge, removes the site's non-default rooms from the history list. This is useful when the "Other User" dialog is opened for a while, and the rooms list grows to large sizes.
History
These do something to the message history text area. Clear clears the history text. Last 10 and Last 100 clear the history, then show the most recent 10 or 100 public messages of the currently selected room. Show All clears the history, then shows all messages for the currently selected room.
Dialogs
These toggle the visibility of the various dialogs boxes: Options, Other Users, Private Messages, and Links. Since you must be logged in to receive private messages, this dialogs is unavailable while you are logged out.
Messages History
This is where messages send by users are displayed. It automatically updates every now and then, which is dependant upon the message frequency - the busier the chatterbox, the more frequently it updates.
User Login
To login, which you need to do in order to send messages from the Java chatterbox:
  1. enter your user name in the leftmost text field
  2. enter your password in the next text field (the password will be displayed *ed out)
  3. press Enter or Return, or right-click (or alternate-click) in the blank area to the right, and select Login from the popup menu, or select Login from the Chatterbox menu
If you entered a valid name and password, you'll be able to send messages; if you made a tpyo or otherwise messed up, you (obviously) can't send messages. Once you're logged in, you may logout by right-clicking (or alternate-clicking) in the blank area to the right and selecting Logout from the popup menu, or select Logout from the Chatterbox menu. If the network is s l o w, you can select Cancel logout that appears in the same places the Login and Logout choices do, which will stop the login attempt. (note: the Login, Logout, and Cancel login menu choices are displayed in the same location; the displayed text varies depending on your login status)
Message Sending
Once you are logged in, you may send messages. Just type whatever (it has to be "whatever", nothing else will work) and hit Enter or press the Talk button. The message will be queued up and sent shortly thereafter. This queue allows you to type several messages in quick succession without waiting for a slow network to send the previous message. To make flooding a bit more difficult, there is a limit of 5... "3" ...I mean, 3. 3 messages that may be queued up at one time. Since there is a message limit of 255 characters (enforced on the server side), you are informed by a beeping (can be turned off) and a status message, if you do not shorten the message length while you are over the limit.
Status Bar
This is where you go to have a drink and possibly increase your status.   However, sometimes it only feels like giving you some information about what is going on in the program. If the text gets chopped off, make the window wider.

Explanation of the Options dialog

Show message time (default: on)
If checked, all new messages displayed have the E2 local time (EUT) hour and minute next to them, in the format hh:mm; otherwise, no time is displayed. If you're running this for a site besides E2, the time zone is omitted.
Beep when sending long messages (default: on)
By default, there is a beeping sound if you exceed the message-length limit. If you turn this off, the status bar of the main window still informs you of a long message.
Enter sends messages (default: on)
By default, when you're typing messages, you can hit the Enter key instead of hitting the "Talk" button. To disable this, uncheck this option.
Disable bad command checking (default: unchecked)
By default, typos made while typing commands prevent the message from sending. Mistakes checked for include:
  • an illegal command:   (accidental /mshs are a thing of the past)
  • a missing /:   msg MafiaBoss I knocked off Vin like you said, where do you want the body?
  • a character other than /, followed by a command, followed by a space:   .me eats [EDB]
To send "fake" command without disabling this, put a space in front, like
    (space)/msh thefez I WILL SMURF YOU
or use /say, like
    /say /msb CowboyNeal Lets delete half of everybody's nodes, and see if they'll notice.
Note that /say is not a valid command in the HTML-based chatterbox.
Allow closing of main window (default: not enabled)
When this is set, hitting the little 'X' or close button on the main window will close it, no questions asked. To help prevent accidental closes, leave this unchecked, so you have to pick "Quit now" from the menu, or type /quit to close the window.
Enable automatic logout (default: enabled, after 15 minutes/900 seconds)
If this options is enabled, then you are automatically logged out if you are idle for the time (in seconds) shown. This setting cannot be changed while logged in.
Use proxy
Some people may have problems logging in because they're over a firewall or proxy. Setting the correct information attempts to fix this problem. However, I have no way of testing this, so don't be surprised if it doesn't help. (Although you could /msg me to help me test this out...
(debug mode) (default: off)
When debug mode is enabled, the place where you normally enter messages instead takes debugging commands. There isn't much need for a normal user to choose this. For more information about the debug mode, see the Programming Section of this manual.
Note that the options are not retained when you close the main applet window. (Although it would be possible to save your settings in a writeup, it isn't private, and you would have to login first anyway, and I know that most people wouldn't want to see billions of writeups for Java Chatterbox prefs.)

Explanation of the Users dialog
The main display is the list of online users, which is updated approximately every minute and a half/90 seconds. Pressing the Refresh button will update the list immediately (or rather, as soon as possible, because of the network delays). Selecting a user's name will give more detailed information about the user. (Currently, only their name and room they're in is given.) Double-clicking on a user name will copy the name to the message box. Secondary-clicking (usually the right mouse button) on a user name will let you copy the name, copy the name in a link, or send a private /msg to the user. Secondary-clicking on the top status bar (where the number of users is displayed) will sort the names by XP (experience), by user name, or by the room they're in.

Explanation of the Private Messages dialog
Here you can see all the private messages you have, and delete the ones you're finished with. Note that this is only available while you are logged in. To help prevent against accidental deletions, the "Disable delete" checkbox must be unchecked in order to delete a message.

Explanation of the Links dialog
This lets you visit a node on Everything, selected by either the title, or by the node_id. In the other windows, when you move the text cursor (caret) inside a [link], this dialog will be updated with that link. This is also updated when you choose a user in the "Other Users" dialog, or choose a message in the "Private Messages" dialog. Of course, you can type in your whatever node title or ID you choose. When you press one of the "Go" buttons, your web browser will visit that page.

What is Next?
Planned for later versions:

  • Want anything else added? Inform the author!
What is Not Next?
I have decided to not do the following in the applet version:
  • formatted text display (too large of an overhead if Swing is used, and I'm not sure how to create my own rich-text displays)

Web Site Section
(information for those who embed the chatterbox into their own Everything-based website)

To embed the Java chatterbox in a web page, you should:

  1. get chatterclient.zip (the zipped Java class files)
  2. (optional, but recommended) create an empty directory
  3. put the zip file into that directory
  4. unzip the file, preserving paths, but do not delete the original zip file
  5. set read and execute permissions on the directory, and read permission for all the files
  6. if the directory you unzipped into is not already accessible from the web site, make it so (either move or map it)
  7. use the applet tag in a web page (example follows)
Here is some demonstration XHTML to embed the Java chatterbox in a web page: 
<applet
    codebase="javachat/"
    code="Launcher.class"
    archive="chatterclient.zip"
    width="250" height="200"
>
    <param name="background-color" value="#00ff00" />
    <param name="launchlink0" value="[EDB and I]" />
    <param name="launchlink1" value="index.pl?node_id=9740|N-Wing|N-Wing's home node" />
    <param name="launchlink2" value="/index.pl?node=yawn|*yawn*|Aren't you tired?" />
    <param name="launchlink3" value="http://slashdot.org|/." />
    <param name="launchlink4" value="http://www.perlmonks.org/|Perl Monks|Pearl Monkeys" />
    <param name="autolaunch" value="true" />
You need Java 1.1 enabled.
</applet>
In the applet tag:
codebase
The directory that the zip file and class files are in; in this example, it is the javachat directory, off of the directory the Everything-engine is in
code
The file "run" by the browser (this must not be changed)
archive
If the browser is newer, it will be able to read the zip file to get all the Java classes, which is faster overall. For older browsers, this is ignored, and will try to read in all the files individually (which takes longer because they are not compressed and it takes multiple HTTP requests). If for some reason
width and height
The number of pixels the applet takes in the web page (just like the width and height attributes in an img tag) While these can be changed, I have found that the given values work well. If you use long list-choice descriptions (see below), though, you may want to increase the width.
autolaunch
if set to true, the main window of the chatterbox will open automatically, so the user doesn't have to press the "Launch Java Chatterbox" button
You need Java 1.1 enabled.
What is displayed if the browser does not understand the applet tag or if Java has been disabled. This can be changed to anything suitable.

The param tags allow for some slight modification to the applet. I highly recommend that the given things are not used, except to experiment with.

The first param sets the background color of the main panel. The name is simply background-color and the value is the HTML-style RGB hex colors, #rrggbb. Currently, named colors (like "green") are not supported; the hex values must be used instead.

On the main panel that display on the actual web page, there are several relevant links, listed in a choice box. When an item is selected, extra information about the link is displayed below (if given). Currently, if the applet is running from Everything2, Perl Monks, or everydevel, there are some links automatically added. The above example demonstrates some ways to add other links. First, the param's name must start with launchlink then be followed by an integer, starting at 0 or 1. As many links as wanted may be added, but the numbers must not skip; otherwise, anything higher than the skipped number will not be added. The actual text of the value tags is divided into 3 parts: URL | display | information . Everything except the URL is optional; if something is not given, a value is guessed at. URL is the URL of the link; display is the text shown in the choice list; information is extra information about the link Explanation of the examples:

[EDB and I]
E2-style link: just surround whatever text with square brackets
index.pl?node_id=9740|N-Wing|N-Wing's home node
relative link: this is currently the only way to link to a specific node_id (this example will only go to N-Wing's home node if the applet is running off E2)
/index.pl?node=yawn|*yawn*|Aren't you tired?
relative link with an absolute path: the / in front goes to the root of the web host
http://slashdot.org|/.
an absolute link to the site /.
http://www.perlmonks.org/|Perl Monks|Pearl Monkeys
another absolute link that will get me (and you, if you use it) in trouble when a user picks "Perl Monks" from the choice list and sees Pearl Monkeys

For determining relative URLs (above), and other web page locations, the Java chatterbox assumes the base URL to get the files from is the directory of the page that the applet is embedded in. For example, if the applet tag is in the page
http://www.everythingtoo.com/to/2.html
then the base URL is
http://www.everythingtoo.com/to/
. In practice, this means that as long as the Java chatterbox page is something like /index.pl?node=blahblah then it should be able to find the XML tickers it uses.

Currently, the tickers must have certain names (although the node_id does not matter). The tickers used are:

chatterbox+XML+ticker
for the public rooms
other+users+XML+ticker
for the list of users online, and the room they're in (this ticker is similar to the Everything Finger page, except the ticker also contains the user_id)
private+message+XML+ticker
for a user's private messages

What is Next?
Planned for later versions:

  • Extended links (proposed by me on EveryDevel) (even if they are not used in the Everything engine, I will support them in the client)
  • Want something added? Inform the author!

Programming Section
(information geared towards those (running the Java chatterbox via appletviewer or something similar) and/or (modifying/viewing the source code))

Pretty recent source code is available at

http://sourceforge.net/projects/jchatter/
and is generally stable. If you want more recent source, try
http://rbepan.net/java/e2chat/
although it may not work as well. If you want really recent source, contact the author. Most classes are released under the LGPL, and the entire applet is released under the GPL.

Once debug mode is activated (toggle is available through the Options dialog), several commands may be typed in the area where messages are normally sent. These commands and arguments are generally case-sensitive.

help or h or ? (or anything invalid)
lists the debug commands available
dump messages
displays all messages received, in XML format, to the history window
property or p
attempts to display properties as retrieved by System.getProperty(String)
version or v
displays the program version
debug
Follow by on or off, then class names, to turn on or off debugging output in the classes (the classes send the debug info to System.err or System.out). Using all is the same as listing every class. The success or failure of changing each class's debug mode is indicated. Using the command with no arguments will display a list of classes.

What is Next?
Planned for later versions:

  • integrated noding environment (although the full environment would have to be an application)
  • dynamically load modules (so can do things like have site-specific home page parsers)
  • Want to add something? Inform N-Wing, to be sure you have the latest information and code.


manual created: 2000.06.16.n5 1:28 EST
manual updated: 2001.01.12.n5 23:41 EST
manual author: N-Wing (Nathan Bronecke) yup, you found the secret message; if you want to know what TWAMTFBR means, the second T and only F are a number

Page category:

I like it! This writeup has been cooled by:  
Cyt, TallRoo, JohnnyGoodyearX 3 C!s

Log in or register to write something here or to contact authors.