3.81
Misc
FNwimp_OStolength(osvalue,scale,inch%)
Converts OS units to mm or inches.
osvalue = OS value to convert, can be integer or floating point.
scale = scaling factor 0-100 (%) can be integer or floating point.
If inch%=0 the value returned is in mm. If inch%=1 the
value returned is in inches.


Misc
FNwimp_changecase(string$,upper%)
Converts a string all to upper or lower case characters.
string$ = string to convert
If upper% = 0 then conversion is to lower case
If upper% = 1 then conversion is to upper case
(The conversion only affects the alphabetical characters A-Z and a-z.
All others are left unchanged.)


Misc
FNwimp_countdirectoryobjects(dir$)
Returns number of objects (i.e. files/applications/directories) in
specified directory.
dir$ - full pathname of directory or application
(NOTE: Will give error if dir$ is not a directory or application)


Misc
FNwimp_createblock(items%,length%)
Creates a block for storing strings in. Returns a handle
to the block. (Load/read block using PROCwimp_putinblock and 
FNwimp_getfromblock only.)
items% = maximum number of strings to store.
length% = maximum possible length of each string.


Misc
FNwimp_decplacesnum(number,decplaces%)
Returns, as a real number, the number formatted to the designated
number of decimal places.
number - is the number to format, can be integer or floating point.
decplaces% - is the number of decimal places required.
Rounding is to the nearest i.e. to two decimal places, 1.635 becomes 
1.64 and, for negative numbers,  -1.635 becomes -1.64
(N.B. this function can suffer from rounding errors. Use the string
version FNwimp_decplacesstr if possible.)


Misc
FNwimp_decplacesstr(number,decplaces%)
Returns, as a string, the number formatted to the designated number of
decimal places.
number - is the number to format, can be integer or floating point.
decplaces% - is the number of decimal places required.
Rounding is to the nearest i.e. to two decimal places, 1.635 becomes 
1.64 and, for negative numbers, -1.635 becomes -1.64


Misc
FNwimp_errorchoice(title$,error$,prefix%)
Reports an error using a standard error box.
It has both OK and CANCEL buttons.
title$ = title of error window.
error$ = error message.
If prefix% = 0 then the title is title$.
If prefix% = 1 then the title is prefixed by Error from .
If prefix% = 2 then the title is prefixed by Message from .
Returns TRUE (-1) if OK pressed. FALSE (0) if CANCEL pressed.
(Note difference from usual Dr Wimp practice of returning 1 or 0)


Misc
FNwimp_getdirectoryobjectname(dir$,objectnumber%)
Returns name of specified object (i.e. file/application/directory) in
specified directory.
dir$ - full pathname of directory or application
(NOTE: Will give error if dir$ is not a directory or application)
objectnumber% is 1 for first object, 2 for second object, etc.
Objects are read in alphabetical order of name - so names starting
with ! (Ascii 33) will come first.
(Use FNwimp_countdirectoryobjects first to find total number of 
objects present in directory.)


Misc
FNwimp_getdirectoryobjecttype(dir$,objectnumber%)
Returns, as a string, the filetype number of specified object (i.e.
file/application/directory) in specified directory. A file will
return xxx where xxx is the filetype hex number e.g. fff for 
textfiles - or 0af for filetype &af.
A directory will return &1000 and an application &2000.
dir$ - full pathname of directory or application
(NOTE: Will give error if dir$ is not a directory or application)
objectnumber% is 1 for first object, 2 for second object, etc.
Objects are read in alphabetical order of name - so names starting
with ! (Ascii 33) will come first.
(Use FNwimp_countdirectoryobjects first to find total number of 
objects present in directory.)


Misc
FNwimp_getdirectorypath(pathname$)
Returns the pathname with the leafname removed i.e. returns the 
directory specification string. The trailing fullstop (or trailing colon, if 
pathname$ is something like Boot:!Help) will be included.
Does not check that removed leafname is actually a file i.e it could be a 
directory or application.
pathname$ = pathname string.
(If pathname$ does not include at least one . or :  character a null-
string will be returned i.e. no leafname is present.)


Misc
FNwimp_getfromblock(block%,pos%)
Returns a string stored in a block by PROCwimp_putinblock.
block% = handle of block.
pos% = position of string in block (ranging from 1 to
maximum as passed to FNwimp_createblock).


Misc
FNwimp_getleafname(path$)
Returns a string containing the leafname from the pathname.
Does not check that leafname is actually a file i.e it could be a 
directory or application.
path$ = pathname string.
(If there is no . or : character in path$, then path$ is returned 
unaltered i.e. path$ was already a leafname.)


Misc
FNwimp_getscreenres(direction%)
Returns the resolution (number of pixels) of the current screen mode
in the specified direction.
If direction%=0 then return is horizontal resolution.
If direction%=1 then return is vertical resolution.


Misc
FNwimp_getscreensize(side%)
Returns the required dimension, in OS units, of the full screen in
current mode.
If side% = 0 returns width.
If side% = 1 returns height.


Misc
FNwimp_getsysvariable(sysvar$)
Returns, as a string, the contents of the system variable sysvar$.
Note < and > are not required in sysvar$.
If designated system variable is not present a null string is returned.


Misc
FNwimp_initialise(name$,wimpmem%,ver%,desktopsave%)
This function registers your application with the Task Manager, 
reserves
some important memory and determines if the application will
give a response to the Wimps desktop save protocol and whether it 
will pass on unused messages from the Wimps messaging system.
name$ = the name of your application eg. MyApp.
wimpmem% = number of bytes to reserve for window, icon and menu 
definitions. (Space for indirected data is allocated automatically.)
ver% = minimum version of RISC OS that the application is allowed to 
run on, multiplied by 100.
If desktopsave% <> 0 then application will respond to Wimps 
desktop save message.


Misc
FNwimp_istaskrunning(taskname$)
Checks whether a task (i.e. an application, module etc.) is already 
running on the Wimp and returns TRUE or FALSE accordingly.
taskname$ is the name of the task - which must be exactly the same as 
that used by the task in the Task Display.
(For an application the task name is often, but not always, the 
application name without the leading !. For an application authored 
using Dr Wimp, the name of the task will be the the string passed in the 
first parameter of the FNwimp_initialise call.)


Misc
FNwimp_lengthtoOS(length,scale,inch%)
Converts a length in mm or inches to OS units.
length = value to convert, can be integer or floating point.
scale = scaling factor 0-100 (%) can be integer or floating point.
If inch%=0 the length value supplied is in mm. If inch%=1
the length value supplied is in inches.


Misc
FNwimp_libversion
Returns the version number (100) of the DrWimp library.
Eg. if the version of the library is 3.61 then 361 will be returned.


Misc
FNwimp_loadfile(filepath$,handle%)
General file loader. Loads a file into a block of memory at handle%.
Returns address (handle) at which to load the next file (if any) into the 
same memory block.
filepath$ = full pathname of file.
Memory must have been created after using FNwimp_measurefile to 
find necessary size.
(Not to be used for spritefiles/drawfiles/JPEGfiles which have their 
own equivalent wimp-functions.)


Misc
FNwimp_measurefile(filepath$)
Returns the size in bytes needed to store a file in memory prior to using 
FNwimp_loadfile(), FNwimp_loaddfile(), FNwimp_loadsprites() or 
FNwimp_loadjpegfile().
Always use this as opposed to any other form of measurement.
filepath$ = full pathname of spritefile.
(This function is also listed in in other sections)


Misc
FNwimp_osversion
Returns the RISCOS version number (100) of the machine being 
used.
Eg. if the RISC OS version is 4.02 then 402 will be returned.


Misc
FNwimp_roundfloat(float)
Rounds the specified floating point number up or down and returns the
integer.


Misc
FNwimp_screentowork(window%,coord%,side%)
Converts the x or y screen coordinate coord% to a work area x or y 
coordinate - all in OS units.
window% = handle of window whose work area coordinate is being 
sought.
coord% = coordinate (x or y).
If side% = 0 then coord% is a x coordinate, and an x coordinate is 
returned.
If side% = 1 then coord% is a y coordinate, and a y coordinate is 
returned.


Misc
FNwimp_testobjectpresent(path$)
Checks whether a Filer object is present and returns, as a string, its file 
type.
path$ - full path of object which may be a directory, application or file.
For a file, the return is normally of the form xxx, where &xxx is the 
filetype. Leading zeros will be added as necessary to bring the return 
string up to three characters. (But, exceptionally, an untyped file will 
return the string -1)
For a directory, the return is 1000
For an application, the return is 2000
If the object is not found then a non-fatal warning will be given and the 
return is a null string.


Misc
FNwimp_testsysvariable(sysvar$)
Returns TRUE (-1) if designated system variable is present, or FALSE 
(0) if not.
Note < and > are not required in sysvar$.
(Note difference from usual Dr Wimp practice of returning 1 or 0)


Misc
FNwimp_worktoscreen(window%,coord%,side%)
Converts the x or y work area coordinate coord% to an x or y screen
coordinate - in OS units
window% = handle of window whose work area coordinate is being 
converted.
coord% = coordinate (x or y).
If side% = 0 then coord% is a x coordinate, and an x coordinate is 
returned.
If side% = 1 then coord% is a y coordinate, and a y coordinate is 
returned.


Misc
PROCwimp_bar(window%,icon%,length%,dir%)
Sets/adjusts the length of a bar - in OS units.
window% = handle of window containing the bar.
icon% = icon number of the bar.
length% = length of the bar in OS units.
If dir% = 0 then the bar moves horizontally keeping the height 
constant.
If dir% = 1 then the bar moves vertically keeping the width constant.


Misc
PROCwimp_error(title$,error$,button%,prefix%)
Reports an error using a standard error box.
title$ = title of error window.
error$ = error message.
If button%=1 then will have an OK button.
If button%=2 then will have a CANCEL button.
prefix% = 0 then the title is title$.
If prefix% = 1 then the title is prefixed by Error from .
If prefix% = 2 then the title is prefixed by Message from .


Misc
PROCwimp_hourglassoff
Turns off the hourglass.


Misc
PROCwimp_hourglasson
Turns on the hourglass.


Misc
PROCwimp_hourglasspercentage(percentage%)
Sets the percentage display on the hourglass.
percentage% is in the range 0 to 99.


Misc
PROCwimp_increaseslot(bytes%)
Increases size of wimpslot by bytes% bytes. If not
enough available RAM then creates an error.


Misc
PROCwimp_pause(seconds)
Introduces a pause into the processing.
seconds = required pause, in seconds. Can be any real positive value.


Misc
PROCwimp_plotwindowcircle(window%,centrex%,centrey%,radius%,fill%)
Plots a circle within a window. (Intended to be used within 
PROCuser_redraw)
window%=handle of window to plot in.
centrex%, centrey% = work area OS coordinates of centre of required 
circle.
radius% = radius of circle in OS units.
If fill% = 1 then circle is filled.
If fill%= 0 then circle is an outline only.


