     Wimp a FORTRAN Wimp subroutine library.

%WPADNI

 CALL WPADNI(IWHAN,IWX,IWY,ITYPE,TEXT,ICONH)

 Purpose: Adds a 'new' type icon to a window.

 Parameters:

   IWHAN   - INTEGER handle of the window for the icon.

   IWX,IWY - INTEGERs position in the window for the icon, measured
                      in OS units from the top left corner of the work area
                      to the bottom left corner of the icon.
                      (IWY <= 0 <= IWX)

   ITYPE   - INTEGER  defines the type of new icon
                    0: plain black text with no background
                    1: text on a 'slab' pushed out
                    2: text on a 'slab' pushed in
                    3: text surrounded by a ridge
                    4: text surrounded by a channel
                    5: text on an action slab
                    6: text on a 'default' action slab
                    7: writeable text
                    8: text with 'option' button (for inclusive selections)
                    9: text with 'radio' button (for exclusive selections)
                   10: 'menu' icon (TEXT ignored)
                   11: 'up arrow' icon (TEXT ignored)
                   12: 'down arrow' icon (TEXT ignored)
            add Nx100 for Exclusive Selection Group (ESG) = N


    TEXT   - CHARACTER text to be displayed in the icon. These data are 
                      always 'indirected' and hence must be in permanent
                      memory (SAVE or COMMON) and the data must be 'null'
                      terminated. 

   ICONH   - INTEGER returned icon handle. In each window, icon handles will
                     start from zero and increase.
                 or negative if the user accepted the error.

 Errors: (-1) unknown window handle,
         (-2) illegal ITYPE,
         (-3) TEXT not 'null' terminated.
         

 Comments: 1) the program TWIMP15 shows examples of each type
           2) 'radio' buttons (ITYPE=9) should be in an ESG
           3) the 'menu' and 'arrow' icons are not shown in their
              'selected' form by clicking on them. Use WPSTIF( , ,21,.TRUE.)
              to select them on receiving a click.
           4) the icons are normally 48 units high and are long enough to
              hold the text. Icons of types 3, 4, 6 & 7 are 64 units high
              because of their wider borders. The sprite-only icons (10-12)
              are 48 units wide.
           5) uses Wimp_CreateIcon, PRM2 p 1180, PRM3 p3-96

%WPADSI

 CALL WPADSI(IWHAN,IWX,IWY,SNAME,ICONH)

 Purpose: Adds a sprite icon to a window

 Parameters:

   IWHAN   - INTEGER handle of the window for the icon

   IWX,IWY - INTEGERs position in the window for the icon, measured
                      in OS units from the top left corner of the work area
                      to the bottom left corner of the sprite.
                      (IWY <= 0 <= IWX)

   SNAME   - CHARACTER name of sprite (not more than 12 characters)

   ICONH   - INTEGER returned icon handle. In each window, icon handles will
                     start from zero and increase.
                 or -1 if the user accepted the error.

 Errors: unknown window handle,
         unknown sprite

 Comments: 1) change the sprite area pointer of your window before it is
           created with WPCHSA if you want to use sprites other than those
           in the Wimp area.
           2) change the default sprite icon flags with WPCHSF before
           calling WPADSI
           4) uses Wimp_CreateIcon, PRM2 p 1180, PRM3 p
                   Wimp_SpriteOp  , PRM2 p 1271, PRM3 p
                   OS_ReadModeVarible, PRM2 p 350, PRM3, p
                   OS_SpriteOp(#40), PRM2 p 423, PRM3, p

%WPADTI

 CALL WPADTI(IWHAN,IWX,IWY,ISX,ISY,STEXT,SVALID,ICONH)

 Purpose: Adds a text icon to a window

 Parameters:

   IWHAN  - INTEGER handle of the window for the icon

   IWX,IWY - INTEGERs position in the window for the icon, measured
                      in OS units from the top left corner of the work area
                      to the bottom left corner of the icon.
                      (IWY <= 0 <= IWX)

   ISX     - INTEGER length of icon in OS units,
                     (use WPTXTW to get minimum width)

   ISY     - INTEGER height of icon in OS units (often 48)

   STEXT   - CHARACTER text to go in the icon (see comments below)

   SVALID  - CHARACTER validation string (see comments) or
             INTEGER   = 0 if not used

   ICONH   - INTEGER returned icon handle. In each window icon handles will
                     start from zero and increase.
                 or -1 if the user accepted the error.

 Error: unknown window handle.

 Comments:  1) the text in an icon can be stored within the icon definition
          provided that it is not more than 12 characters, and is not
          "writable", i.e. you do not want to type into it, or change it
          later. This is the default/efficient way to store the text.
          If the text is longer than 12 characters, it has to be stored
          "indirected", i.e. the CHARACTER variable you supply is not copied
          into the icon, but is referenced by the icon. The text now has to
          be "null terminated", so you must add a CHAR(0) at the end. Also,
          such indirected strings must be in permanent memory (preferably
          COMMON) or else they are likely to disappear before you see them.
            2) you can force indirection of text by setting icon flag 8:
              CALL WPCHTF(8,.TRUE.)
          before calling WPADTI.
            3) for writable icons [CALL WPCHTF(115) first], the
          maximum length of the writable text is determined by the
          CHARACTER*nn definition of STEXT; remember to put a CHAR(0) after
          the useful part of the initial definition, or at the beginning if
          none.
            3) A writable icon can be validated while it is being typed
          into. A typical validation string is:
              'A0-9.+\-'//CHAR(0)
          which allows only the digits (0-9), the decimal point, +, and -.
          SVALID must be in permanent memory, preferably in COMMON unless it
          is zero.
            4) SVALID can also set the colours for text in an anti-aliased
          font: include 'Fxy' in the string where x and y are hexadecimal
          digits giving the bakground (x) and foreground (y) colours.
            5) Uses Wimp_CreateIcon, PRM2 p 1180, PRM3 p

%WPAINT

 CALL WPAINT(SNAME)

 Purpose: Sends sprite file SNAME to !Paint

 Parameter:

   SNAME  - CHARACTER name of file to send to !Paint

 Error: unknown or non-sprite file

 Comments: 1) this is equivalent to double clicking over a sprite file in a
              filer directory window
           3) uses Wimp_SendMessage, PRM2 p 1253, PRM3 p

%WPAM2M

 CALL WPAM2M(MBL2,MBLOC,INDEX)

 Purpose: Attaches a secondary menu to a menu item, so that there is an arrow
          after the item; moving the pointer over the arrow opens the new
          menu.

 Parameters:

   MBL2    - INTEGER array secondary menu block to attach (made by WPMKMB)

   MBLOC   - INTEGER array menu block (made by WPMKMB)

   INDEX   - INTEGER index of menu item where the new menu is to be attached
                     (numbered from zero at the top)

 Error: INDEX is outside the allowed range

%WPAW2M

 CALL WPAW2M(IWHAN,MBLOC,INDEX)

 Purpose: Attaches a window to a menu item, so that there is an arrow after
          the item; moving the pointer over the arrow opens the window.

 Parameters:

   IWHAN   - INTEGER handle of the window to attach

   MBLOC   - INTEGER array menu block (made by WPMKMB)

   INDEX   - INTEGER index of menu item where the window is to be attached
                     (numbered from zero at the top)

 Errors: 1) INDEX is outside the allowed range
         2) unknown window handle

%WPAZ2M

 CALL WPAZ2M(MBLOC,INDEX)

 Purpose: Removes a secondary menu or window from a menu item

 Parameters:

   MBLOC   - INTEGER array menu block (made by WPMKMB)

   INDEX   - INTEGER index of menu item to have its sub-menu (or window)
                     removed; (numbered from zero at the top).

 Error: INDEX is outside the allowed range

%WPBARI

 CALL WPBARI(SPRITE,IPOS,MBLOC,ICONH)

 Purpose: Puts sprite icon on the icon-bar with an attached menu tree

 Parameters:

   SPRITE  - CHARACTER name of sprite

   IPOS    - INTEGER = -2 for left, -1 for right side of the icon bar

   MBLOC   - INTEGER array top level menu block to be attached to the icon
                           or 0 if none

   ICONH   - INTEGER returned icon handle

 Errors: 1) sprite not found in wimp pool
         2) sprite already on icon bar
         3) IPOS not -1 or -2.

 Comments: 1) sprites are stored in the wimp pool with the 'IconSprites'
           command usually found in the !Boot or !Run files of an
           application, or with SPAMRG(-1,FILENM) from the SpriteOp library.
           2) this routine allows only one icon for the taskon the icon bar,
           however an unwanted one can be deleted with WPDELI.
           3) see WPMKMB for menu blocks
%WPBART

 CALL WPBART(SPRITE,IPOS,MBLOC,TEXT,ICONH)

 Purpose: Puts sprite icon with text on the icon-bar with an attached menu
          tree

 Parameters:

   SPRITE  - CHARACTER name of sprite

   IPOS    - INTEGER = -2 for left, -1 for right side of the icon bar

   MBLOC   - INTEGER array top level menu block to be attached to the icon
                           or 0 if none

   TEXT    - CHARACTER - null terminated text string to put below
                         the sprite

   ICONH   - INTEGER returned icon handle

 Errors: 1) sprite not found in wimp pool
         2) sprite already on icon bar
         3) IPOS not -1 or -2.

 Comments: 1) sprites are stored in the wimp pool with the 'IconSprites'
           command usually found in the !Boot or !Run files of an
           application, or with SPAMRG(-1,FILENM) from the SpriteOp library.
           2) this routine allows only one icon for the task on the icon
           bar; however an unwanted one can be deleted with WPDELI.
           3) don't make TEXT too long or the icon will take up lots of the
           icon-bar. TEXT will have the last character set to zero if no
           terminator is found. You can change the text during execution but
           initiate it with the longest string you'll need to reserve the
           space.
           4) see WPMKMB for menu blocks
%WPBEGS

 CALL WPBEGS(IWHAN)

 Purpose: sends vdu output to a window sprite

 Parameters:

   IWHAN  - INTEGER handle of window with sprite

 Errors: Unknown window handle
         Sprite not initialised by WPMAKS (see comment 1)
         Problem opening window sprite (F77_Wimp?) 
 (this will only happen if the sprite has been deleted by another user)

 Comments: 1) the window sprite must have been created before trying to send
              output to it
           2) you must call WPENDS when you have finished sending output to
              it
           3) between calling WPBEGS and WPENDS any standard graphics or
              text commands may be used but they only appear on the screen
              when WPENDS is called.
           4) the coordinates have the origin at the bottom left corner for
              graphics and for text the lines are numbered from the top just
              as in stand-alone graphics.
         
%WPCHFT

 CALL WPCHFT(IFONT)

 Purpose: changes default text icon font

 Parameter:

   IFONT  - INTEGER font handle for new font

 Error: unknown font handle

 Comment: 1) nothing happens if you accept an unknown font error
          2) use WPCHTC to return to the system font by setting a text
          colour
          3) use FTFIND in the font library to set up a font handle and
          try to be sociable by calling FTLOSE when you stop needing the
          icon any longer.

%WPCHSA

 CALL WPCHSA(IAREA)

 Purpose: Changes the default sprite area for icons before making a new
          window with WPMKNW or WPLDTW

 Parameter:

   IAREA  - INTEGER a user sprite area array,
                or  -1 for wimp sprites (default)
                or 0 for system sprite area

 Error: IAREA does not define a sprite area

 Comments: 1) a user sprite area must have been initialised before calling
           this routine.
           2) all icon sprites in a window must be in the same area.

