Learning to program the Wimp in BASIC

Hello everyone,
I’ve been away for a while.
I’m back and now I’m ready to take on the bigger challenges in RISC OS.

I’m looking to get programming with the Wimp in BBC BASIC.

Could you give me some information on how I could go about doing this? I’m looking to make something that’ll work in as many RISC OS configurations as possible so I don’t really want to use extra libraries or anything.

The project idea I’m currently dreaming of is porting this JohnsonScript demo to RISC OS.
https://github.com/dusthillresident/JohnsonScript/blob/master/example_programs/pentomino_puzzle_solver.txt
It’s a GUI puzzle solver for pentomino puzzles.

Thank you,
- PM

There are several multi-tasking programmes written in BASIC. Suggest you try downloading one and getting an idea about how it works. I started with some of the RISC OS apps written in BASIC such as Meastro (I think) in 1988 (before the PRMs were published in 1989) and just added VDU 7 commands in various places so I could work out what bit did what. One example is !DrawDis from !Store which just displays a Draw file in a resizeable window. You can then poke bits into the Draw file and the screen updates.

There are ten little multitasking apps, all written in BBC BASIC, on my website:

http://clive.semmens.org.uk/RISCOS/RISCOS.html

You’re welcome to mess around with them, borrow any bits you find useful, or whatever you want to do with them. They’re not as well commented as they might be, but there are a few comments, and mostly the variable and function names are (semi) meaningful…and all far smaller than Maestro… 8~)

Dr Wimp is a good libary for the WIMP part I find,

Thanks for that, Kevin. I’ve not come across Dr Wimp before. I’ve written numerous WIMP programs, but my repertoire of tricks is limited and my technique probably not optimal, so something like that may well be useful.

There is the “Wimp Programming for All” book by Martyn Fox. If I remember correctly, you get this in the manuals or documents directory with the Risc OS Direct download as a PDF file. This book concentrates on BASIC and is very good.

Ah – that’s the one, Graeme. I was trying to remember the name of the book I had. I might still have it somewhere…

There is the “Wimp Programming for All” book by Martyn Fox.

There’s a conflation of publications…

Wimp Programming for All was by Lee Calcraft and Alan Wrigley, and is available to purchase from R-Comp through the PlingStore.

Martyn Fox’s book was A Beginner’s Guide to Wimp Programming, and is freely available from riscos.com.

Edit to add: it’s worth noting that both books are seriously dated. Unless R-Comp have done a new edition, WPfA doesn’t really cover basic stuff for RISC OS 3 – even when I learned from it in around 1993, I can remember having to fill in a lot of gaps when things didn’t behave like the other applications running on the computer.

ABGtWP does discuss the use of Templates for windows (and even uses WinEd and not FormEd for the examples, which surprised me), but WPfA also does all of its window design the “hard way”.

For a simple, BASIC application shell which uses Templates, you might do worse than the one described in the first chapter of this tutorial – but I am probably biased! It’s permissively licenced, so you can safely use it as a base to work from.

Dr Wimp is a good libary for the WIMP part I find

Is that the most recent version? I seem to have a version 5.04 here, but I’ve no idea if it was officially released or not. I seem to recall there being a few bugs which began to trip over changes made to RISC OS 5, hence the updates.

Wimp Programming for All was by Lee Calcraft and Alan Wrigley

Aha! That wrings moor of a belle!

WPfA also does all of its window design the “hard way”

which is probably what I do…I should update myself…except that I scarcely do window design at all, all my apps simply allow you to drop a file* on the icon bar, and then produce a new file* you can drag off elsewhere to save or drop into some other app. Some of them offer you various options via menus and/or radio buttons.

And of course I’ve only ever used FormEd.

• Or in some cases a bunch of files, or a directory full of files or further directories…

I never realised they were two separate books. Somehow I thought the first edition had the black/green cover and the second edition was white/blue!

Like Clive, I don’t use templates either, building everything through functions and procedures.

The books are both dated but most of the information is still relevant for getting started. This is how I started, then using StrongHelp manuals for more up-to-date information and reference to how WIMP blocks are made.

I have a recreation of Ray Favre’s Dr Wimp’s Surgery near to completion. It’s the result of being mugged by Jim Nagel at the 2019 London show. He needed help in rescuing the book because all Ray’s files and printing masters had been lost.

I’m carrying out a final proof-reading before converting the Impression document into a PDF. Since Jim’s death, I’m now carrying this out under the aegis of Gavin Smith at Archive and when completed it will be available from the Archive web site as a free download.

