• The Legal Stuff

Permission to use, copy, and distribute this software and its documentation without fee for NON-COMMERCIAL purposes is hereby granted, according to the details contained in the enclosed license.htm. Please read that document before continuing.

COMMERCIAL USERS ARE REQUIRED TO REGISTER this software before using it in connection with any commercial enterprise, including its publication on any World Wide Web site intended to publicize, form a part of, or otherwise assist a commercial venture.

Non-commercial users are (of course!) encouraged to register, but are under no obligation to do so. All registered users will be entitled to 6 month's free email support, free updates of the registered title if and when available, and notification of new titles.

For details of pricing and registration, read the accompanying document register.htm.

USE OF THIS SOFTWARE IS TAKEN TO INDICATE ACCEPTANCE OF THE ABOVE TERMS, AND THOSE LAID OUT IN THE ACCOMPANYING LICENSE DOCUMENT.

TreeView is a menu tree of the 'Windows Explorer' mold. It consists of 'folders' and 'pages', with an unlimited number of both available. Folders are simply storage holders for pages. Pages are clickable links to web pages (or any other Internet resource). Clicking a folder opens it to reveal its pages, closing any other open folder in the process so that only one folder is ever open at a time). Clicking the same folder again will close it, hiding its pages. Each page has its own parameters for URL and (optionally) frame target.

The images (folders, pages) and outliners (dotted lines, plus & minus symbols) are placed automatically by the applet, making the whole thing very simple to configure. You can optionally specify a header image and/or label for the menu, an offset to move the menu itself downward to make room for these header elements, and an indent for the header label. TreeView also (optionally) supports sounds - see the section imaginatively entitled Using Sounds below.

Place the file ryTreeView.class in the same folder as the the HTML document in which you want to use the applet, and place either set of images (or both) mentioned under OutlineShading (below) in the same folder. If you want to use sounds, place the sound files into that folder too. Add the following code to your HTML page. (This is a working example, which you might like to use as a basis for working while you read the rest of this documentation.)

<!-- Now set up the folders & pages -->

</APPLET>

If you're experienced in HTML and you've used Java™ applets and the <APPLET> tag, all this should be painfully obvious - you might prefer to skip to the next section.

If you're not used to applets, PLEASE read this, especially the bit about the CODEBASE attribute. I get so many emails about this it's ridiculous, and spend a lot of time just repeating the next paragraph in replies. It isn't that I'm not willing to help, but this is me helping...

The location in which the class file (ryTreeView.class) can be found, relative to the directory containing the HTML document in which you've used the applet. By default, a browser will search for an applet's class file in the folder containing the currently open web page. If that's where you've put the class file, leave out the codebase attribute. If you've put the class file in a subfolder of the current folder called, for example, 'classes', put in that attribute so that it reads: CODEBASE="classes". If this seems confusing, look at it this way: when you use an image on a web page, you have to enter the relative path to the image using the <IMG SRC=> attribute. In the case of images, the SRC= attribute includes both the path to the file and the name of the file. In the APPLET tag, these details are split between two separate attributes: CODEBASE= specifies the path to the class file, and CODE= specifies its name. Therefore, just as with images, if there's no path that the browser needs to follow to find the file, all you need to enter is the filename.

Alternatively, if you get into a pickle with this, you could put in the absolute URL to the class file instead, such as CODEBASE="http://www.my_isp/~me/myfolder/mysubfolder".

This should always read "ryTreeView.class", and case is vital.

The width of the applet. You'll usually want to make the applet as narrow as you can (to save page space!), but check that the text beside all your folders and pages on the menu isn't being cut off. Browsers tend to vary a little in their spacing of text in Java™ applets. To be safe, check your pages in Netscape which applies rather more space to a line of text than Internet Explorer, or visitors to your page that use Netscape might be missing a view characters on the longer labels.

The height of the applet. Once again, you'll want to make this as short as possible. Since only one folder will ever be open at a time, judge the height of the applet relative to what the applet looks like when you open the folder containing the most pages.