Misc
PROCwimp_plotwindowellipse(window%,centrex%,centrey%,semimajor%,semiminor%,rotatedegrees,fill%)
Plots an ellipse within a window. (Intended to be used within 
PROCuser_redraw)
window%=handle of window to plot in.
centrex%, centrey% = work area OS coordinates of centre of required 
ellipse.
semimajor% = half-length of major axis in OS units.
semiminor% = half-length of minor axis in OS units.
rotatedegrees = angle of rotation of ellipse about its centre, in degrees.
If fill% = 1 then ellipse is filled.
If fill%= 0 then ellipse is an outline only.


Misc
PROCwimp_plotwindowline(window%,point1x%,point1y%,point2x%,point2y%,type%)
Plots a straight line within a window. (Intended to be used within 
PROCuser_redraw)
window%=handle of window to plot in.
point1x%, point1y% = work area OS coordinates of one end of 
required line.
point2x%, point2y% = work area OS coordinates of the other end.
If type% = 0 then a full line is drawn.
If type%= 1 then a dotted line is drawn.


Misc
PROCwimp_plotwindowrectangle(window%,bottomleftx%,bottomlefty%,width%,height%,fill%)
Plots a rectangle within a window. (Intended to be used within 
PROCuser_redraw)
window%=handle of window to plot in.
bottomleftx%, bottomlefty% = work area OS coordinates of bottomleft 
corner of required rectangle.
width%, height% = width and height of rectangle in OS units.
If fill% = 1 then rectangle is filled.
If fill%= 0 then rectangle is an outline only.


Misc
PROCwimp_plotwindowtriangle(window%,point1x%,point1y%,point2x%,point2y%,point3x%,point3y%,fill%)
Plots a triangle within a window. (Intended to be used within 
PROCuser_redraw)
window%=handle of window to plot in.
point1x%, point1y% etc. = work area OS coordinates of the three 
vertices of the required triangle.
If fill% = 1 then triangle is filled.
If fill%= 0 then triangle is an outline only.


Misc
PROCwimp_putinblock(block%,string$,pos%)
Stores a string in a block. (The block must have been created using 
FNwimp_createblock).
block% = handle of block.
string$ = string to store.
pos% = position to store string in (ranging from 1 to maximum number 
of strings as passed to FNwimp_createblock).
(Strings stored in this way can be read with FNwimp_getfromblock)


Misc
PROCwimp_quit(type%)
Used to initiate quitting action and also to re-start a wimp shutdown 
that has been temporarily stopped.
If type%=0 an application quit will be initiated.
If type%=1 a temporarily halted shutdown will be re-started.
In both cases, FNuser_quit() will be called with type% passed to it.
(See Section 2.27 of Manual for details.)


Misc
PROCwimp_savefile(savepath$,filehandle%,ftype%)
General file saver. Saves a file stored in a memory block into a normal 
Filer file. (Not to be used for sprites.)
(File in block must have been loaded using FNwimp_loadfile).
filehandle% = handle of stored file to save.
savepath$ = full pathname to save to.
ftype%=filetype required - as hex number e.g. &fff for textfile.


Misc
PROCwimp_setbackgroundcolour(red%,green%,blue%)
Sets the current GCOL background colour to the nearest possible for
the current mode.
red% = amount of red in range 0-255.
green% = amount of green in range 0-255.
blue% = amount of blue in range 0-255.
(Best used immediately before corresponding plotting/printing action - 
see Section 2.33 Graphics colours.)


Misc
PROCwimp_setforegroundcolour(red%,green%,blue%)
Sets the current GCOL foreground colour to the nearest possible for
the current mode.
red% = amount of red in range 0-255.
green% = amount of green in range 0-255.
blue% = amount of blue in range 0-255.
(Best used immediately before corresponding plotting/printing action - 
see Section 2.33 Graphics colours.)


Misc
PROCwimp_starttask(command$)
Sends command$ to the CLI. Omit *.


Polling
PROCwimp_poll
This function provides the main loop of your application.
When it has exited, your application has quitted.
During the loop operation, whenever something happens to your
application eg. an icon has been clicked on, then the relevant
action will be initiated from the loop.


Polling
PROCwimp_pollidle(duration,sec%)
If NULL%=TRUE then PROCuser_null will be called at each period 
set by duration (instead of every time control is passed to the 
application and no event has occurred). 
If sec%=0 then the duration value is interpreted as centiseconds.
If sec%=1 then the duration value is interpreted as seconds.
(duration can be any real positive number.)


Polling
PROCwimp_singlepoll
The same as PROCwimp_poll, except that it is called once
and not in a loop. If something happens then the relevant action will
still be taken before returning.
Useful for making loops multitask, eg: raytracing,
printing, calculating, loading in data, etc.
Note: if calling in PROCuser_null, make sure NULL%=FALSE
before this call is made (can be set to TRUE afterwards) otherwise
recursion will occur.


Polling
PROCwimp_singlepollidle(duration,sec%)
The same as PROCwimp_pollidle, except that it is called
once and not in a loop.
If NULL%=TRUE then PROCuser_null will be called once only after
the period set in duration.
If sec%=0 then the duration value is interpreted as centiseconds.
If sec%=1 then the duration value is interpreted as seconds.
(duration can be any real positive number.)
If something happens then the relevant action will be taken before 
returning.
Useful for incorporating delays into multitasking loops.
Note: if calling in PROCuser_null, make sure NULL%=FALSE
before this call is made (can be set to TRUE afterwards) otherwise
recursion will occur.


User
FNuser_help(window%,icon%)
Used to return a string for interactive help for a
specified window and icon. Otherwise return a null string.
window% = handle of window (containing icon).
icon% = number of icon.


User
FNuser_keypress(window%,icon%,key%)
If a key is pressed while one of your windows has the input focus, or a 
hotkey is pressed, then this function is called (provided icon validation 
string is suitably defined).
If you dont use the key press then return a 0. If you do then return a 1.
window% = handle of window with input focus.
icon% = number of icon with caret.
key% = key code. For most keys it is the ASCII number.
(See Section 2.4 of the Manual for codes of special keys - and Section 
2.22 for validation strings.)


User
FNuser_loaddata(path$,window%,icon%,filetype$,workx%,worky%)
Used to load data into application. Important to return a 1 if data is 
loaded.
path$ = full pathname of source file offered for loading.
window% = handle of window file has been dragged to. (Will be 0 if 
file double-clicked rather than dragged.)
icon% = number of icon file was dragged on to. (Will be -1 if file 
double-clicked rather than dragged.)
filetype$ = filetype of file offered for loading. Will always be at least 
three characters e.g. FFF or 0AF (or 1000 if a directory, or 
2000 if an application)
workx%, worky% = work area coordinates the icon was dropped at 
(these values are both -1 if file was loaded with a double-click rather 
than dragged).


User
FNuser_menu(window%,icon%)
Responds to <menu> clicks. If you want a menu to be displayed when 
you press <menu> over a specified window/icon, then this function 
needs to return the handle of the menu required. Otherwise return 0.
window% = handle of window.
icon% = number of icon.
(<select> and <adjust> clicks handled by PROCuser_mouseclick)


User
FNuser_menuhelp(menu%,item%)
Return a string to be used for interactive help for a specified menu and 
item. Otherwise return a null string.
menu% = handle of menu.
item% = number of item (starting from 1 at the top).


User
FNuser_pane(window%)
If the window has a pane attached to it, then this function should
return the window handle of the pane. If the window doesnt have a
pane attached, then it should return -1.
window% = handle of window.
(See Section 2.6 for use with multiple panes.)


User
FNuser_preclosewindow(window%)
This function is called just before the window whose handle is 
window% is about to be closed.
Return a 1 (default value) to allow the closing action to continue, or 
return 0 to stop the window closing.


User
FNuser_printing(copy%,page%,totpages%,pagepos%)
Called repeatedly by DrWimp during printing so application can keep 
user informed of current printing status and give the option to cancel 
printing.
copy% = number of current copy being printed.
page% = number of current page being printed.
totpages% = total number of pages being printed.
pagepos% = current page being printed (starts at 1 each time and goes 
up to totpages%).
Return a 1 to cancel printing or a 0 to continue.


User
FNuser_quit(type%)
Called when the application is being asked to quit, either due to the 
user choosing to quit the application or because of a desktop shutdown.
If type%=0 then it is an application quit.
If type%=1 then it is a shutdown.
Return a 1 to continue with the quit/shutdown or return a 0 to stop it 
e.g. to allow the user to save any data.
(See Section 2.27 of Manual for details.)


User
FNuser_savedata(path$,window%)
Used to save/export data from an application.
Return a 1 if some data was saved, 2 if an error occurred or return a
0 for no data saved and no error.
path$ = full pathname of file to save data to i.e. destination file.
(Note that this must be a complete file path, not a directory.
Leafname is usually in save window writable icon.)
window% = handle of save window that file icon was dragged from.


User
FNuser_savefiletype(window%)
Used to identify Save windows. If the window is a Save window then 
you return the required filetype (as  hex string. eg. FFF for a textfile). 
Otherwise return a null string.
window% = handle of window%


User
FNuser_slider(window%,icon%)
In order to let DrWimp know that an icon is part of a slider/sliderback 
pair, return the slider icon number. Otherwise return -1.
window% = handle of window with slider pair in.
icon% = icon number of slider back icon.
(Always used with FNuser_sliderback as a complementary pair.)


User
FNuser_sliderback(window%,icon%)
In order to let DrWimp know that an icon is part of a slider/sliderback 
pair, return the slider-back icon number. Otherwise return -1.
window% = handle of window with slider pair in.
icon% = icon number of slider.
(Always used with FNuser_slider as a complementary pair.)


User
PROCuser_closewindow(window%)
If this function is called, then the window whose handle is window%
has just been closed.


User
PROCuser_colourpickermodel(model%,value1,value2,value3,value4,none%)
When the colour picker window is used to select a colour (by pressing 
OK or None) the colour model values of the currently displayed 
colour are passed to this function.
model%=colour model number. 0 is RGB model, 1 is CMYK 
model, 2 is HSV model.
value1, value2 etc. are colour component values appropriate to the 
model, in range 0-100% (except value1 is in range 0-359 degrees for 
HSV model i.e. when model%=2)
Note that value4 is only relevant for CMYK model i.e. when 
model%=1. In other cases value4 will be -1.
If none%=0, OK was pressed in colour picker window i.e. displayed 
colour was selected.
If none%=1, None was pressed in colour picker window i.e. no 
colour selection was made.
(Note: Colour values are still passed when None is pressed.)