%WPCHSF

 CALL WPCHSF(INDEX,SET)

 Purpose: Changes a default icon flag before creating a sprite icon
          with WPADSI

 Parameters:

   INDEX  - INTEGER defines which flag to clear.
                    The flags are in the range [0:31], allowed ones are:
          No.  result when set          default   comment
           2:  icon has a border            set
           5:  icon has filled background unset
          10:  allow multiple ESG select  unset   see ESG comments below
          11:  plot 1/2 sized sprite      unset
          21:  selects the icon           unset
          22:  greys the icon             unset
          23:  closes the icon            unset
       200+n:  set the ESG to n [0:31]        0   see ESG comments below
       100+n:  set button type to n [0:15]  11
                     some useful button types are:
            n=0: ignore button clicks
              2: click notifies task (auto-repeat)
              3: click notifies task, but does not select
              5: click selects, double-click notifies task
              9: 'menu' type, pointer over icon selects, click notifies task
                 (needs at least two icons in an ESG)
             11: click selects, and returns button state (default)

   SET   - LOGICAL sets the flag if .TRUE., clears it if .FALSE.
                   (unused if INDEX > 23)


 Errors: INDEX value not allowed.

 Comments: 1) no action will be taken if the value of INDEX is outside
           the allowed ranges.
           2) use WPSTIF to set an icon flag after creation
           3) The selection of a set of icons can be made mutually exclusive
           by putting them in a Exclusive Selection Group (ESG). The default
           ESG value of 0 means there is no exclusion. If flag 10 is set,
           then clicking with the 'adjust' button overrides the exclusion,
           like selecting files in a filer directory window.
           4) For a complete list of icon flags and button types,
           see Wimp_CreateIcon, PRM2 p 1180, PRM3 p

%WPCHTC

 CALL WPCHTC(INDEX,KOLOUR)

 Purpose: Changes the default colours before creating a text icon with WPADTI

 Parameters:

   INDEX  - INTEGER defines which colour to change:
                 =0,  foreground colour, default:  7 (black)
                 =1,  background colour, default: 12 (cream)

   KOLOUR - INTEGER new colour in the range [0:15]
               0 - 7  white to black grey scale
               8: dark blue    9: yellow      10: green    11: red
              12: cream       13: dark green  14: orange   15: light blue

 Errors: parameters outside allowed ranges

 Comments: 1) if the values are outside the allowed ranges no action will be
           taken .
           2) be careful if you want to "grey-out" an icon: the text may not
           be visible if you use fancy colours.
           3) WPCHTC resets the font to the system font

%WPCHTF

 CALL WPCHTF(INDEX,SET)

 Purpose: Changes a default icon flag before creating a text icon with WPADTI

 Parameters:

   INDEX  - INTEGER defines which flag to clear.
                    The flags are in the range [0:31], allowed ones are:
          No.  result when set         default   comment
           2:  icon has a border           set
           3:  text centred in the icon    set   left justified if unset
           4:  text centred vertically     set
           5:  background filled           set
           8:  text is indirected        unset   default set if text>12 chars
           9:  text is right justified   unset
          10:  allow multiple ESG select unset   see ESG comments below
          21:  selects the icon          unset
          22:  greys the icon            unset
          23:  closes the icon           unset
       200+n:  set the ESG to n [0:31]       0   see ESG comments below
       100+n:  set button type to n [0:15]  11
                     some useful button types are:
            n=0: ignore button clicks
              2: click notifies task (auto-repeat)
              3: click notifies task, but does not select
              5: click selects, double-click notifies task
              9: 'menu' type, pointer over icon selects, click notifies task
                 (needs at least two icons in an ESG)
             11: click selects, and returns button state (default)
             15: writable icon

   SET   - LOGICAL sets the flag if .TRUE., clears it if .FALSE.
                   unused if INDEX > 23


 Errors: INDEX value not allowed.

 Comments: 1) no action will be taken if the value of INDEX is outside
           the allowed ranges.
           2) use WPSTIF to set an icon flag after creation
           3) The selection of a set of icons can be made mutually exclusive
           by putting them in a Exclusive Selection Group (ESG). The default
           ESG value of 0 means there is no exclusion. If flag 10 is set,
           then clicking with the 'adjust' button overrides the exclusion,
           like selecting files in a filer directory window.
           4) selecting a button type of 15 automatically sets flag 8.
           5) For a complete list of icon flags and button types,
           see Wimp_CreateIcon, PRM2 p 1180, PRM3 p

%WPCHWC

 CALL WPCHWC(INDEX,KOLOUR)

 Purpose: Changes the default window colours before making a new window
          with WPMKNW

 Parameters:

   INDEX  - INTEGER defines which colour to change:
             index                             default
              0:  title text & frame            7 (black)
              1:  title background              2 (medium grey)
              2:  work area foreground          7 (black) see WPSETC
              3:  work area background          1 (light grey)
              4:  scrollbar outer               3 (medium grey
              5:  scrollbar slider              1 (light grey)
              6:  highlighted title background 12 (cream)

   KOLOUR - INTEGER new colour in the range [0:15]
               0 - 7 white to black grey scale
               8: dark blue    9: yellow      10: green    11: red
              12: cream       13: dark green  14: orange   15: light blue
                a KOLOUR of 255 is allowed for the work area background
                (INDEX=3) making this area transparent.

 Errors: parameters outside the allowed ranges

%WPCHWF

 CALL WPCHWF(INDEX,SET)

 Purpose: Changes the default window flags before making a new window
          with WPMKNW

 Parameters:

   INDEX  - INTEGER defines which flag to change.
                    The flags are in the range [0:31], allowed ones are:
          No.  result when set              default  comment
           1:  window is moveable              set
           4:  no user drawing required      unset   WQPLOT not called if set
           6:  can be dragged off screen     unset
           8:  scroll requests               unset   see WQSCRL
           9:  as 8, but no auto-repeat      unset
          12:  report 'hot-key' presses      unset   see WQKEYP
          24:  window has Back Icon            set   requires 26
          25:  window has Close Icon           set   requires 26
          26:  window has Title Bar            set
          27:  window has Toggle-size Icon     set   requires 26 or 28
          28:  window has vertical scroll      set
          29:  window has Adjust-size Icon     set   requires 28 or 30
          30:  window has horizontal scroll    set
       100+n:  set the button type to n [0:15]   3
                     some useful button types are:
            n=0: ignore button clicks
              2: click notifies task (auto-repeat)
              3: click notifies task (default)
              5: double-click notifies task
             15: click gains input focus

   SET    - LOGICAL sets the flag if .TRUE. clears it if .FALSE.
                    ignored if INDEX > 30.

 Error: INDEX value not allowed.

 Comments: 1) the icons in the corners of the window boundaries require
           a main boundary element to be used (as shown in the comment column
           above). Conflicts are resolved by assuming that if you try to set
           one of the corner icons, then the main element will also be
           needed. Conversely, if you remove a main boundary element,
           corners which are not supported elsewhere will also be removed.
           The ambiguity which happens when you try to create a toggle-size
           icon and neither the title nor vertical scroll is present is
           resolved by creating a vertical scroll. The same rule applies for
           the adjust-size icon.
           2) for a complete list of window flags and button types,
                  see Wimp_CreateWindow, PRM2 p 1174, PRM3 p

%WPCLST

 CALL WPCLST

 Purpose: Closes file of window templates opened by WPOPNT

 No parameters

 Error: template file not open

 Comment: Uses Wimp_CloseTemplate, PRM2 p 1237, PRM3 p

%WPCLSW

 CALL WPCLSW(IWHAN)

 Purpose: Closes a window from the desktop temporarily

 Parameters:

   IWHAN  - INTEGER handle of window to close

 Error: unknown window handle

 Comments: 1) use WPDELW to remove a window permanently
           2) if the window IWHAN has panes these will also be closed
           3) if the window IWHAN is a pane, the host window will not be
              closed but the pane will be deactivated as well as being
              closed.
           4) uses Wimp_CloseWindow, PRM2 p 1191, PRM3 p

%WPCLTX

 CALL WPCLTX(ISTOP)

 Purpose: Closes a window which has been used for text

  Parameters:

  ISTOP  - LOGICAL .FALSE. to print message 'Press SPACE or click...' first
                   .TRUE. to close the window immediately

 Comments: 1) this window should have been opened with WPOPTX (q.v.).
           2) the window will not actually close until your WQxxxx routine
              RETURNs to the wimp.
           3) uses Wimp_CommandWindow, PRM2 p 1280, PRM3 p

%WPCOPY

 CALL WPCOPY(IWHAN,IX1,IY1,IX2,IY2,NX,NY)

 Purpose: Copies a rectangle to a new place in a window

 Parameters:

  IWHAN   - INTEGER handle of window where rectangle is to be copied

  IX1,IY1 - INTEGERs bottom left corner (inclusive) of rectangle to be copied
                     in work area coordinates (IX1 >= 0 >= IY1)

  IX2,IY2 - INTEGERs top right corner (exclusive) of rectangle to be copied
                     in work area coordinates.

  NX,NY   - INTEGERs bottom left corner where the rectangular area is to be
                     copied in work area coordinates.

 Errors: unknown window handle

 Comments: 1) the wimp will copy as much as is possible from the area which
           is visible on the screen. For any invisible parts, it will
           initialise a re-drawing loop to call WQPLOT. Hence:
           2) this routine must NOT be called from WQPLOT or WQUPDT.
           3) uses Wimp_BlockCopy, PRM2 p 1273, PRM3 p

%WPDELI

 CALL WPDELI(IWHAN,ICONH)

 Purpose: Deletes an icon permanently

 Parameters:

   IWHAN  - INTEGER handle of window containing the icon, or
                    -2, or -1 for left or right icon bar

   ICONH  - INTEGER icon handle

 Errors: 1) unknown window handle
         2) unknown icon handle

 Comments: 1) use WPSTIF(IWHAN,ICONH,23,.TRUE.) to close an icon temporarily
           from view
           2) uses Wimp_DeleteIcon, PRM2 p 1189, PRM3 p

%WPDELS

 CALL WPDELS(IWHAN)

 Purpose: deletes a graphics sprite from a window

 Parameter:

   IWHAN  - INTEGER handle of the window for sprite removal

 Errors: none
        (it does nothing if this is not a sprite window set up by WPMAKS)

 Comments: 1) create graphics window sprites with WPMAKS
           2) WPDELW calls WPDELS to remove its sprite
           3) WPQUIT also calls WPDELS for any remaining sprites
              so there should be no sprites left in the system area when the
              application finishes

%WPDELW

 CALL WPDELW(IWHAN)

 Purpose: Deletes a window permanently

 Parameter:

   IWHAN  - INTEGER handle of window to delete; set to zero on return

 Error: unknown window handle

 Comments: 1) you don't have to delete all windows at the end of your job,
           this is done by WPQUIT.
           2) use WPCLSW to close a window temporarily from the screen
           3) if the IWHAN window has panes, these will also be deleted.
           4) uses Wimp_DeleteWindow, PRM2 p 1188, PRM3 p

%WPDRAG

 CALL WPDRAG(IBLOCK)

 Purpose: Initiates a dragging operation

 Parameter:

   IBLOCK - INTEGER array containing information on the box to be dragged
                   1: unused
                   2: drag type (see below)
                 3,4: bottom left corner of original box (OS coordinates)
                 5,6: top right corner         ..
                 7,8: bottom left corner of allowed region to drag (..)
                9,10: top right corner         ..
 
 Error: drag type not in the range [5:7]

 Comments: 1) normal dragging of file icons is done by WPSAVE and WQWFIL.
           2) the allowed drag types are:
              5: rotating dashed box (this is the standard for file drags)
              6: rotating dashed box, but top left is kept fixed while the
                 mouse drags the bottom right corner
              7: no box is indicated
           3) WQDRAG is called when the mouse button is released
           4) use WPDRGI to drag an icon (similar to a file icon drag)
           5) uses Wimp_DragBox PRM2 p , PRM3 3-145

%WPDRAW

 CALL WPDRAW(SNAME)

 Purpose: Sends drawfile SNAME to !Draw

 Parameter:

   SNAME  - CHARACTER name of file to send to !Draw

 Error: unknown or non-text file

 Comments: 1) this is equivalent to double clicking over a drawfile in a
              filer directory window
           3) uses Wimp_SendMessage, PRM2 p 1253, PRM3 p

%WPDRGI

 CALL WPDRGI(IWHAN,ICONH)

 Purpose: Initiates a dragging operation on an icon

 Parameters:

   IWHAN  - INTEGER handle of the window containing the icon

   ICONH  - INTEGER handle of the icon to be dragged
     
 Errors: illegal window/icon handles

 Comments: 1) normal dragging of file icons is done by WPSAVE and WQWFIL.
           3) WQDRAG is called when the mouse button is released
           4) use WPDRAG to drag other areas of a window
           5) uses Wimp_DragBox PRM2 p , PRM3 3-145