Creates space above and below the applet. The default is 0, but you might want to use this to place some fresh air between the applet and any text or images that appear around it on the page. Note that different browsers apply their HSPACE and VSPACE in different ways: Internet Explorer divides the amount evenly left and right (or above and below), while Netscape sticks the whole lot below (or to the right). There are far more reliable ways to create space around web page elements that HSPACE and VSPACE, and I strongly suggest you use one of those instead until everyone gets their act together. One way to avoid using VSPACE is to increase the applet's height setting and use the HeaderOffset parameter mentioned below.

Creates horizontal space around the applet. See vspace, above.

Align settings for the <APPLET> tag work like those for <IMG>. Using top will ensure that a row of TreeView applets will be placed side by side, regardless of the applet's height-setting, if you're ever in the unlikely situation of using several of them! Use left or right if you want to place a paragraph of text to one side of the applet.

Note that in the details below I've mentioned the default settings for parameters. If this is the setting you'd like to use, you can safely leave that parameter out of your <APPLET> tag. However, if you'd prefer to put the parameter in anyway (so that you can change it to something different later on without referring to this list again, perhaps) that's okay. It's worth noting that the applet doesn't need any parameters at all to run - everything has a default - it just won't be very useful that way.

The applet's background color as a hex triplet. For best results, set this to the same value as that of your page's body-background. The default is FFFFFF (white).

TreeView comes equipped with two sets of outliner images: one set of images is prefixed with the letter 'b' (for 'black'), the other with 'w' (for... go on, guess!). This is to ensure that you can use TreeView on both dark and light colored backgrounds. The choice of values for this parameter are dark or light, and these are not case sensitive. The default setting is dark.

(The 'dark' setting is shown in the accompanying HTML file, Details.htm; the light setting is shown in Example.htm.)

The applet expects to find the images in the same folder as the class file. Therefore, the CODEBASE= attribute (explained above) points to the location of the images as well as the class.

By the way, if you don't intend to chop and change between light and dark settings, there's no need to upload both sets of images to your web server. Both sets consists of 11 images, listed below:

Hex triplet for the color of a folder's label when unfocussed (the mouse isn't over it). The default is 000000 (black).

The color of a folder label when focussed (the mouse is over it). The default is 0000FF (blue).

The color of a folder label when the mouse button is clicked over it. The default is FF0000 (red).

A hex-triplet for the color of a page's label when unfocussed. The default is 000000 (black).

The color of a page's label when focussed. The default is 0000FF (blue).

The color of a page's label when depressed (pushed, not sad). The default is FF0000 (red).

A comma-delimited string giving the name, style and size of the font you want to use for all folder labels. The default settings are Helvetica, in bold, at size 11, which would be written as Helvetica,bold,11. Two important things to note: first, there must be no spaces in this entry; second, the three items must appear in the order name,style,size. Note that the style part of this setting can be plain, bold, italic or bolditalic, and these are not case-sensitive.

By the way, I get a lot of emails asking why Futura Book or BrushScript won't work. Java has its own tiny collection of fonts available and has no support for TrueType fonts. Your possible choices are Dialog, TimesRoman, Helvetica or Courier. It's sad, but it's true.

Another comma-delimited entry giving the name, style and size of the font you want applied to page labels. The default setting is Dialog,plain,10. See FolderFont, above.

