APDL Public Domain 1

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

/ APDL Public Domain 1 / APDL_PD1A.iso / program / basic / eventshell / Docs / Manual-F < prev next >

Wrap

Text File | 1996-04-19 | 65.6 KB | 1,816 lines

CONTENTS 1. Introduction........................................................1 2. Creating An Example Application.....................................1 3. A Tutorial..........................................................2 4. General Overview....................................................5 5. The Tools..........................................................19 6. Distributing EvntShell Applications................................21 7. Debugging..........................................................21 8. The Credits........................................................21 9. Future Enhancements................................................22 10. Change History....................................................22 EvntShell ________________________________________________________________________ 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 Page 1 EvntShell ________________________________________________________________________ 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 ENDPROC : REM ===== Menu_Setup routines =================================== DEF PROCSetUp_Menus LOCAL void% REM Construct the iconbar menu.. MenuHandle_IconBar% = FNshell_MenuNew( "NewApp", "Menu_IBar", 2 ) 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 Page 2 EvntShell ________________________________________________________________________ : 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 : Page 3 EvntShell ________________________________________________________________________ REM ===== Menu_Warning routines ================================= REM ===== Data_Load routines ==================================== REM ===== Data_Save routines ==================================== Let us now look at how events should be attached to a window. It is important to always do this just before the window opens (i.e. in the PreOpen routine) because a static window and a dynamic window can be created from the same template but they will of course have different handles. The following example shows how this should be handled (we are assuming the template in question is called 'xfer' and the program is called 'MyApp'). DEF PROCapp_init ... PROCSetUp_Windows PROCSetUp_Menus PROCshell_AttachHotKey("F3",FALSE,FALSE,FALSE,"",xfer%,"_PreOpen_Xfer"," ") ... ENDPROC : DEF PROCSetUp_Windows ... PROCshell_CreateWindowStatic("xfer",xfer%) ... ENDPROC : DEF PROCSetUp_Menus ... MenuHandle_IconBar%=FNshell_MenuNew("MyApp") MenuItem_Save% =FNshell_MenuAdd(0,"Save","") PROCshell_AttachMenuDBox(MenuItem_Save%,"xfer","_PreOpen_Xfer", "_PostOpen_Xfer") ... ENDPROC : DEF FN_PreOpen_Xfer(h%) ... REM OK icon is 0, Filename icon is 2, File icon is 3, Filetype is &344.. PROCshell_IconPutData(h%,2,filename$),FALSE) PROCshell_AttachDataSave(h%,3,100,&344,2,"_DataSave_Xfer") PROCshell_AttachClickSelect(h%,0,"_ClickSelect_XferOK") ... =0 : DEF FN_PostOpen_Xfer(h%) ... PROCshell_WindowCentreOnPointer(h%) ... =0 Page 4 EvntShell ________________________________________________________________________ : The xfer window will open when F3 is pressed (assuming one of the open windows has the 'grab hot keys' bit set) and also when the sub menu on the 'Save' menu item is opened. In each case FN_PreOpen_Xfer will be called to attach the events and fill in the filename icon. 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 Page 5 EvntShell ________________________________________________________________________ (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 Page 6 EvntShell ________________________________________________________________________ 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 Page 7 EvntShell ________________________________________________________________________ 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 !EvntShell.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 !EvntShell. 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 !EvntShell application and loaded as required. A full Page 8 EvntShell ________________________________________________________________________ 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) DrawFile - used for rendering drawfiles (this module is copyright Acorn) 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. Page 9 EvntShell ________________________________________________________________________ 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: Page 10 EvntShell ________________________________________________________________________ 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. Page 11 EvntShell ________________________________________________________________________ 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 ShellLibRT 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 Page 12 EvntShell ________________________________________________________________________ ShellLibRT. Both can be found inside the !EvntShell application directory. The ShellLibRT file has had the BLibII commands stripped out to save space. 4.9 The !EvntShell Application As large chunks of code are common to all EvntShell applications it makes sense to store it only once on the disk, hence !EvntShell 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. The name '!EvntShell' has been registered with Acorn as an official shared system resource. 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: Page 13 EvntShell ________________________________________________________________________ 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 Page 14 EvntShell ________________________________________________________________________ "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. Interactive help can be enabled or disabled by calls to the EvntShell library. It is useful to offer the option to disable interactive help for experienced users as the applications response times will be improved. 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. Page 15 EvntShell ________________________________________________________________________ 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 Page 16 EvntShell ________________________________________________________________________ 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. 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 : 4.17 Draw Files The standard method of creating and displaying vector graphics on Risc OS computers is the DrawFile, as created by the Acorn Draw application. It is also possible to create a DrawFile under program control using the routines in the supplied DrawLib library - this is seperate from the main shell library as the creation of DrawFiles is a specialised requirement. Page 17 EvntShell ________________________________________________________________________ A good example of the use of program generated DrawFiles would be the production of a graph which could be loaded into a DTP or word processing package. If you want to do something like this it makes sense to use the existing standard of DrawFiles, indeed if you want other applications to be able to load the data there is really no choice. EvntShell handles the creation of DrawFiles by creating the necessary data in memory (hence memory availability limits the size of DrawFile that can be created), first adding a 'pre-header' to the data. The purpose of the 'pre-header' is to store data such as the current drawing colour, the width of the lines etc without using global variables. Each DrawLib routine requires the address of the buffer holding the DrawFile, enabling several DrawFiles to be created in different buffers at the same time. Existing DrawFiles may be loaded, modified by the user application and re-saved. Full control is provided over line thicknesses, patterns, end caps, path and fill colours (stored as 24 bit values which RISC OS displays using dithering). DrawFiles can contain lines, boxes, circles, ellipses and outline font text at the moment which is not an exhaustive list but should suffice for most needs. An example of the use of the DrawLib routines is as follows: LIBRARY "EvntShell:Extensions.DrawLib" buffer% = 0 : REM Just declare the variable PROCshell_DrawCreateFile(buffer%) PROCshell_DrawBox(buffer%,100,100,25,25) which creates a DrawFile and then adds a square at the location x100 y100 (relative to the bottom left of the paper) with sides 25mm long. By default millimetres are used for measurements, but drawing units may additionally be specified in centimeters, inches, OS units or points. Drawing units can be mixed within each file. A demonstration application called TestDraw should have been supplied with EvntShell to enable you to experiment. Note that as displaying a DrawFile uses Acorn's DrawFile module programs using it can only run on Risc OS 3 or later. 4.18 OLE OLE is a technique whereby data can be sent from your application to be edited by another and reloaded when it is saved by the external application. The demo application OLE shows how this works. In addition the TestDraw application shows how a DrawFile can be sent to Draw for editing and how when the Draw window is closed the modified file is passed back for display. Page 18 EvntShell ________________________________________________________________________ 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) is 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 !EvntShell. 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 !EvntShell 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. Page 19 EvntShell ________________________________________________________________________ 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 !StrongEd A text editor which is now a ShareWare product again. The big advantage this has over any other editor is the accompanying !StrongHlp application as pressing F1 over a word in a program known to !StrongHlp causes an hypertext information window to open. 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, and this may be available from PD libraries. The PD/Demo version cannot create files and only allows two files to be open at any one time although this is not much of a problem for evaluation purposes. 5.3.5 !StrongHlp Page 20 EvntShell ________________________________________________________________________ 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. The Archimedes World August 1993 cover disk also contained the PD version of !StrongHlp. The EvntShell library also has a few PROCs to interface with StrongHlp to enable user applications to register help systems. 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. AppBuild will do this for you automatically if you drag the application to the iconbar icon, turn the 'Standalone' switch in the main window on and click OK. 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 Page 21 EvntShell ________________________________________________________________________ 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) - Inclusion of more debugging aids - More drag types - Autoscroll handler when object is dragged within a window - 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. Change History —————————————————— 2.00 - First release version 2 2.01 - Added documentation for interactive help routines - Fixed MenuMaker routines - Fixed OLE problems 2.02 - Added documentation for PROCshell_DrawSetPathNoColour - Added documentation for PROCshell_DrawSetFillNoColour - Added documentation for PROCshell_DrawDestroyFile - Added documentation for PROCshell_DrawSetPathPattern - Parameters changed for FNshell_MenuGetItemHandle - Added routine PROCshell_AttachMenuHelpTag Page 22 EvntShell ________________________________________________________________________ 2.03 - Fixed bug concerning text under iconbar icons not being updated when PROCshell_IconbarSetText was called - Fixed bug with loading a file to a window or icon that had no dataload event attached (possible address exception error) 2.04 - Added routine FNshell_IconGetButtonType - ClickSelect/ClickAdjust events no longer set the icon button type to CLICK if the button type is already MENU (so you can attach these events to icons that invert when the pointer is over them) 2.05 - Width parameter for FNshell_IconBar now working again, any amount of text can be placed under the iconbar icon 2.06 - Added routine PROCshell_WindowSendToBack - PROCshell_WindowBringToTop now works on all windows including those of the current task 2.07 - Added routine PROCshell_SpriteAreaInit - Added routine PROCshell_SpriteLoad - Added routine PROCshell_SpriteRemoveLeftWastage - Added routine PROCshell_SpriteGetSize - Added routine PROCshell_SpriteGetMode - Added routine PROCshell_SpriteLoadAsDraw - Added routine PROCshell_DrawSpriteArea - Added routine FNshell_SpritesGetHeaderSize 2.08 - Fixed bug in FNshell_IconIsWritable - Fixed bug in drag routines which resulted in problems with draggable non writable icons - Contents of draggable writable icons can be dragged to other writables with the following effects :- normal drag copies text from icon 1 to icon 2, overwriting the contents of icon 2. SHIFT deletes the text from icon 1 (i.e. a move). CTRL appends the text from icon 1 to the text of icon 2. SHIFT and CTRL can be used together. (I'll probably get a visit from the Style Guide Police over this one, but 'Personal Accounts 3' does something similar and I think it's useful!) - Added routine PROCshell_IconSetAllWritables - Added routine PROCshell_IconClearAllWritables - Added routine PROCshell_IconDisallowWritableDrags - Added routine PROCshell_IconAllowWritableDrags - Added routine PROCshell_WindowGetPosition - Added routine PROCshell_PointerGetPosition - Added routine PROCshell_PointerGetWindow - Added routine PROCshell_PointerGetIcon - Added routine PROCshell_WindowGetCentre - Added routine PROCshell_PointerGetMovementVector - Added routine PROCshell_PointerGetLastMovementVector - Added routine PROCshell_PointerChangeShape - Added routine PROCshell_PointerLimit - Added routine PROCshell_PointerRemoveLimits Page 23 EvntShell ________________________________________________________________________ - Added routine PROCshell_MouseRemoveLimits - Added routine PROCshell_MenuTickAllItems - Added routine PROCshell_MenuUntickAllItems - Added routine PROCshell_MenuShadeAllItems - Added routine PROCshell_MenuUnshadeAllItems - Added routine FNshell_IconWritableDragStatus - Added routine FNshell_WindowGetTopPaneDepth - Added routine FNshell_WindowGetBottomPaneDepth - Added routine FNshell_Evnts_DragIconStartIcon - Added routine FNshell_Evnts_DragIconStartWindow - Added routine FNshell_Evnts_WritableDragInProgress - Added routine FNshell_PointerIsBelowWindowCentre - Added routine FNshell_PointerIsAboveWindowCentre - Added routine FNshell_PointerIsRightOfWindowCentre - Added routine FNshell_PointerIsLeftOfWindowCentre - Attaching ClickSelect and ClickAdjust events to an icon now only changes the button type if the original type was 'never'. This enables these events to be attached to radio and option icons. - Fixed bug in DragSave routines that was preventing solid sprite dragging - PROCshell_IconEnsureVisible now autoscrolls windows with panes top and bottom correctly (it used to ignore panes!) - If a file icon is dragged from a static window the window is not now automatically closed at the end of the drag - WindowClose event fixed and documentation corrected - Bug in IconWatch handler fixed (returned "0" when string in a text icon was "" ) - Added extension library ShareBan to handle ShareWare banners 2.09 - Added routine PROCshell_PointerGetMouseButton - Fixed bug in routine that loads the EvntData file - Minor optimisations - FNshell_InstallLib removed 2.10 - Bug fix to code that checks whether a valid name has been entered in a file save window (problem with multiple save dboxes only) - Fixed bugs in PROCshell_MenuSortItems (was ignoring start element number and generally not working at all). Added default comparision routine for sorting menu text. 2.11 - Added routine FNshell_SliderGetHandle - Corrected docs for PROCshell_AttachTaskInitialiseHandler 2.12 - Fixed bug in PROCshell_MenuShadeAllItems - Fixed bug in FNshell_CalendarDaysInMonth (there's 31 days in January....) 2.13 - Fixed bug in FNshell_IconHasCaret (always returned FALSE) Page 24 EvntShell ________________________________________________________________________ - Fixed bug in PROCshell_IconPutData for writable icons (caret was being placed at the end of the old icon contents instead of the new contents) - Added routine PROCshell_HidePane - Added routine PROCshell_ShowPane 2.14 - Fixed various bugs in IconWatch event handling (wasn't working at all..) - Added docs for PROCshell_AttachSaveDesktopHandler - Added docs for PROCshell_AttachDeskFontChangeHandler - Added docs for PROCshell_AttachPointerEnteringWindow Handler - Added docs for PROCshell_AttachPointerLeavingWindow Handler 2.14a - Improved StrongHlp manual thanks to !StrongTst. No more dangling links or unreachable pages (I hope..). Lots of corrections to the ASCII documentation as well. 2.15 - Fixed bug in DataLoad routines (double click on a data file belonging to the application loaded the app but not the file). - Added routine PROCshell_DrawSetJoinStyleNone - Added routine PROCshell_DrawSetJoinStyleRound - Added routine PROCshell_DrawSetJoinStyleBevelled Page 25