%WPEDIT

 CALL WPEDIT(SNAME)

 Purpose: Sends file SNAME to editor

 Parameter:

   SNAME  - CHARACTER name of file to send to the editor

 Error: unknown or non-text file

 Comments: 1) this is equivalent to double clicking over a text file in a
              filer directory window
           3) uses Wimp_SendMessage, PRM2 p 1253, PRM3 p

%WPENDS

 CALL WPENDS(IXL,IYL,IXH,IYH)

 Purpose: ends writing to a window sprite

 parameters:

     IXL  - INTEGER x of the left of the area you have been using and which
                    will be updated on the screen (OS units),
                    or -1 to update the whole window with the sprite
     IYL  - INIEGER y of the bottom of the area (may be omitted if IXL=-1)
  
 IXH,IYH  - INTEGERS x,y coordinates of the top right of the area to update.
                    (May be omitted if IXL=-1)

 No errors

 Comment: 1) nothing happens if WPBEGS has not been called first
          2) used to return to sending data to the screen after WPBEGS has
             directed it to a window sprite and to update an area of the
             window
          3) the coordinate system is in OS units and has the origin in the
             bottom left of the window/sprite (unlike the normal work area
             of a window which has it in the top left).

%WPERR

 CALL WPERR(INFLG,STEXT,LFLG)

 Purpose: Displays a standard error report window

 Parameters:

   INFLG  - INTEGER input flags defining additional features:
              1 for 'OK' box, 2 for 'Cancel', 3 for both
              + 16 to avoid prefix 'Error from' in the title bar
              +128 to trun off the Beep (not RISC OS 2)

   STEXT  - CHARACTER text to display in the window (be brief)

   LFLG   - INTEGER returned showing box clicked: 1 or 2 as for INFLG above.

 Comment: 1) the error window title is the WPINIT text string, and will be
          absent until WPINIT has been called.
          2) if INFLG is not in the range [1:3], 1 will be assumed.
          3) uses Wimp_ReportError, PRM2 p 1243, PRM3 p

%WPFTYP

 CALL WPFTYP(ITYPE)

 Purpose: Defines file type for double-click reading

 Parameter:

   ITYPE  - INTEGER file type to read automatically (1 to 4095)

 Errors: none (an illegal file type does nothing)

 Comments: 1) Files of type ITYPE will be passed to WQRFIL with window
           and icon handles = 0
           2) This does not load the program initially; to do this for
           file type nnn you must put the following in !Boot:
              Set File$Type_nnn Name
              Set Alias$@RunType_nnn <Obey$Dir>.!Run %%*0
           This passes the file name as an argument to !Run so in !Run
           invoke the program with:
              Run <Obey$Dir>.Runimage %*0
           and in the program read the parameter with GTARGS and deal with
           the file name appropriately.

%WPGETP

 CALL WPGETP(IPBLK)

 Purpose: Gets the current wimp colour palette

 Parameter:

   IPBLK  - INTEGER array of 20 words to receive the wimp palette block:
                words 1-16 contain the palettes for colours 0-15
                word 17 contains the border colour palette
                words 18-20 contain the 3 pointer colour palettes
            A palette word is of the form BBGGRRnn (Hex)
            BB, GG & RR are blue, green and red colour intensities,
            'nn' is the logical colour used in WPSETC

 Comment: uses Wimp_ReadPalette, PRM2 p 1251, PRM3 p

%WPGTCP

 CALL WPGTCP(IWHAN,IH,IPOS)

 Purpose: Gets the current caret position within an icon

 Parameters:

  IWHAN  - INTEGER returned handle of window containing the caret
                   (-1 if not in a window)

  IH     - INTEGER returned handle of icon containing the caret
                   (-1 if not in an icon)

  IPOS   - INTEGER returned position of the caret indicating which character
                   it is before in the text of the icon.
                   (undefined if IWHAN or IH are -1)

 Comments: 1) the window and icon may belong to any application, not
           necessarily yours.
           2) use WPSTCP to set the caret position.
           3) uses Wimp_GetCaretPosition, PRM2 p 1225, PRM3 p

%WPGTIF

 CALL WPGTIF(IWHAN,ICONH,INDEX,SET)

 Purpose: Gets the current state of an icon flag

 Parameters:

   IWHAN  - INTEGER handle of window containing the icon
                    (-1 or -2 for icon-bar icon)

   ICONH  - INTEGER icon handle

   INDEX  - INTEGER defines which flag to test
                    The flags are in the range [0:31], useful ones are:
          No.  result when set
           0:  icon has text only
           1:  icon is sprite
           2:  icon has a border
           3:  text centred in the icon
           4:  text centred vertically
           5:  background filled
           8:  icon has indirected text
           9:  text is right justified
          10:  allow multiple ESG selections with 'adjust' button
          11:  display 1/2 sized sprite
          21:  icon is selected
          22:  icon greyed out
          23:  icon is closed

   SET   - LOGICAL returned .TRUE. if flag is set, .FALSE. if flag is clear


 Errors: INDEX value outside range
         unknown window/icon handle

 Comments: 1) SET will be unaltered if there is an accepted error.
           2) use WPSTIF to clear or set a flag.
           3) For a complete list of icon flags and button types,
           see Wimp_CreateIcon, PRM2 p 1180, PRM3 p
           4) uses Wimp_GetIconState, PRM2 p 1213, PRM2 p

%WPGTIL

 CALL WPGTIL(IWHAN,INDEX,LIST,NLIST)

 Purpose: Makes a list of those icons in a window which have a particular
          flag bit set

 Parameters:

  IWHAN   - INTEGER handle of window containing the icons

  INDEX   - INTEGER defines which flag to check. The allowed flags are:
          No.   meaning
          0     text icon
          1     sprite icon
          2     icon has border
          3     contents centred horizontally
          4     contents centred vertically
          5     background is filled
          8     icon has indirected data
          9     text is right justified
         10     multiple ESG selections allowed with 'adjust'
         11     sprite displayed 1/2 size
         21     icon is selected
         22     icon is greyed out
         23     icon is closed

  LIST    - INTEGER array of returned handles of icons with flag set
                    (terminated with -1)

  NLIST   - INTEGER returned number of icons with flag set

 Errors: unknown window handle
         INDEX is outside allowed range

 Comments: 1) the dimension of LIST must be 1 more than the maximum possible
           number of icons which can have the flag set.
           2) uses Wimp_WhichIcon, PRM2 p 1232, PRM3 p

%WPGTIS

 CALL WPGTIS(IWHAN,ICONH,IHBLK)

 Purpose: Gets the current position, size, state and contents of an icon

 Parameters:

   IWHAN  - INTEGER handle of window containing the icon

   ICONH  - INTEGER handle of the icon for investigation

   IHBLK  - INTEGER array of 10 words to receive the returned icon block:
               word    contents 
                1      window handle
                2      icon handle
                3,4    work area coords of bottom left of icon
                5,6    work area coords of top right of icon
                7      icon flag bits (see below)
                8,9,10 icon data (depends on flags, see below)

 Error: illegal window or icon handle, if accepted returns IHBLK(2)=-1

 Comments: 1) the icon flag bits are:
              0     text icon
              1     sprite icon
              2     icon has border
              3     contents centred horizontally
              4     contents centred vertically
              5     background is filled
              6     text is in anti-aliased font
              8     icon has indirected data
              9     text is right justified
             10     multiple ESG selections allowed with 'adjust'
             11     sprite displayed 1/2 size
             12-15  icon button type (0 to 15, see e.g. WPCHTF)
             16-20  ESG in range 0 to 31 (see e.g. WPCHTF)
             21     icon is selected
             22     icon is greyed out
             23     icon is closed
             24-27  foreground colour (if bit 6 is not set)
             28-31  background colour (if bit 6 is not set)
          or 24-31  font handle (if bit 6 is set)

          2) the icon data words depend on the flag bits e.g.
           a)For an indirected text icon (bits 0 and 8 set) they contain
             pointers to the text buffer and validation string and length of
             the text buffer.
           b)For an ordinary text icon (bit 0 set, bit 8 clear) they contain
             the text.
           c)For a sprite icon (bit 1 set, bit 8 clear) they contain the
             sprite name.
          3) uses Wimp_GetIconState, PRM2 p 1213, PRM3 p


%WPGTMF

 CALL WPGTMF(NFLAG,MBLOC,INDEX,SET)

 Purpose: Gets a menu item flag

 Parameters:

   NFLAG  - INTEGER which flag
                    0: display a tick before the item
                    1: there is a dotted line after this item
                    2: the item will be greyed out and not selectable
                    3: WQMWRN will be called when moving to its submenu

   MBLOC  - INTEGER array, menu block set up by WPMKMB

   INDEX  - INTEGER index of item in menu (starting from zero at the top)

   SET    - LOGICAL returned .TRUE. if flag is set, .FALSE. if not

 Error: 1) INDEX out of range
        2) NFLAG out of range

 Comments: 1) see WPMKMB for how to set up a menu
           2) use WPSTMF to set a menu item flag.
           3) SET will remain unchanged if 'OK' is clicked for an error.

%WPGTMS

 CALL WPGTMS(ITEMS,NMENU)

 Purpose: Gets state of a menu tree

 Parameters:

   ITEMS  - INTEGER array (must be 1 longer than the longest tree)
                    returns one integer for each level of the menu showing
                    which item has been selected at this level. Items are
                    numbered from zero at the top.

   NMENU  - INTEGER Returned the last level of the tree selected.

 Comments: 1) uses Wimp_GetMenuState PRM3 3-222

%WPGTPI

 CALL WPGTPI(IWHAN,IH,IX,IY,IBUT)

 Purpose: Gets mouse pointer information

 Parameters:

  IWHAN  - INTEGER returned handle of window containing the mouse pointer
                   (-1 if background, -2 if over icon bar)
  IH     - INTEGER returned handle of icon containing the mouse pointer
                   (undefined if IWHAN = -1). If IWHAN >= 0, then
                   >=0 means the pointer is over this icon
                   -1: over work area
                   -2: over 'back' icon
                   -3: over 'close' icon
                   -4: over 'title bar' icon
                   -5: over 'toggle size' icon
                   -6: over 'scroll up' icon
                   -7: over 'vertical scroll bar' icon
                   -8: over 'scroll down' icon
                   -9: over 'adjust size' icon
                  -10: over 'scroll left' icon
                  -11: over 'horizontal scroll bar' icon
                  -12: over 'scroll right' icon
                  -13: over the outer window frame

  IX,IY  - INTEGERs returned OS screen coordinates of the pointer.

  IBUT   - INTEGER returned buttons pressed:
                   1: adjust, 2: menu, 4: select

 Comments: 1) the window may not be one of yours.
           2) the information returned was collected at the time your WQxxxx
           routine was called, not at the current time. Use MOUSE from
           the utils library to find the current position, but then you won't
           know which window it is over.
           3) use WPXY2W to transform the coordinates to the window work area
           system.
           4) uses Wimp_GetPointerInfo, PRM2 p 1214, PRM3 p

%WPGTSS

 CALL WPGTSS(NCSIZ,NNSIZ,NFPOOL)

 Purpose: Gets the current and next application memory slot sizes and also
          the size of the free memory pool

 Parameters:

  NCSIZ  - INTEGER returned size of the current application's memory slot

  NNSIZ  - INTEGER returned size of the next application's memory slot

  NFPOOL - INTEGER returned size of the free memory pool

 Comments: 1) all sizes are in bytes
           2) uses Wimp_SlotSize, PRM2 p 1275, PRM3 p

%WPGTTH

 CALL WPGTTH(NAME,IHAND)

 Purpose: to find the task handle of NAME

 Parameters:

  NAME   - CHARACTER the name of the task for which the handle
                     is requested. This is case sensitive and must
                     not have any trailing blanks

  IHAND  - INTEGER   returned task handle or zero if it does not
                     exist

 Comments: uses TaskManager_EnumerateTasks , PRM3 3-315

  Example:

C       see if 'MyProg' is already running
      CALL WPGTTH('MyProg',ICH)
C       if it is, quit right now!
      IF(ICH.NE.0) STOP
C       initiate MyProg
      CALL WPINIT('MyProg')
  etc.

