Creating a docked window

what does the ‘Pane’ tick in template editors actually do?

AFAIK, it simply indicates that if the “pane” window gets input focus, the highlight should be given to the window behind it in the window stack.

Having done some more research on this, I should probably come back to add that it also seems to prevent the window from stopping the window below it from being at the top of the window stack. This doesn’t seem to be mentioned in the PRM anywhere, but is the gist of cryptic comments in the Wimp’s source. Experimentation may be required.

On which note, does anyone know what the PRM means when it says on page 3-40 that the flag is used

when toggling the [parent] window size, the Wimp must treat panes as transparent.

I suspect that there’s some subtle behaviour of the toggle size icon’s behaviour that I’ve never understood?

I last programmed toolbars in the last century (1998) when I was trying to emulate the Toolbox in BASIC, before !ResEd was widely available, so I am really rusty. ;-)

However, I dug out the code, tidied it up and added the offscreen action for druck. It does not look all that difficult, unless I have missed something important.

FWIW I have put it in a small Toolbars demo.

it also seems to prevent the window […] below it from being at the top of the window stack.

I am not sure that is true. Any toolbar code would make that happen, wouldn’t it?

the Wimp must treat panes as transparent.

My thought was that it would cause the parent window to be redrawn fully before the pane was overlaid. The pane coordinates may not be known until the parent has resized.

It does not look all that difficult, unless I have missed something important.

It’s not that it’s difficult; it’s that it’s not documented anywhere. The beginners books that I’m aware of seem to give up before getting to it¹, while the PRM seems to think that it’s beneath its readers to even consider explaining the process.

ETA. And actually, it’s not easy to get right if you’ve not done it before. It’s just taken me a few minutes of head-scratching to get my example code from the last page to work when actually run on a RISC OS machine, although to be fair it was 80% WinEd’s fault².

I am not sure that is true. Any toolbar code would make that happen, wouldn’t it?

Possibly, although I note that you’ve removed a key part of my sentence with your ellipsis, so it’s no surprise that it made little sense afterwards. :-)

If you grep the Wimp source, all uses of the flag appear to relate to skipping through panes either on the way down the stack (when looking for where to put the focus highlight, presumably) or up the stack (when working out what is above a window). The “window is on top” flag that I lazily assumed existed appears to be a figment of my imagination, but we can still see this in action with the “window is fully visible” flag. If the pane is over the window it belongs to, and has its “pane” flag set, the “fully visible” flag of the parent is set when there are no other windows over it. If we try again without the pane being flagged as one, the parent’s “fully visible” flag is never set – because it’s never fully visible (as the pane, which isn’t a pane, is over it).

My thought was that it would cause the parent window to be redrawn fully before the pane was overlaid.

Yes, that would make sense – thanks. it would be consistent with the comments in the Wimp source about skipping past pane windows, too.

So there we have it: the better, more concise answer to Paul’s question might be “the flag makes the pane window invisible to the Wimp”. :-)

¹ Wimp Programming For All definitely did; I don’t think I ever read Martyn Fox’s book, but given that IIRC he was reading it, Andrew’s question here suggests that it did the same.

² I don’t think the relevant code has my fingerprints on it (yet), though, so I’m going to claim that it doesn’t make it my fault by extension. Unless it’s documented behaviour, in which case I’ll admit that I didn’t RTFM.

it’s that it’s not documented anywhere.

True, but I did work it out with nothing more than the PRM. I think I probably had only a rudimentary understanding of the window stack and the information that a window could be marked as a pane for the purpose. The most tricky bit was dealing with the inverted Y-coordinates. ;-)

FWIW I have put it in a small Toolbars demo.

Thanks for the demo, but I can’t get it to work. Only the main window is displayed, no toolbar. I’ve tried different numbers for Position% (1, 2, 3 – and even binary ones), but no pane…

Now that’s interesting. I am using a mini.m, still with 5.25. How does your differ?

As this was more or less a copy of code written 25 years ago, I am not surprised there could be problems, but it is quite simple. I will have a careful look.

On RISC OS 5, Pi 4. On trying Toolbars, I receive the following message “File ReportClear not found” from an error window.

Seems to work fine here on an ARMX6. I have Reporter running all the time, and the report window is indeed cleared when it runs.

Mine is a Pi4 too, with RISC OS 5.29.

“File ReportClear not found”

That’s because you have to activate Reporter first. You may also comment that line out.

You mean you do not have Reporter running, always? ;-)

Remove the first program line and replace with the error handler of your choice.

I expect there are also those who do not have Basic$Crunch set, which is going to cause problems, because of comments after IF. ;-)

I will purge the example of these.

Edit: Toolbars demo

Here’s a little example of using a pane. The fixed top and bottom regions are the main window, and the scrolling bit is a pane. Resizing the window is interesting. The pane contains two sets of icons, and the scroll setting of the pane is changed in small increments, When the scroll reaches the bottom of the window, it’s reset to the top. The duplicate icons are set up so that the step is (almost) seamless.
http://www.adamshome.org.uk/RiscOS/IMG_3227.MOV

You mean you do not have Reporter running, always? ;-)

I never do – too much habit of just chucking text at DADebug.
(it’s also useful for those naughty people that assume Reporter is running, preferring to crash than check 😜)