User
PROCuser_colourpickerrgb(red%,green%,blue%,none%)
When the colour picker window is used to select a colour (by pressing 
OK or None) the rgb values of the currently displayed colour are 
passed to this function.
red% = red component of colour, in range 0-255.
green% = green component of colour, in range 0-255.
blue% = blue component of colour, in range 0-255.
If none%=0, OK was pressed in colour picker window i.e. displayed 
colour was selected.
If none%=1, None was pressed in colour picker window i.e. no 
colour selection was made.
(Note: Colour values are still passed when None is pressed.)


User
PROCuser_declarefonts
Any fonts being used in printing must be declared in this function 
using PROCwimp_declarefont, PROCwimp_declarefonth and/or 
PROCwimp_declaredfilefonts.
(This is in case the application is used with a PostScript type
printer, which requires font declarations.)


User
PROCuser_enteringwindow(window%)
This function is called when the pointer enters a window.
window% = handle of window.


User
PROCuser_error
A general function providing a convenient location for application-
specific good housekeeping actions which may be desirable when a 
fatal error occurs. This procedure might typically be used to close any 
open files, unset system variables, etc.
It is called only when the global error trap is brought into play - see 
Section 2.8


User
PROCuser_iconise(window%,RETURN text$,RETURN spritename$)
This function is called when iconising action takes place. It allows the 
text and/or sprite used to be customised.
window% = handle of the window where the iconising action has 
occurred.
text$ = text to appear beneath the iconised sprite.
spritename$ = name of the sprite to be used, without the ic_ prefix. A 
sprite with the full name needs to be supplied in the !Sprites/!Sprites22 
files - otherwise the Wimps default sprite will be displayed.
(By default, both text$ and spritename$ will be set to the application 
name as declared in FNwimp_initialise.)
N.B. If spritename$ exceeds 7 characters it will produce an invalid 
iconiser sprite name - and hence the Wimps default iconiser sprite will 
be displayed instead.


User
PROCuser_initialise
A general function providing a convenient location for initialisation 
actions. This procedure should typically contain the following:
Window and menu loading/definition; declaration of global variables;
DIMming of arrays & data blocks; anything that needs to be done 
before polling starts.


User
PROCuser_leavingwindow(window%)
This function is called when the pointer leaves a window.
window% = handle of window.


User
PROCuser_menuopen(menu%,icon%)
Called just before menu (not a sub-menu) is opened.
menu% = handle of menu just about to open.
icon% = icon which pointer is over ( or -1 if not over an icon).


User
PROCuser_menuselection(menu%,item%,font$)
This function is called when the user has chosen a menu item from a 
menu/sub-menu.
menu% = handle of menu/sub-menu. (Will be the font menu handle if 
selection is from a font menu/font sub-menu.)
item% = item number (top item is 1). (Will be 0 if selection is from a 
font menu.)
font$=full period-separated font name.  (Will be null string except if 
selection is from a font menu.)


User
PROCuser_modechange
Called when the mode is changed.


User
PROCuser_mouseclick(window%,icon%,button%,workx%,worky%)
If <select> or <adjust> has been clicked in one of your windows then 
this function is called. (<menu> clicks handled by FNuser_menu)
window% = handle of window clicked over.
icon% = number of the icon clicked on (or -1 if no icon).
button% = which mouse button was pressed.
Eg. 4 for <select>, 1 for <adjust>.
workx%,worky% = work area coordinates of pointer (in window%)
when the mouse button was clicked.


User
PROCuser_null
This is called continuously if you set NULL%=TRUE.
So, if you are writing something like a clock, you would monitor the 
time here and change any windows as required.


User
PROCuser_openwindow(window%,x%,y%,stack%)
If this function is called, then the window whose handle is window% 
has been opened with the top left of the window at x%,y% on the 
screen.
stack% = window handle which window% was opened behind,
or -1 for top of window stack, or -2 for bottom.


User
PROCuser_overmenuarrow(RETURNnextsubmenu%,parentmenuitem%,x%,y%)
Called when pointer moves over arrow-head against menu item,
on way to activating sub-menu.
nextsubmenu% = handle of submenu (or could be window) about
to be opened.
(Note: RETURN means that submenu handle can be changed here, if 
required.)
parentmenuitem% = menu item number which pointer is moving over.
x%/y% are screen OS-unit positions of pointer when over
arrow-head.


User
PROCuser_print(minx%,miny%,maxx%,maxy%,page%)
Called to draw a page for printing, if PROCwimp_print was
called with user%=1.
minx%,miny% = coordinates of bottom left corner of clipping 
rectangle
on page in paper coordinates.
maxx%,maxy% = coordinates of top right corner of clipping rectangle 
on page in paper coordinates.
page% = number of page to print.


User
PROCuser_printerchange
Called when the printer settings or the current printer has changed so 
you can update your page measurements, current printer name, etc.


User
PROCuser_redraw(window%,minx%,miny%,maxx%,maxy%,printing%,page%)
When this function is called, the Wimp wants you to update/redraw the 
specified box (at least).
The box is in the window whose handle is window% or, if printing, 
then it is in paper coordinates with the origin is at the bottom left of the 
paper.
printing% = TRUE if currently printing, FALSE otherwise.
page% = number of page currently being printed if printing%=TRUE.
minx%,miny% = bottom left co-ordinates of box in screen/paper 
coordinates.
maxx%,maxy% = top right co-ordinates of box in screen/paper 
coordinates.


User
PROCuser_redrawtextline()
NOT IN SKELETON !RunImage.
ONLY USED AS PART OF Elixir_01 for fast scrolling of long text 
lists - see Manual Section 2.37 and 3.16 Elixirs
Needs to be used with PROCwimp_calcredrawlines().


User
PROCuser_saveicon(window%,RETURN drag%,RETURN write%,RETURN ok%)
This function allows the three save window icons (the one to drag, the 
writable icon for the filename/pathname and the OK button) to have
their icon numbers set, if you want to override the defaults.
Defaults:
  drag% - 0   write% - 1   ok% - 2
window% = handle of save window.


User
PROCuser_slidervalue(window%,slider%,pcent%,direction%)
When a slider is being dragged or has just finished being dragged, the 
percentage of the slider is passed to this function.
window% = handle of window with slider in.
icon% = icon number of slider.
pcent% = percentage of slider.
direction% = direction of slider (0 is horizontal, 1 is vertical)


User
PROCuser_wimpmessage(messagenumber%,block%,reasoncode%)
Dr Wimp does not use all wimp-messages. This user-function allows 
details of those unused wimp-messages to be passed to the !RunImage, 
if required.
If the global variable UNUSED% is set to TRUE then this user-function 
will be called whenever a wimp-message is received by the application 
but is not used within the DrWimp library. (UNUSED% is set to FALSE 
by default on application start-up.)
messagenumber% = number of the unused wimp-message received.
block%= handle of wimp-message data block, to enable user to get 
further information and respond if necessary.
reasoncode%= reason code passed by wimp (17, 18 or 19 in this case).
(See Section 2.30 of Manual for the list of wimp-messages that are 
currently used within the DrWimp library - and hence would never be 
passed on via this user-function.)


Windows
FNwimp_createwindow(vminx%,vminy%,vmaxx%,vmaxy%,wminx%,wminy%,wmaxx%,wmaxy%,flags%,colourflags%,button%,title$,titleflags%,maxind%,sarea%)
Used for creating a window within a program. The window handle is 
returned.
vminx%,vminy%,vmaxx%,vmaxy% = limits of opening visible 
window in OS screen units.
wminx%,wminy%,wmaxx%,wmaxy% = limits of work area of 
window
in work area OS coordinates.
flags% = number representing window flags.
colourflags% = number representing the colours of 7 items of window 
furniture, each in the range 0-15.
button% = work area button type.
title$ = title of window.
titleflags%= number representing titlebar flags.
maxind% = maximum size of title if indirected.
sarea% = handle of sprite area, or 0 to use Wimp sprite area.
(See Section 2.26 of Manual for details of flags%, colourflags%, 
titleflags%, button%, etc.)


Windows
FNwimp_getscroll(window%,side%)
Returns the current scroll position (in OS units) of the window, in the 
given direction.
window% = handle of window.
If side%=0 then the horizontal scroll position will be returned.
If side%=1 then the vertical scroll position will be returned. (Note that 
vertical scroll values are normally negative.)


Windows
FNwimp_getwindowtitle(window%)
Returns a string containing the window title.
window% = handle of window.


Windows
FNwimp_getwindowvisiblescreen(window%,side%,end%)
Return the screen OS coordinates of the edges of the current visible 
area of the window.
window% = handle of window.
If side%=0 then a x coordinate will be returned.
If side%=1 then a y coordinate will be returned.
If end%=0, then the minimum coordinate will be returned, ie the left
or bottom of the visible area depending on the value of side%.
If end%=1, then the maximum coordinate will be returned, ie the right
or top of the visible area depending on the value of side%.
(Use FNwimp_getwindowvisiblesize to get current visible size.)


Windows
FNwimp_getwindowvisiblesize(window%,side%)
Returns the dimension required, in OS units, of the currently displayed 
size of the specified window i.e. (If window is not open then size that 
would be displayed is returned.)
If side% = 0 returns width. If side% = 1 returns height.
(Use FNwimp_getwindowworksize to get defined work area size. Use 
FNwimp_getwindowvisiblework or FNwimp_getwindowvisiblescreen 
to get visible window edge coordinates.)


Windows
FNwimp_getwindowvisiblework(window%,side%,end%)
Returns the work area OS coordinates of the edges of the current 
visible area of the window. i.e. returns take current scroll values into 
account.
window% = handle of window.
If side%=0 then a x coordinate will be returned.
If side%=1 then a y coordinate will be returned.
If end%=0, then the minimum coordinate will be returned, ie the left
or bottom of the visible area depending on the value of side%.
If end%=1, then the maximum coordinate will be returned, ie the right
or top of the visible area depending on the value of side%.


Windows
FNwimp_getwindowworksize(window%,side%)
Returns the size, in OS units, of a windows defined work area - 
irrespective of its current visible area.
window% = handle of window.
If side%=0 the width of the work area is returned.
If side%=1 the height of the work area is returned.
(Use FNwimp_getwindowvisiblesize to get current visible size.)


Windows
FNwimp_iswindowopen(window%)
Returns TRUE (-1) if the window is open,
otherwise returns FALSE (0).
window% = handle of window.
(Note difference from usual Dr Wimp practice of returning 1 or 0)


Windows
FNwimp_loadwindow(path$,window$,spritearea%)
Loads in a window from a templates file and returns a
handle for the window.
path$ = full pathname to templates file.
window$ = name of window in templates file.
spritearea% = 0 if sprites used are from wimp pool (RMA). Otherwise 
spritearea% is a handle to a user sprite area.