%WPGTWO

 CALL WPGTWO(IWHAN,IX1,IY1,IX2,IY2)

 Purpose: Gets window outline position on the screen

 Parameters:

  IWHAN   - INTEGER handle of window to get outline coordinates

  IX1,IY1 - INTEGERs returned screen coordinates of the bottom left of the
                     window outline (inclusive)

  IX2,IY2 - INTEGERs returned screen coordinates of the top right of the
                     window outline (exclusive)

 Errors: unknown window handle

 Comments: 1) the window outline includes the scroll bars and title, unlike the
           visible area returned by WPGTWS.
           2) uses Wimp_GetWindowOutline, PRM2 p 1245, PRM3 p

%WPGTWS

 CALL WPGTWS(IWHAN,IWBLK)

 Purpose: Gets the current position, size and state of a window

 Parameters:

   IWHAN  - INTEGER handle of window for investigation

   IWBLK  - INTEGER array of 9 words to receive the returned window block:
               word  contents                        comment
                1    window handle
                2,3  OS screen coords of bottom left
                4,5  OS screen coords of top right
                6    x-scroll offset from left       positive or zero
                7    y-scroll offset from top        negative or zero
                8    handle of the window in front   -1 for top
                9    window flags                    see below
             useful window flags are:
          bit  result when set               comment
           1:  window is moveable
           4:  no user drawing required      WQPLOT not called if set
           6:  can be dragged off screen
           8:  scroll requests               see WQSCRL
           9:  as 8, but no auto-repeat
          12:  report 'hot-key' presses      see WQKEYP
          16:  window is open for viewing
          17:  window is all visible
          18:  window toggled to full size
          20:  window has input focus
          24:  window has Back Icon
          25:  window has Close Icon
          26:  window has Title Bar
          27:  window has Toggle-size Icon
          28:  window has vertical scroll
          29:  window has Adjust-size Icon
          30:  window has horizontal scroll

 Error: window handle not found

 Comments: 1) window flags are stored as bits in this word, flag 0 being
           stored in the least significant bit.
           2) uses Wimp_GetWindowState, PRM2 p 1209, PRM3 p

%WPINIT

 CALL WPINIT(SNAM)

 Purpose: Introduces the program to the wimp manager

 Parameter:

   SNAM   - CHARACTER brief title for the program (< 20 characters)

 Comments: 1) the title will be truncated to 19 characters
           2) uses Wimp_Initialise, PRM2 p 1173, PRM3 p

%WPKEYP

 CALL WPKEYP(KEY)

 Purpose: Passes on to other users an unwanted key-press (see WQKEYP)

 Parameter:

   KEY    - INTEGER ASCII value of unwanted key

 Comment: 1) this should normally only be called from WQKEYP (q.v.)
            but you may send characters to an editor using it.
          2) uses Wimp_ProcessKey, PRM2 p 1240, PRM 3 p

%WPHNDL

 CALL WPHNDL(IHAND)

 Purpose: returns the task's handle

 Parameter:

   IHAND    - INTEGER returned task handle

%WPLDTW

 CALL WPLDTW(SNAME,IBUF,SIND,IWHAN)

 Purpose: Loads a window from the current template file

 Parameters:

   SNAME  - CHARACTER name of window as defined by FormEd
                      (not the title displayed in the window)

   IBUF   - INTEGER array, temporary window definition workspace, length:
                    ( 91 + 32*(number of icons) + LEN(SIND) )/4 words

   SIND   - CHARACTER string to receive indirected icon and title data.
                    The length should be the sum of the maximum lengths
                    of all these data. It is best stored in COMMON
                    to ensure that it is in fixed writable memory.

   IWHAN  - INTEGER returned window handle (-1 for an accepted error)

 Errors: 1) window name not found
         2) SIND not big enough

Comments: 1) SIND must be a different string for each window. It is
          possible, but dangerous, to work out where each icon string is
          stored in it and hence to alter the text. Much better is to use
          WPRDTX and WPRDIN
          2) call WPOPNT and WPCLST to open and close the template file
          3) call WPCHSA to change the sprite area of sprite icons 
          3) uses Wimp_LoadTemplate, PRM2 p 1238, PRM3 p
              and Wimp_CreateWindow, PRM2 p 1174, PRM3 p

%WPLOOP

 CALL WPLOOP(MASK)

 Purpose: Starts the wimp polling loop.
         This is central to a wimp program, the wimp poll responds to the
         mouse and keyboard, calling the WQxxxx routines accordingly. It
         does not return until WPQUIT is called when the program leaves the
         wimp environment.

 Parameter:

   MASK   - INTEGER controls which of the WQxxxx functions are not activated.
                    It is a word of bits:
                    bit   value  deactivation
                     0      1      WQNULL
                     1      2      WQPLOT
                     4     16      WQPTWW(IWHAN,.FALSE.)
                     5     32      WQPTWW(IWHAN,.TRUE.)
                     6     64      WQCLIK
                     8    256      WQKEYP
                    11   2048      WQLGCT(.FALSE.,IBLOC)
                    12   4096      WQLGCT(.TRUE.,IBLOC)
                    17 131072      WQMESG(-1, etc.)
                    18 262144      WQMESG( 0, etc.)
                    19 524288      WQMESG( 1, etc.)

 Comments: 1) the reason for deactivating functions is to save time, and
           improve the wimp response for all tasks. It is most important to
           set bit zero (any odd number for MASK), otherwise the wimp will
           call WQNULL every time it cycles the tasks.
           2) setting bits 17, 18 and 19 will stop the dragging of file names
           and notices to quit, so they should be left unset.
           3) bits 1, 6 and 8 should also not be set unless you really want
           to delay knowing what is going on outside.
           4) bits 4,5, 11 and 12 save very little time and are not worth
           setting.
           5) so it is really best to stick to 0 or 1 for MASK!
           6) put MASK in COMMON, so that you can turn WQNULL off and on
           from the WQxxxx routines - this is perfectly legal.
           7) uses Wimp_Poll, PRM2 p 1192, PRM3 p

%WPMAKS

 CALL WPMAKS(IWHAN,NX,NY,MODE)

 Purpose: to create a sprite in a window for simple text and graphics

 Parameters:

   IWHAN  - INTEGER handle of window to receive the sprite

   NX,NY  - INTEGER x- and y-dimensions of the sprite in OS units
                    but see comment 1.

    MODE  - INTEGER graphics mode for the sprite 
                    or -1 for the current mode

 Errors: unknown window handle
         too many sprite windows (>8)
         window must have redraw requests (window flag 4 FALSE)
         illegal mode
         not enough memory

 Comments: 1) The sprite is created with its natural dimensions for the
              requested mode. Normally one would choose the sprite size the
              same as the window size but this will not always give the
              desired effect.
                 For example, with a desktop mode of 20, asking for a sprite
              in mode 15 will result in only the bottom half of the window
              being filled. This is because the mode 15 sprite's pixels
              would normally cover 4 OS units in the y direction while the
              mode 20 screen has 2 OS units per pixel. 
                 Use GRMMV(I,J) to find the power of 2 between the screen
              (I=-1) and the sprite (I=MODE) where J=4,5 for x,y.

%WPMESG

 SUBROUTINE  WPMESG(MTYPE,MTO,MREF,MACT,MESG)

 Purpose: Sends a coded message to other wimp tasks running in the desktop

 Parameters:

   MTYPE  - INTEGER type of message
               =-1: this message does not need to be acknowleged
               = 0: this message must be acknowleged
               =+1: this is an acknowledgement

   MTO    - INTEGER handle of task to which the message is addressed
                    =0 for broadcast to all tasks

   MREF   - INTEGER reference number for message
                   =0 if this is an original message (not a reply)

   MACT   - INTEGER action code; many of these are used by RISC-OS
                    and must be avoided for personal messages between
                    your tasks. Up to RISC-OS 3, numbers between
                    256 and 1023 have not been used by the system.

   MESG   - CHARACTER message data (not longer than 236 characters)
                      this will always be expanded to a multiple of 4 long,
                      unused locations being filled with CHAR(0)
                      data will be truncated to 236 bytes/characters

 Errors: MTYPE illegal (nothing sent)

 Comments: 1) you can use this routine to send messages to any other task
              running under RISC-OS.
           2) the messages used for receiving and saving files to a filer
              task are already processed automatically by the Fortran Wimp
              system.
           3) for the RISC-OS message types, see the write-up of:
              Wimp_SendMessage, PRM2 p 1253, PRM3 3-320

 Example: this shows how two tasks can correspond
      PROGRAM TASK1
      CALL WPINIT( etc.
        .....
C          send a message to wake up my other task
C          must broadcast it since we do not know the other's handle
      CALL WPMESG(0,0,0,256,'Wake up!')
        .....
      SUBROUTINE WQMESG(MTYPE,MFROM,MREF,MREP,MACT,MESG)
C          check that this is not because my 'Wake up!' message was not
C          acknowledged
      IF(MTYPE.EQ.1 .AND. MACT.EQ.256) THEN
C          no response from other task here
         .....
      END

      PROGRAM TASK2
      CALL WPINIT( etc.
         .....
      SUBROUTINE WQMESG(MTYPE,MFROM,MREF,MREP,MACT,MESG)
      CHARACTER*(*) MESG
C         is this a 'Wake up' message for me?
      IF(MTYPE.EQ.0 .AND. MACT.EQ.256 .AND. MESG(1:7).EQ.'Wake up') THEN
C         yes, first must acknowledge this message because
C         it is definitely mine and has type 0
        CALL WPMESG(1,MFROM,MREF,MACT,MESG)
C         now I am awake and can do my thing...
         .....
      ENDIF
      RETURN
      END

%WPMKMB

 CALL WPMKMB(SDATA,MBLOC)

 Purpose: Makes a menu block from the text items

 Parameters:

   SDATA  - CHARACTER the title, followed by text of the menu items
                    ordered from top to bottom, separated by commas.
                    The items must not be longer than 12 characters each.
                    A menu item beginning with '_' is underlined and
                    the '_' is discarded

   MBLOC  - INTEGER array to receive the returned menu block.
                    This is {7 + 6*(number of menu items)} words long,
                    and should be stored in permanent writable memory,
                    preferably in COMMON.

 Errors: 1) title or menu item longer than 12 characters.
         2) no menu items

 Comments: 1) this makes a menu block of the type referenced by WPAM2M,
           WPAW2M, WPBARI and WPSHWM.
           2) set menu flags with WPSTMF
           3) make menu trees with WPAM2M and WPAW2M
           4) no check is made that MBLOC is long enough, so be careful when
           you change the program to add additional items to a menu that you
           also increase the array size.

%WPMKNW

 CALL WPMKNW(IWX,IWY,JWX,JWY,JSX,JSY,KSX,KSY,STITL,IWHAN)

 Purpose: Makes a new window

 Parameters:

   IWX,IWY- INTEGER size of the work area in OS units. This is the whole
                    area. The amount displayed may be less and is:

   JWX,JWY- INTEGER position of the bottom left corner of the window display
                     on the screen.

   JSX,JSY- INTEGER dimensions of visible part of the window
                     4 < JSX <= IWX, 4 < JSY <= IWY

   KSX    - INTEGER scroll offset in x: 0 to display the left hand edge
                     of the work area, satisfying: 0 <= KSX <= IWX-JSX

   KSY    - INTEGER scroll offset in y: 0 to display the top edge of the
                    work area, satisfying: 0 >= KSY >= JSY-IWY
                    KSY is negative to scroll down.

   STITL  - CHARACTER window title (null terminated), e.g. 'Title'//CHAR(0)
                    It must be stored in permanent memory,
                    preferably in COMMON.

   IWHAN  - INTEGER returned window handle (-1 for an accepted error)

 Errors: 1) work area is not positive
         2) screen window bigger than work area
         3) scroll offsets illegal

 Comments: 1) all dimensions are in OS graphics units
           2) the values for the size of the work area should both be
           positive, despite the fact that when y is used it is measured
           from the top and is hence not positive.
           3) use WPCHWC to change the colours of the window parts.
           4) use WPCHWF to change the window flags. Window flags
           determine such things as whether there are scroll bars.
           5) call WPCHSA if you want to make sprite icons from a user
           sprite area
           6) use WPMNWS to change the minimum size of the window; default
           is the size of the title
           7) if you have !FormEd, it is probably easier to make a template
           file and use WPOPNT, WPLDTW and WPCLST to make windows.
           8) this routine does not display the window on the screen,
           use WPOPNW afterwards to see it.
           9) uses Wimp_CreateWindow, PRM2 p 1174, PRM3 p