Specifies whether or not you'd like the applet to play sounds in response to mouse-clicks. The two options are yes or no, and the parameter isn't case sensitive. The default is no (in other words, if you leave the parameter out entirely, you'll have no sounds). See "Using Sounds" below.

Oh gee, I love this parameter! Wish I'd thought of this ages ago. HTML offers it's own range of recognized targets for links: _top, _self, _blank and _parent. But when you use an applet like TreeView that can take countless links, you'll often be opening your pages into a main frame in your browser, perhaps called 'Main', so almost every entry on the menu will need a Target parameter with the value "Main". The DefaultTarget parameter gives you a way to avoid entering all those parameters. Just enter the name of this frame in the DefaultTarget parameter and it will be used by default for any entry on your menu that doesn't have its own Target parameter to override it.

The default setting for this parameter is _top, so if you leave this parameter out, any menu entry that doesn't have its own Target parameter will open its document full-screen in the current window.

The number of folders you want to display in the applet, where the value for this parameter is an integer from 0 to (theoretically anyway) infinity. The default is 1. Although it's quite legal to enter a zero here, I can't see a whole lot of point in doing that unless you really like blank space on your pages to be meaningful. Note that if you tell the applet you want, for example, 6 folders, then enter a Folder7 parameter (see below), that folder won't be shown.

Each folder you want to display will usually require the first two parameters below. The third, Message(n) is optional.

Folder1 Folder2 . . . Folder97 . . . etc

The label for each of the folders you want to display. If you've elected to use 6 folders in the FolderCount parameter (above) and you don't enter a label for folder 3 (for example) by using the parameter <param name=Folder7 value="My Seventh Folder">, this folder will have no label. It can still be opened, though, because the folder image and plus-symbol for it will be placed on the applet in the correct position and can be clicked to open it. Therefore, a folder doesn't necessarily need to have a label.

PageCount1 PageCount2 . . . PageCount97 . . . etc

The number of pages you'd like to display in the correspondingly-numbered folder. So if you want to display 7 pages in folder number 5, your parameter would look like this:

<param name=PageCount5 value="7">. If you don't enter a PageCount parameter for a particular folder, it will default to containing a single page.

Message1 Message2 . . . Message97 . . . etc

A message you'd like to display in the browser's status-bar when the mouse passes over the correspondingly-numbered folder image or label. The default is no message (blank).

Each page you display can take up to four parameters. As usual, none is actually required, but you'll almost certainly want each page to have a label and to link to something, so the first two are pretty vital.

F1-Page1 F1-Page2 . . . F1-Page97 . . . etc

The label to want to appear beside the corresponding page icon. Although this parameter isn't required (a page icon will still appear because you said you wanted one in the PageCount parameter above), if you don't give it a label, it will default to showing LABEL MISSING. I'm basically insisting that you give each page icon a label, and I can do that because it's my applet. ;-)

F1-URL1 F1-URL2 . . . F1-URL97 . . . etc

The URL of the web page or Internet resource you want the correspondingly-numbered entry to fetch when clicked. This may be an absolute URL ("http://www.fishing.net/tangled/up.htm") or a relative URL ("../../another/page.htm"). Note that although Java does support #name anchors appended to URLs (to link to particular parts of a page), not all browsers will react correctly to it, so its use is generally best avoided.

F1-Target1 F1-Target2 . . . F1-Target97 . . . etc

The name of the frame or window you want the correspondingly-numbered page's URL to open in. If no Target parameter is included for an entry, the frame name you entered in the DefaultTarget parameter (above) will be used instead. If you didn't include the DefaultTarget parameter either, the target for this entry will then default to _top.

F1-Message1 F1-Message2 . . . F1-Message97 . . . etc

A message to display in the browser's status-bar when the mouse passes over the correspondingly-numbered page. If you don't include this parameter for a particular page, the status-bar will default to showing the words Link to followed by the corresponding URL entry, showing where that page links to. If you'd prefer that nothing appears in the status-bar at all, include the parameter with nothing between the double-quotes (for example, <param name=F1-Message6 value="">).

The following parameters are very optional indeed. They allow you to place an image, or a menu-heading, or both, at the top of the menu, and to move all the menu's folders and pages downwards to make room. If you don't want to do that, you can ignore all of the following parameters and leave them out of your <APPLET> tag - by default the applet assumes that you don't want any header.

A comma-delimited entry giving the name, style and size of the font you want applied to the header label. The default setting is Helvetica,bold,13. See FolderFont, above, for details on how this value works.

The color of the header label's text. The default is 000000 (black).

The name of an image to display in the header, which the applet expects to find in the same folder as the class file. The image is placed at the left edge of the applet, and is vertically aligned within the center of the area you define as the offset (see HeaderOffset, below).

The text to appear as the label for the header. If you don't include this parameter, no header label will appear. The label will be vertically aligned within the center of the area you define as the offset (see HeaderOffset, below).

An optional 3D text-effect to apply to the header label. There are four possible settings for this value, none of which is case-sensitive:

light Creates a 3D effect by deriving a lighter shade of the text color you chose in the HeaderColor parameter.

dark Creates a 3D effect by deriving a darker shade of the text color you chose in the HeaderColor parameter.

gray Creates a 3D effect using gray shades and ignoring the color of the text label chosen in the HeaderColor parameter.