The intention is that this first essay will be as close as possible to a facsimile of the printed second edition as I can make it. The differences will be down to my ignorance of the base font used and the exact page metrics.

Further editions will become available as and when corrections and suggestions are (hopefully) submitted.

I’ll make a formal announcement when the document is ready for download. That should be sometime before the next millennium.

If anyone is interested in how the book was rescued, there is a video of the talk I gave at the recent MUG virtual show. It’s on YouTube and there is a link to all the talks from this page on Vince Hudd’s Riscository web site.

Sorry about the dressing on my nose; I’d had some minor surgery and am now looking normal, though I realise that is a subjective assessment of my appearance with which you are at liberty to disagree.

The books are both dated but most of the information is still relevant for getting started.

The main problem that I can recall wasting weeks of my time on¹ is that (having checked Martyn’s book online) both books only pass 200 in R0 to Wimp_Initialise, and for very basic modern stuff (eg. Interactive Help on your menu entries) an application would need to pass 310 in order to say “I know about RISC OS 3.1”.

This causes R3 to become significant, and neither book mentions it: effectively passing NULL. Which in turn means “I don’t want any user messages apart from Message_Quit” – something that will make it hard to do any message handling until the missing information has been filled in.

As an aside, I see that I’ve got the meaning of the value passed to R3 wrong in the tutorial that I linked to. Passing a pointer to an empty list (one where list%!0 = 0) in R3 means “I want all Wimp messages”, which is also bad. An application should only request the messages that it actually needs to respond to, so that it isn’t getting paged in every time the Task Manager spams the system with a change. I guess that I’ll be doing an update to fix that.

There are other significant omissions, however – many of which have brought in functionality which massively simplifies the task of the developer. It’s the age-old “not knowing what you don’t know” problem; the lack of a modern tutorial for Wimp programming was partly what caused me to start work on my own².

Like Clive, I don’t use templates either, building everything through functions and procedures.

That has its place, but for a beginner in 2022, I’d still recommend using a decent template editor³ that enforces Style Guide compliance and loading the designs in with Wimp_LoadTemplate. Unless DrWimp offers programmatic routines, the prior knowledge and time investment required to make this easier than using a template editor is likely to be a significant frustration – I know that I ripped out all of the programmatic routines from my software and went to templates as soon as I’d got a copy of FormEd from Beebug⁴.

These days, I might consider programmatically creating standard dialogues in some cases. However, a lot of care would need to be taken to ensure that all text is loaded from the Messages file in order to allow internationalisation, whereas templates solve that problem straight off.

¹ We are talking pre-internet here, when one had to reverse engineer other people’s code, buy the PRMs, or possibly order StrongHelp from a PD Library (if the OS manual existed then).

² It’s for C programmers, however, so not relevant to this thread; it’s here for those who are interested.

³ WinEd is the one that I’m familiar with; there are others, including TemplEd which comes with DrWimp, and FormEd, which I would strongly advise newcomers to avoid.

⁴ Again, see footnote 1.

buy the PRMs

I was in the fortunate position that the Physiological Society bought the PRMs for me…

The other problem with programmatically creating windows and icons is that doing it for 3D widgets requires everything to be indirected, which in turn requires a steep learning curve that isn’t covered in either of the books. It can be done using structured routines, but unless there’s an off-the-shelf library to already do it, I don’t think that a newcomer would find it easy to create those from the start. Both books above use flat, RISC OS 2-era template designs (the ones with action buttons that inverted on mouseover).

In contrast, using WinEd or TemplEd, it’s just a case of dragging the 3D designs from the icon palette into the correct places in the window template, then leaving Wimp_LoadTemplate to sort out all of the pointers and memory allocations automagically.

doing it for 3D widgets requires everything to be indirected

quietly wonders what 3D widgets are, and why I might want them (no criticism of anyone who knows what they are or wants them intended, of course)

I seem to have a version 5.04 here, but I’ve no idea if it was officially released or not.

5.04 is the latest to the best of my knowledge. Martin and I both made a few changes, and I also updated the documentation in line with the various updates. Anyone looking at the changes log shoulod note that Chris Johnson and CAFJ are one and the same. In the department at work all staff were known by their initials in departmental documentation, etc., and I had an autopilot moment.

Once we had made the changes for 5.04, Martin sent the revised versions to Gavin to be placed on the Archive web site in the Ray Favre section. Whether that actually happened I do not know. I know I sent out 5.04 privately to a small number of interested parties.