%WPMNWS

 CALL WPMNWS(IXMIN,IYMIN)

 Purpose: to change the minimum size of a window created with WPMKNW

 Parameters:

   IXMIN - minimum x window size in OS units

   IYMIN - minimum y window size in OS units

 Comments: 1) the default is (0,0) which means the width of the window title
           2) the values must be between 0 and 65535 otherise 0 is assumed

%WPNULT

 CALL WPNULT(ITIME)

 Purpose: determines how often WQNULL is called

 Parameter:

   ITIME  - INTEGER time in centi-seconds between calls to WQNULL
                ITIME = 0 or less means call it as often as possible

 Comments: 1) the default time is 0 if WPNULT is not called.
           2) ITIME>0 uses Wimp_PollIdle (PRM2 p 1246, PRM3 p     )
           to do the polling of the wimp


%WPOPNT

 CALL WPOPNT(SFILE)

 Purpose: Opens the window template file

 Parameter:

   SFILE  - CHARACTER name of file to open

 Errors: 1) file does not exist or is not a template file
         2) attempt to open two template files concurrently

 Comments: 1) use WPLDTW to extract the window definitions from the file,
           and WPCLST to close it.
           2) uses Wimp_OpenTemplate, PRM2 p 1236, PRM3 p

%WPOPNW

 CALL WPOPNW(IWHAN)

 Purpose: Opens a window for viewing

 Parameters:

   IWHAN  - INTEGER handle of window to open

 Error: unknown window handle

 Comments: 1) this will display the window with the same shape and position
              as where it was closed (WPCLSW), or created (WPMKNW, WPLDTW).
              Use WPGTWS and WPSTWS if you want to change its
              characteristics from your program.
           2) if the window is a pane it will be made active, but will not
              appear on the screen unless/until the host is open.
           3) if the window is host to previously activated panes, these
              will also be opened.
           4) uses Wimp_GetWindowState, PRM2 p 1209, PRM3 p
               and Wimp_OpenWindow, PRM2 p 1190, PRM3 p

%WPOPTX

 CALL WPOPTX(STITL)

 Purpose: Opens a simple window which can be used for printing text

 Parameter:

  STITL  - CHARACTER short title for window

 Comments: 1) this is the window which opens in the middle of the screen
           which you get with non-wimp programs; it could be useful for
           debugging.
           2) change the colour of the text with WPSTTC
           3) close the window with WPCLTX
           4) you should not call WPERR to display errors while this text
              window is open
           5) uses Wimp_CommandWindow, PRM2 p 1280, PRM3 p

%WPPANE

 CALLWPPANE(IWPANE,IWHOST,SIDE)

 Purpose: attaches a tool pane to a host window

 Parameters:

  IWPANE - INTEGER handle of the pane window to attach

  IWHOST - INTEGER handle of the host window to attach it to
                  (-1 to detach the pane)

  SIDE   - CHARACTER the first letter defines which side to attach it to:
                     'T' : top
                     'B' : bottom
                     'L' : left side
                     'R' : right side
                     (not needed if IWHOST = -1)

 Errors: 1) unknown pane handle
         2) unknown host handle
         3) pane already attached to a window
         4) pane not yet attached (IWHOST=-1)
         5) unknown side definition
         6) more than 7 panes requested
         7) more than 1 pane on a host's side
         8) pane is already a host
         9) host is already a pane

 Comments: 1) an attached pane will initially be 'inactive',
              i.e. it will not be displayed when the host is displayed.
           2) CALL WPOPNW(IWPANE) will display the pane when the host is
              displayed (active pane)
           3) CALL WPCLSW(IWPANE) will stop the pane being displayed though
              it will remain attached (inactive pane)
           4) CALL WPDELW(IWHOST) will delete all the panes attached to the
              host as well as the host itself.
           5) a maximum of 7 panes is allowed
           6) Panes should normally be created without any border icons
              (title, scroll bars etc.) Call WPCHWF(I,.FALSE.) with I=24,30
              before creating the window with WPMKNW

%WPPICC

 CALL WPPICC(IX,IY,TITLE,IRED,IGREEN,IBLUE)

 Purpose: Asks the Colour-picker for a user colour

 Parameters:

    IX,IY - INTEGERs where to put the Colour Picker window
                     (top left)

    TITLE - CHARACTER title for the Colour Picker window
                      (limited to 39 characters)

     IRED - INTEGER input and returned amount of red colour
                    in the range [0:255] or
                    -1 if colour 'None' is specified
                    -2 returned if user clicks on 'Cancel'

   IGREEN - INTEGER as IRED but for green colour component

    IBLUE - INTEGER as IRED but for blue colour component

 Error: Colour-picker module not loaded

 Comments: 1)Requires the colour-picker module to be loaded.
           2)This subroutine removes control from your program until the
           user has selected a colour or clicked on 'Cancel'. Thus mouse
           clicks and key presses will not be seen by your program while
           the Colour-picker window is open.
           Your program may be requested to redraw windows during the
           Colour-picker dialogue but this should not cause any problem.

%WPPLOT

 CALL WPPLOT(IWHAN,IXL,IYL,IXH,IYH)

 Purpose: Asks the wimp to start a drawing sequence for a window

 Parameters:

   IWHAN  - INTEGER handle of window containing the icon, or

   IXL,IYL- INTEGER coordinates of the bottom left corner of the area to
                    draw in the window work area.
                    If IXL < 0, all the window will be redrawn, and no
                    other parameters need be supplied.
   IXH,IYH- INTEGER coordinates of the top right corner of the area to
                    draw in the window work area.

 Error: unknown window handle

 Comments: 1) coordinates are measured from the top left of the work area,
           so: y <= 0 <= x
           2) although it is easier to request that the whole window is
           drawn, it is faster to request only the piece you really want.
           3) after you return to the wimp (from your WQxxxx routine), it
           will clear your area to the background colour and call WQPLOT
           for you to draw it again.
           4) use WPUPDT if you want to repair an area of the window quickly
           without having it cleared.
           5) uses Wimp_ForceRedraw, PRM2 p 1221, PRM3 p

%WPPREQ

 CALL WPPREQ

 Purpose: Continues the wimp shut down sequence after an intervention
          from WQPREQ

 No Parameter:

 Comment: 1) this should only be called after a shutdown intervention.
             see WQPREQ(IOK)

%WPQUIT

 CALL WPQUIT

 Purpose: Closes down the wimp connection for this task,
          deleting all windows.

 No parameters

 Error: called before WPINIT

 Comments: 1) if you are inside the Wimp poll loop (q.v. WPLOOP) and hence
           call WPQUIT from a WQxxxx routine, the call to WPQUIT will send
           a flag to WPLOOP telling it to leave the wimp and return.
           2) if you have not yet called WPLOOP, then the routine will close
           the connection to the wimp itself.
           3) uses Wimp_CloseDown, PRM2 p 1241, PRM3 p
%WPRDIN

 CALL WPRDIN(IWH,IH,INT,IERR)

 Purpose: reads an integer from an indirected text icon

 Parameters:

   IWH    - INTEGER handle of the window containing the icon

   IH     - INTEGER handle of the icon containing the ASCII integer
                    or -1 for title icon

   INT    - INTEGER returned value extracted from the ASCII

   IERR   - INTEGER returned error
                  0: INT read OK
                 +1: ASCII contains non-numeric data not preceeded by + or -
                 +2: integer is too big.
                 -1: icon or window handle is illegal 
                 -2: icon does not contain indirected text

 Errors: Illegal icon or window handle
         Icon (?) does not contain indirected text

 Comment:  blanks will be ignored before the integer but the first blank
           after a digit will terminate the translation.


%WPRDTX

 CALL WPRDTX(IWH,IH,STRING,LEN)

 Purpose: reads a text string from an indirected text icon

 Parameters:

   IWH    - INTEGER handle of the window containing the icon

   IH     - INTEGER handle of the icon containing the ASCII text
                    or -1 for title icon

   STRING - CHARACTER returned ASCII string from the text icon. It is
                      truncated or blank filled if it is smaller or bigger
                      than the text in the icon.

   LEN    - INTEGER returned error
                >=0: length of the string returned
                 -1: icon or window handle is illegal 
                 -2: icon does not contain indirected text

 Errors: Illegal icon or window handle
         Icon (?) does not contain indirected text

%WPSAVE

 CALL WPSAVE(SFTYP,ISIZE,SFNAM,IWHAN)

 Purpose: Makes a 'save' window with a filer icon for dragging files.

 Parameters:

   SFTYP  - CHARACTER*3 file type
                    e.g. 'FFF' for a text file, 'FFD' for data;
                    a special case is '000' for 'saving' a directory.
                   (letters can be in upper or lower case)

   ISIZE  - INTEGER a guess at the size (in bytes) of file you may wish
                    to write

   SFNAM  - CHARACTER to receive the file name. This should be long enough to
                      hold the complete name: 'filer::disc.path.leaf'.
                      It must be in permanent writable memory, preferably
                      in COMMON. You might like to put in some default name.

   IWHAN  - INTEGER returned window handle

 Errors: 1) if SFNAM is too small, you will get an error message when the
            file is about to be written.
         2) too many 'save' windows.
         3) filer icon for SFTYP not found.

 Comments: 1) a maximum of 16 save windows is allowed
           2) WQWFIL tells you the handle of the 'save' window used for
           dragging at the time you are asked to write the file; this is the
           only way you will know what file is needed, so it is best to have
           a 'save' window for each of your saving needs.
           3) when you drag a file, the complete filename is stored in
           SFNAM, and will be displayed in the file name icon in the 'save'
           window next time you use it. Hence it is inadvisable to use the
           same SFNAM for many 'save' windows because of the possibility of
           saving to the wrong place.
           4) a 'null' terminated string will be stored in SFNAM, so try to
           leave it alone.
           5) uses Wimp_CreateWindow, PRM2 p 1174, PRM3 p
               and Wimp_SpriteOp, PRM2 p1271, PRM3 p

%WPSETC

 CALL WPSETC(IACT,KOLOUR)

 Purpose: Sets the colour for plotting or printing in a window

 Parameters:

   IACT   - INTEGER plot action. Allowed values are:
                   0: overwrite colour on screen
                   1: 'OR' with colours on screen
                   2: 'AND' with colours on screen
                   3: 'EOR' with colours on screen
                   4: invert colour on screen
                   5: do nothing
                   6: 'AND' with the colour on screen the 'NOT' of the data
                   7: 'OR' with the colour on screen the 'NOT' of the data

   KOLOUR - INTEGER new colour for plotting or printing.
                   normal colours are:
               0 - 7  white to black grey scale
               8: dark blue    9: yellow      10: green    11: red
              12: cream       13: dark green  14: orange   15: light blue
                   add 128 to define the background colour

 Errors: IACT or KOLOUR out of range

 Comments: 1) the wimp uses 16 colours however many are available in the
           screen mode; this command makes the best approximation for the
           mode.
           2) use WPGETP and WPSETP to change the actual colours, but this
           will change the colour for all the desktop.
           3) if you want 256 colours in a 256-colour screen mode, you may
           use the graphics library routines to set the graphics colour,
           but this will make your code mode dependent.
           3) uses Wimp_SetColour, PRM2 p 1252, PRM3 p

%WPSETP

 CALL WPSETP(IPBLK)

 Purpose: Sets the current wimp colour palette

 Parameter:

   IPBLK  - INTEGER array of the 20 word wimp palette block:
                words 1-16 contain the palettes for colours 0-15
                word 17 contains the border colour palette
                words 18-20 contain the 3 pointer colour palettes
            A palette word is of the form BBGGRRnn (Hex)
            BB, GG & RR are blue, green and red colour intensities, 
            and the byte nn is set to zero within WPSETP.

 Comment: 1) changing the palette should be avoided. It interferes with
          other wimp programs.
          2) it is easiest to read the current palette block with WPGETP
          and change only the required parts.
          3) uses Wimp_SetPalette, PRM2 p 1250, PRM3 p