Windows
PROCwimp_banner(window%,delay%)
Opens window in the centre of the screen for specified
time before closing it.
window% = handle of window to open.
delay% = number of seconds to keep window on screen.


Windows
PROCwimp_closewindow(window%)
Closes a window (removes it from the screen).
window% = handle of window to close.


Windows
PROCwimp_deletewindow(window%)
Deletes a window definition, closing it if it is open. All the memory
apart from the indirected memory is reclaimed and the window handle
becomes invalid.
window% = handle of window to delete.
PROCwimp_calcredrawlines()
NOT IN DrWimp LIBRARY.
ONLY USED AS PART OF Elixir_01 for fast scrolling of long text 
lists - see Manual Section 2.37 and 3.16 Elixirs
Needs to be used with PROCuser_redrawtextline()


Windows
PROCwimp_openwindow(window%,centre%,stack%)
Opens a window on the screen.
window% = handle of window to open.
If centre% = 0 opens window where it was last left on the screen, or if 
it hasnt been opened before, then where it is positioned in the template 
file.
If centre% = 1 opens the window centred on the screen
(mode independent).
If centre% = 2 opens the window centred on the pointer.
stack% = window handle to open behind, or -1 for top of window 
stack,  -2 for bottom, or -3 for current stack position.


Windows
PROCwimp_openwindowat(window%,x%,y%,stack%)
Opens a window on the screen so the top left of the
window is at co-ordinates x%,y% - in OS units.
window% = handle of window to open.
stack% = window handle to open behind, or -1 for top of window 
stack, -2 for bottom or -3 for current stack position.


Windows
PROCwimp_putwindowtitle(window%,title$)
Changes the window title to title$
window% = handle of window.


Windows
PROCwimp_redrawwindow(window%)
Causes the complete window whose handle is window% to be 
redrawn/updated.


Windows
PROCwimp_resizewindow(window%,width%,height%)
Resizes the work area of the specified window to the specified width 
and height, which are in OS co-ordinates.
(The displayed size of the window will not change unless the new 
work area size is less than the displayed size.)


Windows
PROCwimp_resizewindowvisible(window%,width%,height%)
Resizes the visible area of the window to the specified width and 
height which are in OS co-ordinates.


Windows
PROCwimp_scroll(window%,side%,direction%,distance%)
Causes the window automatically to scroll vertically or horizontally a 
given distance in a given direction.
window% = handle of window to be scrolled.
If side%=0 then a horizontal scroll will be done.
If side%=1 then a vertical scroll will be done.
If direction%=0 then the scroll will be left or down depending on the
value of side%.
If direction%=1 then the scroll will be right or up depending on the
value of side%.
distance% = the amount to scroll the window, in OS units.
(Window does not need to be open to effect scroll.)


Windows
PROCwimp_scrollto(window%,side%,scrollpos%)
Causes the window automatically to scroll vertically or horizontally to 
a given position.
window% = handle of window to be scrolled.
If side%=0 then a horizontal scroll will be done.
If side%=1 then a vertical scroll will be done.
scrollpos% = the scroll position required, in OS units. (Note that 
vertical scroll values are normally negative.)
(Window does not need to be open to effect scroll.)


Windows
PROCwimp_updatewindow(window%,minx%,miny%,maxx%,maxy%)
This procedure tells the Wimp to redraw only the part of a window 
which is defined by the given coordinates.
This greatly speeds up redraws where lots of graphics are used and/or 
the window needs regular updating as it avoids redrawing the whole 
window.
The necessary code needs to be in PROCuser_redraw to enable the 
redraw to be done.
window% = handle of window to be updated.
minx%, miny% = bottom left of box to be redrawn in work area
coordinates.
maxx%, maxy% = top right of box to be redrawn in work area 
coordinates.


Messages
FNwimp_createmessagemenu(messagefilehandle%,token$,title$,size%)
Creates a menu automatically from a Messages file.
messagefilehandle%= handle of messages file to be used (as returned 
by FNwimp_initmessages/FNwimp_reinitmessages).
token$ = token for menu. Eg: if token$=MMenu then the token 
MMenuT will specify the title, MMenu1 the first item, MMenu2 
the second etc.
If title$= then the title defined in the message file will be used, 
otherwise title$ will override whatever is defined in the messages file.
If size%>number of items then the menu is dynamic, ie.
the items can subsequently be increased up to size%. (If size%=0 the 
menu will automatically be created to accomodate just the number of 
items contained in the messages file.)
(All menu text is created as indirected.)
(Also shown in Menu section.)


Messages
FNwimp_getnumberofmessages(messagefilehandle%,token$)
Returns the number of items with the given token in the given message 
file.
messagefilehandle%= handle of messages file (returned from 
FNwimp_initmessages/FNwimp_reinitmessages above).
token$=token of interest.


Messages
FNwimp_initmessages(path$)
Reserves special blocks of memory and sets up a Messages file ready 
for use.
Returns a message handle for file.
path$ = full pathname of messages file to use.


Messages
FNwimp_messlook0(messagefilehandle%,token$)
Returns the string in the messages file for the token token$.
messagefilehandle%= handle of required messages file (returned from 
FNwimp_initmessages/FNwimp_reinitmessages above).


Messages
FNwimp_messlook1(messagefilehandle%,token$,a$)
Returns the string in the messages file for the token token$, but any 
parameters %0 in the string are replaced with a$ before returning.
messagefilehandle%= handle of required messages file (returned from 
FNwimp_initmessages/FNwimp_reinitmessages above).


Messages
FNwimp_messlook2(messagefilehandle%,token$,a$,b$)
Returns the string in the messages file for the token token$, but any 
parameters %0 and %1 are replaced with a$ and b$, respectively, 
before returning.
messagefilehandle%= handle of required messages file (returned from 
FNwimp_initmessages/FNwimp_reinitmessages above).


Messages
FNwimp_reinitmessages(messagefilehandle%,path$)
If, after it has been initiated (with FNwimp_initmessages, above), a 
messages file is altered or a different messages file is now to be used, 
this function allows the changed/new file to be initiated in place of the 
previous file. Re-initiation can be carried out as many times as 
required.
Returns a message handle for the changed/new file - which may be 
different from the previous handle. (It would be normal to assign the 
return to the previous handle-variable - see Section 2.9)
messagefilehandle%= handle of previous messages file.
path$ = full pathname of new/changed messages file to use.


Messages
PROCwimp_recreatemessagemenu(menu%,messagefilehandle%,token$,title$)
Rebuilds a menu from a Messages file.
menu% = handle of menu to rebuild
messagefilehandle%= handle of messages file to be used (as returned 
by FNwimp_initmessages/FNwimp_reinitmessages).
token$ = token for menu items. (See FNwimp_createmessagemenu()  
or Manual Section 2.15 for use of token$)
If title$= then the title defined in the message file will be used, 
otherwise title$ will override whatever is defined in the messages file.
(All menu text is created as indirected.)
(Also shown in Menu section.)


Icons
FNwimp_createicon(window%,wminx%,wminy%,wmaxx%,wmaxy%,flags%,esg%,button%,fcol%,bcol%,font%,text$,sprname$,sarea%,maxind%,valid$)
Creates an icon and returns its handle (icon number).
window% = handle of window to create icon in.
wminx%,wminy%,wmaxx%,wmaxy% are bottom left and top
right corners of icon in work area OS coordinates.
flags% = number representing flags for icon.
esg% = esg number of icon. 0 for icons which arent radio buttons.
button% = button type of icon.
fcol%,bcol% = foreground and background colours of icons (if not 
using outline font) in desktop colours, so both in the range 0-15.
font% = handle of outline font. 0 if not using a font.
text$ = text for icon.
sprname$ = sprite name for icon.
sarea% = handle of sprite area, or 0 to use Wimp sprite area.
maxind% = if icon is indirected then maximum size.
valid$ = icon validation string.
(See Section 2.26 of Manual for details of flags%, button%, etc.)


Icons
FNwimp_getcaretposition(choice%)
Returns information about current caret location/position.
If choice% = 0 handle of window with caret is returned.
If choice% = 1 handle of icon with caret is returned.
If choice% = 2 work area OS-unit x position (in window carrying 
caret) is returned.
If choice% = 3 work area OS-unit y position (in window carrying 
caret) is returned.
If choice% = 4 the position of the caret (the index) within the text of 
a writable icon is returned.
Return is -1 in cases where the caret is not present.


Icons
FNwimp_geticonenable(window%,icon%)
Returns 1 if the icon icon% in the window whose handle
is window% is enabled. Returns 0 if it is disabled(greyed out).


Icons
FNwimp_geticonposition(window%,icon%,coord%)
Returns x/y work area OS-unit coordinates of icon sides.
window%= window handle
icon%- icon handle
If coord% = 0 minimum x coord of icon is returned.
If coord% = 1 minimum y coord of icon is returned.
If coord% = 2 maximum x coord of icon is returned.
If coord% = 3 maximum y coord of icon is returned.


Icons
FNwimp_geticonselect(window%,icon%)
Returns 1 if the icon is selected, or 0 if it is not selected.
Useful for reading the state of radio and option icons.
window% = handle of window containing icon.
icon% = number of icon.


Icons
FNwimp_geticonsize(window%,icon%,side%)
Returns the width/height of an icon, in OS units.
window%= window handle
icon%- icon handle
If side% = 0 width of icon is returned.
If side% = 1 height of icon is returned.


Icons
FNwimp_geticontext(window%,icon%)
Returns a string containing the text from the icon.
window% = handle of window containing icon.
icon% = icon number.


Icons
FNwimp_getsliderpcent(window%,icon%)
Returns the percentage of the slider. If the icon is not
a slider then 0 is returned.
The number returned is a floating point number in the
range 0-100.
window% = handle of window with slider in.
icon% = icon number of slider.


Icons
FNwimp_iconbar(spritename$,text$,maxlen%,pos%)
Creates and places an icon on the iconbar.
spritename$ = name of sprite to put on iconbar.
text$ = text to put underneath the icon.
If text$ =  then sprite-only icon will be created and maxlen% will 
be ignored.
If text$ is any other string then an indirected text-plus-sprite icon will 
be created, with space available for a maximum of maxlen% characters 
(+terminator). (If maxlen% is less than length of text$ then maxlen% 
will be made equal to length of text$.)
If pos% = 1 then the icon will appear on the right of iconbar.
If pos% = 0 then it will appear on the left.
Returns the iconbar window handle (i.e. always -2).


Icons
PROCwimp_colouricon(window%,icon%,colour%,background%)
Sets colour of text/background/border in an icon to colour%.
window% = handle of window containing icon.
icon% = number of icon.
colour% = colour in range 0-15.
background% = 0 to change text (and border, if present) colour.
background% = 1 to change background colour (if icon is filled).
(See Section 2.33 for conditions needed for colour change in icons 
using outline fonts.)


