Comments to caug@accu.org
Duncan's program, !Simple, is on this month's disc.
This article has been written by a total newcomer to C and so should show how easy it is (or not as the case may be) to begin programming the WIMP.
As a quick history, I first started coding C in the spring of this year (1994) for "simple" command line utilities but, as can be expected, I wanted to learn to code in the WIMP environment. This is when I picked up the DeskLib C library from a PD archive server on the Internet. Hopefully, my articles will show where I had the most problems and help others to learn to program C by seeing where I went wrong and not making the same mistakes I did.
First some information on DeskLib. DeskLib is written by various people overseen by Jason Williams and it is an alternative to the Acorn C library RISC_OSLib. It's a PD library (so you don't go out of pocket getting it) and is also supplied with Easy C, the RISC Developments suite of C compiler and debugger programs (see issue 3 for a review). Nearly all of the information needed for using DeskLib is included in the library headers and has been split up into related segments (such as icon functions in one part of the library and file operation functions in another part).
The first code I will look at is a DeskLib conversion of the !Simple program (written by Paul Field) which was on the first disc supplied with the CAUGers magazine.
The application is very simple, in that it puts an icon on the icon bar and, when clicked on, it opens one window (the original program could open more than one window). The window can be moved around and resized, with the OK icon closing the window when clicked. There are also two radio type buttons in the window. The menu on the icon bar gives information about the program, has a tickable entry (which wasn't on the original program, but I put it in anyway ;o) ) and a Quit option.
If you haven't seen this program before, it may be an idea to play around with it to understand what the program actually does so that understanding the code is easier.
This article will not go into too much detail about any of the functions or their parameters but should give a general idea of how the code is constructed (I should point out here that I haven't been told "the right way" to code, so my methods may not be the best available. However, comments are always welcome).
The main points to note are the initialisation of the program and the event handling. The code itself is fully commented (overly so) which will also provide some help in understanding it.
Initialisation in the program is all done in the main()
function, where the code is pointed to the directory where all the Sprites
and Template files are to be used from. A messages file is loaded so that
changes to the menu names or program name can be done without recompliation
of the code (this allows for internationalisation). The templates file
containing the window definitions is also loaded here so that the windows
can be created easily.
WIMP programs work by responding to events. Moving a window, closing a window and clicking on an icon are all events that the WIMP system sends to the program. The code must set up event handlers to deal with them.
DeskLib is different to RISC_OSLib in that the event handlers are much more flexible. In RISC_OSLib the event handlers have to be attached to each window when it is created but DeskLib's handlers can be attached generally to all windows. Registering an event handler is simple;
Event_Claim(event_REDRAW, event_ANY, event_ANY, Handler_NullRedraw, NULL);
The Redraw event occurs when the WIMP wants you to draw some of your
window (such as when it is opened or another window is dragged across it).
After this call Redraw events for all windows will be passed to
Handler_NullRedraw() (a handler supplied with DeskLib). This
handler is very simple in that it doesn't actually do any drawing but it
keeps the WIMP happy.
Handlers are also registered to cater for button clicks (such as a Select or Menu click on the icon bar icon) and for the opening and closing of windows. If a handler is left out for opening or closing a window, or for the redraws, then the behaviour of a window in the desktop is rather limited. It cannot be moved and you can't do anything useful with it (I made this mistake and couldn't work out what had gone wrong). The handlers are needed to oversee what happens when a window is moved, hidden behind another window (or in front of one), and to make sure the window can be opened and closed. A similar thing can be said for the mouse buttons. An event handler is needed to see if there are any Select or Menu clicks, and what to do if it finds one.
The handler for the button clicks is very simple (considering ;o) ). The Menu button (if not over the program window) opens the icon bar menu (Info/Ticked/Quit) (as described from the Messages file - look at the code to see this). The Select button on the icon bar opens the main window (if it isn't open already). To save memory, the window is opened on the spot and deleted when the window is closed.
Hopefully, from the annotations in the code itself, you will be able to see and understand the code of this small application. I could write more on this, but I have probably taken up too much room already. If you have any comments on this (was it useful/useless, over commented, not particularly good coding techniques) then please send them to Paul Field so he can put them in CAUGers and pass them on to me. You can contact me directly via email at: dunc@queeg.demon.co.uk.
The next article will be a slightly (?) more complex program that will go a little deeper into WIMP coding through the DeskLib library, so you can see where I pulled my hair out (I still am while I write this), and where I came across a few pitfalls.
From CAUGers volume 1 issue 5
Comments to caug@accu.org