ARM Club 1

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

/ ARM Club 1 / ARM_CLUB_CD.iso / contents / apps / program / d / eventshell / Docs / Manual-F < prev next >

Wrap

Text File | 1993-12-06 | 60.2 KB | 1,340 lines

Interim User Manual For EvntShell --------------------------------- 1 Introduction 2 Creating A New Application 3 A Tutorial 4 A General Overview 1. Dynamic Windows 2. Static Windows 3. Resources 1. Templates 2. Sprites 3. Message Files 4. Modules 4. Menus 5. Saving Files 6. Loading Files 7. Compressing EvntShell Applications 8. The RunTime Library 9. The !ShellSys Application 10. Handling Panes 11. Outline Fonts 12. Interactive Help 13. User Redraws 1. Simple cases 2. Drawing into a sprite 14. Complex Icon Types 1. Bump Icons 15. Memory Management 16. Error Handling 5 The Tools 1. !AppBuild 2. !ShellDBug 3. Other Tools 1. !BasShrink/!BasShrink_PD 2. !BLibII 3. !TemplEd 4. !StrongEd2 5. !StrongHlp 6. !ThrowBack 6 Distributing EvntShell Applications 7 Debugging 8 The Credits 9 Future Enhancements 10 Changes Since V1.09 1. Introduction A 'Shell' program is a starting point for developing your own applications that run under the RISC-OS wimp system. The EvntShell library contains code to handle most of the 'Events' (i.e. opening a menu, closing a window etc) that can occur, and all your application has to do is inform the library what it should do when certain events occur. For example a menu can be attached to a window or to an icon - the library will open the menu for you (in the correct position!) when the <MENU> button on the mouse is used. PROCshell_AttachModeChangeHandler is another very simple example which calls a function in the 'User Application' (this is the bit you write, starting with a 'Shell' created by the AppBuild tool or by modifying one of the examples) when the screen mode changes. A more complicated example is PROCshell_AttachPane which allows the attachment of pane windows to a parent window. All opening and closing of windows and panes is handled totally by the library code. Normally writing a wimp application is a very complex business, involving much reading of the Programmers Reference Manuals, magazine articles and examining other applications. The aim of the EvntShell library is to reduce the need for this and to enable the speedy creation of easily maintained and robust applications. Another important reason for using this Shell is that it attempts to ensure that any application written using it follows the RISC OS 3 Style Guide which defines how applications should look and behave. For example menus attached to icons ('popup' menus) appear to the right of the icon they are attached to and the mouse pointer is repositioned appropriately. Implementing the Style Guide recommendations is not easy and at the moment very few of the necessary changes to the library code have been made, however, this will improve in future releases. In order to use the library it is necessary to have a reasonable understanding of how to use an Archimedes and the programs supplied with it. Some experience in BASIC is also of course required. This manual does not cover how to use tools like the Template editor which has its own instructions and may not have been supplied with your copy of the EvntShell library. 2. Creating An Example Application The easiest way to create a new application is to use the AppBuild tool. Run this and drag the application icon from the AppBuild window to a directory display. The various options available using AppBuild will be discussed later, but for now just quit AppBuild and run the newly created application. You should see a blank icon appear on the icon bar and clicking <MENU> over this will bring up the usual icon bar menu including the items 'Info' and 'Quit'. 'Info' leads to the normal 'About This Program' window (the icons of which are blank at the moment) and 'Quit' which stops the application and removes it from the icon bar - don't quit it just yet. Clicking <SELECT> on the iconbar icon will open a window which has the usual controls and may be scrolled and moved around the screen. Keep the application you have just created handy as in the next section we'll look at the program code and see how to change it to suit your own needs. As you can see it is very easy to create a new shell application - even if this particular one doesn't do anything useful yet! 3. A Tutorial The first few lines of any EvntShell program initialise the memory management, set up error handlers and load any resources (templates, message files, sprites etc) required by the program. This code should not need editing. PROCapp_init determines what happens when the application starts, in this case an iconbar icon is created and various 'events' are attached to it. The code created by !AppBuild is as shown below, although the REMs have been added for this manual. Try defining other windows and menus and see what happens. DEF PROCapp_init PROCSetUp_Menus :REM set up iconbar menu PROCSetUp_Windows :REM set up main window PROCSetUp_IconBar :REM put icon on the iconbar and attach events REM and now initialise the StrongHlp help system (optional!) PROCshell_InitHelpSystem(FNshell_GetAppDir+".FNshell_GetAppName" ,TRUE) ENDPROC : REM ===== Menu_Setup routines =================================== DEF PROCSetUp_Menus LOCAL void% REM Construct the iconbar menu.. MenuHandle_IconBar%=FNshell_MenuNew("NewApp") MenuItem_Info% =FNshell_MenuAdd(0,"Info","") void% =FNshell_MenuAdd(0,"Quit","_MenuSelect_Quit") REM Attach the 'About this program' dialog box to the 'Info' REM item of the menu. Call FN_PreOpenInfo before opening it so REM that the icons can be filled in, don't call a FN after REM opening it. PROCshell_AttachMenuDBox(MenuItem_Info%,"progInfo", "_PreOpenInfo","") ENDPROC : REM ===== Window_SetUp routines ================================= DEF PROCSetUp_Windows REM create a window from the template called 'mainw', place the REM window handle in mainw% PROCshell_CreateWindowStatic("mainw",mainw%) ENDPROC : REM ===== IconBar_SetUp routines ================================ DEF PROCSetUp_IconBar REM sicon is the handle of the icon. -1 means right side of REM iconbar, -2 would be left side. The name of the sprite for REM the icon is the same as the application directory. A menu REM with the handle 'MenuHandle_IconBar%' is attached. sicon=FNshell_Iconbar(-1,"!"+FNshell_GetAppName,"",120, MenuHandle_IconBar%,0,0,0) REM attach a help tag for the icon, this will send the text REM following 'iconbar:' to the !Help application. See the REM 'Messages' file for this. PROCshell_AttachHelpTag(-1,sicon,"iconbar") REM lastly attach the clickselect event. When <SELECT> is REM clicked over the icon call FN_clickiconbar PROCshell_AttachClickSelect(-1,sicon,"_ClickSelect_IconBar") ENDPROC : REM ===== Dialog_PreOpen routines =============================== DEF FN_PreOpenInfo(h%) REM fill in icons. Try editing the 'Messages' file to make text REM appear in the icons (just add the text after progInfo0: etc). REM h% is the handle of the window. PROCshell_IconPutData(h%,0,FNshell_MessageNoArgs("progInfo0"),0) PROCshell_IconPutData(h%,1,FNshell_MessageNoArgs("progInfo1"),0) PROCshell_IconPutData(h%,2,FNshell_MessageNoArgs("progInfo2"),0) PROCshell_IconPutData(h%,3,FNshell_MessageNoArgs("progInfo3"),0) =0 : REM ===== Dialog_PostOpen routines ============================== REM ===== Click_Select routines ================================= DEF FN_ClickSelect_IconBar(wh%,icon%) REM open the window with the handle mainw% when a click of REM <SELECT> is received on the iconbar icon. wh% is the handle REM of the window over which the click occured (the iconbar) and REM icon% is the handle of the iconbar icon PROCshell_OpenWindowStatic(mainw%) =0 : REM ===== Menu_Select routines ================================== DEF FN_MenuSelect_Quit(blk%) _closedown%=TRUE =0 : REM ===== Menu_Warning routines ================================= REM ===== Data_Load routines ==================================== REM ===== Data_Save routines ==================================== 4. General Overview This section explains the various elements of an application using the EvntShell library, and any limitations and assumptions made by me. 4.1 Dynamic Windows Dynamic windows are those created by moving the pointer over a submenu pointer arrow (i.e the normal 'About this program' window produced by the 'Info' entry on the iconbar menu) or optionally when a 'hot key' is pressed (for example F3 in most applications opens a save box). They are opened with a call to PROCshell_OpenWindowDynamic. When writable icons exist in the dynamic window up/down cursor and TAB/SHIFT TAB keypresses move the caret between the icons using the icon handles to determine where to move next. You should ensure therefore that the order of the icon handles is a logical progression through the dialog box. Icons which are unselectable (i.e. greyed out) will be ignored. Pressing the <RETURN> key causes icon 0 to be pressed (normally a 'default action' icon with an extra border) and the menu/dialog box to be closed. Actually clicking <SELECT> on icon 0 of a dynamic dialog box will cause the shell library to close the window as well. When a 'hot key' is pressed you have the option of opening a dynamic dialog box which will disappear when a mouse click is made outside it or the <ESC> key is pressed, or as a 'Static' dialog box which must be explicitly closed by the user application program. Do not attempt to close a dynamic dialog box with a call to PROCshell_CloseWindow or PROCshell_DeleteWindow as this will cause an error when the shell library tries to close or delete the window. All windows used by the user application are assumed to be defined in the 'Templates' file and edited using FormEd or one of the Public Domain/ShareWare equivalents. 4.2 Static Windows These are opened with a call to PROCshell_OpenWindowStatic and respond to cursor,TAB and <RETURN> keypresses like dynamic dialog boxes except that pressing <RETURN> will not close the window. Static windows must be created with a call to PROCshell_CreateWindowStatic. Closing these windows is the responsibility of the application program (use PROCshell_CloseWindow) except in the case of a click on the 'Close' icon in the title bar icon (if present). You would use a static window for the main window of an application, or perhaps for a save box as in the case of the !WinSave2 example. The advantage of using a static window in this case is that this allows the user to open directory viewers or start other applications while keeping the save box on the screen. 4.3 Resources 'Resources' is a general term for additional files needed by an application. There will (almost) always be some of these, such as sprite files. Others, for example message files may not be required. The EvntShell library now supports ResFind which allows the selection of the desired language for message files etc much easier. Briefly explained it checks the currently configured language of the computer it is running on and sets up a path to the resource files. This would normally be <App$Dir>.Resources.UK for a UK configured computer, or <App$Dir>.Resources.Germany for a German one. This is handled for you if you use !AppBuild to create the application. AppBuild now offers to place the resources in the appropriate directories for you when you create a new application, and to place a call to ResFind in the !Run file. Using ResFind is optional and EvntShell applications will function equally well if you don't use it. It does make the production of applications that can be easily used in any country much easier, however, and this should be encouraged. Most of the programming tools and modules used during the development of this library were written outside the UK. The author would appreciate help in translating the ShellMsgs file and the documentation into other languages. The full ResFind documentation supplied with the library contains further details on how it works and the advantages to be gained by using it. As a taster, here is the part of the documentation intended to be distributed with applications using ResFind. (Base for the application's documentation - please replace <ProgName> by the name of your application without the !) !<ProgName> adapts automatically to the configured language if the corresponding messages etc. are available. For this purpose a Resources directory is contained in the application in which a subdirectory for each language supported resides. If the language you need isn't in there, please feel free to duplicate any of these language directories and translate the contents. When you run the program a utility called ResFind is called which reads the language your computer is configured to and then looks for the corresponding language directory. If this fails the program will run in English (UK). By setting several system variables (best done in your system's !Boot file) you can change the language looked for. With this you can make sure a program runs in a certain language, e.g. to avoid a weird translation. Furthermore it is possible to name several languages you prefer to English. This is controlled by three system variables: <ProgName>$Language, ResFind$LanguagesPref and ResFind$Languages$Suff. When running the application ResFind looks for the first language supported along the following list of languages: 1. Contents of the variable <ProgName>$Language 2. Contents of the variable ResFind$LanguagesPref 3. The configured language 4. Contents of the variable ResFind$LanguagesSuff 5. UK Take a Norwegian user for example (lots of great programs come from there) whose computer is configured to 'Norway'. Since this language isn't too common in Europe most programs won't support it - except for Norwegian ones. But our user is pretty good in German and French but not too fond of English. Therefore he prefers these languages to UK and would thus put the following line in his system's !Boot file: *Set ResFind$LanguagesSuff Germany,France Running an applications (such as this one) using ResFind the list of languages looked for is 'Norway,Germany,France,UK'. In case this user has an application called !Pete supporting the language 'Humorous' the line: *Set Pete$Language Humor in the !Boot file makes sure !Pete will run humorous. A brief description of the various resource files follows. 4.3.1 Templates All windows used by programs based on the shell library would normally be defined using a template editor as this is far simpler than creating the windows/icons in the user program. This is not as inflexible as it may sound as windows and icons can be resized, moved or otherwise altered by shell library routines. The template file must be called 'Templates' and be either in the application directory or in the appropriate language directory if ResFind is in use. Note that if you are using different templates for different languages you must use ResFind. In most cases, however, it is sufficient to have only one template file in the application directory and to insert the text taken from the message file in the language of choice into the icons. A call to PROCshell_ResourcesInit will find the template file and load all the templates it contains allocating memory as required. 4.3.2 Sprites The sprite file must be called 'Sprites' and be either in the application directory or in the appropriate language directory if ResFind is in use. A call to PROCshell_ResourcesInit will find the file if it exists and load all the sprites it contains allocating memory as required. Optionally a second sprite file called 'Sprites22' containing high resolution sprites for users with multisync monitors may be present. If the application is started in a high resolution screen mode and 'Sprites22' is available it will be loaded instead of 'Sprites'. The sprite area pointer for each loaded template will be set to point to the user sprite area, which put simply this means that all sprites displayed in windows must be present in the 'Sprites' and 'Sprites22' files. This may, however, be changed after loading with a call to FNshell_WindowSetSpriteArea. 4.3.3 Message Files The message file is a normal ASCII file written using !Edit or similar that contains message strings preceeded by a message tag. The application program should find the messages as required by tag name which allows the production of foreign language versions (probably by someone else!). It is also far easier to edit the message file to change text displayed by the application than using !FormEd or similar. The !Run file of the user application automatically loads a support module 'MsgTrans' if required (it is built in to RISC OS 3) to provide this facility. The message file must be called 'Messages' and be in the application directory or in the appropriate language directory if ResFind is in use. A call to PROCshell_ResourcesInit will find the file if it exists and load all the messages it contains allocating memory as required. The messages issued by the library code are stored in a file called 'ShellMsgs' inside the !ShellSys.Resources.UK directory. If this file is present in the user application directory (or the application Resources directory) then it is loaded from there, if not it is loaded from !ShellSys. This is to aid the construction of stand alone applications. 4.3.4 Modules Various Public Domain modules are used by the EvntShell library, these are stored in the !ShellSys application and loaded as required. A full list is: Interface - 3D icon effects, changing pointer shapes etc MenuUtils - menu handling FontMenu - font menu handling MsgTrans - message files (supplied for Risc-OS 2 compatability) FontWindow - handling outline fonts across mode changes (not used at the moment) Note that in general no documentation is supplied for these modules, it is all available elsewhere (or why not write to the author?) The EvntShell library makes the assumption that the interface module will always be used. The reason is that firstly that it is highly likely that some other PD program will have already loaded it, and secondly that the facilities it provides for changing pointer shapes over certain icons is extremely useful as a prompt for what the icon is for. Indeed RISC-OS 3 has this built in so even Acorn are supporting 3D buttons etc.... The module is loaded by the !Run file if not already loaded. Using a template editor that is 'Interface Aware' makes incorporating these effects into a user program easy as once the icons have been designed and placed the shell library handles all the redrawing automatically. Note that windows containing 3d interface icons must have the 'Auto Redraw' flag off, but if the template editor displays interface icons then the user application will as well. 4.4 Menus Menus are now handled by MenuUtils which was written by Alex Petrov. Versions of the library prior to 1.20 used a menu editor to create a seperate menu template file, but I have now abandoned this as it was rather inflexible. The use of MenuUtils has enabled me to remove large chunks of slow BASIC code and to provide many more features, such as creation and modification of menus under program control. The menus themselves appear more quickly as well (OK Cy?). Menus may be created by calling functions in the user application, or from a menu command file. The file option is especially useful for lists of items that can be edited by the user - for example the new version of !VideoBase uses menu command files for lists of commonly used categories of recordings (Documentary, Action Film etc) a menu of which can be attached to an icon for easy access. As the command file is a simple text file it is very easy to edit to meet special requirements. A demonstration application !TestMenu should have been supplied with the library code so that you can try out some of the possibilities yourself. The appearance of the RISC OS 3 Style Guide has caused a few changes in the way that EvntShell handles 'popup' menus (menus attached to icons in windows other than the iconbar). Firstly they appear to the right of the icon they are attached to, the mouse pointer also moving to the recommended position, and secondly only SELECT and MENU will call up a popup menu. Note that menus can only be attached to icons in static windows, because as far as RISC OS is concerned a dynamic window is a menu. The support module is automatically loaded by the !Run file to provide the new menu handling SWIs used by the EvntShell library. 4.5 Saving Files This is achieved by a call to PROCshell_AttachDataSave which specifies which filetype the saved file should be given, the name of a function which will actually perform the save and the window/icon handles the drag save event is associated with. It is therefore possible to have different drag save events attached to different icons in the same window. This is useful where it is possible to save the file as more than one type - you can have multiple filetype icons in the save window. PROCshell_AttachDataSave also performs some checking when it is called. For example an error message is generated if the file icon is not a sprite icon. The button type of the file icon is also changed to Click/Drag to avoid the need to get this correct when editing the template file. The EvntShell library supports RAM file transfer for speed when saving data to consenting applications. See the !WinSave2 and !VBase2 example applications for how to use this routine. 4.6 Loading Files This is achieved by a call to PROCshell_AttachDataLoad which tells the EvntShell library which filetypes the user application is interested in and the name of a function to call when a load event occurs. Multiple files may be loaded, but in the current release of the library it is up to the user application to keep track of where they are loaded and if they have been modified. This will change in a future release. When the event is attached a check is made to see if the application was started by double clicking a file which 'belongs' to it. If the filetypes match then the file is loaded as if it had been dragged to the icon bar icon. A filetype is associated with an application by the inclusion of the line: Set Alias$@RunType_xxx Run <Obey$Dir>.!Run %%*0 where xxx is the filetype number. If required the files can be loaded automatically into a reserved block of memory, or the user application can have total control over loading and processing the file. The EvntShell library supports RAM file transfer for speed when loading data from consenting applications. It is also possible to arrange for the user application to respond to a range of filetypes by attaching more than one handler. An example application !DataLoad should have been included with the Library to demonstrate how to do this. This is the code from !DataLoad used to achieve the load : PROCshell_AttachDataLoad(mainw%,0,&FEC,"_dataloadFEC",TRUE) The first parameter, mainw% is the wimp window handle, the second is the icon handle. &FEC is the filetype to respond to and '_dataloadFEC' is the name of the function to call to actually load the file. The last parameter is TRUE to load the file automatically into a reserved block of memory or FALSE if you want to handle the loading yourself. In this case loading is automatic and the loading function is simply: DEF FN_dataloadFEC(loc%,type%,name$,file_size%) void%=FNshell_MessageWindow("File '"+name$+"'",0,"DataLoad","") =0 The data file (of type &FEC, template) has been loaded at location loc%, its type is in type% and the full path name of the file is in name$. All the function itself does is call another function to display a message window so that you can see that loading the file has worked. This is a useful debugging technique! This method of loading a file works well for datafiles that are stored as one continuous block of data such as a text file which will be processed in some way. Suppose, however, you have a simple database type application which needs to load data into BASIC arrays. In this case you would simply use (assuming now the filetype is &205): PROCshell_AttachDataLoad(mainw%,0,&205,"_dataload205",FALSE) FN_dataload205 receives the full pathname of the file which has been dragged to icon 0 (providing the filetype of the file was &205, otherwise the load will be ignored) which may now be opened and the data loaded as usual. If the 'no load' flag was set for this load event and the load was from another application the data is saved in a file called 'ScrapFile' in the user application directory. 4.7 Compressing EvntShell Applications Due to the complex nature of the library code and the desire for it to do as much as possible to make a user application easy to write the ShellLib library file has expanded to around 150K. This is obviously undesirable especially if you are planning to send your finished program to a PD library. If you want people to be able to read your source code you can use the 'RunTime' version of the library which has been mildly compressed, but for the smallest possible program it is necessary to append the library (either version) to the end of the user application, remove the line which loads the library file and run the whole lot through a BASIC program compressor. I recommend !BasShrink or !Shrink_PD (the Public Domain version of !BasShrink) by John Wallace although John's program is slow and not presently multitasking it does produce code that still runs! This is unfortunately not true of Cy Booker's otherwise superb !BC which will not work on the EvntShell library. However, if I or Cy can find out what the problem is we'll fix it. Future versions of !BasShrink should be able to remove unused routines to save even more space, or alternatively BLibII can be used to pre-process the application to link in only the routines that are actually used. See the manual section 'Other Tools' for more details. There is one important point to bear in mind when using the shell library and !BasShrink together - function names that are EVALuated by the shell library should begin with a '_' character and the 'Preserve names starting with' radio button in the !BasShrink window must be ON. In short if you are calling any shell library routine that has a function name as a parameter then that name must start with a '_'. Failure to observe this rule will result in a non-working compressed program! Assuming you have !BasShrink 2.14 or later the EvntShell library can be compressed with all switches on except 'Shorten FN names', 'Shorten PROC names' and 'Remove * comments'. If you are not going to use !BLibII you can switch on 'Remove * comments' to strip out the !BLibII commands. If you append the EvntShell library to the user application manually or by using BLibII you can compress the complete program with all switches on. 4.8 The RunTime Library This is a compressed version of the full library which should be used wherever possible as it will load and run faster. The only reason for using the uncompressed library would be to add extra debugging code or perhaps to modify the routines. In this case, however, it is better to just copy the uncompressed routine into the user application and edit it there. The uncompressed version is called ShellLib, the compressed version is ShellLibRT. Both can be found inside the !ShellSys application directory. The ShellLibRT file has had the BLibII commands stripped out to save space. 4.9 The !ShellSys Application As large chunks of code are common to all EvntShell applications it makes sense to store it only once on the disk, hence !ShellSys which should be treated like the !System application. If you have a hard disk put it in the root directory (or ensure it is booted by your Boot file). If you have a floppy only system put it on all your disks (removing the ShellLib file and making sure all EvntShell applications use ShellLibRT will help save disk space). The system message file and various modules are also to be found here. 4.10 Handling Panes A pane window is a window attached to a parent window which has different properties to the parent. A well-known example is the 'ToolBox' pane attached to a !Draw window which always appears at the top left of the parent window however the parent window is scrolled. Another example could be a parent window without scrollbars which has a scrolling pane attached to the work area which might be used in a 'FindFile' application to display a list of finds. Panes are created using !FormEd or similar with the 'pane' flag set. A call to PROCshell_AttachPane specifies which pane is attached to which window and the position of the pane. Multiple panes may to attached to a parent window (see the example application !Panes). The opening and closing of panes is handled totally by the shell library - a call to PROCshell_OpenWindow after attaching the panes will open the parent window and the panes together. It is normally necessary for certain bits in the window definition block to be set up in a special way if a window is to be treated as a pane. This is not required when using the EvntShell library as the act of attaching the event makes the changes needed. You should avoid attaching a pane to a parent window where it is possible to resize the parent in such a way that the pane lies outside the window it is attached to. This will cause (non-fatal) problems when the windows are redrawn. Most RISC OS programs also avoid this for the same reasons. When attaching a pane it is possible to specify a 'pane flag' value which determines where the pane will be attached and to some extent how it will behave when the parent window is resized. The currently valid pane flags are: 0 = attached to parent window work area 1 = attached to left edge outside parent 2 = attached to top edge 3 = attached to left edge inside parent 4 = attached to bottom edge 5 = attached to right edge In cases 1-5 the library will attempt to stretch the pane window so that it will fill the whole width or depth of the parent window. 4.11 Outline Fonts The EvntShell Library supports Outline Fonts in two ways at the moment. Firstly Joris Röling's FontMenu module is used to display a menu of all available fonts on the system, and secondly the window template loading routine allows icons and window titles to use fonts. Routines are provided to attach a font menu to an existing menu as a submenu (PROCshell_AttachFontSubMenu), or to open the font menu as a menu in its own right (PROCshell_AttachFontMenu). If the user makes a valid font selection the font name can be retrieved (with FNshell_FontMenuGetLastSelectedFont) for use in the user application. Changes to the Font$Path variable such as adding or removing font directories are detected and the font menu rebuilt as necessary. It will not, however, detect fonts being added or removed from an existing font directory while the EvntShell application is running. It appears that a re-boot is required to sort things out after the contents of the font directories have changed. Oh well, it seems that a lot of other applications can't cope with this either! The FontMenu module creates a menu in the relocatable module area which is shared between all applications wishing to use it. As a font menu potentially takes up a lot of space this is a very efficient way of handling it, especially as the menu is laid out so that it is easier to use than a straight list of fonts. A help system containing the full FontMenu documentation is supplied with the EvntShell library as it is a requirement that the the module and its documentation must be supplied together. However, it is unlikely that the SWIs provided by the module will need to be called by the user application as the library code performs the necessary actions. The example application !Redraw demonstrates the use of these routines. 4.12 Interactive Help The EvntShell library supports Acorn's Interactive Help application !Help by searching icon validation strings for the 'I' command (as recommended by the author of the Interface module) for a message tag. The message belonging to the tag will be looked up and sent to !Help (if !Help is running). An example would be a validation string of "iMessTag01", where the file 'Messages' contains the line 'MessTag01:This is a test'. 'This is a test' would be the message displayed. It is also possible to attach a message tag to a window or a window/icon using PROCshell_AttachHelpTag. A message tag is a string consisting of not more than 11 characters long and represents a message string to be found in the 'Messages' file. 4.13 User Redraws 4.13.1 Simple Cases By 'Simple Cases' I mean text, lines, arcs, filled shapes etc. In other words anything that it is easy for the program to redraw quickly - this excludes maps of the world and any kind of random display. For these cases it is much faster to redirect the screen output into a sprite (see the next section). Using the example application you created earlier (or create a new one using AppBuild) add the following line to PROCSetUp_Windows: PROCshell_AttachUserRedraw(mainw%,"_redraw") and add the following FN definition: DEF FN_redraw(blk%,x0%,y0%) REM set colour for circle - colours are numbered 0-15! REM draw the circle.. SYS "Wimp_SetColour",11 CIRCLE FILL x0%+200,y0%-200,120 REM set colour for text... SYS "Wimp_SetColour",8 :REM colours are numbered 0-15! MOVE x0%+80,y0%-340:PRINT "This is an example of" MOVE x0%+40,y0%-380:PRINT "user drawn text and graphics" MOVE x0%+95,y0%-420:PRINT "in a desktop window" =0 The routine that attaches the redraw event also alters the 'flags' of the window so that the 'Auto redraw' bit is set up correctly. When you run the application and open the main window now, a circle and some text will appear in the window. If another window is moved over this one, note that the window is correctly redrawn. The parameters x0% and y0% for the redraw routine are the coordinates of the top left corner of the window. Note that y coordinates are negative! Try experimenting with other drawing commands and putting text in different places in the window to get the hang of this. 4.13.2 Drawing Into A Sprite With a more complicated or random display you need to set up a sprite to draw into. The example application !Redraw2 shows how to do this. Note in this case that the display within the window is animated by calling the plotting routine at every null event received. There also has to be two redrawing routines, one called when you want the display redrawn and one for when the wimp wants it redrawn (hence the call to PROCshell_AttachUserRedraw). In both cases it is necessary just to replot the sprite. 4.14 Complex Icons 4.14.1 Bump Icons Bump icons are simply a pair of (usually!) arrow shaped icons that effect the value displayed in a third icon. The EvntShell library allows you to create this effect with one call to PROCshell_AttachBumpIconHandler. Note that clicking on a bump icon which ADJUST has the opposite effect to using SELECT, i.e. ADJUST on the decrement icon actually increases the value. This is normal RISC OS behaviour and is intended to avoid unnecessary mouse movements. See the !VBase2 demo application for an example of its use. 4.15 Memory Management A crucial element of the EventShell library is the use of memory management routines originally published in Risc User magazine and used with permission. Many library routines require some memory workspace and they obtain this by calling FNshell_HeapBlockFetch(bytes_required) which returns the address of the allocated memory and release it when they are finished with PROCshell_HeapBlockReturn. This is vital for avoiding 'side effects' caused by using the same block of memory for different purposes as most WIMP programs tend to do. Equally important is the fact that as the routines are written in ARM code they are extremely fast. Another point to note is that this memory is claimed from the current wimp slot and not the RMA (Relocatable Module Area). This ensures that all of the memory claimed by the application is released back to the free pool when the application quits - this is not the case if memory is claimed from the RMA. It is only possible to reclaim RMA memory if the free space is at the top of the RMA which leads to the RMA allocation gradually growing as you run and quit applications. Unfortunately (in the authors view!) the MenuUtils module uses the RMA for storage of indirected data and menu structures. Hopefully this data gets put in any small available blocks so that the RMA allocation does not increase. You are strongly advised to use the supplied memory management routines in the user application should you require storage for data, or temporary blocks for use with SWI calls for example. The time penalty for doing this is very small and in any case results in a more reliable and easier to maintain application. 4.16 Error Handling The EvntShell library sets up a default error handler for you if you build the application with AppBuild. Since version 1.21 of the library support has been provided for Joe Taylor's !ThrowBack application which was on the September 1993 cover disk of Archimedes World. This traps errors in the program and opens a window showing the location and type of the error. Clicking on the error line then loads the file into your editor with the offending line highlighted which is a real timesaver. It is not necessary to have !ThrowBack, if it is not present a standard error window will pop up instead. The user application can generate errors on purpose as a way of aborting an operation. Control will then return to the wimp poll loop. This is done with a call to PROCshell_OK which opens an error box with a user defined message and an OK button. Note that an error generated any other way will end the application without further warning. This will be improved in a later release of the library, especially with regard to 'out of memory' errors from the heap manager as at the moment running out of memory aborts the user application instead of giving the user a chance to free up more memory. Also note that the MenuUtils module appears to set up its own error handler while calling the MenuSelect routine (the one you specify will be called when a selection is made for a particular menu item). This means that any errors in this routine appear to be ignored - in fact the routine just aborts at the error location without giving a message. This makes debugging these routines impossible unless you add the line: ON ERROR OFF at the start of the routine, i.e DEF FN_MenuSelect_TID(blk%) LOCAL str$ ON ERROR OFF str$=$(blk%!12) PROCshell_IconPutData(newrec%,4,str$,TRUE) PROCget_entries(file_loc%,(blk%!0)+1) =0 : 5 The Tools Various programming tools have been written by myself and others to make producing wimp applications easier and faster. If you obtained the EvntShell library or updates thereof from the author you will have received all of the tools described here. If you obtained it from a PD library the author has little or no control over what else is supplied on the disk, so you may have to obtain the missing tools from other disks in the PD library, or better still send me a blank disk. Only one of the tools (one of the many Template editors available) are vital to the EvntShell Library, the others you can do without but they do make life easier. The following is a brief description of the tools supplied on APDL disk B122, and some other software which may be useful for developing applications 5.1 !AppBuild Creates new application shells as 'stand alone' applications for distribution, or ones that depend on !ShellSys. You can specify a name for the application, and choose whether or not to make it 'Stand Alone' i.e if all the files required are copied into the new application directory. If it is not a stand alone application then modules, message files etc will be loaded from the !ShellSys directory. This application supports Acorn's !Help application. 5.2 !ShellDBug A very simple debugger that displays trace output from the user application and the library code. Note that currently this application must be running before the application you want to debug. The EvntShell library outputs a commentary on what it is doing into a tracefile, providing that PROCshell_TraceInit and PROCshell_TraceOn have been called. The user application can also place output in this file using PROCshell_Tracef0. Outputting trace information will slow the user application noticeably, especially when starting up as a lot of trace info is generated by the call to PROCshell_ResourcesInit. Therefore it is best to only turn on tracing when necessary, and of course make sure that tracing is off on any applications you distribute! 5.3 Other Tools There follows a brief description of some other PD/ShareWare /Copyrighted programs which I have found useful when developing EvntShell applications. 5.3.1 !BasShrink/!BasShrink_PD Is a BASIC program compressor which has been proved to work with EvntShell applications. !BasShrink_PD is Public Domain and available from various PD libraries, !BasShrink cost £5.00 and can be obtained from: John Wallace, Architype Software, 54 Parkes Hall Road, Woodsetton, Dudley, West Midlands, DY1 3SR ENGLAND See the section on compressing EvntShell programs for guidance on the options that can be used. 5.3.2 !BLibII A BASIC Linker program available on APDL Disk B138. This builds a program from the user application and the EvntShell library containing only the routines that are actually needed. This is very useful for distributing the final application as !BLibII and !BasShrink used together will produce the minimum program size possible. Full instructions are provided with !BLibII, so I won't go into details here except to note that the ShellLib library already contains the extra information that !BLibII requires, although the conditional linking bits are not yet in place. This means that the linked program is bigger than it should be, but an improvement over just appending the library code to the end of the user application. This will improve in future releases. Note that you should use the ShellLib library for linking with BLibII because ShellLibRT has had the BLibII commands removed to save space. 5.3.3 !TemplEd Also on APDL disk B138 this is I believe the best Template editor available anywhere. Forget !FormEd2 which was on some APDL B122 disks, !FormEd (Risc Squad version 2.84b on B053 or 2.87 also on B138) and any Acorn versions. 5.3.4 !StrongEd2 A text editor which may or may not now be in the public domain and thus available from PD libraries. The big advantage this has over any other editor is the accompanying !StrongHlp application. Pressing F1 over a word in a program known to !StrongHlp causes an information window to open. Versions before 1.21 were a bit unstable though. The Archimedes World August 1993 cover disk contained a crippled version of !StrongEd (as the commercial version is known) which can be used for evaluation purposes. 5.3.5 !StrongHlp A hypertext type application which almost removes the need for the Reference Manuals. Files supplied with it detail most of the SWIs available and much more information is provided on BASIC, VDU calls, Filetypes etc. !StrongHlp is now only available as far as I know as a 'free' add on with the commercial version of !StrongED from Stallion Software, although a new PD version may be released in the future. The Archimedes World August 1993 cover disk contained a fully working copy of !StrongHlp (minus most of the help systems, however) which can be used to view the help system for EvntShell. The EvntShell library also has a few PROCs to interface with StrongHlp to enable user applications to register help systems. When a request is sent to StrongHlp the active applications on the icon bar are checked to see if StrongHlp is running. If it is not and its !Boot file has been 'seen' by the Filer then it will be started automatically. If StrongHlp has not been 'seen' then an error will be generated. Note that for the above to work it is vital that the help system directory has the same name as the application (minus the '!'). 5.3.6 !ThrowBack This application appeared on the September 1993 cover disk of Archimedes World and is copyright that magazine. It provides a 'throwback' window when an error occurs, and clicking on the throwback window opens your program editor at the line where the error occured. This is very useful when debugging a program. The EvntShell library contains the necessary support code for this. Note that for this to work properly you need the DDEUtils module and an editor that supports throwback (such as !DeskEdit or !StrongEd), although it will work after a fashion with !Edit as well. 6 Distributing EvntShell Applications It is probably best to copy ShellLibRT, ShellMsgs and the modules into your application directory, not forgetting to alter the !Run file and the LIBRARY statement in the runimage file to point to the new location. That way you are sure that all the necessary files are in one place for ease of copying. 7 Debugging A simple debugger (!ShellDBug) is supplied with the library to display trace messages. You can also do wonders with a few VDU7 calls to check which parts of the application are actually being executed.. 8 The Credits Quite a few people have been (however unwittingly) involved in this project such as: David Breakwell (the original idea), Robert Seago (for using it for things I wouldn't dream of attempting!), Cy Booker (various helpful suggestions - I won't rewrite it in C or Assembler though - RISC-OS 3 Documentation and the FontWindow module), Risc User magazine (for permission to use its heap manager code), Joris Röling (FontMenu module), Simon Huntingdon (Interface module), Alex Petrov (MenuUtils), Jan-Herman Buining (WASP application from which I worked out how to do RAM file transfers) and lastly the wife (Hilke) for putting up with me pounding away at a keyboard for hours when we could have been looking for new furniture instead. 9 Future Enhancements The software will become faster and be able to leap tall buildings with a single bound. Bugs and limitations will become fewer as well. - Support for automatic handling of more complicated icon types, for example sliders, rotating knobs etc (steady now don't get carried away) - Import and display of DrawFiles and Sprites - Inclusion of more debugging aids - More drag types - Autoscroll handler when object is dragged within a window - Colour pick dialogs - Automatic handling of non-icon text within a window (like C txt objects) - Playing of Maestro tunes (ArchWay does!) - Extending message file useage to icons/ windows/menus - Replay Films (!!!) - Better multiple file buffers - Complete German message files - Choice of message file language from within program - Automatic attaching of 'hot key' events by examining menu text 10 Changes Since V1.09 V1.10 - Corrected documentation for PROCshell_AttachHotKey V1.11 - Added support for !BLibII BASIC linker - PROCshell_AttachUserRedraw alters redraw flag of window if necessary V1.12 - PROCshell_AttachPane alters pane window flags if necessary - DataSave routine now automatically saves data if data is in a heapblock and no FN is named to actually perform the save - Added file size parameter to user FN AttachDataLoad V1.13 - Bug fixes for 'no load' from another application V1.14 - More library routines claim private workspace to avoid interactions - Added routine PROCshell_SetIconButtonType - Added routine PROCshell_IconSetESG - Added routine PROCshell_IconSetText - Added routine PROCshell_IconSetSprite - Added routine PROCshell_IconSetBorder - Added routine PROCshell_IconSetHCentred - Added routine PROCshell_IconSetVCentred - Added routine PROCshell_IconSetFilled - Added routine PROCshell_IconSetRightJust - PROCshell_AttachMenu now changes the button type of the icon to 1 (click) if the menu is being attached to an icon V1.20 - Now uses MenuUtils module for menu handling - Added routine PROCshell_IconSetSelected - Added routine PROCshell_IconSetUnselectable - Added routine FNshell_StrongHlpIsAvailable - Added routine FNshell_MenuNew - Added routine FNshell_MenuAdd - Added routine FNshell_MenuDelete - Added routine FNshell_MenuColours - Added routine FNshell_MenuDotted - Added routine FNshell_MenuWritable - Added routine FNshell_MenuTickOnly1 - Added routine FNshell_MenuTickOnly2 - Modified all other menu routines - Added routine FNshell_StrongHlpIsAvailable - Added routine PROCshell_AttachPreQuitHandler - Added routine PROCshell_AttachOpenWindowHandler - Added routine PROCshell_AttachCloseWindowHandler - Added routine FNshell_SpriteAreaLoad - Added routine PROCshell_SpriteAreaSave - Added routine FNshell_SpriteGetPtr - Added routine PROCshell_SpriteRename - Added routine FNshell_OSCheckVersion - Added routine FNshell_OSCheckModuleVersion - Added routine PROCshell_IconSetLeftJust - Fixed PROCshell_IconSetRightJust - Writable icon handler now ignores unselectable icons when moving caret - Added support for ResFind (internationalisation of messages etc) V1.21 - Added support for Joe Taylor's !ThrowBack error handler (see Archimedes World Sep 1993) V1.22 - Clicking on a 'bump' icon with ADJUST now has the opposite effect to clicking with SELECT - Improved error handling and messages - PROCshell_AttachDataSave now alters icon button type of file icon to click/drag and generates an error if the file icon is not a sprite - PROCshell_AttachMenu now sets button type of icon to 3 (Click) - Bug fix to menu attach routine (a menu could appear when another event occurs such as ClickSelect) - Added routine <FNhell_IconIsDraggable - Added routine FNshell_IconIsSprite - Added routine FNshell_GetString - Added routine PROCshell_Ensure - Added routine PROCshell_IconPutDataNow - Added routine PROCshell_MessageSendDataLoad V1.23 - Bug fix for auto press of icon 0 when RETURN is pressed in last writable icon V1.24 - Bug fix for pane handler (pane was not opening fully when wimp adjusts parent window coords - if title is changed for example). Pane handling is still not 100% when a mode change event occurs though V1.25 - Added routine FNshell_MenuMakeFromFile - Added routine FNshell_BinarySearch - Added routine FNshell_MenuGetNrItems - Added routine FNshell_MenuGetNrDotted - Added routine FNshell_MenuGetItemHandle - Added routine FNshell_MenuGetItemHeight - Added routine FNshell_MenuGetItemHandler - Added routine FNshell_MenuCalculateHeight - Added routine FNshell_MenuGetText - Added routine PROCshell_QuickSort - Added routine PROCshell_MenuSortItems - Added routine PROCshell_WindowCentreOnPointer - PROCshell_IconPutData now checks if the new text to put into the icon is the same as the existing text. If it is, no action is taken avoiding flickering of the icon - 'Popup' menus (menus attached to icons in windows other than the iconbar) now appear to the right of the icon, the pointer also being relocated. ADJUST no longer opens a 'popup' menu (Recommendations from the RISC OS 3 Style Guide) - Bug fix to menu opening routine (MENU sometimes failed to open a 'popup' menu) - TAB/SHIFT TAB now move caret between writable icons. RETURN now only activates icon 0, it does not move the caret (Style Guide recommendations) V1.26 - Added routine PROCshell_WindowSetTitleRightJust - Added routine PROCshell_WindowSetTitleCentreJust - Added routine PROCshell_WindowCentreOnScreen - Added routine FNshell_GetLastMouseButton - Added routine FNshell_GetLastWindowClicked - Added routine FNshell_GetLastIconClicked - Running out of memory does not now cause a fatal error and shut down of the application - Double clicking on a file 'belonging' to an application now causes the application to start up and load the file - 'Sprites22' file containing hi-res sprites automatically detected and loaded if the program is started in a hi-res screen mode - Bug fix to PROCshell_WindowMoveToIcon (window was sometimes moved to wrong position because the scroll offset of the icon bar was not being taken into account) Note: This fix only for RISC OS 3 users - Bug fix to PROCshell_IconbarSetText (new text not always redrawn because the scroll offset of the icon bar was not being taken into account) Note: This fix only for RISC OS 3 users - Click on a radio icon with ADJUST selects icon to avoid the situation where all radio buttons in a group are off V1.27 - Bug fix to writable icon handler (could cause a crash if more than 5 writable icons in one window) - Bug fix to template loading routine which sometimes did not allocate enough buffer space