Icons
PROCwimp_deleteicon(window%,icon%,redraw%)
Deletes an icon definition from a window.
The icon will not disappear until the next redraw - which can be forced 
using third parameter.
window% = handle of window containing the icon.
icon% = icon number of icon to delete.
If redraw% is 1 then the window is redrawn.
If redraw% is 0 then it isnt and the icon wont disappear immediately.


Icons
PROCwimp_iconbarsprite(spritename$)
Changes the sprite used for the iconbar icon.
spritename$= name of required sprite, which must already be in Wimp 
sprite pool.


Icons
PROCwimp_iconbit(window%,icon%,bit%,state%)
Ensures a specific bit of an icons icon flags is set to the
specified state.
window% = handle of window containing icon.
icon% = number of icon.
bit% = number of icon flags bit to change.
state% =1 to set bit, or 0 to unset bit.


Icons
PROCwimp_iconenable(window%,icon%,state%)
Allows an icon to be enabled or disabled (greyed out) or toggled 
from one state to the other.
window% = handle of window containing icon.
icon% = number of icon.
If state%=0 icon will be disabled (greyed out) and will not respond to 
mouse clicks.
If state%=1 icon will be enabled.
If state%=2 icon will be changed from its existing state to the other.


Icons
PROCwimp_iconselect(window%,icon%,state%)
Allows an icon to be selected or deselected or toggled from one state to 
the other.
Useful for selecting/deselecting/toggling radio and option icons.
window% = handle of window containing icon.
icon% = number of icon.
If state%=0 icon will be de-selected.
If state%=1 icon will be selected.
If state%=2 icon will be changed from its existing state to the other.


Icons
PROCwimp_losecaret
Removes the caret from the icon it is in - and removes input focus
from the window.


Icons
PROCwimp_putcaret(window%,icon%)
Puts the caret in the icon and gives window input focus.
window% =handle of window containing icon.
icon% = number of icon (or set to -1 if caret not wanted in icon)


Icons
PROCwimp_puticonbartext(text$)
If the iconbar icon has indirected text underneath it then it is
replaced by text$. (The length of text$ must not exceed the iconbars 
defined max. indirected text length.)


Icons
PROCwimp_puticonfont(window%,icon%,fonthandle%)
Changes font of icon text to the font and size specified by 
fonthandle%. (Icon must have been defined as using outline fonts.)
window% = handle of window containing icon.
icon% = number of icon.
fonthandle% = handle of required font.


Icons
PROCwimp_puticontext(window%,icon%,text$)
If the icon is indirected then the text in the icon is replaced with text$.
(For an indirected sprite-only icon, the same function is used to 
change the sprite; in which case text$ is the sprite-name of the required 
new sprite - which must already be in the Wimp sprite pool.)
If the icon is not indirected then an error is caused.
window% = handle of window containing icon.
icon% = number of icon.
text$ = the required new text (or sprite-name) - the length of which 
should not exceed the maximum indirected length specified in the icon 
definition.


Icons
PROCwimp_putsliderpcent(window%,icon%,pcent)
Sets the percentage of the slider. If the icon is not a
slider then this is ignored.
window% = handle of window with slider in.
icon% = icon number of slider.
pcent = percentage to set. Can be integer or floating point number,
but must be in the range 0-100.


Menus
FNwimp_createfontmenu
Creates a complete menu structure of the currently available (active) 
fonts.
A menu handle is returned.
(The many wimp-functions available to manipulate individual menu 
items cannot be applied to font menus.)


Menus
FNwimp_createmenu(menu$,size%)
Creates a menu structure from the string menu$. The menu
handle is returned.
For more information on menu$ see the manual.
If size%>number of items then the menu is dynamic, ie.
the number of menu items can be increased up to size%.
(If size%=0 the menu will automatically be created to accomodate just 
the number of items contained in menu$.)
(All menu text is created as indirected.)


Menus
FNwimp_createmenuarray(array$(),size%)
Creates a menu from the array supplied.
Each item of the menu is in a separate element of the array.
e.g. array$(1)=Info.
The first element, array$(0), is the menu title, and the last
must be the string END.
array$() = array holding item strings.
size% = maximum number of elements to allocate room for
(doesnt have to be the current number). (If size%=0 the menu will 
automatically be created to accomodate just the number of items 
contained in the array.)
Returns a handle to the menu.
(All menu text is created as indirected.)


Menus
FNwimp_createmessagemenu(messagefilehandle%,token$,title$,size%)
Creates a menu automatically from a Messages file.
messagefilehandle%= handle of messages file to be used (as returned 
by FNwimp_initmessages/FNwimp_reinitmessages).
token$ = token for menu. Eg: if token$=MMenu then the token 
MMenuT will specify the title, MMenu1 the first item, MMenu2 
the second etc.
If title$= then the title defined in the message file will be used, 
otherwise title$ will override whatever is defined in the messages file.
If size%>number of items then the menu is dynamic, ie. the items can 
subsequently be increased up to size%. (If size%=0 the menu will 
automatically be created to accomodate just the number of items 
contained in the messages file.)
(All menu text is created as indirected.)
(Also shown in Messages section.)


Menus
FNwimp_getmenudottedline(menu%,item%)
Checks whether or not a menu item has a dotted line beneath it.
menu% = handle of menu.
item% = number of item (top item is 1).
Returns a 1 if the menu item has a dooted line beneath it.
Returns a 0 if the menu item does not have a dooted line beneath it.


Menus
FNwimp_getmenuenable(menu%,item%)
Checks whether a menu item is enabled or disabled (greyed out).
menu% = handle of menu.
item% = item number (top item is 1).
Returns 1 if menu item is enabled.
Returns 0 if menu item is disabled (greyed out).


Menus
FNwimp_getmenuitem(menu%,menuitemtext$)
Returns the menu item number (top=1) of the menu item whose text 
matches menuitemtext$.
menu% = handle of menu to search
menuitemtext$ = text string to match (not case sensitive)
Returns 0 if no match found.


Menus
FNwimp_getmenutext(menu%,item%)
Returns a string containing the text of the menu item in position 
item%.
menu% = handle of menu.
item% = number of item (top item is 1).


Menus
FNwimp_getmenutick(menu%,item%)
Returns 1 if the specified menu item is ticked, or returns 0 if it isnt.
menu% = handle of menu.
item% = number of item (top item is 1).


Menus
FNwimp_getmenutitle(menu%)
Returns a string containing the title of the menu.
menu% = handle of menu.


Menus
FNwimp_menumaxsize(menu%)
Returns the maximum number of entries (items) allowed in the menu, 
as determined on creation.
menu% = handle of menu.


Menus
FNwimp_menusize(menu%)
Returns the current number of entries (items) in the menu.
menu% = handle of menu.


Menus
FNwimp_recreatefontmenu(fontmenu%)
Re-creates a complete menu structure of the currently available (active) 
fonts, for a previously created font menu.
fontmenu% = handle of previously created font menu.
The menu handle is returned (which may be a new value).
(The many wimp-functions available to manipulate individual menu 
items cannot be applied to font menus.)


Menus
PROCwimp_attachsubmenu(menu%,item%,submenu%)
Attaches a submenu to a menu item.
menu% = handle of menu.
item% = item number (top item is 1).
submenu% = handle of submenu or window handle.


Menus
PROCwimp_menuclose
Closes the currently active menu.
Used if menu closure is required other than by normal (automatic) 
wimp process.


Menus
PROCwimp_menudottedline(menu%,item%,on%)
Adds/removes a dotted line to the menu below the item.
menu% = handle of menu.
item% = number of item (top item is 1).
If on%=1 dotted line is added; if on%=0 dotted line is removed.


Menus
PROCwimp_menuenable(menu%,item%,state%)
Allows a menu item to be enabled/disabled(greyed out) or to be 
toggled between these two states.
menu% = handle of menu.
item% = item number (top item is 1).
If state% =0, the menu item will be disabled (greyed out) and will not 
respond to mouse clicks.
If state% =1, the menu item will be enabled.
If state% =2, the menu item will be toggled from its existing state to 
the other.


Menus
PROCwimp_menuitemcolour(menu%,item%,colour%,background%)
Changes the text colour of the menu item specified.
menu% = handle of menu.
item% = item number (top item is 1).
colour% = colour required (standard Wimp colours in range 0-15)
(Colours 8, 10, 11, 13, 14 and 15 are best for visibility)
If background% = 1 then the background colour is changed.
If background% = 0 then the foreground colour is changed


Menus
PROCwimp_menupopup(menu%,pos%,x%,y%)
Displays the menu (or window) whose handle is menu%.
If pos%=0 then menu is displayed with its top left corner at screen 
coordinates x%,y%.
If pos%=1 then menu will be positioned as for an iconbar menu, as if
iconbar icon is at screen coordinate x% i.e. with left edge to the left of 
x% and at 96 OS units above the bottom of screen. (y% value is needed 
but is ignored.)
If pos%=2 then menu will be centred on screen (x%/y% values ignored 
but must be present)
If pos%=3 then menu will be opened slightly to the right of (and 
slightly above) pointer position - optimised to butt onto right edge of 
ptr_menu shape.
If pos%=4 then menu will be opened butting up against the right edge 
of  the icon over which the mouse was clicked. (Designed to be used 
with pop-up menu icons.)
Can also be used to open windows that close when the mouse is 
clicked elsewhere.


Menus
PROCwimp_menutick(menu%,item%,state%)
This function puts/removes a tick against the specified menu item - or 
toggles between these two states.
menu% = handle of menu.
item% = item number (top item is 1).
If state% = 0, any tick against the item will be removed.
If state% =1, a tick will be put against the item.
If state%=2, the tick will be toggled from its existing state to the other.


Menus
PROCwimp_menuwrite(menu%,item%,maxlength%,border%)
Makes the menu item writable.
menu% = handle of menu.
item% = number of item (top item is 1)
maxlength% = maximum length of text allowed to be entered.
If border%=1 a border will be placed around writable item.
If border%=0 no border will appear.
(Any text already in the item will be re-inserted into the new writable 
item. If the existing text is longer than maxlength% then maxlength% 
will be increased accordingly.)


Menus
PROCwimp_putmenuitem(menu%,item%,item$)
Adds a new menu item at position item%. Any items below will be 
shuffled down. (menu% must have been already created with sufficient 
capacity to add extra items - see manual Section 2.15)
menu% = handle of menu.
item% = position of new item% (1 is first item) If item% is bigger than 
the current number of items+1, then it will be added to the bottom.
item$ = text of new item.


Menus
PROCwimp_putmenutext(menu%,item%,text$)
Replaces menu item text with text$.
menu% = handle of menu.
item% = number of item (Top item is 1).


Menus
PROCwimp_putmenutitle(menu%,title$)
Changes the title of the menu.
More than 11 characters can be used.
menu% = handle of menu.
title$ = new title.