Here’s a little example of using a pane.

This is all interesting stuff. I have done panes in the past but no idea how. In the end I got up (like three in the morning) and dragged some ancient code into Zap.

Ah. I didn’t do panes. DeskLib did. It has not one but two pane handling methods, which can do Draw style panes, in-at-the-top panes, and floating Artworks style too. Plus a demo app showing it in use.

Steve: your demo has an interesting effect. When the window is dragged close to the right-hand side of the screen, the toolbar width shrinks to zero. This is especially noticeable if the main window is shrunk first, as the toolbar shrinkage occurs while the main window is still fully on-screen.

Screen mode here is 2560 × 1440 in case that matters.

(Yes, doesn’t do it in 1280×1024)

Screen mode here is 2560 × 1440 in case that matters.
(Yes, doesn’t do it in 1280×1024)

Doesn’t do it in 1920×1080 either.

Ah! Another effect of just copying old code. ;-(

Look in PROCToolbar and you will see 4096 appears twice. That is supposed to be ‘a number greater than the width or height (in OS units) of any screen you may encounter’. At the time that was true, but not now. Replace that by a suitably large number, say &70000000, and all should be well again, I think.

Edit: I checked, it looks ok.

I didn’t do panes. DeskLib did.

Similarly, I have not ‘done panes’ since this code was written. If I have wanted one, I have used a Toolbox Toolbar object and all these problems vanish. ;-)

If I have wanted one, I have used a Toolbox Toolbar object and all these problems vanish. ;-)

Aha! Someone finally said it!

I’ve been following this thread with a kind of morbid curiosity for the past few days, asking “Whyyyyy?!” :)

I’ve been following this thread with a kind of morbid curiosity for the past few days, asking “Whyyyyy?!” :)

It’s newfangled witchcraft, that there Toolbox… :-)

The more serious answer is probably that the OP appeared to already have a non-Toolbox BASIC program, and whilst the correct answer may well be “use the Toolbox”, that’s less useful when someone already has a commitment to a chunk of code, and wants to use the BASIC code, templates and so on that they have already developed.

It’s the same reason why it’s apparently unwelcome to suggest that BASIC might not be the best choice of language for a large application, even though it’s self-evidently the correct answer… :-)

I’m a bit slow to the party for examples, at least partly because I foolishly decided to do things properly and then got sidetracked tidying up my XML documentation building tools so that they could be used to do more than one project at a time, but I’ve put some thoughts on handling Draw-style toolbars up on my website.

It’s still incomplete, as the vague plan is to add a cross-window toolbar chapter, then re-implement that in the Nested Wimp, then look at some of the other fun stuff that the Nested Wimp can do – and the example code has been crafted with that in mind, which is why it’s probably overkill for the one example that currently exists. However, what’s there now might be of interest to others in its own right.

Feedback welcome, although I’m not sure how much attention I’ll be paying to RISC OS for the next couple of weeks.

At the end of the first example page, there’s a link to the second example, which is broken. Going to the second example from the front page works. The leafname is “a-side-toolbox” in the working link, “a-side-toolbar” in the broken one.

Interesting articles, thanks.

Just as an aside – where is the Toolbox? Is it part of the DDE? If so, that’s a significant reason why I didn’t use it. When I started my biggest (and ongoing) software project I’d just paid a premium price for a computer – A3000 – and could not possibly pay almost as much again for the DDE. That’s also part of the reason why I never investigated C.

The scrolling window example I posted a video of was written shortly afterwards, and has just worked ever since.

where is the Toolbox? Is it part of the DDE?

It’s a little more complicated than that. The Toolbox itself is a collection of modules and I believe that they’re all part of the ROM these days. There’s also an app called ResEd for creating Toolbox resource files, which is bundled with the DDE but is also downloadable separately.

The DDE gets you a 534 page manual called “User Interface Toolbox”, and I don’t believe that this is redistributable. You also get some C headers and libraries, although I think these are freely downloadable from GitLab.

There’s an expectation that your app uses C and all the example code uses it, but I don’t believe that there are any technical reasons why it couldn’t be used from BASIC. (Edit: The manual says “it can be used from C, C++, BASIC or Assembler with equal ease”, although this is the only mention of BASIC in the entire manual).

ResEd is on my mini.m in ‘Develop.Toolbox’. Is it part of the standard disc image? Anyway, it is easy to download, as you say.

If you go to the dark side you can read the UIT manual in the online version.

It certainly can be used from BASIC and the simplest way in is AppBasic, which has excellent support materials. That is in ‘Develop.AppBasic’ here.

It can be used from assembler, but hardly ‘with ease’. The Toolbox is written with a SWI interface, but its design is very OOP, and Basalt added such an interface to BASIC.

Excellent write-up, Steve. I think I had better have a look over some of my library code, as I am sure I have had issues with windows appearing not to be fully visible because of mishandling panes.

At the end of the first example page, there’s a link to the second example, which is broken.

Thanks — the perils of renaming a chapter at the last minute and then doing an FTP update by hand. It should be fixed now, but note that internal links into that page will be changing again at some point (they’re all still …side-bar… and should be …side-box…).

Interesting articles, thanks.

No problem — it’s interesting to research and write, anyway, and I’ve learned a bit doing it, too. :)