The Datafile PD-CD 5

home *** CD-ROM | disk | FTP | other *** search

/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / w / wimpext / Manual next >

Wrap

Text File | 1993-08-16 | 85.0 KB | 2,347 lines

________________________________ WimpExtension 2.18 (16-Aug-1993) ________________________________ (c) Jon Ribbens of DoggySoft, 1993 Licence ======= You can give copies of WimpExtension, with or without the accompanying documentation and example application, to anybody you like, as long as you don't make any money out of doing so. You can, however, include WimpExtension with other commercial products. ie: You can sell a program which uses WimpExtension, and include WimpExtension with it, but you can't sell WimpExtension on its own. There is no warranty at all, express or implied or whatever. If anything goes wrong, don't blame me. I will, however, try to fix any problems you find. NB If you find any bugs in WimpExtension, or you think I should include some -- extra feature, don't just sit there muttering to yourself, TELL me about it. Introduction ============ WimpExtension is designed to make the task of programming the Wimp easier. It also enables you to use 3D icons (like Impression). It is designed to enable you, when you are writing your programs, to think less 'It's a Desktop program' and more 'It's a program to do ...'. It has been written over a period of more than a year, reaching over twelve thousand lines of source code, hopefully carefully designed to be as easy to use as possible. You use WimpExtension by a set of SWI (BASIC's SYS) commands. There are calls to put icons on the iconbar, to change the pointer shape, to pop icons in and out, link windows so they move about together (for toolboxes and windows-in-windows), there are facilities for options window handling, for dialogue boxes, for controlling indirected icons, for loading templates, for colour menus, for RAM templates, for dragging icons, for menu handling, for draw-files and sprites, for immediate windows, for memory management, etc., etc. This manual explains all the features of WimpExtension, and how to use them. For a quick overview of the SWI calls read the file 'SWIs'. There is an accompanying example application, ExtDemo, which should be included with the WimpExtension module. This shows off some of the features of WimpExtension. It is written in BASIC so that you can see how it works. General points ============== * WimpExtension needs to know which task is calling it. It is told when you call WimpExt_Initialise or WimpExt_Action, but calls to Wimp_Poll may change it (as other tasks call it). If you have not called WimpExt_Initialise or WimpExt_Action since the last Wimp_Poll therefore, you should call WimpExt_CurrentTask to tell WimpExtension your task handle. * In general, all strings are control-terminated, ie. they may not contain any characters less than 32, which are treated as terminators. * Some features of WimpExtension are controlled by the validation strings of icons. To have a validation string, the icon must be indirected text (plus sprite if you want). (If you don't want text, make it text, just don't put any text in it.) Validation commands are separated by semicolons; you can put as many as you want on a single icon. You shouldn't use the same command twice, unless you are specifically told you can. (The behaviour is undefined if you do - ie. different versions of WimpExtension may do different things.) * Since it claims workspace for tasks it knows about, WimpExtension MUST know when a task closes down. You should therefore, always call WimpExt_CloseDown before your task exits. To catch any unavoidable slips (eg. Address Exceptions in BASIC) WimpExtension initialises a module task which will call WimpExt_CloseDown for any tasks that exit. You must not rely on this, though. * All SWIs corrupt R0, even if they are not using it to return a result. * Because WimpExtension provides more than 64 SWIs, another module called 'WimpExtShadow' appears in the module list. This is perfectly normal and should be ignored. Essential SWIs ============== These are SWIs you MUST call if you are going to use ANY of the features of WimpExtension. WimpExt_Initialise &45780 ------------------------------- R0 = 16 R1 = task handle R2 = features flags bit meaning 0 semi-automatic slabbing if set, automatic otherwise 1 automatically recreate menus if set 2 task wants to use font menus if set 3 automatically compact heap once a second if set 4 'correct' radio icons if set 5 semi-automatic help if set, automatic otherwise 6 use alternative parameters for flag-setting SWIs if set 7 use R0 of WimpExt_SetIconString[N] 8 automatically call WimpExt_MoveCaret 9 Unset other icons in ESG when setting icons 10 Automatically call WimpExt_ViewIcon after moving caret 11 Don't allow TAB for moving between writeable icons 12-31 reserved; MUST BE 0 Exit: R0 = WimpExt version number * 100 R2 = pointer to WimpExt's sprite pool Must be called prior to using any other WimpExt calls. R0 must be 11 on entry. This is so that WimpExtension can work out what version the program thinks it is calling (so I can change the functionality of calls later whilst still retaining backwards-compatibility). R2 holds features flags, for specifying certain things at start-up. If bit 1 of R2 is set then if the user selects a menu option with the ADJUST button then the menu will automatically be recreated when you next call WimpExt_PrePoll (assuming you used 'WimpExt_CreateMenu' to create the menu, that is). If bit 2 of R2 is set then you are allowed to call WimpExt_GetFontMenu and WimpExt_DecodeFontMenu - you are NOT allowed to call them if you do not set bit 2. If bit 4 of R2 is set then the user won't be able to deselect all of a group of radio icons by clicking adjust on the selected icon. WimpExt_CloseDown &45781 ------------------------------- R0 = task handle Must be called prior to the task exiting. WimpExt_PrePoll &457B4 ------------------------------- To be called immediately before Wimp_Poll or Wimp_PollIdle. WimpExt_Action &45784 ------------------------------- R0 = task handle R1 = Wimp_Poll block R2 = Wimp_Poll reason code Exit: R0 = Wimp_Poll reason code (possibly altered) To be called immediately after Wimp_Poll. WimpExtension may alter the code returned - eg. if the user clicks in a requester window then the code will be translated before your program gets to see it. The general structure of your program, therefore, will be: SYS "Wimp_Initialise"... SYS "WimpExt_Initialise"... WHILE NOT quit% SYS "WimpExt_PrePoll" SYS "Wimp_Poll"... SYS "WimpExt_Action"... ENDWHILE SYS "WimpExt_CloseDown"... SYS "Wimp_CloseDown"... END 3D icons and window redraws =========================== 3D borders are treated as user graphics, so the 'auto-redraw' flag in the window definition should not be set. 3D borders are controlled by the 'w' validation command: 'w' (border type) Syntax: w<border number>,<slabbing mask>,<slabbing time>,<top left colour>, <bottom right colour>,<popped in colour>,<popped out colour>, <channel colour> All the numbers apart from the border number are optional. The defaults are: wxx,4,15,4,0,1,14,12. These defaults can be changed by the user, using the command 'WimpExt Defaults' - see below. You can specify only some, eg: w2,4,20 or w2,,,,3. The border numbers are: 0 : Standard 3D border. Used for headings and buttons. Pops in if clicked on. 1 : Ridged grouping border. Put it around things of a similar nature. 2 : Like 0, with a channel round it. Used for the default button (ie. the one that is pressed if you press RETURN). 3 : Wide border for writeable icons - leave the normal black border on the icon and make the background white. 4 : Popped in border - for things that are for information only. 5 : Trenched border - the opposite of border 1. Can be clicked on. Suggested use is as an alternate border 1. 6 : Title border - similar to border 0, but with two 'dents'. This border is designed to be used as the title of a group, with a border 1 icon behind it as the frame - see ExtDemo for examples. If you add 8 to the border number, it will become inert - ie. it will ignore all mouse clicks and not pop in. Bordered icons should be filled if you want them to change colour when clicked on (which is definitely recommended), and you should initially set the background colour of the icon to the out-colour. Anti-aliased font icons are now supported. The icon MUST have an 'F' validation command, as the Wimp needs this to specify the icon's colour. Note that slabbing font icons doesn't look very good in 16-colour modes, due to anti-aliasing (this isn't WimpExtension's fault, it's just a fact of life). If you set the in-colour and out-colour the same then the icon won't ever be slabbed in or out. If you really really want an icon which doesn't change colour when slabbed in and out unset the 'Filled' flag. I don't recommend having icons which don't change colour, anyway - they look awful. Note that when WimpExtension redraws border type 6, if the icon is filled (as it should be using this border) then WimpExtension fills the icon at the same time. This means that you only very very briefly see the ridged border behind it. WimpExt_SlabIcon &45782 ------------------------------- R2 = window handle or 0 for slabbed icon R3 = icon handle If semi-automatic slabbing is enabled, then: R4 = 0 to pop out, any other to pop in To be called to force an icon to be slabbed (for example to slab the default action icon if RETURN is pressed). If semi-automatic slabbing is enabled then the icon will be popped in or out depending on R4, otherwise it will be popped in and then out again. If R2 is zero then the last icon to be slabbed in (either implicity or explicity) is used. Note that in this case the SWI might return an error (eg. if the window has been deleted), so use the X form if the SWI. WimpExt_Redraw &45783 ------------------------------- R1 = Wimp_RedrawWindow block To be called in the window redraw loop, to draw the 3D borders round icons. If you use 3D borders, you MUST call WimpExt_Redraw, or they won't appear. Your redraw loop would probably look something like: SYS "Wimp_RedrawWindow",,q% TO flag% WHILE flag% SYS "WimpExt_Redraw",,q% ... SYS "Wimp_GetRectangle",,q% TO flag% ENDWHILE WimpExt_AutoRedraw &45798 ------------------------------- R1 = Wimp_Poll reason code 1 block This call can be used instead of the normal Wimp_RedrawWindow/GetRectangle loop if the window doesn't contain any graphics drawn by your program. It does the equivalent of: SYS "Wimp_RedrawWindow",,q% TO flag% WHILE flag% SYS "WimpExt_Redraw",,q% SYS "Wimp_GetRectangle",,q% TO flag% ENDWHILE Iconbar sprites =============== Two SWIs are provided for putting icons on the iconbar - one for sprites only, and one for text-plus-sprite icons. These read the size of the sprite to get the width of the icon. WimpExt_IconBarSprite &45785 ------------------------------- R2 = -2 for left of iconbar, -1 for right R3 = pointer to sprite name R5 = icon button type (eg. 3) Exit: R0 = icon handle Will place a sprite on the iconbar, returning the icon handle. Note that the sprite name is copied out of the memory block, which can be reused. Also note that the number in R5 is just the button type, not the flags. WimpExt_IconBarText &45786 ------------------------------- R2 = -2 for left of iconbar, -1 for right R3 = pointer to sprite name R4 = pointer to text (max. 128 chars inc. terminator) R5 = icon button type (eg. 3) Exit: R0 = icon handle Will place a sprite on the iconbar, with a text message underneath, returning the icon handle. Note that the sprite name is copied out of the memory block, which can be reused, but the text remains where it is; this is so you can change the text after creating the icon. Also note that the number in R5 is just the button type, not the flags. Linked windows ============== Linked windows are good for option setting and lists of things. They consist of a main window, which is normal, and a subwindow, which moves around with the main window. The subwindow normally has no titlebar and no horizontal scrollbar, just the vertical scrollbar, although this is a matter of style. To have more than one subwindow in a main window you should link the subwindows together. eg: SYS "WimpExt_LinkWindows",,,mainw%,link1w%,0 SYS "WimpExt_LinkWindows",,,link1w%,link2w%,0 SYS "WimpExt_LinkWindows",,,link2w%,link3w%,0 ... WimpExtension makes linked windows very easy - to set up a linked window, just use SWI WimpExt_LinkWindows, and use WimpExt_OpenLinked and WimpExt_CloseLinked instead of Wimp_OpenWindow and Wimp_CloseWindow. WimpExt_LinkWindows &45787 ------------------------------- R2 = main window handle R3 = sub-window handle R4 = flags bit meaning 0 clip linked window to the left of the main window 1 clip linked window to the right of the main window 2 clip linked window above the main window 3 clip linked window below the main window 4-30 reserved; MUST BE 0 31 link is hidden Will link two windows so the sub-window moves with the main window. Currently there is a limit of 16 linked windows - this may be removed in a later version. WimpExt_OpenLinked &45788 ------------------------------- R1 = Wimp_OpenWindow block To be used instead of Wimp_OpenWindow. It does the same thing, but if the window is linked then it will handle the link. If the window is not linked, it has the same effect as Wimp_OpenWindow. WimpExt_CloseLinked &45789 ------------------------------- R1 = Wimp_CloseWindow block To be used instead of Wimp_CloseWindow. It does the same thing, but if the window is linked then it will close the linked window as well. If the window is not linked, it has the same effect as Wimp_CloseWindow. WimpExt_UnLinkWindows &4578A ------------------------------- R2 = main window handle R3 = sub-window handle Will remove the link between the specified window and its subwindow. Note that this just removes the pointer in WimpExtension workspace, if the windows are on the screen they will remain there. You do not have to call UnLinkWindows before you exit - it is here so that you can unlink windows while your application is still running. WimpExt_HideLink &457A8 ------------------------------- R0 = main window handle R2 = sub-window handle Temporarily hides the link between the specified window and its sub-window. This is useful, for example, for removing toolboxes in such a way that they can be replaced later. Note that this call does no screen update - ie. the sub-window remains where it is. WimpExt_UnHideLink &457A9 ------------------------------- R0 = main window handle R2 = sub-window handle Unhides the previously hidden link. Note that this call does no screen update - ie. the sub-window remains where it is. WimpExt_ManualLink &46389 ------------------------------- R2 = main window handle R3 = sub-window handle R4 = flags bit meaning 0 clip linked window to the left of the main window 1 clip linked window to the right of the main window 2 clip linked window above the main window 3 clip linked window below the main window 4-30 reserved; MUST BE 0 31 link is hidden R5 = X offset between main and sub-window R6 = Y offset between main and sub-window Will link two windows so the sub-window moves with the main window. Currently there is a limit of 16 linked windows - this may be removed in a later version. Templates ========= Using templates usually is quite tedious, as you have to open the template file and read in the definitions for each window individually, calling Wimp_CreateWindow for each one and storing the window handle. Using WimpExtension you just call WimpExt_LoadTemplates and all the windows in the named file will be loaded and created, and the handles stored in a buffer. The only time you cannot do this is if you have more than one window that you want to open multiple copies of. If you have no such windows, you're OK, if you want one such window then you simply make sure it's the last window in the templates file, and its definition will be in the buffer after the SWI call. Note that by using this call your program is dependent on the order of the templates in the file. This shouldn't matter, as when you make the templates file you know what order you've got them in, and nobody else has any business changing your templates file. WimpExt_LoadTemplates &4578C ------------------------------- R0 = pointer to buffer for storing window handles R1 = pointer to user buffer for template (big enough for largest template) R2 = pointer to workspace for indirected icons R3 = pointer to end of workspace for indirected icons R4 = 256-byte font reference array (-1 for no fonts) R5 = pointer to filename of templates file R6 = pointer to sprite area control block (+1 for Wimp sprite pool) Loads in all the templates from the file whose name is pointed to by R5, and called Wimp_CreateWindow for each one. The value in R6 is placed in the window block at offset +64. Stores the window handles sequentially in the buffer pointed to by R0, in the order they are found in the templates file. On exit the buffer pointed to by R1 will contain the template for the last window in the file. The buffer for window handles should be big enough to store all the window handles, each of which is a word. For each window, if the word on entry is zero the window will be created as usual. Bits that are set have the following meanings: Bit Meaning if set ---------------------------------------------- 0 centre window horizontally 1 don't create window 2 centre window vertically Bit 1 is useful if you have the last window in the file as one that you want repeatedly, but you don't want it created at once. Another SWI is provided for RAM templates. This is provided mainly for module tasks, where the templates must be part of the main code. You can use the supplied BASIC function 'FNtemplate' to include the template as part of your code, and then use WimpExt_LoadRAMTemplate to turn this into a window definition. WimpExt_LoadRAMTemplate &457A5 ------------------------------- R1 = pointer to user buffer for window definition R2 = pointer to workspace for indirected icons R3 = pointer to end of workspace for indirected icons R4 = -1 for no fonts - fonts not supported at present R5 = pointer to template Exit: R2 = pointer to end of workspace used (ie. first free byte) This call is similar to Wimp_LoadTemplate except that it uses templates in RAM. This is designed to be used in Module tasks, where you cannot have a separate Templates file. You would use the supplied 'FNtemplate' function to insert the template in your module, and then call WimpExt_LoadRAMTemplate to convert this to a window definition. At present fonts in templates are not supported - this shouldn't cause too much of a problem as I have never seen a program which uses this feature anyway. Icon handling ============= Lots of SWIs are provided for handling icons, eg. setting the string in a text icon, shading icons, reading a number from an icon, etc... WimpExt_SetIconString &4578D ------------------------------- R0 = non-zero for ellipsis (only if enabled in WimpExt_Initialise) R2 = window handle R3 = icon handle R4 = pointer to string Copies the string pointed to by R2 into the specified indirected text icon, and updates the screen if necessary. If the caret was in the icon then it is moved to the end of the new string. Only updates the screen if anything was changed - ie. if the new string is the same as the old string then nothing will happen. If R0 is non-zero and bit 7 was set in R2 in WimpExt_Initialise and the string is longer than the icon can hold then the string will be post-fixed with '...'. WimpExt_SetIcon &4578F ------------------------------- R2 = window handle R3 = icon handle R4 = 0 to deselect icon, non-zero to select icon If bit 6 of R2 was set in WimpExt_Initialise: R4 = 0 to deselect icon, 1 to select icon, 2 to toggle icon Exit: R0 = old state of icon (0 for unset, 1 for set) Selects the icon if R4 is non-zero, deselects it otherwise. Updates the screen if necessary. If bit 6 of R2 was set in WimpExt_Initialise then the alternative parameters are used as shown. If bit 9 of R2 was set in WimpExt_Initialise and you are setting the icon, then other icons in the same ESG will be unset. WimpExt_GetIcon &45790 ------------------------------- R2 = window handle R3 = icon handle Exit: R0 = 0 if icon is not selected, 1 if it is selected R3 = word at iconblock+20 (ie. pointer to indirected text for indirected text icon) Detects whether the icon is selected, and returns 1 in R0 if it is, 0 otherwise. Also returns in R1 then value in the iconblock at offset 20. For an indirected text icon this will be a pointer to the text. WimpExt_SetNumberIcon &45791 ------------------------------- R0 = base R2 = window handle R3 = icon handle R4 = value Converts the signed integer in R4 into a string and places it in the icon. Updates the screen as necessary. The base to be used is specified in R0 - it must be in the range 2-36. WimpExt_GetNumberIcon &45792 ------------------------------- R0 = default base R2 = window handle R3 = icon handle Exit: R0 = value Converts the string in the icon to a signed integer and places it in R0. The base to be used by default is specified in R0 - it must be in the range 2-36. WimpExt_IncNumberIcon &45793 ------------------------------- R0 = base R2 = window handle R3 = icon handle R4 = maximum value R5 = step Exit: R0 = new value Converts the string in the icon to an signed integer, adds the step, and puts it back. Updates the screen as necessary. The value will not go beyond the value passed in R4, and the new value is returned in R0. WimpExt_DecNumberIcon &45794 ------------------------------- R0 = base R2 = window handle R3 = icon handle R4 = minimum value R5 = step Exit: R0 = new value Converts the string in the icon to an signed integer, subtracts the step, and puts it back. Updates the screen as necessary. The value will not go beyond the value passed in R4, and the new value is returned in R0. WimpExt_SetIconStringN &457A0 ------------------------------- R0 = non-zero for ellipsis (only if enabled in WimpExt_Initialise) R2 = window handle R3 = icon handle R4 = pointer to string Copies the string pointed to by R2 into the specified indirected text icon, and updates the screen if necessary. If the string is longer than the size of the buffer then the right-hand end of the string is copied (as opposed to the left-hand end, which is the case if you use WimpExt_SetIconString). If the caret was in the icon then it is moved to the end of the new string. If R0 is non-zero and bit 7 was set in R2 in WimpExt_Initialise and the string is longer than the icon can hold then the string will be pre-fixed with '...'. WimpExt_SetIconColour &457B0 ------------------------------- R2 = window handle R3 = icon handle R4 = foreground colour (0-15 or -1 to keep the same) R5 = background colour (0-15 or -1 to keep the same) Exit: R0 = old foreground colour + old background colour * 16 Changes the specified icon's colour(s). If there is no change then the icon is not updated (ie. it doesn't flicker). This call will now work for anti- aliased fonts, but the icon MUST have an 'F' validation command, as the Wimp needs this to specify the icon's colour. WimpExt_ShadeIcon &457B1 ------------------------------- R2 = window handle R3 = icon handle R4 = 0 to unshade icon, non-zero to shade icon If bit 6 of R2 was set in WimpExt_Initialise: R4 = 0 to unshade icon, 1 to shade icon, 2 to toggle shade flag Exit: R0 = old state of icon (0 for unshaded, 1 for shaded) Shades the icon if R2 is non-zero, unshades it otherwise. Updates the screen if necessary. If the caret was in the icon and you are telling WimpExtension to shade it then the caret is removed (disowned). If bit 6 of R2 was set in WimpExt_Initialise then the alternative parameters are used as shown. WimpExt_ViewIcon &4638B ------------------------------- R0 = movement type: 0 = scroll window minimum amount necessary 1 = centre icon in window (only if it's currently outside the window) 2 = choose 0 or 1 depending on how far outside the window the icon is R2 = window handle (or -1 for caret window and icon) R3 = icon handle (if R2<>-1) Checks to see if the specified icon is in the portion of the window which is visible on the screen, and scrolls the window to display it if it isn't. If R2=-1 then the icon containing the caret (if if belongs to your task) is used. R0=2 is the recommended movement type to use. Pointer handling ================ Pointer changes over icons are controlled by the 'wp' validation command. 'wp' (change pointer) Syntax: wp<pointer name>,<x hotspot>,<y hotspot> The x and y hotspots are optional. What happens is that when the pointer is over the icon it will changed to the named sprite. The 'hotspot' is the area that is the actual 'point' of the pointer. Apart from the following supplied standard pointers, the sprite must be in the Wimp sprite pool. Standard supplied pointers are: ptr_write (4,4) should be used over writeable icons ptr_menu (6,5) should be used over icons that lead to menus when clicked with SELECT ptr_direct (12,6) should be used for resizing objects ptr_hand (10,9) should be used for dragging objects ptr_cross (8,4) should be used for accurate pointing All these pointers are stored (with hi-res versions as well) inside the WimpExtension module itself, so they are always available. Pointer sprites should be designed in mode 8, maximum size 32x32 pixels. You should be wary of using logical colour 2 in pointer sprites, as it doesn't work in high-res mono modes. The pointer can have a palette if you want it to. If you are in a hi-res mode then WimpExtension will try to use a sprite of name "<pointer>22", and then try "<pointer>" if that didn't work. Therefore you can supply hi-res pointers as well (they should be in mode 19). The pointer changing is done entirely by the WimpExtension task, so you CAN disable null events and pointer changing will still work. On RISC OS 3 the 'p' command is attempted by the operating system, so WimpExtension uses the 'wp' command as RISC OS gets the pointer changing wrong. There is also a SWI provided so that your program can change the pointer directly: WimpExt_SetPointer &45795 ------------------------------- R0 = pointer to sprite name in the Wimp sprite pool, or 0 to reset pointer If R0>0: R2 = hotspot X R3 = hotspot Y Stores the old pointer palette, and changes the pointer palette and shape to the sprite specified in R0 (palette optional). The 'hotspot' is defined by the X and Y coordinates (pixels) in R2 and R3. If R0 is 0 then it will reset the pointer to its original state. You don't need to check if the pointer is already reset or changed as WimpExtension will do this for you. Note that the pointer will keep changed until you specifically ask for it to be reset - ie. pointer changes over icons will be suspended, and the pointer will remain changed outside your window's workarea. WimpExt_LimitPointer &457A2 ------------------------------- R0 = window handle Limits the mouse pointer to the visible area of the window specified. Note that if there are draggable objects within this area and these are used then the mouse rectangle is reset. It is also reset if there is a change of mode, eg. if the user presses F12 and then Return. WimpExt_ReleasePointer &457A3 ------------------------------- Releases the limits on the mouse pointer - ie. sets the mouse rectangle to be the entire screen. Note that this call resets the graphics origin and the graphics and text windows (ie. it does a 'VDU 26'). Colour menus ============ Colour menus are useful if you want the user to be able to select any WIMP colour for some reason. WimpExtension will automatically create a colour menu for you, and will work out whether each menu item should be black or white. WimpExt_ColoursMenu &45797 ------------------------------- R0 = colour to be ticked R2 = 0 to have just colours, 1 to have extra option Exit: R0 = pointer to colour menu Creates a colour menu (like Edit's 'Background' and 'Foreground' ones), making the text of each option black or white depending on the brightness of that colour in the current palette. If the value in R0 on entry is in the range 0-15 then that colour will be ticked in the menu. The call returns a pointer to the menu block (in RMA workspace). If the value in R2 on entry is 1 then a 17th option will be added, 'Transparent'. You can change the text of this by changing the menu block if you want (it's in RMA). The 17th option will be ticked if R0 on entry is 16. Window handling =============== WimpExt_CentreWindow &45799 ------------------------------- R1 = pointer to block: R1 + 0 visible area minimum x coordinate R1 + 4 visible area minimum y coordinate R1 + 8 visible area maximum x coordinate R1 + 12 visible area maximum y coordinate R1 + 28 window flags Exit: Block contains altered coordinates This call shifts the x coordinates in the supplied block so that the window described would be centred horizontally on the screen. You can use this call before Wimp_CreateWindow - eg: SYS "WimpExt_CentreWindow",,q% SYS "WimpExt_CreateWindow",,q% TO handle% or you can use it before Wimp_OpenWindow - eg: SYS "WimpExt_CentreWindow",,q%+4 SYS "WimpExt_OpenWindow",,q% If you are using WimpExt_LoadTemplates then windows can be centred automatically for you (see description above). WimpExt_CentreWindowV &457BE ------------------------------- R1 = Pointer to block: R1 + 0 visible area minimum x coordinate R1 + 4 visible area minimum y coordinate R1 + 8 visible area maximum x coordinate R1 + 12 visible area maximum y coordinate R1 + 28 window flags Exit: Block contains altered coordinates This call shifts the y coordinates in the supplied block so that the window described would be centred vertically on the screen. You can use this call before Wimp_CreateWindow - eg: SYS "WimpExt_CentreWindowV",,q% SYS "WimpExt_CreateWindow",,q% TO handle% or you can use it before Wimp_OpenWindow - eg: SYS "WimpExt_CentreWindowV",,q%+4 SYS "WimpExt_OpenWindow",,q% If you are using WimpExt_LoadTemplates then windows can be centred automatically for you (see description above). WimpExt_CheckWindowOpen &4579D ------------------------------- R0 = window handle (or -3 for requester window) Exit: R0 = 0 if window closed, 1 if open Checks to see if the specified window is open. WimpExt_SetWindowTitle &4579F ------------------------------- R2 = window handle R3 = pointer to string Copies the string in R3 into the window whose handle is in R2. The title must be indirected. Updates the screen if necessary. WimpExt_OpenFullSize &457A4 ------------------------------- R2 = window handle R3 = window to open behind (-1 = top, -2 = bottom) Opens the window to maximum size - ie. the same as clicking on the toggle icon. WimpExt_SetExtent &457B5 ------------------------------- R0 = window handle R1 = pointer to block R1+00 = new work area minimum x R1+04 = new work area minimum y R1+08 = new work area maximum x R1+12 = new work area maximum y Sets the work area extent of the specified window, altering the values to be whole pixels, and reopening the window (if already open) so that the change is reflected on the screen. Key handling ============ As it is often needed that RETURN do the same as clicking on the default icon (the one with border type 2), and also that the up and down arrow keys move to writeable icons above and below, WimpExtension will handle these keys for you. Simply include the validation code 'wr' in the writeable icon's validation string: 'wr' Syntax: wr[RETURN icon number],[up icon number],[down icon number] The icons specified will be used when the user presses RETURN, up arrow (or shift-tab) and down arrow (or tab) respectively. If the icon specified is a writeable icon then the caret will be moved to that icon, otherwise WimpExtension will generate a fake Mouse_Click event for that icon, which will make it appear to your task as if the user clicked with button status %100 on the icon (the mouse coordinates given will be those of the caret). You may leave out any of the numbers in the syntax, if you do so then WimpExtension will not affect the handling of that key. WimpExt_PutCaretIcon &4579B ------------------------------- R2 = window handle R3 = icon handle Works out the length of the text icon specified and calls Wimp_SetCaretPosition to position the caret at the end of the string. WimpExt_MoveCaretIcon &46384 ------------------------------- R2 = window handle R3 = icon handle Moves the caret into the specified icon, keeping its vertical position as nearly unchanged as possible. If the caret is currently disowned then it is placed at the end of the string in the icon. WimpExt_MoveCaret &457B6 ------------------------------- R0 = key R2 = window handle R3 = icon handle Exit: R0 preserved if no action taken, 0 otherwise Moves the caret from its current writeable icon to the next one above or below (in number) if the key in R0 is up arrow (or shift-tab) or down arrow (or tab). If you set bit 8 of R2 on entry to WimpExt_Initialise then this SWI will be called automatically for you in WimpExt_Action, and the reason code translated to a null event if the key is processed. Radio icons =========== There are a couple of validation commands for helping with radio icons. 'ws' allows icons to select and deselect other icons when clicked on, and 'wu' allows icons to shade and unshade other icons. 'ws' Syntax: ws<action>,<icon>[,<icon>][,<icon>][,<icon>]... The action code is as follows: 0 deselect specified icons 1 select specified icons 2 toggle specified icons The syntax is exactly the same for 'wu' except that the icons will be shaded instead of selected. You can specify several of these commands in one validation string - eg. 'ws1,4;ws2,5;ws0,1'. Menu handling ============= WimpExtension can do a couple of helpful things with menus. If you use WimpExt_CreateMenu instead of Wimp_CreateMenu and you set bit 1 in R2 when you call WimpExt_Initialise then WimpExtension will automatically recreate menus when the user clicks Adjust. WimpExt_OpenDialogue &4579C ------------------------------- R2 = window handle R3 = X Offset R4 = Y Offset Opens the specified window using Wimp_CreateMenu at the pointer position, offset by R3 and R4. The coordinates used are PointerX-R3,PointerY+R4. WimpExt_CreateMenu &457AC ------------------------------- R1 = pointer to menu structure, or window handle, or -1 to close menus R2 = menu X R3 = menu Y Exactly the same as Wimp_CreateMenu, except that the parameters are stored so that, after you have processed the selection, if the user clicked ADJUST you can call WimpExt_ReCreateMenu (see below) to reopen the menu, or this can be done for you (see WimpExt_Initialise). WimpExt_ReCreateMenu &457AD ------------------------------- Reopens the last menu opened with WimpExt_CreateMenu. Generates an error if the last operation was to close a menu, or if you have not called WimpExt_CreateMenu yet. WimpExt_ShadeEntry &457AE ------------------------------- R1 = pointer to menu structure R2 = number of option to shade/unshade (0...nn) R3 = 0 to unshade, any other to shade If bit 6 of R2 was set in WimpExt_Initialise: R3 = 0 to unshade entry, 1 to shade icon, 2 to toggle shade flag Exit: R0 = old state of menu entry (0 for unshaded, 1 for shaded) Shades or unshades the specified menu entry. If bit 6 of R2 was set in WimpExt_Initialise then the alternative parameters are used as shown. WimpExt_TickEntry &457AF ------------------------------- R1 = pointer to menu structure R2 = number of option to tick/untick (0...nn) R3 = 0 to untick, any other to tick If bit 6 of R2 was set in WimpExt_Initialise: R3 = 0 to untick entry, 1 to tick entry, 2 to toggle tick flag Exit: R0 = old state of menu entry (0 for unticked, 1 for ticked) Ticks or unticks the specified menu entry. If bit 6 of R2 was set in WimpExt_Initialise then the alternative parameters are used as shown. WimpExt_MenuWidth &46382 ------------------------------- R1 = pointer to menu structure This SWI scans through the specified menu, altering its width and the widths of all its submenus, so that all the menus are the minimum width possible while still displaying the text correctly (and neatly). Incrementing and decrementing icons =================================== If, as is often the case, you have a number in an indirected icon on the screen and you want the user to be able to alter it, it is nice to have bumper icons next to it as well as making it writeable. For this purpose, you can specify that an icon should decrement/increment another icon when clicked on in the validation string. The syntax of the command is: 'wi' (increment) Syntax: wi<icon>,<minimum>,<maximum>,<step> The default values are: wixx,0,&7FFFFFFF,1. All the values are optional apart from the icon number. To make it decrement the icon instead, use a negative step value. If the user clicks with Adjust instead of Select then the icon will be incremented instead of decremented, or decremented instead of incremented, in keeping with other RISC OS features. See 'icon handling', WimpExt_IncNumberIcon and WimpExt_DecNumberIcon for more information. Requester windows ================= A requester window has a title message, a text string, and up to four buttons. It can be used as a general-purpose way of asking the user for some response which must be answered before anything else happens - like the Wimp's Wimp_ReportError window, but a lot nicer and more flexible. An advantage of the requester windows is that you can specify the text of the buttons, what Escape and Return do, and the computer still multitasks while the requester is open. (If you don't want a multitasking requester, see 'Immediate windows'.) WimpExt_OpenRequester &457A6 ------------------------------- R2 = title (eg. 'Message from MyTask') R3 = text (eg. 'Document not saved. Save?') R4 = pointer to block containing button definitons text for default button (eg. 'Save') text for button 1 (eg. 'Discard') text for button 2 (eg. 'Cancel') ... R5 = button to be used if 'Escape' is pressed (0-3) Opens a requester box with a title, a message and some buttons along the right-hand edge. The pointer is constrained to the requester window. The buttons may contain any text up to 8 characters. You can have up to 4 buttons. They are filled with the text specified from the bottom one (the default) upwards. If the text for a button is a null string then that button will not be created. If the user presses Return then the default button is pressed. If the user presses Escape then the button specified in R5 is pressed. Mouse_Click events to the requester window will be passed from WimpExt_Action filtered so that only Select and Adjust are passed through, the window handle is -3, and the icon handle will be 0-3. You can check whether the requester window is open by using WimpExt_CheckWindowOpen. WimpExt_CloseRequester &457A7 ------------------------------- Closes the requester window and releases the mouse pointer. This is done automatically if the user selects a button in the requester box, or presses Escape or Return. If the window wasn't open then no error is generated. Help ==== WimpExtension provides a couple of SWIs and a validation command to make providing multitasking help easier. The validation command is: 'wh' (help) Syntax: wh<message> When the pointer is over the icon, Acorn's Help application would display the message specified. If you set bit 5 of R2 when you called WimpExt_Initialise, specifying 'semi-automatic' help then, instead of sending the message to Help for you, WimpExtension will instead give YOU a message, &45783, giving you the suggested help string. This feature was suggested by Peter Greenham, so that help strings can be converted via MsgTrans. The message format is as follows: R1+16 &45783 R1+20 mouse X R1+24 mouse Y R1+28 button state R1+32 window handle (-1 for background, -2 for icon bar, -3 for requester window) R1+36 icon handle R1+40 suggested text You may notice that this is the same as message &502, with the message number changed and the suggested text tagged on the end. To send this on unchanged, you would use: SYS "WimpExt_SendHelp",q%+40,q% WimpExt_SendHelp &457AA ------------------------------- R0 = message text R1 = pointer to message block containing message of type &502 or &45783 Sends a reply to message type &502, with the specified text. The message will appear in Help's Interactive Help Window, or WimpHelp's Standard Help Window. WimpExt_SendWimpHelp &457AB ------------------------------- R2 = keyword R3 = filename Sends a message to WimpHelp, telling it to open a hypertext help window from a file as specified in R3, with the keyword as specified in R2. Graphics handling ================= WimpExtension can help you with plotting sprites (including 256-colour ones) and also with operations on Draw files (including displaying them). WimpExt_SpriteOp &46386 ------------------------------- R0 = reason code +256 for user sprite area, R2 points to sprite name +512 for user sprite area, R2 points to sprite unless otherwise specified: R1 = sprite control block pointer (or +1 for Wimp sprite pool) R2 = sprite pointer other registers as appropriate for reason code This SWI performs various operations on sprites, including displaying them onto the screen (or printer). Note that these calls need ColourTrans if you are using them with 256-colour sprites. Sprites in the system sprite area are not supported. R0 = 0 : Display sprite ----------------------- R3 = x coordinate (OS units) R4 = y coordinate (OS units) R5 = plot action Plots the specified sprite on the screen. This call is mode-independent, so if necessary the sprite is changed size and/or the colours are chosen appropriately. R0 = 1 : Get palette -------------------- Exit: R3 = pointer to sprite's palette, or 0 if it doesn't have one R4 = number of entries in palette Locates the specified sprite's palette. R0 = 2 : Make pixel translation table ------------------------------------- R3 = pointer to block to contain table (1 byte per colour) Exit: block contains pixel translation data Calculates a pixel translation table for displaying the specified sprite in the current mode. If the sprite has no palette then the desktop's colours are used. R0 = 3 : Make scaling table --------------------------- R3 = pointer to 16-byte block to contain table Exit: block contains scaling table Calculates a scaling table for displaying the specified sprite at normal size in the current mode. R0 = 4 : Display sprite scaled ------------------------------ R3 = x coordinate (OS units) R4 = y coordinate (OS units) R5 = plot action R6 = pointer to sprite scaling table: R6 + 00 x multiplier R6 + 04 y multiplier R6 + 08 x divisor R6 + 12 y divisor Plots the specified sprite on the screen, scaled according to the table. This call is mode-independent, so if necessary the sprite is changed size and/or the colours are chosen appropriately. The sprite is first scaled to be the correct size in the current mode, then the specified scaling table is used. R0 = 5 : Copy sprite -------------------- R3 = pointer to destination sprite area (or +1 for Wimp sprite pool) Copies the specified sprite into the destination sprite area. Gives an error if there isn't enough room. Note that sprites with duplicate names will NOT be overwritten; you will end up with two sprites with the same name. R0 = 6 : Copy sprite area ------------------------- R1 = source sprite control block pointer (or +1 for Wimp RMA sprite pool, or +2 for Wimp ROM sprite pool) R2 = target sprite control block pointer (or +1 for Wimp sprite pool) Copies ALL the sprites from the source sprite area to the target sprite area. Gives an error if there isn't enough room. Note that sprites with duplicate names will NOT be overwritten; you will end up with two sprites with the same name. R0 = 7 : Remove duplicate names ------------------------------- R1 = sprite control block pointer (or +1 for Wimp sprite pool) Checks for sprites with duplicate names. If any exist, all copies except the LAST one will be deleted. R0 = 8 : Copy sprite area sprite by sprite ------------------------------------------ R1 = source sprite control block pointer (or +1 for Wimp RMA sprite pool, or +2 for Wimp ROM sprite pool) R2 = target sprite control block pointer (or +1 for Wimp sprite pool) Copies ALL the sprites from the source sprite area to the target sprite area. Gives an error if there isn't enough room. The sprites will be copied one by one, with duplicate sprite names removed before each copy. This means that this call, while being slower than 'Copy sprite area' followed by 'Remove duplicate names', often requires less free memory in the target sprite area. R0 = 9 : Check if sprite needs to be transformed ------------------------------------------------ R3 = mode to check for, or -1 for current mode Exit: R0 = bit meaning if set 0 a pixel translation table would be needed 1 a scaling table would be needed 2-31 undefined; will be 0 if the sprite doesn't need transforming Checks whether the specified sprite needs to be scaled or needs a pixel translation table to be plotted correctly in the specified mode. If either of these things are required, other WimpExt_SpriteOp calls exist to calculate them for you. R0 = 10 : Global replace ------------------------ R3 = search colour R4 = replace colour Replaces all pixels of colour R3 with pixels of colour R4. This routine isn't very fast, but it works. Currently it won't work with 256-colour sprites. WimpExt_DrawOp &46385 ------------------------------- R0 = reason code other registers as appropriate for reason code This SWI performs various operations on Draw files, including rendering them onto the screen (or printer). R0 = 0 : Render draw file ------------------------- R1 = pointer to scaling and position table: R1+00 = amount to multiply X by * 65536 R1+04 = 0 R1+08 = 0 R1+12 = amount to multiply Y by * 65536 R1+16 = X origin (OS units) R1+20 = Y origin (OS units) R2 = pointer to first object (ie. beginning of Draw file+40) R3 = pointer to end of file R4 = pointer to graphics clip box, or 0 for no clipping: R4+00 = XMin R4+04 = YMin R4+08 = XMax R4+12 = YMax Exit: F0-F2 corrupted This call displays a draw file. Objects will be checked one by one to see if they are in the clipping area, and redrawn if they are. Currently the following objects are supported: 0 - font table 1 - text 2 - path 5 - sprite 6 - group 7 - tag This is all the objects specified in the RISC OS 2 PRMs, except for text AREA objects, which are hardly ever used and are very very complicated. Magnifying a draw file by more than about 8 times is probably not a good idea because rounding errors in the Draw module will start to become significant. Note that this call requires the ColourTrans module. It also requires the FPEmulator module, if and only if the scaling is not 1:1. This call replaces the old SWI WimpExt_RedrawDraw, which should now not be used. (This call is much better anyway.) R0 = 1 : Calculate bounding box ------------------------------- R2 = pointer to first object R3 = pointer to end of last object Exit: R4 = XMin (Draw units) R5 = YMin (Draw units) R6 = XMax (Draw units) R7 = YMax (Draw units) Calculates the bounding box of the specified objects. The coordinates are returned in Draw units (which are OS Units * 256). Grouped objects are not checked individually - the group's bounding box is used. Unknown object types will not be checked. (This call 'knows' all the types described in the RISC OS 2 PRMs.) R0 = 2 : Register unknown object handler ---------------------------------------- R2 = pointer to routine (or 0 for no unknown object handler) R3 = pointer to workspace This routine will be called if the Render Draw File code encounters an unknown object. The routine has the following entry and exit conditions: Entry: (SVC mode) R2 = pointer to object R4 = pointer to scaling and position table R6 = clipping rectangle XMin (pretransformed) R7 = clipping rectangle YMin (pretransformed) R8 = clipping rectangle XMax (pretransformed) R9 = clipping rectangle YMax (pretransformed) R12 = your workspace pointer R13 = pointer to supervisor stack (at least 256 bytes guaranteed) R14 = return address Exit: R1-R11,R13 preserved V flag set on error, with R0 pointing to standard error block WimpExtension's Sprite Pool =========================== WimpExtension has a built-in Font menus ========== Font menus have tended to be huge and impossible to use, with every single variety of every single font listed all in one menu. WimpExtension will automatically create a hierarchial font menu for you, with all the fonts listed by family. Note that you must set bit 2 of R2 when you call WimpExt_Initialise if you wish to use font menus. WimpExt_GetFontMenu &457B7 ------------------------------- R0 = 0 to unshade 'System font' entry, 1 to shade it R1 = pointer to menu title (12 chars max), or 0 for default title ('Font') Exit: R1 = pointer to menu structure Reads in the list of fonts currently available and creates a hierarchial menu structure with all the fonts listed by family. 'System font' is also on the root menu. This menu structure is guaranteed to remain in the same place for as long as your task is active. The font list MAY be read in the first time you call WimpExt_GetFontMenu, or it may have been read in earlier. This SWI may only be called if you set bit 2 of R2 when you called WimpExt_Initialise. WimpExt_DecodeFontMenu &457B8 ------------------------------- R0 = pointer to buffer for font name R1 = pointer to Wimp_Poll block, reason code Menu_Selection The font menu is decoded and the correct font name is placed in the buffer. If the user selects, for example, 'Trinity' of 'Trinity.xxx','Trinity.yyy' the submenus will be followed through, and the font name at the top of each menu used. This SWI may only be called if you set bit 2 of R2 when you called WimpExt_Initialise. Immediate windows ================= Immediate windows are nothing to do with the Wimp. They are redrawn entirely by WimpExtension, and do not multitask. They can be for reporting the progress of a non-multitasking operation, or for getting an immediate response from the user. Because the redraw routine is entirely within WimpExtension, not all features of windows and icons are supported. Windows are fully supported apart from scrollbars and the control icons in the window border. Icons at the moment don't include sprites, but this will be improved upon in a later version of WimpExtension. WimpExt_ControlImmediate &457B9 ------------------------------- R1 = 0 or -1 : close immediate window = 1 : check for mouse click in immediate window = 2 : open immediate requester and wait for mouse click = 3 : redraw icon - icon handle in R0 = 4 : slab icon - icon handle in R0 (-1 to use currently slabbed icon), R2 = 1 to slab in, 0 to slab out = 5 : limit pointer to immediate window = 6 : redraw icon's 3D border - icon handle in R0 = 7 : redraw icon: R0 = pointer to icon block R2 = 'Work area' X origin R3 = 'Work area' Y origin >= &8000 : open immediate window using data pointed to by R1 If R1 = 2 then rest of registers as for WimpExt_OpenRequester Exit: If R1 = 1 or 2 : R0 = Icon handle of icon clicked on, or -1 for none This SWI is for using windows like the Wimp_ReportError window that are not multi-tasking. You can only have one 'immediate window' open at a time, it is always on top of the window pile, and you MUST NOT call 'Wimp_Poll' while the immediate window is open. If R1 is 0 or -1 on entry, the immediate window is closed. If it was not open then no error is generated. If R1 is 1 on entry, then the program will check for mouse clicks on icons in the window. 3D icons will be slabbed automatically. -1 is returned if no iconwas clicked on. If R1 is 2 on entry, the rest of the registers are as for WimpExt_OpenRequester. It opens an 'immediate requester' and waits for a mouse click on one of the action buttons, or ESCAPE or RETURN. The icon clicked on is returned in R0. If R1 is 3 on entry, the icon in the immediate window whose handle is in R0 will be redrawn (presumably because you have changed the indirected data). The 3D border is not redrawn. If R1 is 4 on entry, the icon whose handle is in R0 will be slabbed in or out depending on R2 - similar to WimpExt_SlabIcon for normal icons. If the specified icon handle is -1 and R2 is 0 then the currently slabbed icon (if any) is used. If R1 is 5, the mouse rectangle is redefined to be the size of the immediate window - similar to WimpExt_LimitPointer for normal windows. Use WimpExt_ReleasePointer to release the pointer again afterwards. If R1 is 6, the specified icon's 3D border is redrawn. If R1 is 7, the specified icon is drawn. You do not need to have an immediate window open to use this reason code. If R1 is greater than or equal to &8000 on entry, then an immediate window is created from the Wimp_CreateWindow block pointed to by R1. If you call WimpExt_PrePoll while an immediate window is open then it will be closed automatically - the Wimp does not know about immediate windows and the screen display would become corrupted if you kept an immediate window open over a call to Wimp_Poll[Idle]. Icon types currently supported are: sprite-only non-indirected text-only, all types Unknown icon types will be ignored. Heap manager ============ One of the biggest problems in writing multitasking programs (or single- tasking ones for that matter) is memory management. For any program which has more than one memory array which may change size during use it can get very complicated. For this reason, WimpExtension provides a complete heap manager. You call the initialise routine at the beginning of your program, and from then on whenever you need some memory simply ask for it, and return it when you don't need it any more. WimpExtension will automatically tidy the heap, and reduce and enlarge the WimpSlot where necessary/possible. The heap management system takes control of all your task's memory above the start of the heap (specified when you call the initialise routine). You should NOT change your task's WimpSlot when using the heap management routine (ie. don't call Wimp_SlotSize with R0<>-1). So that the memory blocks can be moved about by the tidy routine, you are not given the address of the block, but the address of its 'anchor'. This is a single word which points to the block. The tidy routine can then move the block about and then update the anchor so you still know where it is. Note that blocks will not mysteriously move on their own, they will only move on calls to WimpExt_Heap, and then only for reason codes 5, 6, 11 and 12. (See below.) You specify the number of anchors to create when calling WimpExt_Heap's initialise routine. More anchors can be created later using the increase anchors routine, but this is quite slow. If you use the 'allocate with extend' routine for allocating blocks then the increase anchors routine will be called for you automatically when necessary. You cannot decrease the number of anchors. If you specify 0 anchors in the initialise entry then a default value of 256 is used - this is loads and should be more than sufficient for most needs. Note that the size of all memory blocks is a multiple of 8 plus 4 (ie. size = 8N+4). The size will be rounded up on calls to the allocate routine. The size of the block is stored 4 bytes before the start of the block. All blocks are guaranteed word aligned. When calling WimpExt_Heap routines, you can either refer to a block by a pointer to it, or by a pointer to its anchor. I will refer to this as a 'block pointer'. The tidy routine can be automatically called once a second in WimpExt_PrePoll if you set bit 3 of R2 when you call WimpExt_Initialise. Remember not to mask out null events, though - it's probably best to use Wimp_PollIdle. The routines are fairly robust, and will usually produce the error 'Heap corrupt' or 'Bad heap operation' rather than an address exception or corrupting memory if something goes wrong. Both of these should probably be treated as fatal errors, but you can do with them what you like. Note that when there are no blocks allocated in the heap, it takes no memory at all - even the list of anchors is destroyed. This means that if you are a module task with a heap at &8000 then you won't be unnecessarily using 16k (or whatever page size the computer is using) all the time. The calls all act on the currently selected heap. Use the call R0=14 to select different heaps. Heaps are specified through a 'heap pointer', which is set out as follows: +00 hp_heap offset of heap data area +04 hp_free offset of first free block, or 0 if no free blocks +08 hp_anchors offset of first anchor +0C hp_heapsize total size of heap in bytes +10 hp_heapfix 'fixed' counter +14 hp_tidytime monotonic time of last Tidy call +18 hp_heaptidy tidy flag; 0 if heap is fully tidied, non-zero otherwise +1C hp_created created flag; 0 if heap is uncreated, non-zero otherwise +20 hp_base pointer to base of heap memory +24 hp_pagesize 'page' size +28 hp_setsize pointer to routine to change size of heap, entered in SVC mode: R0 = size required R10 = heap pointer R13 = supervisor stack R14 = return address exit: R0 = 0 indicates failure, non-zero indicates success all other registers preserved +2C hp_numblocks number of blocks claimed +30 hp_rootptr pointer to pointer to base of heap memory +34 hp_misc depends on what sort of heap this is See the file "Heap" for a detailed explanation of the heap memory manager. WimpExt_Heap &457BA ------------------------------- R0 = reason code other registers as appropriate for reason code R0 = 0 - Initialise standard heap: ---------------------------------- R1 = pointer to base of heap R2 = number of anchors to allocate Initialises the standard heap. R1 points to the base of the heap - it will grow upwards from here. R2 specifies the numbers of anchors to allocate initially. Each anchor takes 8 bytes. Note that R1 is rounded up to the nearest multiple of 8 plus 4 (ie. 8N+4). The heap is automatically selected as the current heap. R0 = 1 - Describe heap: ----------------------- Exit: R0 = currently selected heap pointer, or +1 for standard heap R2 = largest available block size R3 = total free R4 = memory used by heap R5 = number of anchors allocated R6 = number of anchors in use Adds up all the sizes of the free blocks, and returns information about memory used by the heap. If the heap is empty then R2-R6 will be zero. R0 = 2 - Allocate block: ------------------------ R2 = size of block required Exit: R1 = pointer to anchor or zero if allocation failed Tries to find a block of the required size. Increases the WimpSlot if necessary. If a call to Wimp_SlotSize fails then zero will be returned. Note that the size is rounded up to the next multiple of 8 plus 4. R0 = 3 - Free block: -------------------- R1 = block pointer Frees the memory used by the specified block. R0 = 4 - Reallocate block: -------------------------- R1 = block pointer R2 = new size required Exit: R1 = pointer to anchor (the same anchor as before) or 0 if reallocate failed Tries to resize the specified block. You should check R1 on exit to see if the resize was successful (only on increasing the size, decreasing the size will always be successful). R0 = 5 - Tidy heap: ------------------- Tries to tidy the heap, reducing the WimpSlot if possible. This can be automatically performed once a second (in WimpExt_PrePoll) if you set bit 3 of R2 when you called WimpExt_Initialise. Note that this routine does not tidy the heap fully, it just does a little bit each time it is called. This is to keep the time cost down. R0 = 6 - Compact heap: ---------------------- Repeatedly calls Tidy Heap, until the heap is as small as it can get. R0 = 7 - Find anchor: --------------------- R1 = block pointer Exit: R1 = pointer to anchor Given a block pointer, returns a pointer to that block's anchor. R0 = 8 - Fix blocks: -------------------- Fixes the heap. Subsequent calls to the Tidy or Compact routines will have no effect. Effectively, the heap becomes a non-relocatable heap like the RMA. This call is provided so that if you temporarily need to rely on the blocks not moving, you can easily do so. WimpExtension keeps a counter of the number of times you call this routine, so that if you, for example, fix the blocks twice in a row then you need to unfix them twice in a row before they are actually unfixed. R0 = 9 - Unfix blocks regardless of counter: -------------------------------------------- Unfixes the heap, so that garbage disposal routines will work again. This call zeroes the counter straight away - ie. the blocks are immediately unfixed no matter how many times you called the fix routine. R0 = 10 - Unfix blocks: ----------------------- Unfixes the heap, so that garbage disposal routines will work again. This routine decrements the fix counter, and only actually unfixes the blocks if the counter reaches zero. R0 = 11 - Increase anchors: --------------------------- R2 = number of anchors to add Exit: R1 = 0 indicates failure, non-zero indicates success Increases the number of anchors. This routine is quite slow as it often has to move the entire heap up in memory so you should use this routine sparingly, if you need to use it at all. Note that this SWI causes blocks to be relocated. R0 = 12 - Allocate with anchor extend: -------------------------------------- R2 = size of block required Exit: R1 = pointer to anchor or zero if allocation failed Tries to find a block of the required size. Increases the WimpSlot if necessary. If a call to Wimp_SlotSize fails then zero will be returned. Note that the size is rounded up to the next multiple of 8 plus 4. If no free anchors are available then the increase anchors call is used to make some more; therefore using this SWI can cause blocks to be relocated. It is, however, the recommended call to use for allocating blocks as it isn't limited by the number of anchors already created. R0 = 13 - Free all blocks ------------------------- Frees all blocks in the currently selected heap belonging to your task. R0 = 14 - Select heap --------------------- R1 = heap pointer, or +1 for standard heap, or -1 for no change Exit: R0 = previous heap pointer, or 0 if no previously selected heap R1 = current heap pointer, or 0 if no currently selected heap Selects a new heap to be used by the other WimpExt_Heap calls. R0 = 15 - Relocate heap ----------------------- Compares the heap addresses specified by hp_base and hp_rootptr. If they are different, then hp_base is updated by hp_rootptr, and the anchors are recalculated to account for the change of address. R0 = 16 - Create a heap in a heap block --------------------------------------- R1 = heap pointer (blank, it will be filled in by this call) R2 = number of anchors to create Exit: R1 = heap pointer, or 0 if the call failed due to lack of memory This call creates a new heap inside a heap block in the currently selected heap. The new heap is NOT selected as the current heap. Data transfer ============= WimpExtension can handle saving files if your file is in a contiguous area of memory (ie. not split up in several chunks all over the place). You just call WimpExt_DataSave when you receive the User_Drag_Box event from the user dropping the icon in a filer window or onto another task. When the transfer is complete (successful or otherwise) you will be sent a message, &45782, telling you that the transfer is complete, and whether everything went OK. The SWI supports the full data transfer protocol, including the Wimp$Scrap method and RAM transfer. Note that if you are saving from a WimpExt_Heap block, you should fix the heap beforehand, and unfix it afterwards. WimpExtension can also handle loading of files. Files can either be loaded into a WimpExt_Heap block (the preferred method) or they can be loaded into a fixed-size area of memory. Use is similar to WimpExt_DataSave - you just pass the DataSave or DataLoad message to WimpExt_DataLoad, and wait for a message telling you the transfer is complete. WimpExt_DataSave &457BC ------------------------------- R0 = File length R1 = Pointer to filename (pathname or leafname) R2 = File type R3 = Pointer to data R4 = Zero to allow files to be saved to your own task, non-zero otherwise Exit: R0 = 0 if failed due to attempt to save to own task, non-zero otherwise Used to save a file from your program to a filer or to another task. When you receive the User_Drag_Box event after the user has dragged the icon to where they want it put, call WimpExt_DataSave to handle the data transfer. If R4 is non-zero on entry, then if the user has dragged the file to a window or icon belonging to your task then no action will be taken, and R0 will be zero on exit. Otherwise, when the transfer has finished, WimpExtension will send you a message, number &45782, with the word at R1+20 having the following meaning: 0 = file not saved 1 = file saved but is 'unsafe' (eg. saved to another task) 2 = file saved If the code is 2, then the filename the file was saved as is at R1+24. WimpExt_DataLoad &46383 ------------------------------- R0 = 0 : Load into heap block R1 = pointer to DataSave or DataLoad message block R2 = block pointer of block to receive file, or 0 to create new block R3 = offset in block to place file R0 = 1 : Load into fixed block R1 = pointer to DataSave or DataLoad message block R2 = pointer to block to receive file R3 = length of block Use this SWI to load files from the filer or other applications. If R0=0 then the file is loaded into a WimpExt_Heap block, and can be any length, memory permitting. If R0=1 then the file is loaded into a fixed area of memory, and will not be loaded if it exceeds the length of the area. When you receive the DataSave or DataLoad message, pass the block onto WimpExt_DataLoad, and the transfer will be handled automatically. As long as this SWI doesn't return an error, when the transfer has finished, WimpExtension will send you a message, number &45784, with the word at R1+20 having the following meaning: 0 = file not loaded. Error block at R1+28 1 = file transferred successfully from another task 2 = file loaded successfully from disc A pointer to the block's anchor is at R1+24, if it was loaded into a heap block. Otherwise a pointer to the area is at R1+24. If R1+20<>0 then the rest of the block contains: R1+28 = length of file R1+32 = load address of file R1+36 = exec address of file R1+40 = filename (leafname if transferred from task) Obviously you need to have initialised a heap to use this SWI. Note that WimpExtension won't free the block if there's an error; your error handler must do this if appropriate. The load and exec addresses don't indicate the date if the file was transferred from another task (the relevant bits will all be zero). Dragging icons ============== To make dragging icons about easier, WimpExtension provides a single SWI 'WimpExt_DragIcon'. Normally this will produce an ordinary rotating dash-box like normal. If you have the DragASprite module loaded, however, it can be made to use that instead (if the user has configured the computer to use this module by setting bit 1 of CMOS RAM location 28). The DragASprite module is included with RISC OS 3 and above. However, the module can be altered to work on RISC OS 2 by simply removing the call to OS_ReadSysInfo in the initialise entry. I have no idea whether it is legal to take a copy of DragASprite from a RISC OS 3 machine, alter it, and put it on a RISC OS 2 machine, so I haven't supplied a RISC OS 2-compatible copy of DragASprite. WimpExt_DragIcon &4579A ------------------------------- R0 = flags: 0-1 Horizontal position: 00 = left 01 = middle 10 = right 11 = undefined 2-3 Vertical position: 00 = bottom 01 = middle 10 = top 11 = undefined 4-5 Mouse bounding box: 00 = whole screen 01 = constrain to parent window 10 = constrain to box pointed to by R5 11 = undefined 6 constrain sprite if set, otherwise constrain pointer 7 shadow if set 8 use DragASprite even if CMOS flag isn't set 9-31 reserved; MUST BE 0 R1 = pointer to sprite block, +1 for Wimp sprite area, 0 to use dash box R2 = Window handle R3 = Icon handle R4 = pointer to sprite name (if R1<>0) R5 = pointer to mouse bounding box (only if necessary - see flags) +00 xmin +04 ymin +08 xmax +12 ymax This SWI does one of two things. If the DragASprite module is loaded, and bit 1 of byte 28 of the CMOS RAM is set, and R1<>0 then it will use the DragASprite module as follows: Work out the parameters to 'DragASprite_Start' and call it. If this produces an error then try again with dash box as described below. Otherwise it makes an ordinary rotating dash box as follows: Work out the parameters to 'Wimp_DragBox' and call it. Bits 0-3 and 7 of the flags are ignored. If you are using this SWI at any time with R1<>0 then remember to call XDragASprite_Stop at appropriate points. You MUST use the X form of the SWI, and you must ignore errors. This SWI has been altered since version 1.63 of WimpExtension - if you wish to use it as before simply set R0 and R1 to zero. Defaults and sprites ==================== The 'WimpExt Defaults' command is intended to allow the user to customise the colours of the 3D borders, or to make the 3D borders flat. Whenever the command is issued, a message (no. &45791) is broadcast, and then the screen is redrawn. You can read the defaults settings by using WimpExt_MiscOp 0. The problem with making the 3D borders flat is that sprites in the window will still be 3D. For this reason, WimpExtension contains both flat and 3D versions of the most commonly used sprites. A pointer to the sprite area containing these sprites in returned in R2 when you call WimpExt_Initialise. The sprites available are: radioon, radiooff, optoff, opton, yes, no, inc1, dec1, dec, inc. A copy of the 3D sprites group is included in the file '3DSprs' so you can see the sprites while you're designing your templates. When you receive the 'defaults changed' message, you should read the new defaults, and make whatever alterations are necessary if the style has changed. Hotkeys ======= If you aren't using WimpExtension, and you want your task to provide a hot-key (ie. a key which does something even when your task doesn't have the caret) then you have to open a window permanently somewhere off the screen. This wastes memory on RISC OS 3, and means that you run out of windows even more quickly than usual on RISC OS 2. WimpExtension opens a hot-key window for you, and then will tell you about any key-press events it is given. This saves windows because one window is shared between all WimpExtension tasks. When WimpExtension receives a keypress event, it broadcasts a message as follows: R1+16 = &45790 R1+20 = key code If you decide to do something with the keypress, you should acknowledge the message to prevent WimpExtension from passing it on to other tasks. Miscellaneous SWIs ================== WimpExt_CurrentTask &4578B ------------------------------- R0 = task handle Exit: R0 = previous task handle Informs WimpExtension which task is currently active. Not needed if you have called WimpExt_Initialise or WimpExt_Action since the last Wimp_Poll. The previous user is returned in R0. WimpExt_Divide &45796 ------------------------------- R2 = Numerator R3 = Denominator Exit: R0 = Result R2 = Remainder Returns (R2 DIV R3) in R0 and (R2 MOD R3) in R2. Useful for calculating which area of window needs to be updated. An error is produced if R3 is zero on entry. WimpExt_CopyString &4579E ------------------------------- R2 = 'From' pointer R3 = 'To' pointer Copies the control-terminated string from R2 to R3. The string stored at R3 will be zero-terminated whatever the terminator was for the original string. WimpExt_FindLeaf &457A1 ------------------------------- R0 = Pointer to pathname Exit: R0 = Pointer to leafname Finds the last occurence of '.' in the string pointed to by R0, and returns a pointer to the next character. eg. given 'scsi::HardDisc.$.first.second.last' it will return a pointer to 'last'. This can be useful for both extracting the leaf name, and for determining what directory the file is in (by poking a zero to (R0-1) - eg. MOV R2,#0 STRB R2,[R0,#-1] ). WimpExt_MemCopy &457BB ------------------------------- R0 = 'From' address (word aligned) R1 = 'To' address (word aligned) R2 = Length (not necessarily word aligned) Exit: R0 preserved Copies an area of memory very quickly. Can cope with overlap, R0=R1 or R2=0. WimpExt_PlotBorder &457BD ------------------------------- R0 = reason code R0 = 0 => R1 = pointer to icon block R2 = window handle (or -1 for no window) R0 = 1 => R1 = pointer to block: R1 + 0 Minimum work area x coordinate R1 + 4 Minimum work area y coordinate R1 + 8 Maximum work area x coordinate R1 + 12 Maximum work area y coordinate R1 + 16 Border type R2 = window handle (or -1 for no window) Like Wimp_PlotIcon, except it just redraws the 3D border. R0 specifies how the coordinates and border type are to be specified. If bit 31 of R0 is set then the border will be plotted slabbed in. WimpExt_Sort &46380 ------------------------------- R0 = number of objects to sort R1 = pointer to array of objects R2 = pointer to comparison routine R3 = workspace pointer for comparison procedure R4 = size of object R5 = address of temporary workspace of R4 bytes (only needed if R4>63) This SWI will sort an array of objects. It is very similar to the OS_HeapSort SWI, except that you can use it to sort an array of ANY object, rather than just arrays of pointers. R2 points to a routine which is entered, in SVC mode, as follows: R0 = address of object a R1 = address of object b R12 = value supplied to WimpExt_Sort in R3 R13 = supervisor stack R14 = return address The routine should compare the two objects and return, preserving all registers apart from R0,R1,R12 and R14, with flags set as follows: a<b Z=0, C=0 a=b Z=1, C=1 a>b Z=0, C=1 The actual method of sorting is unspecified; suffice it to say it's fast... Although R5 doesn't have to be word-aligned, the sort will probably be faster if it is. WimpExt_MemMove &46381 ------------------------------- R0 = from R1 = to R2 = size in bytes Copies R2 bytes from R0 to R1. R0 and R1 need not be word-aligned, and R2 need not be a multiple of 4. This SWI uses the optimised memory copying routine given in the RISC OS 2 PRMs. It does not cope with overlap (which is why it's separate from WimpExt_MemCopy). WimpExt_Intersect &46387 ------------------------------- R0 = 0 : Boxes in registers: R2 = XMin1 R3 = YMin1 R4 = XMax1 R5 = YMax1 R6 = XMin2 R7 = YMin2 R8 = XMax2 R9 = YMax2 R0 = 1 : Boxes in blocks: R2 = pointer to XMin1,YMin1,XMax1,YMax1 R3 = pointer to XMin2,YMin2,XMax2,YMax2 Exit: If boxes intersect: R0 = 1, C flag set If boxes don't intersect: R0 = 0, C flag clear Checks whether the specified rectangles intersect. WimpExt_BorderOp &46388 ------------------------------- R0 = reason code other registers as appropriate for reason code R0 = 0 : Get border number -------------------------- R1 = pointer to icon block Exit: R0 = border number, or -1 if the icon has no 3D border Returns the number of the 3D border of the specified icon. -1 is returned if the icon has no 3D border. R0 = 1 : Get border width ------------------------- R2 = border number (0-6) Exit: R0 = width in OS units, or 0 if R2 did not contain a valid border number Returns the width of the 3D border outside the icon's bounding box. 0 is returned if an invalid border type is specified. R0 = 2 : Get bounding box in registers -------------------------------------- R1 = pointer to icon block Exit: R2 = XMin R3 = YMin R4 = XMax R5 = YMax Returns the bounding box of the icon, including the 3D border if present. R0 = 3 : Get bounding box in block ---------------------------------- R1 = pointer to icon block R2 = pointer to 16-byte block to receive bounding box Exit: R2 + 0 = XMin R2 + 4 = YMin R2 + 8 = XMax R2 + 12 = YMax Returns the bounding box of the icon, including the 3D border if present. WimpExt_MiscOp &4638A ------------------------------- R0 = reason code other registers as appropriate for reason code R0 = 0 : Read defaults ---------------------- R1 = pointer to block to read values (64 bytes long) Exit: R1 + 0 = top-left colour R1 + 4 = bottom-right colour R1 + 8 = in colour R1 + 12 = channel colour R1 + 16 = minimum slabbing time R1 + 20 = sprite style bit meaning 0 0 = 3D, 1 = flat 1-31 reserved Reads in the default values as specified by *WimpExt Defaults. The block should be at least 64 bytes long, to allow room for future expansion. R0 = 1 : Read window border thickness ------------------------------------- Exit: R2 = title thickness (OS Units) R3 = vertical scrollbar thickness (OS Units) R4 = horizontal scrollbar thickness (OS Units) Reads the thickness of the window borders. Needed because on RISC OS 3 Acorn rather stupidly decided to make it so that you can change their thickness. WimpExt_SubstituteArgs &4638C ------------------------------- R0 = pointer to template string R1 = pointer to buffer to hold resulting string R2 = pointer to string %0 R3 = pointer to string %1 R4 = pointer to string %2 R5 = pointer to string %3 R6 = pointer to string %4 Exit: R0 = pointer to zero-byte terminator of substituted string Takes a string of the form 'This is an %0 of the %1 of %2_%3' and substitutes the given strings when %0,%1,%2,%3 or %4 is encountered. eg: SYS "WimpExt_SubstituteArgs","This is an %0 of the %1 of %2_%3",q%,"example","use","WimpExt","SubstituteArgs" TO ,string$ would give 'This is an example of the use of WimpExt_SubstituteArgs'. Any strings not used in the template do not need to have sensible values in the corresponding register, although you may like to make the register zero, in which case WimpExtension will fault that string's use. To include a % in the template, use %%. WimpExt_RedirectSprites &4638D ------------------------------- R0 = pointer to sprite area control block, or +1 for Wimp sprite area R1 = pointer to Wimp_CreateWindow block Sets the sprite area control block pointer of all the indirected, sprite-only icons in the CreateWindow block to R0. OS commands =========== WimpExtension provides the OS-command 'X'. This is used to execute other OS commands, but any errors produced by that command will be ignored. This can be useful in obey files. eg: X Delete <Obey$Dir>.Backup X Rename <Obey$Dir>.Data <Obey$Dir>.Backup or X Run <Obey$Dir>.Title WimpExtension also provides a command 'WimpExt Defaults'. This is used to specify the default colours and slabbing time for 3D borders. The syntax is: *WimpExt Defaults <top-left> <bottom-right> <in> <channel> <time> <sprite style> The default defaults (ie. those used if you don't issue a WimpExt Defaults command) are 4 0 14 12 15 0. This command is NOT to be used by your programs; it is provided so that the user can decide what colour scheme THEY prefer. This command can also be used if you don't like 3D borders; if you try *WimpExt Defaults 7 7 3 1 15 1 you will find that all the borders are now completely flat. (And it doesn't look too bad, either.) The sprite style parameter is 0 for 3D sprites, and 1 for flat sprites. This allows you to choose whether you want flat or 3D sprites in WimpExtension applications which take note of this value. The Defaults command really is only to be used by the user, not by any programs. It'll probably be removed in a later version of WimpExtenion, when I put in the 'Style manager', which'll do all that WimpExt Defaults does and a lot lot more (TM). :-) BTW, There really IS a good reason for making it a bizarre two-worded command. All will become clear later ;-) Things possibly to be included in a later version... ==================================================== * Resizeable RamFS and common data area (very very useful) * List handling (quite useful when you come to think of it) * Fast text displayer (very useful) * Libraryification (quite literally, useful) <--- COMING SOON (hopefully) Plus anything else useful anybody comes up with... Improving immediate windows is definitely Acorn's problem - the fact that they are not provided in the Wimp is a major failing of the RISC OS desktop. (Or rather, they ARE provided in the Wimp, Acorn just haven't provided a way for us ordinary mortals to get at them.) Aha! RISC OS 3 now provides immediate icons, but not immediate windows. I'll add this into WimpExtension sometime, but I'm still waiting for immediate windows in the OS... (Look, come on. All we need is a SWI Wimp_FinishRedraw.) (Basically, by 2022 WimpExtension will be slightly larger than the solar system and will have more features than are dreamt of in your philosophy.) Thanks ====== Thanks to Aiden Corey (hope I spelt that right) for helpful suggestions. Thanks to Jon Thackray for disappearing off to Canterbury and claiming he's poor when he quite blatantly bought an A410 and an ARM3 and a huge hard drive, and Impression, and ... Thanks to James Ponder for uploading stuff to BBSes ( :-) <- that's a smiley, for people who haven't used bulletin boards, I mean, I didn't know what it was at first). James is really annoying and has a 14k4 modem, which is silly. Thanks to Mr. Clare, for looking mildly amused at whatever stunning programs I pass his way... Thanks to David Cox for being able to get me the SWI chunk for this module, and being the first person other than me to use it in one of their programs. (But certainly not the last ;-) ) Thanks to Ben Dooks for winning "Mr. Thinny" Contest three years running. Thanks to Andrew Clover for not being eight feet tall. Thanks to Acorn for making sprite and draw-file displaying so incredibly complicated, and for making RISC OS so flexible, honest. Finally, thanks to Ben Curthoys for generally complaining at me to get things finished (maybe I WILL write a game someday), and for a black plastic bag. (Which has now shuffled off this mortal coil :-( ). Plugs ===== Look out for other PD stuff by me... VEnd ... HourMake ... EliteCht ... RoughTime IV ... SWI ... StopClock ... Quitter ... WimpHelp (coming soon!) ... Also, products from other members of DoggySoft... The Hacker, only £5, the original and BEST games hacker - makes it incredibly easy to create cheats for games. Many many wonderful features. Just press Alt-Alt during the game, and The Hacker will pop up... (As seen in Acorn Computing, BBC Acorn User and Archimedes World...:-) ) Diss, only £10, by far the best desktop disassembler available for the Archimedes. Diss has FAR too many features to list them all here, but they include: * Multiple files/multiple views * FAST disassembly with optional colour-coding * Labels - you can add labels to any address to aid disassembly. eg. Instead of: B &381239471 you get: B mouse_click * Automatic un-squeezing of Squeezed files * Automatic labels generation for: Modules (eg. entry points, SWIs, OS commands, etc.) Shared C Library functions C programs BASIC in-line-assembler programs LINKed programs ABC programs * Search facilities (including search for reference (incredibly useful)) etc. etc. etc... Diss is invaluable for any serious programmer. (As seen in Archimedes World. :-) ) Finally ======= Any money, bug reports, information, demos, just about anything to: Jon Ribbens 39 Nutkins Way Chesham Bucks. HP5 2BE I can also be reached on Arcade BBS, but don't hold your breath...