Menus
PROCwimp_recreatemenu(menu%,menu$)
Rebuilds a menu using the string menu$.
More items can be included than the first time as long as you dont go
over the pre-defined limit.
menu% = handle of menu to rebuild.


Menus
PROCwimp_recreatemenuarray(menu%,array$())
Rebuilds a menu using the items in the array.
The first array item (array$(0)) is the menu title, and the
last has to be the string END.
Things like ticks and dotted lines are removed.
menu% = handle of menu to rebuild
array$() = array to get items from.


Menus
PROCwimp_recreatemessagemenu(menu%,messagefilehandle%,token$,title$)
Rebuilds a menu from a Messages file.
menu% = handle of menu to rebuild
messagefilehandle%= handle of messages file to be used (as returned 
by FNwimp_initmessages/FNwimp_reinitmessages).
token$ = token for menu items. (See FNwimp_createmessagemenu()  
or Manual Section 2.15 for use of token$)
If title$= then the title defined in the message file will be used, 
otherwise title$ will override whatever is defined in the messages file.
(All menu text is created as indirected.)
(Also shown in Messages section.)


Menus
PROCwimp_removemenuitem(menu%,item%)
Removes the item from the menu. Any items below are
shuffled up. If there is only one item on the menu, then
it cannot be removed.
menu% = handle of menu.
item% = number of item to remove.


Sprites
FNwimp_countsprites(spritearea%)
Returns the number of sprites in a sprite area.
spritearea% = handle of sprite area.


Sprites
FNwimp_getspritename(spritearea%,spritenumber%)
Returns the name of a sprite in a sprite area, which has been loaded by 
FNwimp_loadsprites.
spritearea% = handle of sprite area.
spritenumber% = number of sprite in sprite area. First sprite is 1.


Sprites
FNwimp_getspritesize(spritename$,spritearea%,side%)
Returns the width/height (in OS units) of a sprite in a sprite area, which 
has been loaded by FNwimp_loadsprites or is in the Wimp sprite pool.
spritename$ = name of sprite.
spritearea% = handle of sprite area containing sprite (0 means in sprite 
pool).
If side%=0 then returns width of sprite.
If side%=1 then returns height of sprite.


Sprites
FNwimp_loadsprites(filepath$,address%)
Loads a spritefile into a block of memory at address%.
The memory block must have already been created after using 
FNwimp_measurefile().
Returns the address at which to load the next file (if any) into the same 
memory block.
filepath$ = full pathname of spritefile.


Sprites
FNwimp_measurefile(filepath$)
Returns the size in bytes needed to store a file in memory prior to using 
FNwimp_loadfile(), FNwimp_loaddfile(), FNwimp_loadsprites() or 
FNwimp_loadjpegfile().
Always use this as opposed to any other form of measurement.
filepath$ = full pathname of spritefile.
(This function is also listed in in other sections)


Sprites
PROCwimp_rendersprite(spritename$,spritearea%,bx%,by%,minx%,miny%,maxx%,maxy%,xscale,yscale)
Renders (plots) a sprite on the screen at the specified screen 
coordinates, using the clipping rectangle.
spritename$ = name of sprite to plot.
spritearea% = 0 if sprite is in Wimp sprite pool, or
spritearea% = handle of sprite area containing sprite, which has been 
loaded by FNwimp_loadsprites.
bx%,by% = screen coordinates (OS units) at which to put bottom left
corner of sprite.
minx%,miny% = coordinates of bottom left corner of clipping 
rectangle in screen coordinates (OS units).
maxx%,maxy% = coordinates of top right corner of clipping rectangle 
in screen coordinates (OS units).
xscale,yscale = respectively, required scaling factors in x and y 
directions. Values <1 reduce displayed size; values >1 increase size.
(1 meaning no change in size).


Sprites
PROCwimp_renderwindowsprite(window%,spritename$,spritearea%,bx%,by%,minx%,miny%,maxx%,maxy%,xscale,yscale)
Renders (plots) a sprite in a window at specified work area 
coordinates. The window must have its auto-redraw flag unset.
window% = handle of window to render sprite in.
spritename$ = name of sprite to render.
spritearea% = 0 if sprite is in Wimp sprite pool, or
spritearea% = handle of sprite area containing sprite, which has been 
loaded by FNwimp_loadsprites.
bx%,by% = work area coordinates (OS units) of where to put bottom 
left of sprite.
minx%,miny% = coordinates of bottom left corner of clipping
rectangle in screen coordinates (OS units).
maxx%,maxy% = coordinates of top right corner of clipping rectangle 
in screen coordinates (OS units).
(Clipping rectangle is the same as that passed to PROCuser_redraw.)
xscale,yscale = respectively, required scaling factors in x and y 
directions. Values <1 reduce displayed size; values >1 increase size.
(1 meaning no change in size).


Sprites
PROCwimp_savesprites(savepath$,spritearea%)
Saves the contents of a sprite area to a file. The sprites must have been 
loaded into the spritearea by FNwimp_loadsprites.
savepath$ = full pathname of file to be saved.
spritearea% = handle of sprite area containing sprites.


Pointer
FNwimp_getpointerposition(side%)
Returns the screen coordinates of the pointer, in OS units.
If side%=0 then the x coordinate is returned.
If side%=1 then the y coordinate is returned.


Pointer
PROCwimp_bindpointer(window%)
Binds the mouse pointer within the given window in the same manner 
as a standard error message. It should be used when the window the 
mouse is to be bound in is opened.
The pointer is also placed inside the bound area if it was outside it.
Useful if your application uses its own error or message windows 
which you want to force the user to respond to.
As the pointer cannot reach any of the window control icons, your 
window should have a title bar at most.


Pointer
PROCwimp_pointer(pointer%,spritearea%,pointer$)
Changes mouse pointer between the default (number 1) and
the user defined pointer (number 2).
If pointer% = 0 default pointer is used.
If pointer% = 1 user defined pointer is used.
If spritearea% = 0 Wimp sprite pool is used, otherwise spritearea% is a 
handle to a sprite area.
pointer$ = sprite name of pointer.


Pointer
PROCwimp_releasepointer
Releases the mouse pointer to roam over the whole screen after using 
PROCwimp_bindpointer. It should be used when the window the 
mouse is bound in is closed.


Pointer
PROCwimp_setpointerposition(x%,y%)
Moves the pointer to a given position on the screen - in OS units.
x%,y% = screen coordinates to move the pointer to.


Drawfiles
FNwimp_getdfilesize(dfile%,side%)
Returns the width/height (in OS units) of drawfile graphic which has 
been loaded into memory using FNwimp_loaddfile().
dfile%= drawfile handle  
If side% = 0 returns width.
If side% = 1 returns height.
N.B. the returned dimensions are those of the overall bounding box 
surrounding all the drawfile objects i.e. as if all objects were grouped.


Drawfiles
FNwimp_loaddfile(filepath$,address%)
Loads a drawfile into a block of memory at address%.
The memory block must have already been created after using 
FNwimp_measurefile().
Returns the address (handle) at which to load the next file (if any) into 
the same memory block.
filepath$ = full pathname of drawfile.


Drawfiles
FNwimp_measurefile(filepath$)
Returns the size in bytes needed to store a file in memory prior to using 
FNwimp_loadfile(), FNwimp_loaddfile(), FNwimp_loadsprites() or 
FNwimp_loadjpegfile().
Always use this as opposed to any other form of measurement.
filepath$ = full pathname of spritefile.
(This function is also listed in in other sections)


Drawfiles
PROCwimp_initdfiles
Initialises various blocks of memory ready to use with drawfiles.


Drawfiles
PROCwimp_render(dfile%,bx%,by%,minx%,miny%,maxx%,maxy%,scalex,scaley,origin%)
Renders (draws) a drawfile at the specified screen coordinates, using a 
clipping rectangle. All coordinates are in OS units.
dfile% = handle of drawfile to render (from using FNwimp_loaddfile)
bx%,by% = screen coordinates of where to put bottom left corner of
drawfile.
minx%,miny% = screen coordinates of bottom left corner of clipping 
rectangle.
maxx%,maxy% = screen coordinates of top right corner of clipping 
rectangle.
(Clipping rectangle is the same as that passed to PROCuser_redraw.)
scalex,scaley = respectively, required scaling factors in x and y 
directions. Values <1 reduce displayed size; values >1 increase size.
(1 meaning no change in size).
If origin% = 0 drawfile will be rendered with bottom left corner of 
drawfile page at bx%/by%.
If origin% = 1 drawfile will be rendered with bottom left corner of 
drawfile objects overall bounding box at bx%/by%. (See Section 2.20)


Drawfiles
PROCwimp_renderwindow(window%,dfile%,bx%,by%,minx%,miny%,maxx%,maxy%,scalex,scaley,origin%)
Renders (draws) a drawfile in a window at the specified work area 
coordinates, using a clipping rectangle. The window must have its
auto-redraw flag unset. All coordinates are in OS units.
window% = handle of window.
dfile% = handle of drawfile to render (from using FNwimp_loaddfile)
bx%,by% = work area coordinates of where to put bottom left corner 
of drawfile.
minx%,miny% = screen coordinates of bottom left corner of clipping 
rectangle.
maxx%,maxy% = screen coordinates of top right corner of clipping 
rectangle.
(Clipping rectangle is the same as that passed to PROCuser_redraw.)
scalex,scaley = respectively, required scaling factors in x and y 
directions. Values <1 reduce displayed size; values >1 increase size.
(1 meaning no change in size).
If origin% = 0 drawfile will be rendered with bottom left corner of 
drawfile page at bx%/by%.
If origin% = 1 drawfile will be rendered with bottom left corner of 
drawfile objects overall bounding box at bx%/by%. (See Section 2.20)


Drawfiles
PROCwimp_savedfile(savepath$,dfile%)
Saves a drawfile stored in memory into a file.
dfile% = handle of drawfile to save (which must have been loaded into 
memory using FNwimp_loaddfile).
savepath$ = full pathname to save to.


Text
FNwimp_fontchangeh(font%)
Returns control codes in a string to change the current outline font.
Useful for using in the middle of a string of outline font text being 
plotted.
font% = handle of font to change to.


Text
FNwimp_fontcolour(fr%,fg%,fb%,br%,bg%,bb%)
Returns control codes in a string to change the current outline font 
colour. Useful for using in the middle of a string of outline font text 
being plotted.
fr%,fg%,fb% = red, green and blue components respectively of the 
foreground colour, in the range 0-255.
br%,bg%,bb% = red, green and blue components respectively of the 
background (anti-alias) colour, in the range 0-255.


Text
FNwimp_fontunderline(on%)
Returns control codes in a string to turn underlining on or off.
Useful for using in the middle of a string of outline font text being 
plotted.
If on%=0 turns underlining off.
If on%=1 turns underlining on.