@Patrick M An alternative to Dr Wimp is AppBasic which can be downloaded from http://appbasic.jettons.co.uk/downloads/. It has an IDE and contains all you need to create WIMP applications using Basic and RISC OS Toolbox modules. Lots of examples and well worth a look.

quietly wonders what 3D widgets are, and why I might want them

The grey, bevelled, “3D effect” icons that have been standard on the desktop since the RiscPC.

Prior to that, icons were usually 2D: white with a black border for text, and cream with a black border for action buttons.

The effect requires an R validation command to be set up for every icon, which is relatively non-trivial to do easily in a programmatic way. Not impossible, but I suspect that it’s a hassle that a new programmer could easily do without – and using templates solves the problem.

Once we had made the changes for 5.04, Martin sent the revised versions to Gavin to be placed on the Archive web site in the Ray Favre section. Whether that actually happened I do not know.

The link that I have for DrWimp was to Ray’s old website, which I think Jim was maintaining and I suspect did carry 5.04. However, it went offline some time after Archive changed hands, and is still down to this day. The link that Kevin supplied was a different site, and I’m unsure if it was up to date.

I know I sent out 5.04 privately to a small number of interested parties.

I have a copy here. What I’m not clear on is if it was a pre-release version, or not. :-)

Update: The Wayback Machine suggests that 5.02 was the last version published on Ray’s site before it vanished, too. Unless there’s a hidden bit on the Archive website, maybe 5.04 never made it out into the wild?

Thanks, Steve – I wondered whether perhaps that was it.

I suspect that it’s a hassle that a new programmer could easily do without

It’s a hassle an old programmer can easily do without, too

and using templates solves the problem

if simply not bothering with them isn’t regarded as a perfectly adequate solution.

Unless there’s a hidden bit on the Archive website

In the latest docs I have (March 2021) there is listed a subdomain of the archivemag web site, viz. rayfavre.archivemag, but it seems to redirect to the archivemag home page.

Maybe I should contact Martin (Avison) to work out what the latest files are.

I should point out that, although I have made a number of updates to the DrWimp library (and some of Rays apps based on DrWimp) I have never used the library or apps in anger. What I did was essentially the result of lots of prodding from the late Jim Nagel. I seemed to be his number one goto whenever there was a problem with a bit image or the Drwimp stuff.

The latest datestamp I have for v. 5.04 is 23 Jan 2018, and that corresponds to the date in the history file, so I guess that is the latest.

A lot of the changes I made to the docs in 2021 were related to changes of direct references to Ray Favre stuff and substituting with archive magazine addresses, urls, etc.

and using templates solves the problem

if simply not bothering with them isn’t regarded as a perfectly adequate solution.

Templates versus building windows?

Been there, done that.

Here’s the self-flagellation of making windows in memory blocks:

https://heyrick.eu/blog/index.php?diary=20151226

Since BASIC has no data structuring, you get joy like this:

icon% = icon% + 32  : REM Set base of icon data for icon two
icon%!0  = 6        : REM Mostly the same as icon zero.
icon%!4  = -122
icon%!8  = 206
icon%!12 = -78
icon%!16 = (&17<<24)
icon%!16+= %1100010001
icon%!20 = wimp%+306
icon%!24 = -1
icon%!28 = 11
$(wimp%+306) = "Fahrenheit"+CHR$(0) : REM Icon text

And that’s just one icon. Repeat it several times for the other icons, and then a whole load more for the window to put them in. It’s painful, and not in a good way.

And the very next day, do it “sensibly”, using templates, where window creation is a pointly-clicky affair.

https://heyrick.eu/blog/index.php?diary=20151227

And all of that crap to build the window becomes this:

REM Now get the Wimp to create this window
SYS "Wimp_OpenTemplate",, "<CtoF$Dir>.Templates"
SYS "Wimp_LoadTemplate",, wimp%, icon%, (icon%+400), -1, "main", 0
SYS "Wimp_CreateWindow",, wimp% TO win%
SYS "Wimp_CloseTemplate"

It’s obviously a tad more comlicated as indirected icons need some room, and so on, but dealing with that (and there are plenty of libraries available for BASIC and C) is so much easier than dealing with the Wimp at the bits and bytes level to make a window from scratch.
If there are multiple windows, just repeat the LoadTemplate and CreateWindow lines for all of the others, changing the parameters as applicable.

I’d give an example here, but all I can find is stuff written in C.

Templates versus building windows?

I’m not questioning that, very far from it. I’m only too well aware of what a pain constructing stuff in memory blocks is. All I’m questioning is whether the 3D widgets matter at all.