%WPSHWM

 CALL WPSHWM(MBLOC,IX,IY)

 Purpose: displays the first column of a menu

 Parameters:

   MBLOC  - INTEGER array containing the menu block for display.
                    (or -1 to close all menus)

   IX,IY  - INTEGER OS screen coordinates of the top left corner.
                    (not needed if MBLOC = -1)

 Comments: 1) menu blocks are made with WPMKMB
           2) you may want to relate the position of the menu to a window,
           if so, call WPGTWS to find out where the window is.
           3) WPSHWM is called automatically from WPLOOP when there is a
           'menu' click over an icon on the icon bar set up with WPBARI,
           provided you supplied WPBARI with a menu block.
           4) uses Wimp_CreateMenu, PRM2 p 1226, PRM3 p

%WPSTCP

 CALL WPSTCP(IWHAN,IH,IPOS)

 Purpose: Sets the caret to a position in a writeable icon.

 Parameters:

  IWHAN  - INTEGER handle of window to receive the caret
                   (-1 to disown the caret and remove input focus)

  IH     - INTEGER handle of the icon to receive the caret
                   (not required if IWHAN=-1)
                   (-1 if not in an icon)

  IPOS   - INTEGER character number where the caret is to be put
                   (not required if IWHAN=-1)
                   (-1 to make it invisible)

 Errors: unknown window handle
         unknown or illegal icon handle
         illegal position (? what happens ?)

 Comments: 1) find the caret position using WPGTCP.
           2) uses Wimp_SetCaretPosition, PRM2 p 1223, PRM3 p
%WPSTIC

 CALL WPSTIC(IWHAN,ICONH,KOLOUR)

 Purpose: Changes an icon's colour

 Parameters:

   IWHAN  - INTEGER handle of window containing the icon

   ICONH  - INTEGER icon handle

   KOLOUR - INTEGER new wimp colour for the icon in range 0 to 15
                   normal colours are:
               0 - 7  white to black grey scale
               8: dark blue    9: yellow      10: green    11: red
              12: cream       13: dark green  14: orange   15: light blue
                   add 128 to define the background colour
 Errors: illegal window/icon handle
         illegal colour number
         icon text is in an anti-aliased font

 Comments: 1) Use WPGTIS to find the colours of an icon
           2) uses Wimp_SetIconState, PRM2 p 1211, PRM3 p

%WPSTIF

 CALL WPSTIF(IWHAN,ICONH,INDEX,SET)

 Purpose: Clears or sets an icon flag

 Parameters:

   IWHAN  - INTEGER handle of window containing the icon
                    (-1 or -2 for icon-bar icon)

   ICONH  - INTEGER icon handle

   INDEX  - INTEGER defines which flag to change
                    The usual flags are in the range [0:31], allowed ones are:
          No.  result when set
           2:  icon has a border
           3:  text centred in the icon
           4:  text centred vertically
           5:  background filled
           9:  text is right justified
          10:  allow multiple ESG select  (see comment 2)
          11:  plot 1/2 sized sprite
          21:  selects the icon
          22:  greys the icon
          23:  closes the icon
       200+n:  set the ESG to n [0:31]
       100+n:  set the button type to n [0:15]
                     some useful button types are:
            n=0: ignore button clicks
              2: click notifies task (auto-repeat)
              3: click notifies task
              5: click selects, double-click notifies task
              9: 'menu' type, pointer over icon selects, click notifies task
                 (needs at least two icons in an ESG)
             11: click selects, and returns button state (default)
             15: writable icon

   SET    - LOGICAL .TRUE. to set the flag, .FALSE. to clear it
               SET is not used if INDEX > 23

 Errors: INDEX value not allowed
         unknown window/icon handle

 Comments: 1) use WPGTIF to find the value of a flag
           2) use WPCHSF and WPCHTF to change the default flags before
           creating a sprite
           3) The selection of a set of icons can be made mutually exclusive
           by putting them in a Exclusive Selection Group (ESG). The default
           ESG value of 0 means there is no exclusion. If flag 10 is set,
           then clicking with the 'adjust' button overrides the exclusion,
           like selecting files in a filer directory window.
           4) For a complete list of icon flags and button types,
           see Wimp_CreateIcon, PRM2 p 1180, PRM3 p
           5) uses Wimp_SetIconState, PRM2 p 1211, PRM3 p

%WPSTMD

 CALL WPSTMD(MODE)

 Purpose: Sets the desktop screen mode

 Parameters:

  MODE   - INTEGER new desktop screen mode

 Comments: 1) you should avoid doing this if at all possible, and certainly
           not before giving a warning message and getting the 'OK'.
           Programs ought to be able to run in any screen mode, but
           sometimes you may require more colours than are available in the
           current mode.
           2) uses Wimp_SetMode, PRM2 p 1249, PRM3 p

%WPSTMF

 CALL WPSTMF(NFLAG,MBLOC,INDEX,SET)

 Purpose: Changes a menu item flag

 Parameters:

   NFLAG  - INTEGER which flag
                    0: display a tick before the item
                    1: put a dotted line after the item
                    2: the item will be greyed out and not selectable
                    3: WQMWRN will be called when moving to its submenu
                       (on by default)

   MBLOC  - INTEGER array, menu block set up by WPMKMB

   INDEX  - INTEGER index of item in menu (starting from zero at the top)

   SET    - LOGICAL  .TRUE. to set the flag, .FALSE. to clear it

 Errors: INDEX or NFLAG out of range

 Comments: 1) see WPMKMB for how to set up a menu
           2) use WPGTMF to find the state of a menu flag
           2) see WQMWRN for how to change menus dynamically
           3) nothing will happen if INDEX or NFLAG are out of bounds

%WPSTNS

 CALL WPSTNS(NSIZE)

 Purpose: Sets memory available for the next application

 Parameters:

  NSIZE  - INTEGER requested memory (in bytes) for the next application

 Comments: 1) the memory request will be rounded up to a memory page size,
           i.e. 32K, 16K or 8K etc. depending on the implementation.
           2) there may not be enough memory available; use WPGTSS to find out
           how much has been granted.
           3) uses Wimp_SlotSize, PRM2 p 1275, PRM3 p

%WPSTTC

 CALL WPSTTC(ICOL)

 Purpose: Sets text colour in a special text window

 Parameters:

  ICOL   - INTEGER text colour in the range [0:15]
                   add 128 to change the background colour

 Error: colour not in the ranges [0:15], [128:143]

 Comments: 1) this special window is opened with WPOPTX, closed with WPCLTX.
           2) uses Wimp_TextColour, PRM2 p 1282, PRM3 p

%WPSTIS

 CALL WPSTIS(IWHAN,ICONH,IWX,IWY,ISX,ISY)

 Purpose: changes the position and size of an icon (RISC-OS 3.5 or more)

 Parameters:

   IWHAN  - INTEGER handle of the window for the icon

   IWX,IWY - INTEGERs position in the window for the icon, measured
                      in OS units from the top left corner of the work area
                      to the bottom left corner of the icon.
                      (IWY <= 0 <= IWX)

   ISX     - INTEGER length of icon in OS units,
                     (use WPTXTW to get minimum width of a text icon)

   ISY     - INTEGER height of icon in OS units (often 48)

 Error: nothing happens if used in RISC-OS version less than 3.5
        or the icon or wimp handles are illegal

 Comment: Uses Wimp_Resizeicon PRM3 5-217.


%WPSTWA

 CALL WPSTWA(IWHAN,IXSIZ,IYSIZ)

 Purpose: Sets the work area size associated to a window

 Parameters:

  IWHAN  - INTEGER handle of window for size change

  IXSIZ  - INTEGER new x-dimension of work area (>0)

  IYSIZ  - INTEGER new y-dimension of work area (>0)

 Errors: unknown window handle

 Comments: 1) no check is made that the new work area is big enough for the
           window on the screen. Most likely you will be increasing the work
           area size, so this will not cause a problem.
           2) uses Wimp_SetExtent, PRM2 p 1233, PRM3 p

%WPSTWS

 CALL WPSTWS(IWBLK)

 Purpose: Sets a window's state or size.

 Parameter:

   IWBLK  - INTEGER 8-word array window block, obtained with WPGTWS
               word  contents                     comment
                1    window handle                leave this alone
                2,3  OS screen coords of bottom left
                4,5  OS screen coords of top right
                6    x-scroll offset from left    positive or zero
                7    y-scroll offset from top     negative or zero
                8    window heap position         -1 for top, -2 for bottom

 Error: unknown window handle

 Comments: 1) Use WPGTWS to get the current window block of 9 words.
           2) To change a window's position and/or size on the screen,
           change words 2 to 5; to scroll it, change words 6 & 7; to move it
           to the top or bottom of the heap of displayed windows, change
           word 8.
           3) if the window is a pane it will be made active, but will not
           appear on the screen unless/until the host is open. The
           position can not be altered since it is attached to a host;
           Its size can be changed if the host is open by changing words 4
           and 5 relative to words 2 and 3.
           4) if the window is host to previously activated panes, these
              will also be opened.
           5) Uses Wimp_OpenWindow, PRM2 p 1190, PRM3 p

%WPTASK

 CALL WPTASK(SCOMND)

 Purpose: Starts up a new task

 Parameters:

  SCOMND - CHARACTER a command string of less than 256 characters
                     which will cause a new program to run.
                E.g. 'BASIC -quit myprog' to run a program written in basic

 Comments: 1) if the new program is a Wimp program, then WPTASK will return
           as soon as the new task enters its wimp polling loop (equivalent
           to calling WPLOOP).
           2) if the new program is not a wimp program, WPTASK will only
           return when it exits.
           3) call WPSTNS to set the appropriate memory size for the new
           program before calling WPTASK
           4) SCOMND will be truncated to 255 characters
           5) uses Wimp_StartTask, PRM2 p 1242, PRM3 p

%WPTEXT

 CALL WPTEXT(IX,IY,STEXT)

 Purpose: Sends text to a window during a draw request

 Parameters:

   IX,IY  - INTEGERs coordinates in the window work area of the top left
                     of the first letter of the string

   STEXT  - CHARACTER text string to be printed in the window.

 Comments: 1) coordinates are measured from the top left of the work area,
           so: y <= 0 <= x
           2) this routine provides a convenient way of sending a character
           string to a window from WQPLOT or WQUPDT. It is much faster than
           GRMOVE and PRINT.
           3) embedding non-printing characters (ASCII < 32 or > 127)
           in the string should be avoided.

%WPTIME

 CALL WPTIME(REALT,CPUT)

 Purpose: Tells how much time the task has taken

 Parameters:

   REALT  - REAL returned elapsed time since WPINIT was called (seconds).

   CPUT   - REAL returned task CPU time since WPINIT was called (seconds).

 Comments: 1) the results will be nonsense before WPINIT has been called,
          and after more than 248 days since the computer was turned on
          or reset.
           2) the CPU time is found by counting the centi-second time
          clicks ocurring while the task has the CPU. Therefore the result
          has a statistical element and will not be exactly reproducible.

%WPTXTC

 CALL WPTXTC(IRF,IGF,IBF,IRB,IGB,IBB)

 Purpose: Sets colour for text printing in the desktop font (mainly for
          (RISC OS 3.5)

 Parameters:

    IRF  - INTEGER Red intensity of text in range 0 to 255

    IGF  - INTEGER Green intensity of text in range 0 to 255

    IBF  - INTEGER Blue intensity of text in range 0 to 255

    IRB  - INTEGER Red intensity of text background in range 0 to 255

    IGB  - INTEGER Green intensity of text background in range 0 to 255

    IBB  - INTEGER Blue intensity of text background in range 0 to 255

 Error: intensities outside the range 0 to 255 are taken modulo 255;
        e.g. -1 is the same as 255

 Comments: 1) for RISC OS before 3.5 this just sets the graphics colour to
           (IRF,IGF,IBF); IRB,IGB,IBB must be specified but are ignored.
           2) use WPTXTF to print text using the colours set up here.
           3) uses Wimp_TextOp 0: PRM3 5-212
           
%WPTXTF

 CALL WPTXTF(IX,IY,IWHAND,STEXT)

 Purpose: Sends text in the default desktop font to a window
          during a draw request

 Parameters:

   IX,IY  - INTEGERs coordinates in the window work area of the top left
                     of the first letter of the string

  IWHAND  - INTEGER handle of the window to contain the text

   STEXT  - CHARACTER text string to be printed in the window.

 Error: illegal window handle (if ignored, no text will be printed).

 Comments: 1) coordinates are measured from the top left of the work area,
           so: y <= 0 <= x
           2) this routine is equivalent to WPTEXT for RISC OS versions
           before 3.5;
           with 3.5 or later it uses the configured desktop font.
           3) embedding non-printing characters (ASCII < 32 or > 127)
           in the string should be avoided.
           4) use WPTXTC to set the colour of the text
           5) use WPTXTW to find the length of the text in OS units
           6) uses Wimp_TextOp 2: PRM3 5-214

