Back to Contents        Previous        Next









1. Getting going **

With your freshly-copied version of !MyApp visible in a filer window, double-click on it. Nothing should happen. But if you now open the Task Manager display and look at the list of tasks, you should see “MyApp” at the bottom. i.e. something did happen: the skeleton application really works and is properly loaded into the Wimp - although it currently does nothing and you can only quit from this Task display.

The skeleton !MyApp application
Now open the !MyApp application directory - using <shift-double-click> - and you will see something like this (although there may be minor differences and certainly the window title will not be the same:

Picture Pics/pic003.png

You will probably recognise the contents as similar to any simple Wimp application i.e. there are !Boot, !Run, !Sprites, !Sprites22 and Templates files plus a !RunImage file where the main application program resides. Here the !RunImage is a Basic file because that is the programming language the Dr Wimp package uses.

The only unfamiliar file is the DrWimp Basic file. This is the DrWimp Library, already briefly introduced in Section 1.2

The short main program
Now load the !RunImage into !Edit (or your other favourite text editor) and take a look at what is happening. The first ten lines of the listing are:

10 REM>!RunImage - for DrWimp Library Version x.xx **
20 LIBRARY “<MyApp$Dir>.DrWimp”
30 :
40 appname$=“MyApp”
50 ver$=“1.00 (01-Nov-01)”
60
70 ON ERROR PROCwimp_error(appname$,REPORT$+“ at line ”+ STR$(ERL),1,””,0,0,”Quit “+appname$):PROCuser_error: PROCwimp_closedown:END
80 task%=FNwimp_initialise(appname$,7000,360,0)
90 PROCwimp_poll
100 END
(Note: the REM line and date may not be the same as shown here.)

Have a look inside the !Run file as well - and note that its first line of the !Run file effectively copies the system variable Obey$Dir into a new system variable MyApp$Dir, exactly as was described in Section 1.6.

Thus the LIBRARY command in the first working line of the above !RunImage listing uses this system variable and tells the computer that the DrWimp library is also located within the !MyApp application directory - and that it is to be loaded from there into your application’s memory space.


The next two working lines puts an application name and version number/date into the string variables appname$ and ver$. These variables are used later on in the listing.


The next line is a ‘global error trap’ in case an error occurs in your coding. What it does is firstly call a wimp-function PROCwimp_error which displays the error and where it has happened - and then it calls PROCuser_error and PROCwimp_closedown, in turn, to make an orderly exit ending the application. These functions can be safely ignored for now and will be looked at in more detail later on (Section 2.8).

Note: don't add any lines between this error line and the following FNwimp_initialise line, as this could cause problems with the error handling.

The next line is very important:

task%=FNwimp_initialise(appname$,7000,360,0)

Your application can’t do anything until it has been called. It registers your application with the Task Manager and it returns a ‘handle’ for your task (another example of using a handle). Here the handle has been put into task%.

Having said it is important, at this stage of your learning curve it is sufficient to ignore the detail of this wimp-function for the moment - but we need to explain it somewhere and this is the logical place. So you could safely skip the descriptions of each parameter in the following indented paragraphs and come back to them later, if you wish. But don’t forget to come back sometime soon!

The first parameter of this wimp-function is self-explanatory. Note that this is the text that will appear in the Task Display window when the application is run, and can be anything. Try it and see - but not all of it will be displayed if it is too long. The Wimp automatically truncates it if it is too long.
The second parameter - which you will see has the variable name
wimpmem%
in Section 3 of this Manual - specifies how much memory is to be reserved for
window definitions
(including all the icons in the windows). For the moment it is just set to a largish value. When the application is finished you can reduce it to as low as possible consistent with the application still working fully. (It is unnecessary to go into greater detail about memory needs at this point but Section 2.34 revisits
wimpmem%
and also covers the important
WimpSlot
.)


The third parameter is the minimum
version number of RISC OS
that the application is allowed to run on, multiplied by 100. The default is 360, so the skeleton !MyApp will run on RISC OS 3.60 or better. It is up to you to decide this in the light of what you include in the !RunImage. Most Dr Wimp wimp-functions will operate successfully with RISC OS 3.00 or higher, but a few need higher versions. To use all Dr Wimp’s facilities RISCOS 3.60 or higher is needed and this is why the default value here is set at 360.


The fourth and final parameter tells Dr Wimp whether or not you want your application to respond to the ‘desktop save’ protocol - 1 if you do, 0 if you don’t. This is explained in more detail later and, for now, it is left set at 0.

One of the many things that FNwimp_initialise does is to call PROCuser_initialise, whose DEF is a little lower down in the !RunImage listing and currently empty. PROCuser_initialise is specifically intended for you to use for the wide range of application-specific initialistion tasks that are necessary or sensible before wimp-polling starts. For instance, loading window definitions, creating menus, DIMming arrays, declaring global variables, etc.


The final line of the earlier !RunImage extract (the line before END) calls PROCwimp_poll. This deceptively simple call is the driving engine of most Dr Wimp applications - which makes them multitasking. Effectively, this call sets up a continuous wimp-poll loop controlling all user activities. It is only exited when your application quits for some reason, such as “Quit” being chosen from the iconbar menu .

These first ten lines are, in fact, the complete main program for many applications.

You may have been expecting more, but you will find that most of your applications will follow this same very short and simple pattern - needing no more than these few lines of main program.


The rest of the skeleton !RunImage file contains all the DEFs of the user-functions. They are all ‘empty’ at the moment as described in Section 1.2 i.e. they do nothing or return default values. It is the filling of these which makes up the bulk of the programming effort for any application.

As was said above, !MyApp doesn’t do much at the moment and there is nowhere for the user to get access to it. So how and where do we start?

Adding an iconbar icon
The best thing to do first is to add an icon to the iconbar.

So, find the (currently empty) DEF PROCuser_initialise, and add the following new line to it:

iconbar%=FNwimp_iconbar(“!myapp”,“”,0,1)

i.e. between the DEF PROC line and the ENDPROC line.

(If you use clipboarding to export this line to your !RunImage listing, remember the warning on the cover page about ‘smart quotes’!)


This wimp-function creates an iconbar icon and returns a handle for the window that contains it i.e. a handle for the iconbar itself, which is just a special window. So we have assigned the return to a variable with the name iconbar%. (We are not normally interested in the icon number/handle of an application’s iconbar icon, because there is only one iconbar icon per application.) You might wish to note in passing that the iconbar window always has the handle value of -2 - so you will find that the return from this particular wimp-function - and thus the value held in iconbar% - is always ­2.

The first parameter of our new wimp-function (“!myapp”, here) is the name of the sprite to use for the iconbar icon. This sprite must already be known to the Wimp - either because it is a standard one automatically loaded on computer start-up, or because it is included in the !Sprites/!Sprites22 sprite­files in the application directory. In this case it is the latter. (Have a look to check!).

The second parameter is the text to place under the iconbar icon, if you want some. If it is an empty string (a ‘null string’, as here) then no text is printed.

We can leave the third parameter for now: just ensure that it is set at a small value - and 0 is a good idea. We will look in more detail at the use of this third parameter later - in Section 2.15.

The final parameter decides which side of the iconbar the icon appears, 0 for left and 1 for right.

Now save the amended !RunImage and double-click on the application icon as usual to run it. You will see that !MyApp now ‘loads to the iconbar’ in the usual way, with the iconbar icon showing the sprite called “!myapp” without any text beneath it.


Now do some playing: try changing the sprite name to “!draw” in the above call and see what happens after saving and re-running it. (”!draw” is a sprite which will already exist on all RISC OS computers.) Also, try entering some text in the second parameter. Do you see the difference on the iconbar?

After playing, restore the wimp-function call to that shown earlier.

You will note that you are still only be able to quit the application from the Task Window at the moment.






Top of page        Back to Contents        Previous        Next