Back to Contents Previous Next
33. Bits & bobs
Here are a few other useful points.
Current day/date/time
It is often useful to be able to insert the current day and/or date and/or time into text etc. The following wimp-function is provided for this:
FNwimp_getdaydatetime(choice%)
Depending on the value of choice%
- see Section 3.1 - a string is returned containing either the day, the date, the time, or all three.
Number formatting
There are numerous occasions when numbers need to be presented in a certain format and Dr Wimp provides several wimp-functions for this. For example:
FNwimp_decplacesstr()
- gives (as a string) a number rounded to a chosen number of decimal places.
FNwimp_decplacesnum(
) - as above but returns a number instead of a string.
FNwimp_roundfloat()
- rounds a number to the nearest integer.
FNwimp_numtodecstring()
- converts a number in any format to a decimal integer (as a string).
FNwimp_numtosigneddecstring()
- converts a number in any format to a signed decimal integer (as a string).
FNwimp_numtohexstring()
- converts a number in any format to an integer hex value (as a string).
FNwimp_numtobinstring()
- converts a number in any format to an integer binary value (as a string).
Note that most of these wimp-functions produce a string output. This is because in wimp-programming the display of numbers is invariably in string form.
Directory paths/Leafnames
Sometimes it can be useful to get a directory path or a leafname from a pathname.
If the pathname is:
IDEFS::Andy.$.Progs.Project1.!Wow.Sprites
then the the directory path is IDEFS::Andy.$.Progs.Project1.!Wow.
(note the trailing fullstop.)
and the leafname is Sprites
DrWimp can extract these names for you with:
FNwimp_getdirectorypath
(path$)
which returns the directory path, including the trailing fullstop (or trailing colon if something like “Boot:!Help” is the full path) and:
FNwimp_getleafname
(path$)
which returns the leafname.
Filer actions with files and other directory objects
It is often convenient to be able to replicate normal Filer actions by programming instructions. Several wimp-functions are provided for these purposes. They are:
FNwimp_copyobject(sourcepath$,destinationpath$,deletesource%,ne-wer%,restamp%,force%,warning%)
FNwimp_deleteobject(filepath$,force%,warning%)
PROCwimp_setfiletypenumber(file$,filetype%,warning%)
PROCwimp_setfiletypehexstring(file$,filetype$,warning%)
FNwimp_getobjecttypenumber(path$,warning%)
FNwimp_getobjecttypehexstring(path$,warning%)
PROCwimp_doubleclickobject(path$,warning%)
PROCwimp_createdir(path$,warning%)
FNwimp_renameobject(existingpath$,newpath$,warning%)
PROCwimp_opendirectory(dir$,default%,topx%,topy%,width%, height%,iconsize%,sortby%,warning%)
PROCwimp_closedirectory(dir$)
FNwimp_copyobject()
can be used for both copying and moving a file/directory/application. Its first two parameters define the object to be copied/moved and the pathname of the copied/moved object. (Both can be wildcarded within the same constraints as using the *Copy
star command. Recursion will take place, as necessary.)
If the third parameter, deletesource%
, is set to 0 the object will be copied, and if it is set to 1 the original object will be deleted after it has been copied - effectively moving the file. But note that the move option (i.e. setting the third parameter to 1) will not work for locked files unless the force%
parameter is also set to 1.
The parameter newer%
only comes into effect if the copying action would overwrite existing objects, when setting newer%
to 1 will only overwrite if the source object is newer than the destination object.
If set to 1, the parameter restamp%
gives the option of re-stamping the copied object with the current time/date.
If warning%
is set to 1, a warning will be given if the source object does not exist. (If the object does not exist and warning%
is set to 0 then no action will take place.)
Finally, this function normally returns 1, but will return 0 if the copying action fails in any way.
FNwimp_deleteobject()
is similar but, of course, takes only one file-path. If force%
is set to 1 locked objects will be deleted: if it is set to 0 they will not be. Again, directory recursion and wild-carding can be used. warning%
acts as in the previous function. Also, the function normally returns 1, but will return 0 if the action fails in any way.
PROCwimp_setfiletypenumber()
is straightforward. The required filetype needs to be set in the second parameter filetype%
as a numerical value in the range 0 to &FFF. (Anything outside this range will be set as &FFF.) Again, warning%
acts as in the previous functions but covers more circumstances. Its companion is PROCwimp_setfiletypehexstring()
and in this case the required filetype needs to be set in the second parameter filetype$
as a string in the hex form “&FFF” or just “FFF”. The same range correction will apply and warning%
acts as in the previous functions but covers more circumstances.
To find the file-type of a named object use either FNwimp_getobjecttypenumber() or FNwimp_getobjecttypehexstring()
. The first returns the filetype as a number and the second as a string. Again, warning%
acts as in the previous functions.
Note that the second function is an exact repeat of FNwimp_testobjectpresent()
but with a different name for convenience. Note also that the file-type of an object identified by number in a named directory can be found using FNwimp_getdirectoryobjecttype()
.
PROCwimp_doubleclickobject()
acts exactly as if the user has double-clicked on the specified object. Again, warning%
acts as in the previous functions.
PROCwimp_createdir()
is straightforward and creates an empty directory. Again, warning%
acts as in the previous functions but covers more circumstances.
FNwimp_renameobject()
is also straightforward - it will rename an existing Filer object. Again, warning% acts as in the previous functions but covers more circumstances.
PROCwimp_opendirectory()
opens a Filer directory window - and if warning%
is not 0 a non-fatal warning if the specified directory cannot be found. If default%
is not 0 then the window opens centred on the screen and with the default settings currently in force for the Filer. If default%
is 0 then the other parameters are taken into account to specify the window position, the size of the Filer icons and how they are sorted. See Section 3.1 for details.
PROCwimp_closedirectory(dir$)
simply closes the specified directory window.
Note that the above wimp-functions have deliberately been structured to avoid giving fatal errors. Further, those that are FNs give a return of 0 (or null string) if the required action does not take place. You are therefore able to capture the return value to take action on errors if you so wish.
Sending a file to the printer
The wimp-function PROCwimp_sendfiletoprinter(filepath$,delete%)
is intended to have the same effect as dragging a file to the printer icon on the iconbar.
filepath$
is the full path of the file to be sent to the printer and delete%
gives the option of deleting the file after it has been printed. If delete%=0
the file will not be deleted.
Note that this wimp-function will give non-fatal errors if a printer driver is not loaded or the specified file cannot be found.
Caret location
FNwimp_getcaretposition
returns information about the current location/position of the caret.
Five items of information are available: the handle of window and icon with the caret in them; the x and y work area coordinates of the caret in a window; the position (’index’) of the caret within the text of a writable icon.
DrWimp library version number and upgrades
The DrWimp library periodically gets upgraded with modifications or improvements and this can mean that applications which you have made with earlier versions may not work properly (or at all) if you try to substitute the new DrWimp library.
To protect against this, there is a wimp-function to read the version number of the library. So, for example, at the start of your program you could add a short routine to read the library version number and alert you if it is not the same one as you used to create the application.
The wimp-function is FNwimp_libversion
and it returns the DrWimp library version number x 100. So, if it is Version 4.30 then it will return 430.
Don’t forget that there is no need to use any later DrWimp version with an application that is working to your satisfaction with an earlier version - even less need if you have used the post-programming utilities such as !Linker, etc.
However, if/when you decide to upgrade your application then it will probably make sense to use the then latest Dr Wimp version to do it and you can start by incorporating the new DrWimp version before making other changes. Always read the ‘Upgrade’ file - within the ‘Documents’ folder - to see what changes (if any) will need to be made to applications constructed with previous DrWimp library versions. Usually, where changes are necessary, they are very simple to do.
Of course, if you are starting a new application then it always makes sense to start with the latest version of Dr Wimp.
It is probably obvious, but in any complete version of the Dr Wimp package, the !Fabricate utility will always produce its skeleton application using the !RunImage/DrWimp library version of that package.
Resizing windows
PROCwimp_resizewindow
resizes a window’s work area to the supplied width and height. The work area is set to the new values, but the visible size will not be changed (unless the new work area is smaler than the visible size).
Use PROCwimp_resizewindowvisible
to alter displayed size. N.B. If the visible window is wholly on the screen before using this wimp-function then it will be kept wholly on the screen after the re-sizing i.e. scrolling may take place automatically to achieve that.
Scrolling windows
There are three wimp-functions to manipulate the scrolling of windows from your program:
PROCwimp_scroll()
allows you to scroll a window up/down/left/right by a user-given amount from its current position.
PROCwimp_scrollto()
allows you to scroll a window to a specific scroll position (vertically or horizontally).
FNwimp_getscroll()
returns the current scroll position of a window (vertically or horizontally).
All three wimp-functions can be used when the window is closed - and, with the first two wimp-functions, the new scroll position will be correctly in place when the window is next opened.
Note that the position of a vertical scroll will normally be a negative value.
To scroll a window at any particular time it must, at that time, have a visible size less than its full size (in the direction of the scroll) - and the definition of its minimum allowable visible area (in this same direction) must be such as to permit the required scroll. Dr Wimp will always carry out the scroll to the maximum extent possible if scrolling to the full amount intended is restricted. (If scrolling does not appear to happen it is invariably due to the fact that the window is either already at full size or already at one of its defined limits of allowable scroll.)
Icon colours
PROCwimp_colouricon
can be used to change the colour of the text/background/border of an icon. The colour choice is from the standard 16 desktop colours - numbered 0-15.
From Dr Wimp version 3.62 colour change can be applied to icons defined to use either outline fonts or not.
However, if the icon is defined to use an outline font then some other conditions must exist in order that colour changing can be effected. The main condition is that you must then design the icon with a validation string which includes an F-command (See Section 2.28). If you omit an F-command - even for the default colours of ‘Black on White’ (F-command F07) - colour changing will not work for outline font cases. Non-fatal warnings will appear to tell you what is wrong. To enter a validation string into an icon definition it will also be necessary to tick the ‘text’ and ‘indirected’ options in the ‘Icon edit’ window of the Template editor.
When intending to change the colours of icon text/background/border, care needs to be taken to ensure that you have the appropriate ‘border’ and/or ‘filled’ options ticked in the icon definition. For example, you can’t change the background colour if the icon isn’t ‘filled’. Similarly, the border colour (same as text colour) will only be seen if a border has been chosen.
Note that with PROCwimp_colouricon
you can “grey-out” labels which usually look better if not ‘filled’. (If you do that with PROCwimp_iconenable
(window%,icon%,0)
then the unfilled background turns white.)
Icon size and position
FNwimp_geticonsize
is like FNwimp_getwindowvisiblesize
in that is returns the dimensions of an icon - and FNwimp_geticonposition
returns the work area position of an icon.
If you want to change the size (and/or position) of an existing icon in a window you can use PROCwimp_resizeicon()
or, only to move it, PROCwimp_moveicon()
.
Icon selected/de-selected
FNwimp_geticonselect
returns 1 if the icon is selected, or 0 if it isn't.
Icon ‘hide’
FNwimp_iconhide
allows an existing icon to be hidden from display, or displayed again if it is hidden - or toggled between these two states.
‘Icon flag’ bits
PROCwimp_iconbit
allows a specific bit of an icon’s ‘icon flags’ to be set, unset or toggled between the two states.
It is complemented by FNwimp_geticonbit
which returns the current state of a specified bit of an icon’s ‘icon flags’.
Graphics colours
PROCwimp_setcolour
sets the current foreground or backround GCOL
colours for drawing/printing when the colour setting is not a part of the plotting function parameters. Dithering is used if the exact colour is not available in the current mode.
This function is best used immediately before the plotting/printing action to which it is to apply. In particular, when this function is required in a ‘redraw’ process it is essential that it is used within DEF PROCuser_redraw rather than outside it.
Also, it is often wise to restore the foreground/background to their original colours after they have been changed for a particular plotting/printing action.
Simple geometric shapes
Intended for use within PROCuser_redraw
, there are wimp-functions to plot, respectively, a line (full or dotted), a rectangle, a circle, an ellipse (rotatable) and a triangle in a window. Where relevant, there is an option to draw the shape filled or in outline. The functions are:
PROCwimp_plotwindowline
PROCwimp_plotwindowrectangle
PROCwimp_plotwindowcircle
PROCwimp_plotwindoweelipse
PROCwimp_plotwindowtriangle
.
(These functions will often be used in conjunction with PROCwimp_setcolour
, described in the preceding sub-section.)
Storing strings and integers in memory blocks
Although arrays are the traditional way to store indexed strings and numbers, the storage space they use (via the DIM
statement) is necessarily part of their application’s WimpSlot. This can sometimes be a disadvantage: for instance, when the number of strings/numbers needs to change while the application is running, perhaps because the user loads a different data file.
As an alternative, for strings and integer numbers only, Dr Wimp offers a small suite of functions which carry out the same purpose as arrays but can, if required, use dynamic area storage space. Their speed of operation is only very marginally slower than using arrays.
For strings, a storage block is created using:.
block%=FNwimp_createstringblock(n%,len%,da%)
where n%
is the maximum number of strings to be stored and len%
is the maximum length of any of the strings (limited to 255, as usual).
If da%
is any value other than 0 then the storage block will be created as a dynamic area. If da%
is 0 then a normal DIM
creation will be used.
The return - here, assigned to block%
- is the handle of the created storage space.
Once the block has been created, strings can be put in it using:
PROCwimp_putinstringblock(block%,string$,pos%,error%)
where block%
is the block handle, string$
is the string to enter and pos%
is the string position in the block (i.e. the same as an array index).
error%
is a flag to determine what happens if you try to use a value of pos%
outside the range for which the block was created. E.g. if a block for a maximum of 30 strings was created then the valid range for pos%
would be 1-30. If error%
is any value other than 0 then an error messge will be generated and no action will be taken. If error%
is 0 then the string will be put into the lowest position (1) or the maximum position, depending whether pos%
is less than 1 or greater than the maximum.
Similarly, to retrieve a string from a block use:
s$=FNwimp_getfromstringblock(block%,pos%,error%)
where the meanings of the parameters are the same as above.
However it is important to note that the function always needs to generate a return whatever the values of pos%
and error%
. If pos%
is outside the valid range and error%
is not 0 then the return will be the string stored in either the lowest or highest position. Whereas if pos%
is outside the valid range and error%
is 0 the return will always be a null string. As these returns are otherwise valid strings - albeit false - extra care should be taken to ensure pos%
is not used outside its valid range. (In this respect it is strongly suggested that error%
ought to set to 1 during development of an application to ensure that use of non-valid values of pos%
are picked up and the reasons eliminated.)
The final function of the small suite is:
PROCwimp_setstringblock(block%,string$)
which is hopefully self-explanatory and is provided to set all elements of a created block to the same value - in a similar way to using
arrays()=string$
to set all elements of an array.
For integer numbers there is an entirely complementary suite comprising:
FNwimp_createintegerblock(n%,da%)
PROCwimp_putinintegerblock(block%,value%,pos%,error%)
FNwimp_getfromintegerblock(block%,pos%,error%)
PROCwimp_setintegerblock(block%,value%)
Hourglass
PROCwimp_hourglasson
and PROCwimp_hourglassoff
turn the hourglass on and off respectively. Once the houglass has been switched on, it can be changed to show a percentage value using PROCwimp_hourglasspercentage
.
Please note that the percentage value must be in the range 0-99 and any value outside this range will switch off the percentage display.
Further, note that calls to turn the hourglass on/off can be nested but any use of the percentage can only be associated with the nesting level in which it is initially started - and turning the hourglass off from that nesting level will cancel the percentage display.
‘Desktop save’
You have the option to choose whether or not your application responds to the Wimp’s ‘desktop save’ protocol.
This protocol means that if a user selects ‘Desktop save’ from the Task Manager iconbar menu whilst your application is running then - if you have chosen to activate the option - your application will be duly entered into the list of tasks to be run automatically on future start-ups. (See User Guide for more details on ‘desktop save’.)
The option is exercised on task initialisation by setting the fourth (final) parameter of FNwimp_initialise
. Seting this parameter to 0 disables the action: setting it to 1 enables the action. See Section 2.1 also.
Auto-extraction of any start-up options and/or start-up file
Two special global string variables called wStartupoption$
and wStartupfile$
have been created within the DrWimp library.
If, for any reason, you wish to start your application with a call of the form, say:
Run <MyApp$Dir>.!RunImage %*0 -option1 -option2
or
Run <MyApp$Dir>.!RunImage <filepath$> -option1 -option2
then, after start-up, wStartupoption$
will contain:
“-option1 -option2“
There can be as many of these ‘options’ as you wish (up to the usual string limit of 255 characters) but each must be separated by a <space> character as shown. N.B. Any such options must be at the end of the command, as in the examples above.
You can then interpret this options string as you wish in your application coding.
As you will already know, if you start your application by double-clicking on a file that is ‘owned’ by the application - or include a file in a starting command as shown above - then Dr Wimp automatically passes that file to your application by calling FNuser_loaddata()
- see Section 2.11. Additionally, after start-up, the global variable wStartupfile$
will also contain the full path of the same file. This feature is offered for convenience only and can be useful in some circumstances: it does not impinge on the normal operation in any way.
Buffer space
Those of you who delve may wish to know that attempts have been made in DrWimp to avoid unnecessary re-DIMming of buffers etc. e.g. when a change of indirected text can fit into the existing buffer space. This should be entirely invisible to you, but some users ‘like to know’.
Debugging
With any programming exercise there will always be a need for debugging i.e. locating and correcting the source of errors.
There is no perfect solution and each programmer has their own favourite methods. However, in recent years some very useful debugging utilities have appeared on the PD scene, One in particular has a very wide range of easily-understood and easily-used facilities - and is under active support. It is !Reporter, which is Freeware by Martin Avison and is available from:
http://www.avisoft.force9.co.uk/
Post programming utilities
Please don’t forget to explore the utilities included in the Dr Wimp package (in the Utils folder) for use after you have completed the programming of an application. You may find them helpful. They include:
!Linker
for merging your !RunImage with the DrWimp library and at the same time eliminating any wimp-function DEFs not actually used. This often allows a significant reduction in the required WimpSlot size.
!StrongBS (Freeware by Mohsen Alshayef) a very comprehensive ‘Basic compactor’. This always gives a good reduction in program size (WimpSlot need - see Section 2.34) and renders it very difficult to read and amend. A run-time speed increase also normally results.
(Note that !StrongBS has options to carry out the same actions as !Linker and !MaheApp - at the same time as compacting, if required.)
Using a Basic ‘compiler’
The purpose of a Basic compiler is to take a completed Basic application and convert it into a machine-code equivalent, so that the program no longer runs in Basic’s ‘interpreted’ mode - and therefore, in principle, runs faster.
At the time of writing there is only one compiler known to be available; namely the ABC compiler (”A Basic Compiler”) from Castle Technology.
This compiler currently will not handle operations involving ‘whole arrays’ - a standard Basic operation which is used in Dr Wimp in two places:
FNwimp_createmenuarray
PROCwimp_recreatemenuarray
both of which include a ‘whole array’ as one of their parameters.
Therefore, if you are intending to try the ABC compiler on your Dr Wimp product you must not use either of these wimp-functions.
Neither must you use any operations on ‘whole arrays’ in any of your own coding that you add in developing your !RunImage. For example, the common ‘whole array’ operation statement:
array%()=0
used to set all elements of an array to the same value (here 0) would need to be replaced with a suitable FOR/NEXT
loop, perhaps like this:
FOR N%=0 TO arraysize%
array%(N%)=0
NEXT
Finally, for compiling it is always best to declare any global variables before you first use them - and doing this in DEF PROCuser_initialise
is a good place.
Amount of free RAM available
The wimp-function FNwimp_getfreeRAM
allows you to check the amoint of free RAM available at any time. It is useful to use this to check before, say, creating or increasing the size of Dynamic Areas.
Top of page Back to Contents Previous Next