%WPTXTW

 CALL WPTXTW(STEXT,IWIDTH)

 Purpose: finds the graphics length of text to be printed.

 Parameters: 

   STEXT  - CHARACTER text string for which the length is to be found

  IWIDTH  - INTEGER returned length of the text in OS units

 Comments: 1) this may also be used to fine the length of the text in
           a text icon created with the default font in RISC OS 3.5
           2) in RISC OS versions before 3.5 it returns 16*LEN(STEXT)
           3) uses Wimp_TextOp 1: PRM3 5-213

%WPUPDT

 CALL WPUPDT(IWHAN,IXL,IYL,IXH,IYH)

 Purpose: Forces an area of a window to be updated immediately without
          returning to the wimp manager.

 Parameters:

   IWHAN  - INTEGER handle of window requiring update

   IXL,IYL- INTEGER coordinates of the bottom left corner of the area to
                    update in the window work area.
                    If IXL < 0, all the window will be updated, and no
                    other parameters need be supplied.
   IXH,IYH- INTEGER coordinates of the top right corner of the area to
                    update in the window work area.

 Error: unknown window handle

 Comments: 1) coordinates are measured from the top left of the work area,
           so: y <= 0 <= x
           2) this call starts a sequence of calls to WQUPDT requesting you
           to fix up part of your window. The window is not cleared to the
           background as is done for the WPPLOT request.
           2) use this routine to alter parts of a window, say,
           in response to a mouse click.
           3) use WPPLOT if you want to completely re-draw an area from
           scratch.
           4) uses Wimp_UpdateWindow, PRM2 p 1206, PRM3 p

%WPVRSN

 CALL WPVRSN(IVERSN)

 Purpose: Tells which wimp version is available

 Parameter:

   IVERSN - INTEGER returned 3-digit wimp version number 
                    2xx for RISC-OS 2
                    3xx for RISC-OS 3

 Comments: 1) the result will be zero before WPINIT has been called.

%WPWRIN

 CALL WPWRIN(IWH,IH,INT,IERR)

 Purpose: writes an integer to an indirected text icon

 Parameters:

   IWH    - INTEGER handle of the window containing the icon

   IH     - INTEGER handle of the icon to receive the ASCII integer
                    or -1 for title icon

   INT    - INTEGER value to be stored in ASCII in the icon

   IERR   - INTEGER returned error
                  0: INT written to icon OK
                 +1: INT is too big to fit into icon
                 -1: icon or window handle is illegal 
                 -2: icon does not contain indirected text

 Errors: Illegal icon or window handle
         Icon (?) does not contain indirected text

 Comment: to write a REAL number, use WRITE(TEMP,*)REAL
          and CALL WPWRTX
 
%WPWRTX

 CALL WPWRTX(IWH,IH,STRING,LEN)

 Purpose: writes a text string to an indirected text icon

 Parameters:

   IWH    - INTEGER handle of the window containing the icon

   IH     - INTEGER handle of the icon to be written with ASCII text
                    or -1 for title icon

   STRING - CHARACTER ASCII string to be written in the text icon. 

   LEN    - INTEGER returned error
                >=0: length actually sent to the icon
                       (excludes trailing blanks)
                 -1: icon or window handle is illegal 
                 -2: icon does not contain indirected text

 Comment: If the text icon is shorter than the string, it will be truncated.
          This can be detected by LEN returning a smaller length than
          expected.

%WPXY2S

 CALL WPXY2S(IWHAN,IXW,IYW,JXS,JYS)

 Purpose: Transforms window work area coordinates to screen coordinates

 Parameters:

   IWHAN   - INTEGER window handle with the coordinates to transform

   IXW,IYW - INTEGERs coordinates in the window's work area system

   JXS,JYS - INTEGERs returned coordinates in screen system

 Error: unknown window handle

 Comments: 1) window work area coordinates are measured from the top left,
              so x >= 0 >= y
           2) screen coordinates are measured from the bottom left,
              so x,y >= 0
           3) uses Wimp_GetWindowState, PRM2 p 1209, PRM3 p
%WPXY2W

 CALL WPXY2W(IWHAN,IXS,IYS,JXW,JYW)

 Purpose: Transforms screen coordinates to window work area coordinates

 Parameters:

   IWHAN   - INTEGER handle of window to transform the coordinates to

   IXS,IYS - INTEGERs coordinates in screen system

   JXW,JYW - INTEGERs returned coordinates in the window's work area system

 Error: unknown window handle

 Comments: 1) screen coordinates are measured from the bottom left,
              so x,y >= 0
           2) window work area coordinates are measured from the top left,
              so x >= 0 >= y
           3) uses Wimp_GetWindowState, PRM2 p 1209, PRM3 p

%WQCLIK

 SUBROUTINE WQCLIK(IWHAN,ICONH,IX,IY,IBUTT)

 Purpose: called when there is a mouse button click

 Parameters passed:

   IWHAN  - INTEGER handle of the window over which the mouse was clicked
               or   -1 for background, -2 for icon bar

   ICONH  - INTEGER handle of the icon over which the mouse was clicked
               or   -1 if not over icon

   IX,IY  - INTEGERs OS coordinates of the pointer relative to the screen
                     origin

   IBUTT  - INTEGER button pressed: 4=select, 2=menu, 1=adjust

 Default routine: does nothing

 Comments: 1) you must have selected a suitable  button type for the window
           or icon for this routine to be called (see WPCHWF, WPCHTF)
           2) "menu" over the icon bar icon will not call this routine, the
           menu is opened automatically.
           3) clicks over a "save" window (made with WPSAVE) also will
           not call this routine.
           4) use WPGTWS(IWHAN,IWB) to find where your window is if you want
           the position of the mouse pointer in work area coordinates, then:
              IXWORK = IX - IWB(2) + IWB(6)
              IYWORK = IY - IWB(5) + IWB(7)
              Easier is to call WPXY2W.
           5) called for wimp poll reason 6, PRM2 p 1196, PRM3 p

%WQCLSW

 SUBROUTINE WQCLSW(IWHAN)

 Purpose: Request from the wimp to close a window, in response to a click
          over its 'close' icon.

 Parameter:

   IWHAN  - INTEGER handle of window to be closed

 Default routine: calls WPCLSW(IWHAN)

 Comments: 1) useful if you want to close other windows dependent on the one
           which is requested to be closed. Also you might want to request
           confirmation by calling WPERR first.
           2) for simple programs, the default is sufficient.
           3) called for wimp poll reason 6, PRM2 p 1196, PRM3 p

%WQDRAG

 SUBROUTINE WQDRAG(IWHAN,ICONH,IBOX)

 Purpose: decides what to do when a user drops a drag-box not initiated from
          a standard save window (see WPSAVE)

 Parameter:

   IWHAN   - INTEGER handle of the window where the box is dropped
                     -1 for background, -2 for icon bar

   ICONH   - INTEGER handle of icon on which the box was dropped

   IBOX    - INTEGER array of 4 coordinates of the box:
                left, bottom, right, top;
             coordinates are relative to the work area origin of a window
             or relative to the screen origin if not over a window    

 Default routine: does nothing

 Comments: 1) This routine is called if you have set up your own drag box by
              calling WPDRAG or WPDRGI
           2) called for wimp poll reason 7, PRM2 p 1197, PRM3 p3-121

%WQHELP

 SUBROUTINE WQHELP(IWHAN,ICONH,IX,IY,SHELP)

 Purpose: called on a request from the RISC-OS !Help module so that you may
          supply on-line help.

 Parameters:

   IWHAN  - INTEGER a) handle of the window with the pointer in it
                    b) 1st word of menu block if over a menu tree
                    c) <0 if over the icon on the icon bar

   ICONH  - INTEGER a) handle of the icon with the pointer over it
                       (-1 if not over an icon)
                    b) menu item (starts at 0) if over a menu tree

   IX,IY  - INTEGER location of the pointer relative to the work area origin
                    of the window (screen coordinates if IWHAN<0)

   SHELP  - CHARACTER*240 string for your returned help message

 Default routine: says 'Sorry, no help available'

 Comments: 1) you have to load the !Help application from !Apps on to the
           icon bar to activate this on-line help.
           2) the !Help text window holds 4 lines of 77 characters
           3) insert the string '|M' in your text to force a new line.
           4) The following abbreviations will be translated by !Help
              '\S':'Click SELECT to '  '\D':'Drag SELECT to '
              '\A':'Click ADJUST to '  '\d':'Drag ADJUST to '
              '\R':'Move the pointer right to '  '\T':'This is the '
              '\G':'This option is greyed out because '  '\a':'ADJUST'
              '\W':'This window is '  '\w':'window'  '\s':'SELECT'
              but remember to put '\\' if you really want '\' unless
              it is in a messages file.

%WQKEYP

 SUBROUTINE WQKEYP(IWHAN,ICONH,IX,IY,ICIND,KEY)

 Purpose: called when a key is pressed when one of your windows has
          the input focus

 Parameters passed:

   IWHAN  - INTEGER handle of the window with input focus

   ICONH  - INTEGER handle of the writable icon in use
                    (-1 if none)

   IX,IY  - INTEGER location of the caret in OS units
                    relative to the work area origin

   ICIND  - INTEGER index of caret into the icon text
                    (undefined if ICONH=-1)

   KEY    - INTEGER value of the key pressed

 Default routine: calls WPKEYP

 Comments: 1) coordinates are measured from the top left of the work area,
           so: y <= 0 <= x
           2) if you have a window with the 'hot-key' bit set, then it will
           receive key-presses which are unacceptable to the window or icon
           with the input focus. E.g. the function keys are always hot-keys.
           They have special codes in the range 256 to 511.
           If you are not able to use this key signal, CALL WPKEYP(KEY)
           so that other users may see if they want it.
           3) WQKEYP will not be called after typing in a file name to a
           "save" window made by WPSAVE, WQWFIL will be called instead.
           4) called for wimp poll reason 8, PRM2 p 1197, PRM3 p

%WQLGCT

 SUBROUTINE WQLGCT(GAIN,IWBLK)

 Purpose: signals that a window has gained or lost the caret

 Parameters:

   GAIN   - LOGICAL .TRUE. if the caret is gained, .FALSE. if it is lost

   IWBLK  - INTEGER array 6-word block of explanation
               (1) window handle (-1 if none)
               (2) icon handle (-1 if none)
               (3),(4) displacement of the caret from the work area origin
                       in OS units
               (5) caret height and flags
               (6) index of caret into icon text (-1 if not defined)

 Default routine: does nothing

 Comments: 1) coordinates are measured from the top left of the work area,
           so: y <= 0 <= x
           2) this is useful for text processing/editing programs where you
           may need to keep track of what is happening to the caret.
           3) called for wimp poll reason 11,12, PRM2 p 1201, PRM3 p

%WQMENU

 SUBROUTINE WQMENU(MBLOC,ITEMS,NMENU)

 Purpose: called when the user clicks over a menu item

 Parameters:

   MBLOC  - INTEGER array, your top level menu block

   ITEMS  - INTEGER array (must be 1 longer than the longest tree)
                    returns one integer for each level of the menu showing
                    which item has been selected at this level. Items are
                    numbered from zero at the top.

   NMENU  - INTEGER size of the array ITEMS, showing which is the last level
                    of the tree selected.

 Default routine: does nothing

 Comments: 1) if you have more than one menu tree, use MBLOC to find out
           which menu it is. The first word in a menu block is the beginning
           of the title, so if the first 4 characters differ between your
           titles, it is sufficient to check the first word. Otherwise you
           had better use LOC(MBLOC) to find the one with the correct
           address.
           2) called for wimp poll reason 9, PRM2 p 1199, PRM3 p

