Back to Contents Previous Next
2. An overview
In this Manual all functions (FN) and procedures (PROC) will be referred to as just “functions”.
The heart of Dr Wimp programming focusses on two provided Basic files: the skeleton !RunImage and the DrWimp library file. These two files are an integrated pair and work in harmony.
The DrWimp library does all the detailed, clever work (and you should leave it strictly alone to do that!) - and the skeleton !RunImage file is where you add Basic coding to build your own application.
The DrWimp library is a collection of Basic function definitions, most of which are intended for you to call from the !RunImage file - just as with a normal Library. All the user-available function names in DrWimp are in lower case and preceded by “wimp_
” . For example:
PROCwimp_dosomethingamazing(curtain$)
and so this Manual refers to these functions as “wimp-functions”. (There are also a number of internal functions in the DrWimp library. They have lower case names starting with “wint_
” and you should ignore these.)
Some of the functions in the DrWimp library need help from you, the programmer. To get your help, the DrWimp library calls a number of functions which have their DEFs in the skeleton !RunImage file. All these functions in the !RunImage also have lower case names, but they are preceded by “user_
” . For example:
FNuser_givemesomehelp(tomato$)
and so this Manual refers to these as “user-functions”,
So, the DrWimp Library holds wimp-function definitions (and some internal functions) and the !RunImage holds user-function definitions - and the two files are inextricably linked by the fact that the user-functions are automatically called by functions in the DrWimp library when needed. (The set of user-functions belonging to one version of the Dr Wimp package will normally only work with the set of wimp-functions in the DrWimp library of the same Dr Wimp version.)
Note also that only the DrWimp library can call the user-functions - you must not make calls to the user-functions yourself.
All the user-functions have to be in your !RunImage at all times, regardless of whether they do anything or not, otherwise your application might complain that one of them can’t be found.
To save you having to type in the complete set of user-function definitions every time you start the !RunImage of a new application, the Dr Wimp package always comes with a skeleton application called “!MyApp”. !MyApp is a fully working Wimp application that does nothing - it awaits your added code. Inside !MyApp is the skeleton !RunImage file with all the correct user-function definitions for that version plus its matching DrWimp library file - plus a !Run file and a !Sprites file.
It is strongly recommended that you always start a new application from a copy of the supplied !MyApp - preserving the original !MyApp as a master.
(There is also the utility !Fabricate which will be introduced later. This enables you to build a rather more useful skeleton application automatically.)
At the start, for a “blank” application which does nothing (e.g. the supplied !MyApp) all the user-function definitions will be ‘empty’ i.e. they will look like this:
DEF PROCuser_something
ENDPROC
or:
DEF FNuser_something
=0 :REM** Or some other ‘default return’ value. **
where the ‘default return’ value (here, 0) signifies ‘do nothing’.
Examination of the skeleton !RunImage listing in the supplied !MyApp application will show the different ‘default return’ values used. For example, you will find that -1, 1 or a null string are also used. Whatever default return value is shown, it still signifies ‘do nothing’ as far as the DrWimp library is concerned and it is vital that you do not change these default values in the supplied master !MyApp application.
To develop an application, you therefore gradually add Basic coding to one or more of the user-function definitions in the !RunImage - often calling the wimp-functions, as we will shortly see in Section 2 of this Manual. Also, you will need to arrange for the return values from user-functions of the DEF FNuser_xxxxx
type to change from their ‘default return’ values in specific circumstances i.e. so that Dr Wimp does not ‘do nothing’ in those circumstances. These actions are fully described in Section 2.
As with any Basic program, it is often convenient and structurally better to put specific routines into PROC/FNs and Dr Wimp offers no restrictions here - you can add as many custom DEF PROC/FNs as you like to the !RunImage or in separate libraries. (But don’t touch the DrWimp library!)
Section 3 of this Manual - and the utility !Fnc’n’Prc, and its StrongHelp equivalent FuncProc (both supplied in the “Utils” folder) - contains a catalogue of all the user- and wimp-functions available to you, giving details what the parameters mean and, where appropriate, what is returned. (!Fnc’n’Prc was written using DrWimp, of course!) The Manual and the above-mentioned utilities are changed for each new release of the Dr Wimp package and will therefore only be valid for their stated version.
The main difference that you will probably notice when developing multitasking Wimp programs is that the program doesn’t ‘start at the top and work its way to the bottom’. Instead, multi-tasking programs proceed in small loops centred on the ‘wimp poll’ and which loop happens to be used at any one time depends on whether an icon has been clicked on, or a window dragged, or a menu item chosen, etc. Your coding of your application therefore is mainly to respond to these different “events” - and you will be pleasantly surprised how easy it is with Dr Wimp.
(The charity book “Dr Wimp’s Surgery” mentioned in Section 1.1 gives a detailed introduction to the multitasking Wimp environment.)
Top of page Back to Contents Previous Next