Text
FNwimp_getfont(font$,size%)
Obtains a font handle for a particular outline font at a particular point 
size.
font$ = name of font, period separated. eg: Trinity.Medium.
size% = point size of font.
Returns 0 if the font cannot be found.


Text
FNwimp_gettextsize(text$,font$,size%,side%)
Returns the size (in OS units) of a text string as if it had been plotted in 
a particular outline font, using a string-specified font.
text$ = string to measure.
font$ = name of font, period separated, eg: Trinity.Medium.
size% = point size of font.
If side%=0 then the plotted width (length) of the text is returned.
If side%=1 then the plotted height of the text is returned.


Text
FNwimp_gettextsizeh(text$,font%,side%)
Returns the size (in OS units) of a text string as if it had been plotted in 
a particular outline font, using a font handle.
text$ = string to measure.
font% = handle of font.
If side%=0 then the plotted width (length) of the text is returned.
If side%=1 then the plotted height of the text is returned.


Text
PROCwimp_deskplottext(t$,c%,x%,y%,fr%,fg%,fb%,br%,bg%,bb%)
Plots text directly to screen, using the current desktop font
(always the System Font on pre-RISC OS 3.50).
t$ = string to plot.
If c%=1 then text is horizontally centred around x%.
If c%=0 then left side of text is placed at x%.
x%,y% = screen coordinates (OS units) to plot the text at. (y% value is 
bottom of text)
fr%,fg%,fb% = foreground colour red, green and blue amounts in 
range 0-255.
br%,bg%,bb% = background colour red, green and blue amounts in 
range 0-255.


Text
PROCwimp_deskplotwindowtext(window%,t$,c%,x%,y%,fr%,fg%,fb%,br%,bg%,bb%,minx%,miny%,maxx%,maxy%)
Plots text in a window, using the current desktop font
(always the System Font on pre-RISC OS 3.50). 
window% = handle of window to plot in.
t$ = string to plot.
If c%=1 then text is horizontally centred around x%.
If c%=0 then left side of text is placed at x%.
x%,y% = work coordinates (OS units) to plot the text at. (y% value is 
bottom of text)
fr%,fg%,fb% = foreground colour red, green and blue amounts in 
range 0-255.
br%,bg%,bb% = background colour red, green and blue amounts in 
range 0-255.
minx%,miny% = coordinates (OS units) of bottom left corner of 
clipping rectangle in screen coordinates.
maxx%,maxy% = coordinates (OS units) of top right corner of clipping
rectangle in screen coordinates.
(Clipping rectangle is the same as that passed to PROCuser_redraw.)


Text
PROCwimp_losefont(font%)
Forgets about a font i.e. closes its handle, like closing a file.
Should be called when you have finished with the font, eg. when the
application is quitting.
font% = handle of font to lose.


Text
PROCwimp_plottext(t$,f$,s%,x%,y%,fr%,fg%,fb%,br%,bg%,bb%)
Plots text directly to screen, using string-specified font.
t$ = string to plot.
f$ = name of font period spaced eg: Trinity.Medium
s% = point size of font.
x%,y% = screen coordinates (OS units) to plot the text at (y% value is 
bottom of text)
fr%,fg%,fb% = foreground colour red, green and blue amounts in 
range 0-255.
br%,bg%,bb% = background colour red, green and blue amounts in 
range 0-255.


Text
PROCwimp_plottexth(t$,font%,x%,y%,fr%,fg%,fb%,br%,bg%,bb%)
Plots text directly to screen, using font specified by font handle.
t$ = string to plot.
font% = handle of font.
x%,y% = screen coordinates (OS units) to plot the text at (y% value is 
bottom of text)
fr%,fg%,fb% = foreground colour red, green and blue amounts in 
range 0-255.
br%,bg%,bb% = background colour red, green and blue amounts in 
range 0-255.


Text
PROCwimp_plotwindowtext(window%,t$,f$,s%,x%,y%,fr%,fg%,fb%,br%,bg%,bb%,minx%,miny%,maxx%,maxy%)
Plots text in a window, using string-specified font.
window% = handle of window to plot in.
t$ = string to plot.
f$ = name of font to use, period separated, eg: Trinity.Medium.
s% = point size of font.
x%,y% = work area coordinates (OS units) to plot text at. (y% value is 
bottom of text)
fr%,fg%,fb% = foreground colour red, green and blue amounts in the 
range 0-255.
br%,bg%,bb% = background colour red, green and blue amounts in the 
range 0-255.
minx%,miny% = coordinates (OS units) of bottom left corner of 
clipping rectangle.
maxx%,maxy% = coordinates (OS units) of top right corner of clipping
rectangle.
(Clipping rectangle is the same as that passed to PROCuser_redraw.)


Text
PROCwimp_plotwindowtexth(window%,t$,font%,x%,y%,fr%,fg%,fb%,br%,bg%,bb%,minx%,miny%,maxx%,maxy%)
Plots text in a window, using font specified by font handle.
window% = handle of window to plot in.
t$ = string to plot.
font% = handle of font to use.
x%,y% = work area coordinates (OS units) to plot text at. (y% value is 
bottom of text)
fr%,fg%,fb% = foreground colour red, green and blue amounts in the 
range 0-255.
br%,bg%,bb% = background colour red, green and blue amounts in the 
range 0-255.
minx%,miny% = coordinates (OS units) of bottom left corner of 
clipping rectangle.
maxx%,maxy% = coordinates (OS units) of top right corner of clipping
rectangle.
(Clipping rectangle is the same as that passed to PROCuser_redraw.)


Printing
FNwimp_getpapersize(side%,type%)
Returns various information about the current paper size set up in 
loaded printer driver - in OS units.
If side%=0 then a horizontal measurement is returned.
If side%=1 then a vertical measurement is returned.
Which measurement is determined by type%.
If type%=0 then the width or height is returned.
If type%=1 then the left or bottom margin is returned.
If type%=2 then the printable width or printable height is returned.
If type%=3 then the right or top margin is returned.


Printing
FNwimp_getpdrivername
If a printer driver is loaded, the name of the printer driver is returned.
Check to make sure one is loaded first, with FNwimp_pdriverpresent.


Printing
FNwimp_papertoscreen(window%,coord%,side%,orient%)
Converts a paper x or y coordinate to a screen x or y coordinate - all in 
OS units.
window% = handle of window whose work area to use.
(A window reference is needed because paper values are assumed to 
map to positions in a window - from which screen coords are 
calculated.)
coord% = coordinate (x or y).
If side%=0 then coord% is a x coordinate, and an x coordinate is 
returned.
If side%=1 then coord% is a y coordinate, and a y coordinate is 
returned.
If orient%=0 then page is portrait.
If orient%=1 then page is landscape.


Printing
FNwimp_papertowork(coord%,side%,orient%)
Converts a paper x or y coordinate to a work area x or y coordinate - 
all in OS units.
(Paper values are assumed to map to positions in a window. Hence x 
values are the same and y values only referenced to different corner.)
coord% = coordinate (x or y).
If side%=0 then coord% is a x coordinate, and an x coordinate is 
returned.
If side%=1 then coord% is a y coordinate, and a y coordinate is 
returned.
If orient%=0 then page is portrait. If orient%=1 then page is landscape.


Printing
FNwimp_pdriverpresent
Checks to see if a printer driver is loaded.
Returns TRUE (-1) if a printer driver is loaded, or FALSE (0) if not.
(Note difference from usual Dr Wimp practice of returning 1 or 0)


Printing
FNwimp_screentopaper(window%,coord%,side%,orient%)
Converts a screen x or y coordinate to a paper x or y coordinate - all
in OS units.
(A window reference is needed because paper values are assumed to 
map to positions in a window.)
window% = handle of window whose work area to use.
coord% = coordinate (x or y).
If side%=0 then coord% is a x coordinate, and an x coordinate is 
returned.
If side%=1 then coord% is a y coordinate, and a y coordinate is 
returned.
If orient%=0 then page is portrait.
If orient%=1 then page is landscape.


Printing
FNwimp_worktopaper(coord%,side%,orient%)
Converts a work area x or y coordinate to a paper x or y coordinate -
all in OS units.
(Paper values are assumed to map to positions in a window. Hence x 
values are the same and y values only referenced to different corner.)
coord% = coordinate (x or y).
If side%=0 then coord% is a x coordinate, and an x coordinate is 
returned.
If side%=1 then coord% is a y coordinate, and a y coordinate is 
returned.
If orient%=0 then page is portrait. If orient%=1 then page is landscape.


Printing
PROCwimp_declaredfilefonts(dfile%)
Declares the fonts used in a drawfile (especially) for postscript 
printing. (Intended to be used within PROCuser_declarefonts)
dfile% = handle of drawfile to be printed, which must have been 
loaded using FNwimp_loaddfile.


Printing
PROCwimp_declarefont(font$)
Declares a font for printing. (Intended to be used within 
PROCuser_declarefonts)
font$ = name of font to declare, period separated e.g. 
Trinity.Medium.


Printing
PROCwimp_declarefonth(font%)
Declares a font for printing using font handle. (Intended to be used 
within PROCuser_declarefonts)
font% = handle of font to declare.


Printing
PROCwimp_print(user%,window%,fpage%,lpage%,perpage%,copies%,orient%)
Initiates printing of a document.
If user%=0 PROCuser_redraw is called to draw the pages (with 
printing% set to TRUE and the clipping rectangle set to the page 
coordinates).
If user%=1 PROCuser_print is called to draw the pages, with the 
clipping rectangle set to the page coordinates.
window% = handle of window to redraw if user%=0.
fpage% = page number of first page to print.
lpage% = page number of last page to print.
perpage% = number of A4 pages to fit onto a physical A4 page. Can be
1, 2 or 4.
copies% = number of copies of the document to print.
If orient%=0 then page is portrait.
If orient%=1 then page is landscape.


Dynamic areas
FNwimp_changedynamic(darea%,absolute%,size%)
Changes the size of a dynamic area.
darea% = handle of dynamic area to be resized.
If absolute%=1 then the size in bytes given in size% is the new 
absolute size of the dynamic area.
If absolute%=0 then the size in bytes given in size% is the amount to 
change the dynamic area size by. (In this case, if size% is positive then 
the area will become larger, if size% is negative then the area will 
shrink.)
Returns a handle for the dynamic area, which may not be the same 
location as before.
Note the point about multiples of 4kbytes in 
FNwimp_createdynamic() above.