off No 3D effect. This is the default setting.

The theory behind the choice of three different 'on' settings is that you should be able to find a setting that looks good whatever your choice of BgColor and HeaderColor settings. It's a case of experimentation. If you stick with the default settings of a white background and black header color, the gray setting works best, and will probably be the most reliable choice in most situations. Bear in mind that if your HeaderColor already uses shades set at maximum (such as FF0000 for full-on red), the light setting applied to this will just tend to blur the text - it will be exactly the same color since it can't lighten the red any more.

If you haven't included the Header parameter to place a label in the header, it doesn't matter what this parameter is set at, it'll be ignored.

The value for this parameter is an integer, with a default of 0. When you include the Header parameter to specify a heading label for the menu, that label will be aligned to the left edge of the applet. You can use the HeaderIndent parameter to move the label further to the right. You might do this for aesthetic reasons (you want the label centered, for example). More practically, if you're including an image in the header as well, you might want the label to appear to its right rather than over the top of it, or you might want the text to begn at a precise point on top of the image to create some weird and wonderful effect. It's worth noting that if you haven't included the Header parameter to place a label in the header, it doesn't matter what this parameter is set at, it'll be ignored.

The value for this parameter is also an integer, with a default of 0. If you include a header label and/or image using the parameters above, they'll appear over the top of the first menu entry or entries. This parameter shifts the menu itself downwards to create a space for the image/label. If your image is 20 pixels high, for example, you'd want to enter a value of at least 20 for this parameter to prevent it overlapping your first folder.

Both the image and the header label are automatically aligned within the center of the area you define in this parameter. In other words, as you increase the value of the offset, the menu will move downwards, and the image and header label move upwards so that the space above and below them increases.

Note that this parameter takes effect whether or not you've included the Header and/or HeaderImage parameters. So you can use it to create blank space above your menu, as a substitute for the VSPACE attribute. If you do use this parameter, remember that you'll also need to increase the height of your applet to allow for the extra space it now takes.

Three audio files (.au format) are included in the zip archive. If you'd like TreeView to accompany mouse-clicks with sounds, place these three files in the same directory as the class file (ryTreeView.class) and set the value of the Sound parameter to yes. If you prefer your pages to be seen and not heard, you have three options: you can set the parameter's value to no, remove the parameter entirely (it defaults to 'no sound' anyway) or just take the audio files out of the folder. It's quite permissible to even set the parameter to yes and then take all the audio files out of the folder - it will still run quite happily (and quietly!).

That also means that you can use just some of the sounds if you prefer. Set the parameter's value to yes, and remove the sound file(s) you don't want to use from the folder. It will just use those it can find.

The names of the three files are fixed: show.au plays when a folder is clicked to open it. hide.au plays when you click the same folder a second time to close it. select.au plays when you click a 'page' entry on the menu. If you'd like to change the sound files themselves, go right ahead. The only restrictions are that the files must be in Sun/NeXT format (.au), must be in the class directory, and must use the filenames given above.

The positions of the images (folder and pages) and outliners (dotted lines and plus/minus symbols) are fixed. You can't indent them, increase the spacing between them, or anything like that in this version. It's something I intend to add later. Font options are included though, which could seem like an anomaly. It means that you can adjust the look of the text within reason, but if you set your font size too high, all the labels will overlap. You can safely use a large font like Helvetica at up to 16, but it'll start to look pretty odd beyond that.

To keep the height of the applet to a minimum, distribute your pages evenly between several folders. If one folder has a dozen pages and all the rest have four, you're using a lot more real estate than if every folder had six pages instead.

The sets of 11 images that create the outliners and folders/pages are not actually required by the applet. If you remove them it doesn't look like much of a menu tree, but it still runs. I'd rather you didn't remove them though - it doesn't look like something I want my name on!

Thanks for downloading this applet and giving it a whirl. If you like it, that's great. If you don't, please tell me why - I'm not sensitive about these things!

If you decide to use it on your own non-commercial site, I'd appreciate an email containing the URL so that I can nip along and take a look.

rob.young@btinternet.com

http://www.btinternet.com/~ry/CodeBase

Java is a registered trademark of Sun MicroSystems Inc.