GUI Toolkits and the art of Documentation

For an API designed to empower you with the ability to create graphical interfaces for your applications, the documentation for wxWidgets is really lacking when it comes to graphical aids.

For the most part, the reference documentation for wxWidgets is complete, only the newer/lesser used/incomplete features lack documentation. It's also got pretty good descriptions on how you're meant to use certain classes.

However, it seems straightforward to me, that when creating something visual from pre-defined building blocks, it would be helpful to have an example of what those building blocks might look like. For instance, take a look at the following items:

• wxNotebook
• wxToolbook
• wxTreebook

When reading the documentation, it's not hard to figure out what a "notebook" probably is (though of course, until you actually use it, or see it in action it's not for definite). A "toolbook" though? Not sure what that is, apparently it uses a toolbar instead of tabs. How does that work? Thankfully there's a sample in the SDK which demos all of the various "book" widgets. At which point it becomes obvious what a "toolbook" is and you start kicking yourself for not realising from the off. Though you wouldn't have had this confusion in the first place if the documentation had some pictures or diagrams to show you exactly what it is.

Though in that instance we were able to rely on the presence of a sample to inform us that's not necessarily always the case. But in either case, it would be nice not to have to compile some source code in order to know what a certain widget looks like.

It's not as though this problem is limited to wxWidgets either. Here's the official MSDN documentation for a couple of widgets:

• CListBox
• CListCtrl

They've gone to great lengths to describe how these two similarly named but very different widgets look and operate and yet there is not one image to assist the description. A picture is worth a thousand words became a cliché for good reason, don't forget. Juce also does exactly the same thing. Perhaps it's unfair to judge their documentation when a lot of it is actually generated from the source code - but there's no reason why they couldn't have a separate page with a bunch of reference screenshots (which they could then link to from the main docs).

Is it just me that finds this to be an incredibly obvious oversight?

Jucey

I discovered Juce via the rather handy list on Wikipedia. It's actually really easy to get started with and provides lots of documentation for the burgeoning front end developer. And like any decent GUI toolkit it's cross compatible on Windows, Linux and Mac (and even iPhone).

And that's why I'm talking about it today. Where most GUI toolkits seek to wrap the native functionality of the platform or at least emulate it in some way, Juce has it's own look and feel (which is actually quite similar to OS X) which it maintains across all platforms.

This has the end result that (for the most part at least) an application developed with Juce will look the same no matter if it was run on Windows or Linux or OS X. This also means it won't blend in with your standard window decorations.

I'm in 2 minds about whether this is a good idea or not. On the one hand, variety is what keeps things new and interesting, and if you can pull it off well, like Google Chrome or Steam, you can get away with it. There's also the idea that if you have to use the program in an unfamiliar OS you won't succumb to culture shock doing so.

But on the other hand, consistency (across your platform of choice) with window decorations makes new programs easier to figure out and understand, and can also make them feel a lot more polished and professional. I've downloaded many applications from Sourceforge that are perfectly good at what they do, but because they've used a GUI toolkit that draws the widgets differently from the native application, it can stick out like a sore thumb. Take BoncEnc - it's a fantastic program that I use to rip my CDs for playing on my MP3 player, but it doesn't invoke confidence to look at. The strangely thin menu buttons (and drop down items), and the title bar with it's minutiae minimise/maximise/close buttons - it just feels so out of date.

Another thing that Juce does is adopt the OS X traffic light system for the close/minimise/maximise buttons. Unfortunately (in Windows at least, and probably Linux too) to stay consistent with the standard order of these buttons the colour order is amber->green->red. Also, in my personal opinion, I don't really consider "maximise window" to be the opposite of "close window". For me, it would be "Run", but that's not really applicable in this context. In the standard Windows XP theme, the close button is indeed red, but the other two are just blue, the same as the rest of the window decorations.