%WQMESG

 SUBROUTINE  WQMESG(MTYPE,MFROM,MREF,MREP,MACT,MESG)

 Purpose: called when a message is received

 Parameters:

   MTYPE  - INTEGER type of message
               =-1: sender is not expecting a reply
               = 0: sender is expecting a reply or acknowledgement
               =+1: returned message because of no acknowledgement

   MFROM  - INTEGER task handle of sender

   MREF   - INTEGER sender's reference number for message

   MREP   - INTEGER your original reference number (see WPMESG) if this is a
                    reply, or =0 if this is an original message

   MACT   - INTEGER action code; many of these are used by RISC-OS
                    the following are intercepted by WPLOOP:
                    0 to 4, 8, 9, ?I502, ?I400C0 and ?I400C1
                    and are used for file dragging, quitting, Help etc.

   MESG   - CHARACTER message data
                      this will always be a multiple of 4 long, unused
                      locations being filled with CHAR(0)

 Default routine: does nothing

 Comments: 1) see WPMESG for help on how to send messages between tasks
           2) called for wimp poll reasons 17, 18 and 19
                   PRM2 p 1202, PRM3 p 3-230

%WQMODC

 SUBROUTINE WQMODC

 Purpose: to warn you that a screen mode change is about to happen. You may
          want to save some parameters with the current mode.

 No parameters

 Default routine: does nothing

 Comments: 1) after this call, the whole screen will be redrawn with
           appropriate calls to WQPLOT
           2) called for wimp message type 400C1 received
                PRM2 p 1259, PRM3 p

%WQMODF

 SUBROUTINE WQMODF(JFONT)

 Purpose: to warn you that the RISC-OS 3.5 desktop font has changed. 

 Parameter:

   JFONT  - INTEGER the new font handle or 0 for system font

 Default routine: does nothing

 Comments: 1) called for wimp message type 400CF received
               PRM3 p5-219

%WQMWRN

 SUBROUTINE WQMWRN(MBLOC,ITEMS,NMENU)

 Purpose: called when a sub-menu is about to be opened, provided you have
          set flag 3 for the menu item

 Parameters:

   MBLOC  - INTEGER array, your top level menu block

   ITEMS  - INTEGER array, one integer for each level of the menu showing
                    which item has been selected at this level. Items are
                    numbered from zero at the top. The last entry in ITEMS
                    shows the one for which the submenu is about to be
                    opened.

   NMENU  - INTEGER size of the array ITEMS, showing which is the last level
                    of the tree selected.

 Default routine: does nothing

 Comments: 1) if you have more than one menu tree, use MBLOC to find out
           which menu it is. The first word in a menu block is the beginning
           of the title, so if the first 4 characters differ between your
           titles, it is sufficient to check the first word. Otherwise you
           had better use LOC(MBLOC) to find the one with the correct
           address.
           2) this is useful if you want to change the sub-menu or
           sub-window before it is opened, or at least to know that it is
           going to be looked at.
           3) called for wimp message type 400C0 received.
                PRM2 p 1258, PRM3 p

%WQNULL

 SUBROUTINE WQNULL

 Purpose: called every wimp cycle to allow you to do background calculations
          or to inspect frequently the progress of other functions: e.g. the
          state of the printer buffer.

 No parameters

 Default routine: does nothing

 Comments: 1) try to split up any background work into small chunks to be
           processed each time WQNULL is called, otherwise the desktop will
           become sluggish and/or erratic in its response.
           2) if you only want WQNULL to be called occasionally, set the
           time interval for the calls with WPNULT
           3) if you are not going to use WQNULL, be sure to set the
           argument, MASK, of WPLOOP to 1 (or some odd number)
           4) called for wimp poll reason 0, PRM2 p 1194, PRM3 p

%WQOPNW

 SUBROUTINE WQOPNW(IWBLK)

 Purpose: Request from the wimp to open a window.

 Parameter:

   IWBLK  - INTEGER 8-word array window block (as obtained with WPGTWS)
               word  contents                     comment
                1    window handle                leave this alone
                2,3  OS screen coords of bottom left
                4,5  OS screen coords of top right
                6    x-scroll offset from left    positive or zero
                7    y-scroll offset from top     negative or zero
                8    window heap position         -1 for top, -2 for bottom


 Default routine: calls WPSTWS(IWBLK)

 Comments: 1) this is called whenever you finish moving a window around the
           desktop, or change its size, or move the scroll bars. It will
           start a WPPLOT sequence for the window. The default will almost
           always be sufficient.
           2) called for wimp poll reason 2, PRM2 p 1194, PRM3 p

%WQPALC

 SUBROUTINE WQPALC

 Purpose: warns of a change in the wimp palette

 No parameters

 Default routine: does nothing

 Comments: 1) this is to allow you to redraw your windows by calling WPPLOT
           2) CALL WPGETP to find the new palette
           3) called for wimp message type 9 received
                PRM2 p 1257, PRM3 p

%WQPLOT

 SUBROUTINE WQPLOT(IWHAN,IX1,IY1,IX2,IY2)

 Purpose: called when an area of a window needs to be plotted

 Parameters passed

   IWHAN  - INTEGER handle of the window which needs plotting

   IX1,IY1- INTEGER coordinates of the bottom left corner of the area
                     to plot in OS units with origin at the top left
                     corner of the work area of the window

   IX2,IY2- INTEGER coordinates of the top right corner of the area to plot
                    with the same convention.

 Default routine: does nothing

 Comments: 1) coordinates are measured from the top left of the work area,
           so: y <= 0 <= x
           2) do NOT change the graphics window with GRGWIN, it has already
           been set to the the area (IX1,IY1,IX2,IY2), and the origin
           to the origin of your work area.
           3) do NOT call any of the WPxxxx routines which affect the
           windows from WQPLOT; some exceptions are: WPSETC to set the
           colour and WPTEXT for writing text.
           Do NOT use GRWOG or GRWOT or GRWBIG for text, but do use the
           GRxxxx drawing routines for graphics.
           4) because there is a graphics window set, it easiest to plot the
           whole work area, though this may take longer.
           5) called from WPLOOP (may be prompted by WPPLOT).

%WQPREQ

 SUBROUTINE WQPREQ(IOK)

 Purpose: allows you to tidy up before being shut down

 Parameter:

   IOK   - LOGICAL see comments below

 Default routine: does nothing

 Comments: 1) Do not use this routine if you can tidy up without any
           interaction from the user, (use the WQQUIT for any automatic
           tidying up instead).
           2) Set IOK to .FALSE. and open your dialogue window for
           interaction with the user.
           3) When you have finished, CALL WPPREQ to continue the shutdown.
           4) Called for wimp message type 8 received
                PRM2 p 1257, PRM3 p

%WQPTWW

 SUBROUTINE WQPTWW(IWHAN,ENTER)

 Purpose: tells you that the pointer is entering or leaving one of your
          windows. This is to allow you to change to a special pointer.

 Parameters:

   IWHAN  - INTEGER window handle

   ENTER  - LOGICAL .TRUE. if the pointer is entering the window
                    .FALSE. if the pointer is leaving the window

 Default routine: does nothing

 Comment: called for wimp poll reasons 4, 5, PRM2 p 1194, PRM3 p

%WQQUIT

 SUBROUTINE WQQUIT

 Purpose: tells you that your task is about to be killed off.

 No parameters

 Default routine: does nothing

 Comments: 1) this is your last chance to save known files while in the wimp
           part of your program; it is too late to call any WPxxxx routines.
           2) called for wimp message type 0 received
                PRM2 p 1257, PRM3 p

%WQRFIL

 SUBROUTINE WQRFIL(IWHAN,ICONH,ISIZE,ITYPE,SFILE)

 Purpose: tells you that some task wants you to read a file;
          a filer icon has been dropped onto one of your windows or icons.

 Parameters:

   IWHAN  - INTEGER handle of the window where the drag box was dropped
                    (<0 if over the icon bar, =0 for double-clicked file
                      see comment 2)

   ICONH  - INTEGER handle of the icon  where the drag box was dropped
                    (-1 if not over an icon, =0 for double-clicked file)

   ISIZE  - INTEGER size of the file (in bytes)

   ITYPE  - INTEGER file type (in range 0 - 4095) but see comment 3)

   SFILE  - CHARACTER complete filename (filer::disc.path.leaf) which
                      you are being requested to read

 Default routine: displays warning message

 Comments: 1) you do not have to read the file, but it would be useful to
           display a warning message if it is not one you want.
           2) if a file type has been set up with WPFTYP (q.v.) then
           double-clicking on a filer icon will send the file name to WQRFIL
           with zero window and icon handles.
           3) ITYPE will be 4096 if a directory is dropped into your
           program. In this case SFILE is the full directory name and you
           can find all the files in it using FLDIRE in the utilities
           library.
           4) called for wimp message type 3 (or 5) received
                PRM2 p 1257, PRM3 p

%WQSCRL

 SUBROUTINE WQSCRL(IWBLK)

 Purpose: allows you to decide how much to scroll a window when the user
          clicks on one of the scroll bar icons

 Parameter:

   IWBLK  - INTEGER array of 10 words. The first 8 are the usual window
                    state, as described in WPSTWS, words 9 (10) show the
                    requested change in the x (y) directions:
                    0: no change
                    1: move right (up) after click on scroll arrow
                    2: page right (up) after click in scroll bar outer area
                    -1,-2 are the opposite of +1 and +2.

 Default routine: does nothing

 Comments: 1) if you set the scroll request flag when you make a window by
           CALL WPCHWF(8,.TRUE.), you had better write this routine, the
           default does nothing, and the window will not scroll.
           2) called for wimp poll reason 10, PRM2 p 1257, PRM3 p

 Example:

      SUBROUTINE WQSCRL(IWBLK)
      DIMENSION IWBLK(10)
C            loop over x and y
      DO 10 IXY = 1, 2
C            get the request
       IREQ = IWBLK(IXY+8)
C            if zero, no action
       IF(IREQ .EQ. 0) GO TO 10
C            IF 1, move on by 32 OS units (e.g. 1 character)
       IF(ABS(IREQ) .EQ. 1) THEN
          IWBLK(IXY+5) = IWBLK(IXY+5) + 32 * IREQ
       ELSE
C            IF 2, move on by 1 window size
        IWBLK(IXY+5) = IWBLK(IXY+5) + (IREQ/2)*(IWBLK(IXY+3)-IWBLK(IXY+1))
       ENDIF
   10 CONTINUE
C            now change the window
      CALL WPSTWS(IWBLK)
      RETURN
      END

%WQUPDT

 SUBROUTINE WQUPDT(IWHAN,IX1,IY1,IX2,IY2)

 Purpose: called when an area of a window needs to be updated

 Parameters passed

   IWHAN   - INTEGER handle of the window which needs updating

   IX1,IY1 - INTEGER coordinates of the bottom left corner of the area
                      to update in OS units with origin at the top left
                      corner of the work area of the window

   IX2,IY2 - INTEGER coordinates of the top right corner of the area
                     to update with the same convention.

 Default routine: does nothing

 Comments: 1) coordinates are measured from the top left of the work area,
           so: y <= 0 <= x
           2) do NOT change the graphics window with GRGWIN, it has already
           been set to the the area (IX1,IY1,IX2,IY2), and the origin
           to the origin of your work area.
           3) do NOT call any of the WPxxxx routines which affect the
           windows from WQUPDT; some exceptions are: WPSETC to set the
           colour and WPTEXT for writing text.
           Do NOT use GRWOG or GRWOT or GRWBIG for text, but do use the
           GRxxxx drawing routines for graphics.
           4) because there is a graphics window set, it easiest to plot the
           whole work area, though this may take longer.
           5) any updating of a window you do with this routine must also be
           reflected into what you draw with WQPLOT. Otherwise, next time
           the user moves, or changes the size of the window, your updates
           may disappear.
           6) called from WPUPDT through WPLOOP.

%WQWFIL

 WQWFIL(IWHAN,SFILE)

 Purpose: a file handling task is ready to receive a file which you have
          dragged to its window.

 Parameters:

   IWHAN  - INTEGER handle of the drag-box window you set up with WPSAVE
                    which has been used for the drag.

   SFILE  - CHARACTER string containing the complete file name

 Default: prints a message saying that it can't write a file

 Comment: 1) called as the result of a long dialogue with a filer after
             selecting a file name from a save window. See WPSAVE for
             setting up a save window.
          2) WPSAVE may have given you a directory, not a file. You
             recognise this from IWHAN and then must create the directory
             with a statement like:
             CALL OSCLI('CDIR '//SFILE)
