Creating the Outline applet (again…)

(Or "How I should have done it the first time")

My video worries me. I make my living as a programmer and I’m ashamed to say that I can’t record Coronation Street.

This is partly the result of my complete incompetence with any machine without a space bar, and partly I think it’s a design flaw. You see, there are just so many clever but pointless features on it that I have trouble getting to the ones I really want.

Before I get submerged under a tidal wave of emails from offended VCR designers, I must put my hands up and plead guilty to the same offence. When I’m designing applets I spend far too much time adding features that I think are useful, and not enough removing features that aren’t.

Well over a year ago now, I created and distributed an applet that could be used like an outline tree control that you see in the File Explorer in Windows. It didn’t take long to do and I was really pleased with the result. Why? Well, it had a couple of novel features that I hadn’t seen in other applets. Firstly, the images of the folders, the icons and so on were not stored as separate GIFs or JPGs. I had worked out a way of storing them inside the class files.

Secondly, it didn’t get its configuration information from the parameters that were passed to the applet. Instead it read the HTML code that sat between the <applet> and </applet> tags. Very clever.

And, of course, completely useless.

I had spent so much time thinking about making the applet original that I had forgotten about making it good. The truth is that the applet was horrendous to use. The images that were stored inside the class files as bitmaps, which doubled the size. And the applet was so strict in its interpretation of HTML that it became virtually impossible to use a visual page editor with it.

And then there were all the features I had left out. Not only were the icon images fixed, but you couldn’t even change the background colour.

So you can see, I am writing as a penitent – humbly asking forgiveness for all those who had so much trouble using my little Outline applet, and detailing how I went about fixing it.

 

Designing from the outside in

The people who are going to use your applets are going to do so from the outside. They won’t really care how clever they are internally. So the first thing I did was write down a list of the features I wanted the applet to have, without thinking how I would code them.

The most important thing was to make it easy to pass the outline/tree information into the applet. The old idea of getting it from the underlying web page had it’s merits (it could read the code provided for non-Java browsers, and in so it reduced duplication) but it was so horrendous to use that most people gave up on it.

One of the easiest ways to store highly structured data is in an XML file. XML is a file format that’s a little like HTML, but instead of describing how data should look, it describes what the structure of the data is, e.g.:

<FOLDER><TEXT>The main folder</TEXT>

<FOLDER><TEXT>A sub folder</TEXT>

</FOLDER>

</FOLDER>

Although it looks a little complicated at first sight, I figured it would still be relatively simple for a web designer to amend.

The next feature I decided to add was a changeable background colour. I had more requests for this feature than anything else. And of course it was an extremely simple feature to add. But sometimes the more obvious a feature is, the less likely the programmer is to spot it. As well as changing the background I decided to make the other colours configurable too: the hyperlinks, the foreground colour, the text colour and the selected item colour.

The third feature was to allow the web designer to change the icons. That meant getting rid of my very clever internal-bitmap code, which nearly broke my heart but made the applet a million times more useful.

And then I stopped. I could think of a lot of other bells and whistles that I could add - like sound, animation and transition effects – and whilst some people would undoubtedly find these useful, a lot more would probably find them confusing. If I were to get requests from designers later on I might change my mind, but for the moment I decided to stick with the ones listed.

 

Programming from the inside out

Having got a list of features down on paper, it was time to turn them into reality. I started with the trickiest part first: the XML data structure for a tree.

Java is soon to get a set of XML class libraries that will make the whole thing child’s play, but for the moment you have to do it yourself.

The XML code is contained in the FolderData class. I began with a simple command-line application that read in a formatted file and then split it up into tags and non-tags. Once this was working, I needed to turn that raw string data into a more structured form.

A tree structure needs nodes: and each of these nodes is a member of the Folder class. A folder may have a parent folder and it may have sub-folders. It may also be open or closed. These and other details were added before I’d even thought of how the main applet class would work.

If the internal data structures were wrong, it wouldn’t matter how pretty the applet was; it simply wouldn’t work.

 

The next stage

The rest of the features related to appearance, so that was the next part I started to program: the applet itself.

The bulk of the methods written at this stage are in the Paint Section of the Outline.java file. The heart of it is the recursive drawBranch() method, which draws a single folder and all of its sub-folders.

drawBranch() was the first really complicated piece of code I had to write. The problem lay in how to draw the connectors (the dotted lines that join up the hierarchy). If I was going for a full bells-and-whistles approach to the design, I would have created each folder as a separate container, with the name and folder icon at the top of the panel and the dotted line down the side. It was a nice design but I suspected it would be slow.

Instead, each branch draws a full set of vertical lines (one for each level of indent) to the left of it, and then after a full branch has been drawn, the extraneous lines are removed. The result is sufficiently quick that the appearing/disappearing lines are not visible, even on a reasonably humble PC. And it's a good deal simpler than resizing one embedded container after another.

To begin with I had written constants into the code for the different properties, and after I got it working it was time to go back and replace them with proper attributes. Each colour attribute contains a "get" method, a "set" method and "setValue" method. Why a "setValue"? Well, more advanced browsers like Internet Explorer 4 and Netscape 4 can call applet methods directly, but they like to pass strings in rather than other types of objects. The "setValue" methods allow a browser's Java engine to dynamically change the colour of the applet. This potentially adds a lot of value to the applet with very little work. It also means that the init() method in Outline.java it made considerably more readable, because I have an easy way of turning parameters straight into attribute values.

 

Make it interactive

The first thing I had to decide when designing the mouse interaction was the level of Java it should support.

JDK 1.1 is the version of Java found in virtually every browser these days. But you can guarantee that the very small proportion of people who are still using old browsers, like Netscape 3, will fire off emails complaining about a "bug" in the applet as soon as it's released. It's not too bad if they send them straight to the applet author, but if the applet is being used on a third-party site it could acquire an ill-deserved reputation. So, I decided to stick with JDK 1.0 mouse operations. When the old Java engine is dead and buried it should a reasonably simple task to switch the applet over.

The next big decision was how precisely would the mouse interact with the applet. Most people using Windows have got used to single clicking a folder to select it, and then double clicking to open it. But I wanted the folders to also work as hyper-links, and most people will only click hyperlinks once. This sort of confusion caused Microsoft to switch off single-click execution in later releases of Internet Explorer 4. Also, people from non-Windows backgrounds, may hate double clicking anything.

The solution that I finally adopted was to make double-clicks the same as single-clicks. The applet does this by ignoring clicks if they come within 300 milliseconds of a preceding one. That way, the worst that could happen is that someone might accidentally open or close a folder, but they would at least know how to reverse the action. In tests, I found that most people were unaware that anything strange was happening.

 

Keep it simple

The second time I wrote the applet I think it was a lot better. It just wasn't as clever. The two features that had been hardest to create in the first version were thrown out and a whole raft of new features I could have added were shelved.

But the new version let's a web designer have much more control over the appearance (see the examples on the CD-ROM) and they will find it a lot more configurable.

By removing the features that most people didn't need, it opens up a lot more features that they do.

Now, if I could only get that damn VideoPlus+ menu to work…