Dynamic areas
FNwimp_createdynamic(size%,maxsize%,type%,drag%,name$)
Creates a dynamic area and returns a handle for it.
size% = initial size of dynamic area in bytes.
maxsize% = maximum size of dynamic area in bytes. Only of 
relevance if type%=0 and OS is 3.50 or higher. (-1 means no limit 
but use of this special value is not recommended.)
If type%=0 (the recommended setting) then Dr Wimp will 
automatically locate the dynamic area according to the OS Version the 
application is running under. (A specific dynamic area if OS 3.5 or 
higher; in the RMA otherwise.)
If type%=1 then the dynamic area will be created in the RMA.
If type%=0 and OS is 3.50 or higher, then drag% and name$ are taken 
into account. Then, if drag% = 1 the user can change the size of the 
area by dragging in the Task Display; and name$ is the name of the 
dynamic area appearing in the Task Display.
Note: Dynamic area sizes may be restricted by the OS to multiples of 
4kbytes (4096 bytes). Automatic rounding up will then occur. See 
Section 2.28 of manual.


Dynamic areas
FNwimp_measuredynamic(darea%)
Returns the current size of a dynamic area in bytes.
darea% = handle of dynamic area to measure.


Dynamic areas
PROCwimp_deletedynamic(darea%)
Deletes a dynamic area.
darea% = handle of dynamic area to delete.


Colour picker
PROCwimp_opencolourpickermodel(model%,dialoguetype%,value1,value2,value3,value4,none%,x%,y%)
Opens the colour picker window with the colour model set by 
model% and the initial colour set by the values of value1, value2, etc.
model%=0 for RGB model, 1 for CMYK model, 2 for HSV 
model.
value1, value2 etc. are in range 0-100%, except that value1 is
in the range 0-359 degrees (the colour angle in HSV) when 
model%=2.
value4, which must always be present, is ignored unless model%=1 
(CMYK model).
x%/y% are screen OS-unit coordinates of top left corner of window.
If dialoguetype%=0 the window will be closed by specific action e.g. 
selecting its Close icon.
If dialoguetype%=1 the window will close if the mouse is clicked 
outside the window.
If none%=0 the None button will be disabled.
If none%=1 the None button will be enabled and deselected.
If none%=2 the None button will be enabled and selected.
(Note: the window also closes when OK or None button is selected.)


Colour picker
PROCwimp_opencolourpickerrgb(dialoguetype%,red%,green%,blue%,none%,x%,y%)
Opens the colour picker window with the initial colour set by the 
values of red%, green% and blue%, which are in the range 0-255.
The window will open in the RGB model (which means the set colour
values will actually be shown as percentages in the range 0-100%).
x%/y% give the screen OS-unit coordinates of the top left corner of
the opening window.
dialoguetype% determines how the window will close:
If dialoguetype%=0 the window will be closed by specific action e.g. 
selecting its Close icon.
If dialoguetype%=1 the window will close if the mouse is clicked 
outside the window.
If none%=0 the None button will be disabled.
If none%=1 the None button will be enabled and deselected.
If none%=2 the None button will be enabled and selected.
(Note: the window also closes when the OK or None button is 
selected.)


Colour picker
PROCwimp_opensubmenucolourpickermodel(model%,value1,value2,value3,value4,none%,x%,y%)
Opens the colour picker window as a sub-menu, with the colour 
model set by model% and the initial colour set by the values of value1, 
value2, etc.
model%=0 for RGB model, 1 for CMYK model, 2 for HSV 
model.
value1, value2 etc. are in range 0-100%, except that value1 is
in the range 0-359 degrees (the colour angle in HSV) when 
model%=2.
value4, which must always be present, is ignored unless model%=1 
(CMYK model).
x%/y% are screen OS-unit coordinates of top left corner of window.
If none%=0 the None button will be disabled.
If none%=1 the None button will be enabled and deselected.
If none%=2 the None button will be enabled and selected.
As with any sub-menu, the window will close if the mouse is clicked 
outside the window or when the mouse pointer retraces the opening 
route. (Note: the window also closes when the OK or None button is 
selected.)


Colour picker
PROCwimp_opensubmenucolourpickerrgb(red%,green%,blue%,none%, x%,y%)
Opens the colour picker window as a sub-menu, with the initial 
colour set by the values of red%, green% and blue%,
which are in the range 0-255.
The window will open in the RGB model (which means the set colour
values will actually be shown as percentages in the range 0-100%).
x%/y% give the screen OS-unit coordinates of the top left corner of
the opening window.
If none%=0 the None button will be disabled.
If none%=1 the None button will be enabled and deselected.
If none%=2 the None button will be enabled and selected.
As with any sub-menu, the window will close if the mouse is clicked 
outside the window or when the mouse pointer retraces the opening 
route. (Note: the window also closes when the OK or None button is 
selected.)


JPEG files
FNwimp_getjpegsize(jpeghandle%,side%)
Returns the width/height (in OS units) of a JPEG graphic which has 
been loaded into memory using FNwimp_loadjpegfile().
jpeghandle%= JPEG file handle.
If side% = 0 returns width.
If side% = 1 returns height.
N.B. the returned dimensions are those of the overall bounding box 
surrounding the graphic.


JPEG files
FNwimp_getjpegsizefile(filepath$,side%)
Returns the width/height (in OS units) of a JPEG graphic directly from 
its file.
filepath$ = full JPEG file path.
If side% = 0 returns width.
If side% = 1 returns height.
N.B. the returned dimensions are those of the overall bounding box 
surrounding the graphic.


JPEG files
FNwimp_loadjpegfile(filepath$,address%)
Loads a JPEG file into a block of memory at address%.
The memory block must have already been created after using 
FNwimp_measurefile().
Returns the address (handle) at which to load the next file (if any) into 
the same memory block.
filepath$ = full pathname of JPEG file.


JPEG files
FNwimp_measurefile(filepath$)
Returns the size in bytes needed to store a file in memory prior to using 
FNwimp_loadfile(), FNwimp_loaddfile(), FNwimp_loadsprites() or 
FNwimp_loadjpegfile().
Always use this as opposed to any other form of measurement.
filepath$ = full pathname of spritefile.
(This function is also listed in in other sections)


JPEG files
PROCwimp_renderjpeg(jpeghandle%,bx%,by%,minx%,miny%,maxx%,maxy%,scalex,scaley)
Renders (draws) a JPEG at the specified screen coordinates, using a 
clipping rectangle. All coordinates are in OS units.
The JPEG must already have been loaded into memory using 
FNwimp_loadjpegfile().
jpeghandle% = handle of JPEG
bx%,by% = screen coordinates of where to put bottom left corner of 
JPEG.
minx%,miny% = screen coordinates of bottom left corner of clipping 
rectangle.
maxx%,maxy% = screen coordinates of top right corner of clipping 
rectangle.
(Clipping rectangle is the same as that passed to PROCuser_redraw.)
scalex,scaley = respectively, required scaling factors in x and y 
directions. Values <1 reduce displayed size; values >1 increase size.
(1 meaning no change in size).


JPEG files
PROCwimp_renderjpegfile(jpegfilepath$,bx%,by%,minx%,miny%,maxx%,maxy%,scalex,scaley)
Renders (draws) a JPEG directly from its file to the specified screen 
coordinates, using a clipping rectangle. All coordinates are in OS units.
jpegfilepath$ = fullpath of JPEG file
bx%,by% = screen coordinates of where to put bottom left corner of 
JPEG.
minx%,miny% = screen coordinates of bottom left corner of clipping 
rectangle.
maxx%,maxy% = screen coordinates of top right corner of clipping 
rectangle.
(Clipping rectangle is the same as that passed to PROCuser_redraw.)
scalex,scaley = respectively, required scaling factors in x and y 
directions. Values <1 reduce displayed size; values >1 increase size.
(1 meaning no change in size).
(Note: This function cannot be used for printing.)


JPEG files
PROCwimp_renderwindowjpeg(window%,jpeghandle%,bx%,by%,minx%,miny%,maxx%,maxy%,scalex,scaley)
Renders (draws) a JPEG in a window at the specified work area 
coordinates, using a clipping rectangle. The window must have its
auto-redraw flag unset. All coordinates are in OS units.
The JPEG must already have been loaded into memory using 
FNwimp_loadjpegfile().
window% = handle of window.
jpeghandle% = handle of JPEG
bx%,by% = work area coordinates of where to put bottom left corner 
of JPEG.
minx%,miny% = screen coordinates of bottom left corner of clipping 
rectangle.
maxx%,maxy% = screen coordinates of top right corner of clipping 
rectangle.
(Clipping rectangle is the same as that passed to PROCuser_redraw.)
scalex,scaley = respectively, required scaling factors in x and y 
directions. Values <1 reduce displayed size; values >1 increase size.
(1 meaning no change in size).


JPEG files
PROCwimp_renderwindowjpegfile(window%,jpegfilepath$,bx%,by%,minx%,miny%,maxx%,maxy%,scalex,scaley)
Renders (draws) a JPEG directly from its file to a window at the 
specified work area coordinates, using a clipping rectangle. The 
window must have its auto-redraw flag unset.
All coordinates are in OS units.
window% = handle of window.
jpegfilepath$ = fullpath of JPEG file
bx%,by% = work area coordinates of where to put bottom left corner 
of JPEG.
minx%,miny% = screen coordinates of bottom left corner of clipping 
rectangle.
maxx%,maxy% = screen coordinates of top right corner of clipping 
rectangle.
(Clipping rectangle is the same as that passed to PROCuser_redraw.)
scalex,scaley = respectively, required scaling factors in x and y 
directions. Values <1 reduce displayed size; values >1 increase size.
(1 meaning no change in size).
(Note: This function cannot be used for printing.)


JPEG files
PROCwimp_savejpeg(savepath$,jpeghandle%)
Saves a JPEG currently loaded in memory to a file. The JPEG must 
have been loaded into memory by FNwimp_loadjpegfile.
savepath$ = full pathname of file to be saved.
jpeghandle% = handle of memory area containing the JPEG.


Elixirs
PROCuser_redrawtextline(x%,y%,line%)
NOT IN SKELETON !RunImage.
ONLY USED AS PART OF Elixir_01 for fast scrolling of long text 
lists - see Manual Section 2.37 and 3.16 Elixirs
Needs to be used with PROCwimp_calcredrawlines().
x% - x-position to plot text line (in screen OS units)
y% - y-position to plot text line (in screen OS units)
line% - the number of the list line to be plotted/redrawn.


Elixirs
PROCwimp_calcredrawlines(leftmargin%,topmargin%,totallines%,linespacing%)
NOT IN DrWimp LIBRARY.
ONLY USED AS PART OF Elixir_01 for fast scrolling of long text 
lists - see Manual Section 2.37 and 3.16 Elixirs
Needs to be used with PROCuser_redrawtextline().
leftmargin% - horizontal margin between left edge of list window and start of list text (in OS units).
topmargin% - vertical margin between top of list window and start of list area (in OS units).
totallines% - the total number of lines in the list.
linespacing% - the vertical spacing between lines of the list (in OS units).


