Handling Panes

One area of the RISC OS Wimp which appears to be shrouded in mystery is the handling of pane windows. Whilst many modern applications will have toolbars or status displays, how they’re implemented is something that doesn’t seem to get a mention in any of the books on programming. Even the usually helpful Programmer’s Reference Manual is coy on the subject.

This guide was written after seeing the question asked many times in the forums and newsgroups. It isn’t intended to be a beginner’s guide to Wimp programming, but rather a more detailed look at the specific issues surrounding the handling of pane windows within applications. If you’re looking for an entry-level guide to the much larger subject of writing desktop applications, then for BASIC programmers I would suggest looking at A Beginner’s Guide To Wimp Programming or Wimp Programming For All (which is available to buy from R-Comp through their PlingStore application). If your preferred language is C, then you may find my own Wimp Programming In C tutorial helpful.

It’s worth remembering that these days there are many ways to handle panes. In addition to doing things the ‘old-fashioned way’, there’s the Nested Wimp, the Toolbox and even third-party libraries such as DeskLib if you're working in C. Whilst I’ll cover some of these here, I won’t cover them all. If you’re starting work on a new application, it’s definitely worth considering what the best approach would be – the newer, ‘higher level’ solutions were created by Acorn to make developers’ lives easier!

The examples in this tutorial are written in BASIC, but the techniques are equally applicable to other languages such as C – I hope that I have managed to explain them in a way that allows them to be applied in your environment of choice. The example code is all licenced under the MIT No Attribution Licence, with the aim of making it as widely useful as possible.

Many thanks to all those on the ROOL Forums who have offered suggestions while I’ve worked on this guide; in particular Steve Drain, whose input helped to clarify some of my misunderstandings on the subject.

Chapter 1: An Example Application
We’ll need a simple application to add our panes to, so let’s start by putting one together.
Chapter 2: A Side Toolbox
Everyone knows what the toolbox in Draw looks like, so let’s make one of our own.
Chapter 3: A Top Toolbar
Many applications have toolbars across the tops of their windows; just don’t call them ribbons.
Chapter 4: Column Headings
So far our toolbar has ignored the main window contents; what if we want it to remain in step with the work area?
Chapter 5: Does Order Matter?
The order in which we open our windows can have some surprising effects – at least on some systems.
Chapter 6: The Nested Wimp
It isn’t necessary to do everything with panes by hand, so let’s see how the Wimp can help us out.
Chapter 7: Responsive Nesting
We can still alter the contents of nested child windows – it just requires a slightly different approach.
Chapter 8: Moving the Furniture
Our panes don’t have to be over the window’s work area – we can turn them into window furniture, too!
Chapter 9: An Embedded Toolbox
For a truly minimalist look, we can embed a toolbox into one of our window’s scroll bars.

About this tutorial

This tutorial is licenced under Version 1.2 of the European Union Public Licence, and the source – in the form of a collection of XML files and the associated graphics and example downloads – can be found on GitHub. It can be built into the format required by this website using my XML Docs tools; these may be useful as a starting point for using the content in other forms, and are also released under the EUPL v1.2.

The content of the example archives, made available to download at points throughout the tutorial, is licenced under the MIT No Attribution License in order to make the examples as useful as possible to those wishing to learn from them. The intent is that whilst re-use of the tutorial text itself must be done within the terms of version 1.2 of the EUPL, free use of the example code can be made by developers in their own RISC OS applications.