home *** CD-ROM | disk | FTP | other *** search
/ ARM Club 1 / ARM_CLUB_CD.iso / contents / apps / program / d / eventshel1 / Docs / Manual-F < prev    next >
Encoding:
Text File  |  1994-02-07  |  64.6 KB  |  1,454 lines

  1.       Interim User Manual For EvntShell
  2.       ---------------------------------
  3.       
  4.       1  Introduction                          
  5.       2  Creating A New Application
  6.       3  A Tutorial
  7.       4  A General Overview
  8.           1.  Dynamic Windows
  9.           2.  Static Windows
  10.           3.  Resources
  11.                1. Templates
  12.                2. Sprites
  13.                3. Message Files
  14.                4. Modules
  15.           4.  Menus
  16.           5.  Saving Files
  17.           6.  Loading Files
  18.           7.  Compressing EvntShell Applications
  19.           8.  The RunTime Library
  20.           9.  The !ShellSys Application
  21.           10. Handling Panes
  22.           11. Outline Fonts
  23.           12. Interactive Help
  24.           13. User Redraws
  25.                1. Simple cases
  26.                2. Drawing into a sprite
  27.           14. Complex Icon Types
  28.                1. Bump Icons
  29.           15. Memory Management
  30.           16. Error Handling
  31.           17. Draw Files
  32.       5  The Tools
  33.           1. !AppBuild
  34.           2. !ShellDBug
  35.           3. Other Tools
  36.               1. !BasShrink/!BasShrink_PD
  37.               2. !BLibII
  38.               3. !TemplEd
  39.               4. !StrongEd2
  40.               5. !StrongHlp
  41.               6. !ThrowBack
  42.       6  Distributing EvntShell Applications
  43.       7  Debugging
  44.       8  The Credits
  45.       9  Future Enhancements
  46.       10 Changes Since V1.09
  47.  
  48.     
  49.       1. Introduction
  50.  
  51.       A 'Shell' program is a starting point for developing your own 
  52.       applications that run under the RISC-OS wimp system. The 
  53.       EvntShell library contains code to handle most of the 'Events' 
  54.       (i.e. opening a menu, closing a window etc) that can occur, and 
  55.       all your application has to do is inform the library what it 
  56.       should do when certain events occur. For example a menu can be 
  57.       attached to a window or to an icon - the library will open the 
  58.       menu for you (in the correct position!) when the <MENU> button on 
  59.       the mouse is used. 
  60.  
  61.       PROCshell_AttachModeChangeHandler is another very simple example 
  62.       which calls a function in the 'User Application' (this is the bit 
  63.       you write, starting with a 'Shell' created by the AppBuild tool 
  64.       or by modifying one of the examples) when the screen mode 
  65.       changes. A more complicated example is PROCshell_AttachPane which 
  66.       allows the attachment of pane windows to a parent window. All 
  67.       opening and closing of windows and panes is handled totally by 
  68.       the library code. 
  69.  
  70.       Normally writing a wimp application is a very complex business, 
  71.       involving much reading of the Programmers Reference Manuals, 
  72.       magazine articles and examining other applications. The aim of 
  73.       the EvntShell library is to reduce the need for this and to 
  74.       enable the speedy creation of easily maintained and robust 
  75.       applications. 
  76.  
  77.       Another important reason for using this Shell is that it attempts 
  78.       to ensure that any application written using it follows the RISC 
  79.       OS 3 Style Guide which defines how applications should look and 
  80.       behave. For example menus attached to icons ('popup' menus) 
  81.       appear to the right of the icon they are attached to and the 
  82.       mouse pointer is repositioned appropriately. Implementing the 
  83.       Style Guide recommendations is not easy and at the moment very 
  84.       few of the necessary changes to the library code have been made, 
  85.       however, this will improve in future releases. 
  86.  
  87.       In order to use the library it is necessary to have a reasonable 
  88.       understanding of how to use an Archimedes and the programs 
  89.       supplied with it. Some experience in BASIC is also of course 
  90.       required. This manual does not cover how to use tools like the 
  91.       Template editor which has its own instructions and may not have 
  92.       been supplied with your copy of the EvntShell library. 
  93.  
  94.       2. Creating An Example Application 
  95.  
  96.       The easiest way to create a new application is to use the 
  97.       AppBuild tool. Run this and drag the application icon from the 
  98.       AppBuild window to a directory display. The various options 
  99.       available using AppBuild will be discussed later, but for now 
  100.       just quit AppBuild and run the newly created application. You 
  101.       should see a blank icon appear on the icon bar and clicking 
  102.       <MENU> over this will bring up the usual icon bar menu including 
  103.       the items 'Info' and 'Quit'. 'Info' leads to the normal 'About 
  104.       This Program' window (the icons of which are blank at the moment) 
  105.       and 'Quit' which stops the application and removes it from the 
  106.       icon bar - don't quit it just yet. 
  107.  
  108.       Clicking <SELECT> on the iconbar icon will open a window which 
  109.       has the usual controls and may be scrolled and moved around the 
  110.       screen. Keep the application you have just created handy as in 
  111.       the next section we'll look at the program code and see how to 
  112.       change it to suit your own needs. 
  113.  
  114.       As you can see it is very easy to create a new shell application 
  115.       - even if this particular one doesn't do anything useful yet! 
  116.  
  117.       3. A Tutorial 
  118.  
  119.       The first few lines of any EvntShell program initialise the 
  120.       memory management, set up error handlers and load any resources 
  121.       (templates, message files, sprites etc) required by the program. 
  122.       This code should not need editing. PROCapp_init determines what 
  123.       happens when the application starts, in this case an iconbar icon 
  124.       is created and various 'events' are attached to it. The code 
  125.       created by !AppBuild is as shown below, although the REMs have 
  126.       been added for this manual. Try defining other windows and menus 
  127.       and see what happens. 
  128.  
  129.       
  130.       DEF PROCapp_init
  131.       PROCSetUp_Menus   :REM set up iconbar menu
  132.       PROCSetUp_Windows :REM set up main window
  133.       PROCSetUp_IconBar :REM put icon on the iconbar and attach events
  134.       REM and now initialise the StrongHlp help system (optional!)
  135.       PROCshell_InitHelpSystem(FNshell_GetAppDir+".FNshell_GetAppName"
  136.       ,TRUE)
  137.       ENDPROC 
  138.       :
  139.       REM ===== Menu_Setup routines ===================================
  140.       
  141.       DEF PROCSetUp_Menus
  142.       LOCAL void%
  143.       REM Construct the iconbar menu..
  144.       MenuHandle_IconBar%=FNshell_MenuNew("NewApp")
  145.       MenuItem_Info%     =FNshell_MenuAdd(0,"Info","")
  146.       void%              =FNshell_MenuAdd(0,"Quit","_MenuSelect_Quit")
  147.       REM Attach the 'About this program' dialog box to the 'Info'
  148.       REM item of the menu. Call FN_PreOpenInfo before opening it so
  149.       REM that the icons can be filled in, don't call a FN after
  150.       REM opening it.
  151.       PROCshell_AttachMenuDBox(MenuItem_Info%,"progInfo",
  152.       "_PreOpenInfo","")
  153.       ENDPROC
  154.       :
  155.       
  156.       REM ===== Window_SetUp routines =================================
  157.       
  158.       DEF PROCSetUp_Windows
  159.       REM create a window from the template called 'mainw', place the
  160.       REM window handle in mainw%
  161.       PROCshell_CreateWindowStatic("mainw",mainw%)
  162.       ENDPROC
  163.       :
  164.       
  165.       REM ===== IconBar_SetUp routines ================================
  166.       
  167.       DEF PROCSetUp_IconBar
  168.       REM sicon is the handle of the icon. -1 means right side of
  169.  
  170.       REM iconbar, -2 would be left side. The name of the sprite for
  171.       REM the icon is the same as the application directory. A menu
  172.       REM with the handle 'MenuHandle_IconBar%' is attached.
  173.       sicon=FNshell_Iconbar(-1,"!"+FNshell_GetAppName,"",120,
  174.       MenuHandle_IconBar%,0,0,0)
  175.       REM attach a help tag for the icon, this will send the text
  176.       REM following 'iconbar:' to the !Help application. See the
  177.       REM 'Messages' file for this.
  178.       PROCshell_AttachHelpTag(-1,sicon,"iconbar")
  179.       REM lastly attach the clickselect event. When <SELECT> is
  180.       REM clicked over the icon call FN_clickiconbar
  181.       PROCshell_AttachClickSelect(-1,sicon,"_ClickSelect_IconBar")
  182.       ENDPROC
  183.       :
  184.       
  185.       REM ===== Dialog_PreOpen routines ===============================
  186.       
  187.       DEF FN_PreOpenInfo(h%)
  188.       REM fill in icons. Try editing the 'Messages' file to make text
  189.       REM appear in the icons (just add the text after progInfo0: etc).
  190.       REM h% is the handle of the window.
  191.       PROCshell_IconPutData(h%,0,FNshell_MessageNoArgs("progInfo0"),0)
  192.       PROCshell_IconPutData(h%,1,FNshell_MessageNoArgs("progInfo1"),0)
  193.       PROCshell_IconPutData(h%,2,FNshell_MessageNoArgs("progInfo2"),0)
  194.       PROCshell_IconPutData(h%,3,FNshell_MessageNoArgs("progInfo3"),0)
  195.       =0
  196.       :
  197.       
  198.       REM ===== Dialog_PostOpen routines ==============================
  199.       
  200.       REM ===== Click_Select routines =================================
  201.       
  202.       DEF FN_ClickSelect_IconBar(wh%,icon%)
  203.       REM open the window with the handle mainw% when a click of
  204.       REM <SELECT> is received on the iconbar icon. wh% is the handle
  205.       REM of the window over which the click occured (the iconbar) and
  206.       REM icon% is the handle of the iconbar icon
  207.       PROCshell_OpenWindowStatic(mainw%)
  208.       =0
  209.       :
  210.       
  211.       REM ===== Menu_Select routines ==================================
  212.       
  213.       DEF FN_MenuSelect_Quit(blk%)
  214.       _closedown%=TRUE
  215.       =0
  216.       :
  217.       
  218.       REM ===== Menu_Warning routines =================================
  219.       
  220.       REM ===== Data_Load routines ====================================
  221.       
  222.       REM ===== Data_Save routines ====================================
  223.       
  224.       
  225.       Let us now look at how events should be attached to a window. It 
  226.       is important to always do this just before the window opens (i.e. 
  227.       in the PreOpen routine) because a static window and a dynamic 
  228.       window can be created from the same template but they will of 
  229.       course have different handles. The following example shows how 
  230.       this should be handled (we are assuming the template in question 
  231.  
  232.       is called 'xfer' and the program is called 'MyApp'). 
  233.  
  234.       
  235.       DEF PROCapp_init
  236.       ...
  237.       PROCSetUp_Windows
  238.       PROCSetUp_Menus
  239.       
  240.       PROCshell_AttachHotKey("F3",FALSE,FALSE,FALSE,"",xfer%,"_PreOpen_Xfer","")
  241.       ...
  242.       ENDPROC
  243.       :
  244.       DEF PROCSetUp_Windows
  245.       ...
  246.       PROCshell_CreateWindowStatic("xfer",xfer%)
  247.       ...
  248.       ENDPROC
  249.       :
  250.       DEF PROCSetUp_Menus
  251.       ...
  252.       MenuHandle_IconBar%=FNshell_MenuNew("MyApp")
  253.       MenuItem_Save%     =FNshell_MenuAdd(0,"Save","")
  254.       PROCshell_AttachMenuDBox(MenuItem_Save%,"xfer","_PreOpen_Xfer",
  255.       "_PostOpen_Xfer")
  256.       ...
  257.       ENDPROC
  258.       :
  259.       DEF FN_PreOpen_Xfer(h%)
  260.       ...
  261.       REM OK icon is 0, Filename icon is 2, File icon is 3, Filetype is 
  262.       &344..
  263.       PROCshell_IconPutData(h%,2,filename$),FALSE)
  264.       PROCshell_AttachDataSave(h%,3,100,&344,2,"_DataSave_Xfer")
  265.       PROCshell_AttachClickSelect(h%,0,"_ClickSelect_XferOK")
  266.       ...
  267.       =0
  268.       :
  269.       DEF FN_PostOpen_Xfer(h%)
  270.       ...
  271.       PROCshell_WindowCentreOnPointer(h%)
  272.       ...
  273.       =0
  274.       :
  275.       
  276.       
  277.       The xfer window will open when F3 is pressed (assuming one of the 
  278.       open windows has the 'grab hot keys' bit set) and also when the 
  279.       sub menu on the 'Save' menu item is opened. In each case 
  280.       FN_PreOpen_Xfer will be called to attach the events and fill in 
  281.       the filename icon. 
  282.  
  283.       4. General Overview 
  284.  
  285.       This section explains the various elements of an application 
  286.       using the EvntShell library, and any limitations and assumptions 
  287.       made by me. 
  288.  
  289.       4.1 Dynamic Windows 
  290.  
  291.       Dynamic windows are those created by moving the pointer over a 
  292.       submenu pointer arrow (i.e the normal 'About this program' window 
  293.       produced by the 'Info' entry on the iconbar menu) or optionally 
  294.       when a 'hot key' is pressed (for example F3 in most applications 
  295.       opens a save box). They are opened with a call to 
  296.       PROCshell_OpenWindowDynamic. 
  297.  
  298.       When writable icons exist in the dynamic window up/down cursor 
  299.       and TAB/SHIFT TAB keypresses move the caret between the icons 
  300.       using the icon handles to determine where to move next. You 
  301.       should ensure therefore that the order of the icon handles is a 
  302.       logical progression through the dialog box. Icons which are 
  303.       unselectable (i.e. greyed out) will be ignored. Pressing the 
  304.       <RETURN> key causes icon 0 to be pressed (normally a 'default 
  305.       action' icon with an extra border) and the menu/dialog box to be 
  306.       closed. Actually clicking <SELECT> on icon 0 of a dynamic dialog 
  307.       box will cause the shell library to close the window as well. 
  308.  
  309.       When a 'hot key' is pressed you have the option of opening a 
  310.       dynamic dialog box which will disappear when a mouse click is 
  311.       made outside it or the <ESC> key is pressed, or as a 'Static' 
  312.       dialog box which must be explicitly closed by the user 
  313.       application program. 
  314.  
  315.       Do not attempt to close a dynamic dialog box with a call to 
  316.       PROCshell_CloseWindow or PROCshell_DeleteWindow as this will 
  317.       cause an error when the shell library tries to close or delete 
  318.       the window. 
  319.  
  320.       All windows used by the user application are assumed to be 
  321.       defined in the 'Templates' file and edited using FormEd or one of 
  322.       the Public Domain/ShareWare equivalents. 
  323.  
  324.       4.2 Static Windows 
  325.  
  326.       These are opened with a call to PROCshell_OpenWindowStatic and 
  327.       respond to cursor,TAB and <RETURN> keypresses like dynamic dialog 
  328.       boxes except that pressing <RETURN> will not close the window. 
  329.       Static windows must be created with a call to 
  330.       PROCshell_CreateWindowStatic. 
  331.  
  332.       Closing these windows is the responsibility of the application 
  333.       program (use PROCshell_CloseWindow) except in the case of a click 
  334.       on the 'Close' icon in the title bar icon (if present). 
  335.  
  336.       You would use a static window for the main window of an 
  337.       application, or perhaps for a save box as in the case of the 
  338.       !WinSave2 example. The advantage of using a static window in this 
  339.       case is that this allows the user to open directory viewers or 
  340.       start other applications while keeping the save box on the 
  341.       screen. 
  342.  
  343.       4.3 Resources 
  344.  
  345.       'Resources' is a general term for additional files needed by an 
  346.       application. There will (almost) always be some of these, such as 
  347.       sprite files. Others, for example message files may not be 
  348.       required. 
  349.  
  350.       The EvntShell library now supports ResFind which allows the 
  351.       selection of the desired language for message files etc much 
  352.       easier. Briefly explained it checks the currently configured 
  353.       language of the computer it is running on and sets up a path to 
  354.       the resource files. This would normally be <App$Dir>.Resources.UK 
  355.       for a UK configured computer, or <App$Dir>.Resources.Germany for 
  356.       a German one. This is handled for you if you use !AppBuild to 
  357.       create the application. 
  358.  
  359.       AppBuild now offers to place the resources in the appropriate 
  360.       directories for you when you create a new application, and to 
  361.       place a call to ResFind in the !Run file. 
  362.  
  363.       Using ResFind is optional and EvntShell applications will 
  364.       function equally well if you don't use it. It does make the 
  365.       production of applications that can be easily used in any country 
  366.       much easier, however, and this should be encouraged. Most of the 
  367.       programming tools and modules used during the development of this 
  368.       library were written outside the UK. 
  369.  
  370.       The author would appreciate help in translating the ShellMsgs 
  371.       file and the documentation into other languages. 
  372.  
  373.       The full ResFind documentation supplied with the library contains 
  374.       further details on how it works and the advantages to be gained 
  375.       by using it. As a taster, here is the part of the documentation 
  376.       intended to be distributed with applications using ResFind. 
  377.  
  378.       (Base for the application's documentation - please replace 
  379.       <ProgName> by the name of your application without the !) 
  380.  
  381.       !<ProgName> adapts automatically to the configured language if 
  382.       the corresponding messages etc. are available. For this purpose a 
  383.       Resources directory is contained in the application in which a 
  384.       subdirectory for each language supported resides. If the language 
  385.       you need isn't in there, please feel free to duplicate any of 
  386.       these language directories and translate the contents. 
  387.  
  388.       When you run the program a utility called ResFind is called which 
  389.       reads the language your computer is configured to and then looks 
  390.       for the corresponding language directory. If this fails the 
  391.       program will run in English (UK). By setting several system 
  392.       variables (best done in your system's !Boot file) you can change 
  393.       the language looked for. With this you can make sure a program 
  394.       runs in a certain language, e.g. to avoid a weird translation. 
  395.       Furthermore it is possible to name several languages you prefer 
  396.       to English. 
  397.  
  398.       This is controlled by three system variables: 
  399.  
  400.       
  401.       <ProgName>$Language, ResFind$LanguagesPref and 
  402.       ResFind$Languages$Suff.
  403.       
  404.       
  405.       When running the application ResFind looks for the first language 
  406.       supported along the following list of languages: 
  407.  
  408.       
  409.        1. Contents of the variable <ProgName>$Language
  410.        2. Contents of the variable ResFind$LanguagesPref
  411.        3. The configured language
  412.        4. Contents of the variable ResFind$LanguagesSuff
  413.        5. UK
  414.       
  415.       
  416.       Take a Norwegian user for example (lots of great programs come 
  417.       from there) whose computer is configured to 'Norway'. Since this 
  418.       language isn't too common in Europe most programs won't support 
  419.       it - except for Norwegian ones. But our user is pretty good in 
  420.       German and French but not too fond of English. Therefore he 
  421.       prefers these languages to UK and would thus put the following 
  422.       line in his system's !Boot file: 
  423.  
  424.       
  425.       *Set ResFind$LanguagesSuff Germany,France
  426.       
  427.       
  428.       Running an applications (such as this one) using ResFind the list 
  429.       of languages looked for is 'Norway,Germany,France,UK'. 
  430.  
  431.       In case this user has an application called !Pete supporting the 
  432.       language 'Humorous' the line: 
  433.  
  434.       
  435.       *Set Pete$Language Humor
  436.       
  437.       
  438.       in the !Boot file makes sure !Pete will run humorous. 
  439.  
  440.       A brief description of the various resource files follows. 
  441.  
  442.       4.3.1 Templates 
  443.  
  444.       All windows used by programs based on the shell library would 
  445.       normally be defined using a template editor as this is far 
  446.       simpler than creating the windows/icons in the user program. This 
  447.       is not as inflexible as it may sound as windows and icons can be 
  448.       resized, moved or otherwise altered by shell library routines. 
  449.  
  450.       The template file must be called 'Templates' and be either in the 
  451.       application directory or in the appropriate language directory if 
  452.       ResFind is in use. Note that if you are using different templates 
  453.       for different languages you must use ResFind. In most cases, 
  454.       however, it is sufficient to have only one template file in the 
  455.       application directory and to insert the text taken from the 
  456.       message file in the language of choice into the icons. 
  457.  
  458.       A call to PROCshell_ResourcesInit will find the template file and 
  459.       load all the templates it contains allocating memory as required. 
  460.  
  461.       4.3.2 Sprites 
  462.  
  463.       The sprite file must be called 'Sprites' and be either in the 
  464.       application directory or in the appropriate language directory if 
  465.       ResFind is in use. A call to PROCshell_ResourcesInit will find 
  466.       the file if it exists and load all the sprites it contains 
  467.       allocating memory as required. 
  468.  
  469.       Optionally a second sprite file called 'Sprites22' containing 
  470.       high resolution sprites for users with multisync monitors may be 
  471.       present. If the application is started in a high resolution 
  472.       screen mode and 'Sprites22' is available it will be loaded 
  473.       instead of 'Sprites'. 
  474.  
  475.       The sprite area pointer for each loaded template will be set to 
  476.       point to the user sprite area, which put simply this means that 
  477.       all sprites displayed in windows must be present in the 'Sprites' 
  478.       and 'Sprites22' files. This may, however, be changed after 
  479.       loading with a call to FNshell_WindowSetSpriteArea. 
  480.  
  481.       4.3.3 Message Files 
  482.  
  483.       The message file is a normal ASCII file written using !Edit or 
  484.       similar that contains message strings preceeded by a message tag. 
  485.       The application program should find the messages as required by 
  486.       tag name which allows the production of foreign language versions 
  487.       (probably by someone else!). It is also far easier to edit the 
  488.       message file to change text displayed by the application than 
  489.       using !FormEd or similar. 
  490.  
  491.       The !Run file of the user application automatically loads a 
  492.       support module 'MsgTrans' if required (it is built in to RISC OS 
  493.       3) to provide this facility. 
  494.  
  495.       The message file must be called 'Messages' and be in the 
  496.       application directory or in the appropriate language directory if 
  497.       ResFind is in use. A call to PROCshell_ResourcesInit will find 
  498.       the file if it exists and load all the messages it contains 
  499.       allocating memory as required. 
  500.  
  501.       The messages issued by the library code are stored in a file 
  502.       called 'ShellMsgs' inside the !ShellSys.Resources.UK directory. 
  503.       If this file is present in the user application directory (or the 
  504.       application Resources directory) then it is loaded from there, if 
  505.       not it is loaded from !ShellSys. This is to aid the construction 
  506.       of stand alone applications. 
  507.  
  508.       4.3.4 Modules 
  509.  
  510.       Various Public Domain modules are used by the EvntShell library, 
  511.       these are stored in the !ShellSys application and loaded as 
  512.       required. A full list is: 
  513.  
  514.       
  515.       Interface   - 3D icon effects, changing pointer shapes etc
  516.       MenuUtils   - menu handling
  517.       FontMenu    - font menu handling
  518.       MsgTrans    - message files (supplied for Risc-OS 2
  519.                     compatability)
  520.       FontWindow  - handling outline fonts across mode changes (not
  521.                     used at the moment)
  522.       
  523.       
  524.       Note that in general no documentation is supplied for these 
  525.       modules, it is all available elsewhere (or why not write to the 
  526.       author?) 
  527.  
  528.       The EvntShell library makes the assumption that the interface 
  529.       module will always be used. The reason is that firstly that it is 
  530.       highly likely that some other PD program will have already loaded 
  531.       it, and secondly that the facilities it provides for changing 
  532.       pointer shapes over certain icons is extremely useful as a prompt 
  533.       for what the icon is for. Indeed RISC-OS 3 has this built in so 
  534.       even Acorn are supporting 3D buttons etc.... 
  535.  
  536.       The module is loaded by the !Run file if not already loaded. 
  537.       Using a template editor that is 'Interface Aware' makes 
  538.       incorporating these effects into a user program easy as once the 
  539.       icons have been designed and placed the shell library handles all 
  540.       the redrawing automatically. 
  541.  
  542.       Note that windows containing 3d interface icons must have the 
  543.       'Auto Redraw' flag off, but if the template editor displays 
  544.       interface icons then the user application will as well. 
  545.  
  546.       4.4 Menus 
  547.  
  548.       Menus are now handled by MenuUtils which was written by Alex 
  549.       Petrov. Versions of the library prior to 1.20 used a menu editor 
  550.       to create a seperate menu template file, but I have now abandoned 
  551.       this as it was rather inflexible. 
  552.  
  553.       The use of MenuUtils has enabled me to remove large chunks of 
  554.       slow BASIC code and to provide many more features, such as 
  555.       creation and modification of menus under program control. The 
  556.       menus themselves appear more quickly as well (OK Cy?). 
  557.  
  558.       Menus may be created by calling functions in the user 
  559.       application, or from a menu command file. The file option is 
  560.       especially useful for lists of items that can be edited by the 
  561.       user - for example the new version of !VideoBase uses menu 
  562.       command files for lists of commonly used categories of recordings 
  563.       (Documentary, Action Film etc) a menu of which can be attached to 
  564.       an icon for easy access. As the command file is a simple text 
  565.       file it is very easy to edit to meet special requirements. 
  566.  
  567.       A demonstration application !TestMenu should have been supplied 
  568.       with the library code so that you can try out some of the 
  569.       possibilities yourself. 
  570.  
  571.       The appearance of the RISC OS 3 Style Guide has caused a few 
  572.       changes in the way that EvntShell handles 'popup' menus (menus 
  573.       attached to icons in windows other than the iconbar). Firstly 
  574.       they appear to the right of the icon they are attached to, the 
  575.       mouse pointer also moving to the recommended position, and 
  576.       secondly only SELECT and MENU will call up a popup menu. 
  577.  
  578.       Note that menus can only be attached to icons in static windows, 
  579.       because as far as RISC OS is concerned a dynamic window is a 
  580.       menu. 
  581.  
  582.       The support module is automatically loaded by the !Run file to 
  583.       provide the new menu handling SWIs used by the EvntShell library. 
  584.  
  585.       4.5 Saving Files 
  586.  
  587.       This is achieved by a call to PROCshell_AttachDataSave which 
  588.       specifies which filetype the saved file should be given, the name 
  589.       of a function which will actually perform the save and the 
  590.       window/icon handles the drag save event is associated with. It is 
  591.       therefore possible to have different drag save events attached to 
  592.       different icons in the same window. This is useful where it is 
  593.       possible to save the file as more than one type - you can have 
  594.       multiple filetype icons in the save window. 
  595.  
  596.       PROCshell_AttachDataSave also performs some checking when it is 
  597.       called. For example an error message is generated if the file 
  598.       icon is not a sprite icon. The button type of the file icon is 
  599.       also changed to Click/Drag to avoid the need to get this correct 
  600.       when editing the template file. 
  601.  
  602.       The EvntShell library supports RAM file transfer for speed when 
  603.       saving data to consenting applications. 
  604.  
  605.       See the !WinSave2 and !VBase2 example applications for how to use 
  606.       this routine. 
  607.  
  608.       4.6 Loading Files 
  609.  
  610.       This is achieved by a call to PROCshell_AttachDataLoad which 
  611.       tells the EvntShell library which filetypes the user application 
  612.       is interested in and the name of a function to call when a load 
  613.       event occurs. Multiple files may be loaded, but in the current 
  614.       release of the library it is up to the user application to keep 
  615.       track of where they are loaded and if they have been modified. 
  616.       This will change in a future release. 
  617.  
  618.       When the event is attached a check is made to see if the 
  619.       application was started by double clicking a file which 'belongs' 
  620.       to it. If the filetypes match then the file is loaded as if it 
  621.       had been dragged to the icon bar icon. A filetype is associated 
  622.       with an application by the inclusion of the line: 
  623.  
  624.       
  625.       Set Alias$@RunType_xxx Run <Obey$Dir>.!Run %%*0
  626.       
  627.       
  628.       where xxx is the filetype number. 
  629.  
  630.       If required the files can be loaded automatically into a reserved 
  631.       block of memory, or the user application can have total control 
  632.       over loading and processing the file. 
  633.  
  634.       The EvntShell library supports RAM file transfer for speed when 
  635.       loading data from consenting applications. 
  636.  
  637.       It is also possible to arrange for the user application to 
  638.       respond to a range of filetypes by attaching more than one 
  639.       handler. 
  640.  
  641.       An example application !DataLoad should have been included with 
  642.       the Library to demonstrate how to do this. 
  643.  
  644.       This is the code from !DataLoad used to achieve the load : 
  645.  
  646.       
  647.       PROCshell_AttachDataLoad(mainw%,0,&FEC,"_dataloadFEC",TRUE)
  648.       
  649.       
  650.       The first parameter, mainw% is the wimp window handle, the second 
  651.       is the icon handle. &FEC is the filetype to respond to and 
  652.       '_dataloadFEC' is the name of the function to call to actually 
  653.       load the file. The last parameter is TRUE to load the file 
  654.       automatically into a reserved block of memory or FALSE if you 
  655.       want to handle the loading yourself. In this case loading is 
  656.       automatic and the loading function is simply: 
  657.  
  658.       
  659.       DEF FN_dataloadFEC(loc%,type%,name$,file_size%)
  660.       void%=FNshell_MessageWindow("File '"+name$+"'",0,"DataLoad","")
  661.       =0
  662.       
  663.       
  664.       The data file (of type &FEC, template) has been loaded at 
  665.       location loc%, its type is in type% and the full path name of the 
  666.       file is in name$. All the function itself does is call another 
  667.       function to display a message window so that you can see that 
  668.       loading the file has worked. This is a useful debugging 
  669.       technique! 
  670.  
  671.       This method of loading a file works well for datafiles that are 
  672.       stored as one continuous block of data such as a text file which 
  673.       will be processed in some way. Suppose, however, you have a 
  674.       simple database type application which needs to load data into 
  675.       BASIC arrays. In this case you would simply use (assuming now the 
  676.       filetype is &205): 
  677.  
  678.       
  679.       PROCshell_AttachDataLoad(mainw%,0,&205,"_dataload205",FALSE)
  680.       
  681.       
  682.       FN_dataload205 receives the full pathname of the file which has 
  683.       been dragged to icon 0 (providing the filetype of the file was 
  684.       &205, otherwise the load will be ignored) which may now be opened 
  685.       and the data loaded as usual. If the 'no load' flag was set for 
  686.       this load event and the load was from another application the 
  687.       data is saved in a file called 'ScrapFile' in the user 
  688.       application directory. 
  689.  
  690.       4.7 Compressing EvntShell Applications 
  691.  
  692.       Due to the complex nature of the library code and the desire for 
  693.       it to do as much as possible to make a user application easy to 
  694.       write the ShellLib library file has expanded to around 150K. This 
  695.       is obviously undesirable especially if you are planning to send 
  696.       your finished program to a PD library. If you want people to be 
  697.       able to read your source code you can use the 'RunTime' version 
  698.       of the library which has been mildly compressed, but for the 
  699.       smallest possible program it is necessary to append the library 
  700.       (either version) to the end of the user application, remove the 
  701.       line which loads the library file and run the whole lot through a 
  702.       BASIC program compressor. 
  703.  
  704.       I recommend !BasShrink or !Shrink_PD (the Public Domain version 
  705.       of !BasShrink) by John Wallace although John's program is slow 
  706.       and not presently multitasking it does produce code that still 
  707.       runs! This is unfortunately not true of Cy Booker's otherwise 
  708.       superb !BC which will not work on the EvntShell library. However, 
  709.       if I or Cy can find out what the problem is we'll fix it. 
  710.  
  711.       Future versions of !BasShrink should be able to remove unused 
  712.       routines to save even more space, or alternatively BLibII can be 
  713.       used to pre-process the application to link in only the routines 
  714.       that are actually used. See the manual section 'Other Tools' for 
  715.       more details. 
  716.  
  717.       There is one important point to bear in mind when using the shell 
  718.       library and !BasShrink together - function names that are 
  719.       EVALuated by the shell library should begin with a '_' character 
  720.       and the 'Preserve names starting with' radio button in the 
  721.       !BasShrink window must be ON. In short if you are calling any 
  722.       shell library routine that has a function name as a parameter 
  723.       then that name must start with a '_'. Failure to observe this 
  724.       rule will result in a non-working compressed program! 
  725.  
  726.       Assuming you have !BasShrink 2.14 or later the EvntShell library 
  727.       can be compressed with all switches on except 'Shorten FN names', 
  728.       'Shorten PROC names' and 'Remove * comments'. If you are not 
  729.       going to use !BLibII you can switch on 'Remove * comments' to 
  730.       strip out the !BLibII commands. 
  731.  
  732.       If you append the EvntShell library to the user application 
  733.       manually or by using BLibII you can compress the complete program 
  734.       with all switches on. 
  735.  
  736.       4.8 The RunTime Library 
  737.  
  738.       This is a compressed version of the full library which should be 
  739.       used wherever possible as it will load and run faster. The only 
  740.       reason for using the uncompressed library would be to add extra 
  741.       debugging code or perhaps to modify the routines. In this case, 
  742.       however, it is better to just copy the uncompressed routine into 
  743.       the user application and edit it there. 
  744.  
  745.       The uncompressed version is called ShellLib, the compressed 
  746.       version is ShellLibRT. Both can be found inside the !ShellSys 
  747.       application directory. 
  748.  
  749.       The ShellLibRT file has had the BLibII commands stripped out to 
  750.       save space. 
  751.  
  752.       4.9 The !ShellSys Application 
  753.  
  754.       As large chunks of code are common to all EvntShell applications 
  755.       it makes sense to store it only once on the disk, hence !ShellSys 
  756.       which should be treated like the !System application. If you have 
  757.       a hard disk put it in the root directory (or ensure it is booted 
  758.       by your Boot file). If you have a floppy only system put it on 
  759.       all your disks (removing the ShellLib file and making sure all 
  760.       EvntShell applications use ShellLibRT will help save disk space). 
  761.       The system message file and various modules are also to be found 
  762.       here. 
  763.  
  764.       4.10 Handling Panes 
  765.  
  766.       A pane window is a window attached to a parent window which has 
  767.       different properties to the parent. A well-known example is the 
  768.       'ToolBox' pane attached to a !Draw window which always appears at 
  769.       the top left of the parent window however the parent window is 
  770.       scrolled. Another example could be a parent window without 
  771.       scrollbars which has a scrolling pane attached to the work area 
  772.       which might be used in a 'FindFile' application to display a list 
  773.       of finds. 
  774.  
  775.       Panes are created using !FormEd or similar with the 'pane' flag 
  776.       set. A call to PROCshell_AttachPane specifies which pane is 
  777.       attached to which window and the position of the pane. Multiple 
  778.       panes may to attached to a parent window (see the example 
  779.       application !Panes). 
  780.  
  781.       The opening and closing of panes is handled totally by the shell 
  782.       library - a call to PROCshell_OpenWindow after attaching the 
  783.       panes will open the parent window and the panes together. 
  784.  
  785.       It is normally necessary for certain bits in the window 
  786.       definition block to be set up in a special way if a window is to 
  787.       be treated as a pane. This is not required when using the 
  788.       EvntShell library as the act of attaching the event makes the 
  789.       changes needed. 
  790.  
  791.       You should avoid attaching a pane to a parent window where it is 
  792.       possible to resize the parent in such a way that the pane lies 
  793.       outside the window it is attached to. This will cause (non-fatal) 
  794.       problems when the windows are redrawn. Most RISC OS programs also 
  795.       avoid this for the same reasons. 
  796.  
  797.       When attaching a pane it is possible to specify a 'pane flag' 
  798.       value which determines where the pane will be attached and to 
  799.       some extent how it will behave when the parent window is resized. 
  800.       The currently valid pane flags are: 
  801.  
  802.       
  803.         0 = attached to parent window work area
  804.         1 = attached to left edge outside parent
  805.         2 = attached to top edge
  806.         3 = attached to left edge inside parent
  807.         4 = attached to bottom edge
  808.         5 = attached to right edge
  809.       
  810.       
  811.       In cases 1-5 the library will attempt to stretch the pane window 
  812.       so that it will fill the whole width or depth of the parent 
  813.       window. 
  814.  
  815.       4.11 Outline Fonts 
  816.  
  817.       The EvntShell Library supports Outline Fonts in two ways at the 
  818.       moment. Firstly Joris Röling's FontMenu module is used to display 
  819.       a menu of all available fonts on the system, and secondly the 
  820.       window template loading routine allows icons and window titles to 
  821.       use fonts. 
  822.  
  823.       Routines are provided to attach a font menu to an existing menu 
  824.       as a submenu (PROCshell_AttachFontSubMenu), or to open the font 
  825.       menu as a menu in its own right (PROCshell_AttachFontMenu). If 
  826.       the user makes a valid font selection the font name can be 
  827.       retrieved (with FNshell_FontMenuGetLastSelectedFont) for use in 
  828.       the user application. Changes to the Font$Path variable such as 
  829.       adding or removing font directories are detected and the font 
  830.       menu rebuilt as necessary. 
  831.  
  832.       It will not, however, detect fonts being added or removed from an 
  833.       existing font directory while the EvntShell application is 
  834.       running. It appears that a re-boot is required to sort things out 
  835.       after the contents of the font directories have changed. Oh well, 
  836.       it seems that a lot of other applications can't cope with this 
  837.       either! 
  838.  
  839.       The FontMenu module creates a menu in the relocatable module area 
  840.       which is shared between all applications wishing to use it. As a 
  841.       font menu potentially takes up a lot of space this is a very 
  842.       efficient way of handling it, especially as the menu is laid out 
  843.       so that it is easier to use than a straight list of fonts. 
  844.  
  845.       A help system containing the full FontMenu documentation is 
  846.       supplied with the EvntShell library as it is a requirement that 
  847.       the the module and its documentation must be supplied together. 
  848.       However, it is unlikely that the SWIs provided by the module will 
  849.       need to be called by the user application as the library code 
  850.       performs the necessary actions. 
  851.  
  852.       The example application !Redraw demonstrates the use of these 
  853.       routines. 
  854.  
  855.       4.12 Interactive Help 
  856.  
  857.       The EvntShell library supports Acorn's Interactive Help 
  858.       application !Help by searching icon validation strings for the 
  859.       'I' command (as recommended by the author of the Interface 
  860.       module) for a message tag. 
  861.  
  862.       The message belonging to the tag will be looked up and sent to 
  863.       !Help (if !Help is running). An example would be a validation 
  864.       string of "iMessTag01", where the file 'Messages' contains the 
  865.       line 'MessTag01:This is a test'. 'This is a test' would be the 
  866.       message displayed. 
  867.  
  868.       It is also possible to attach a message tag to a window or a 
  869.       window/icon using PROCshell_AttachHelpTag. A message tag is a 
  870.       string consisting of not more than 11 characters long and 
  871.       represents a message string to be found in the 'Messages' file. 
  872.  
  873.       4.13 User Redraws 
  874.  
  875.       4.13.1 Simple Cases 
  876.  
  877.       By 'Simple Cases' I mean text, lines, arcs, filled shapes etc. In 
  878.       other words anything that it is easy for the program to redraw 
  879.       quickly - this excludes maps of the world and any kind of random 
  880.       display. For these cases it is much faster to redirect the screen 
  881.       output into a sprite (see the next section). 
  882.  
  883.       Using the example application you created earlier (or create a 
  884.       new one using AppBuild) add the following line to 
  885.       PROCSetUp_Windows: 
  886.  
  887.       
  888.       PROCshell_AttachUserRedraw(mainw%,"_redraw")
  889.       
  890.       
  891.       and add the following FN definition: 
  892.  
  893.       
  894.       DEF FN_redraw(blk%,x0%,y0%)
  895.       REM set colour for circle - colours are numbered 0-15!
  896.       REM draw the circle..
  897.       SYS "Wimp_SetColour",11
  898.       CIRCLE FILL x0%+200,y0%-200,120
  899.       REM set colour for text...
  900.       SYS "Wimp_SetColour",8 :REM colours are numbered 0-15!
  901.       MOVE x0%+80,y0%-340:PRINT "This is an example of"
  902.       MOVE x0%+40,y0%-380:PRINT "user drawn text and graphics"
  903.       MOVE x0%+95,y0%-420:PRINT "in a desktop window"
  904.       =0
  905.       
  906.       
  907.       The routine that attaches the redraw event also alters the 
  908.       'flags' of the window so that the 'Auto redraw' bit is set up 
  909.       correctly. When you run the application and open the main window 
  910.       now, a circle and some text will appear in the window. If another 
  911.       window is moved over this one, note that the window is correctly 
  912.       redrawn. 
  913.  
  914.       The parameters x0% and y0% for the redraw routine are the 
  915.       coordinates of the top left corner of the window. Note that y 
  916.       coordinates are negative! Try experimenting with other drawing 
  917.       commands and putting text in different places in the window to 
  918.       get the hang of this. 
  919.  
  920.       4.13.2 Drawing Into A Sprite 
  921.  
  922.       With a more complicated or random display you need to set up a 
  923.       sprite to draw into. The example application !Redraw2 shows how 
  924.       to do this. 
  925.  
  926.       Note in this case that the display within the window is animated 
  927.       by calling the plotting routine at every null event received. 
  928.       There also has to be two redrawing routines, one called when you 
  929.       want the display redrawn and one for when the wimp wants it 
  930.       redrawn (hence the call to PROCshell_AttachUserRedraw). In both 
  931.       cases it is necessary just to replot the sprite. 
  932.  
  933.       4.14 Complex Icons 
  934.  
  935.       4.14.1 Bump Icons 
  936.  
  937.       Bump icons are simply a pair of (usually!) arrow shaped icons 
  938.       that effect the value displayed in a third icon. The EvntShell 
  939.       library allows you to create this effect with one call to 
  940.       PROCshell_AttachBumpIconHandler. 
  941.  
  942.       Note that clicking on a bump icon which ADJUST has the opposite 
  943.       effect to using SELECT, i.e. ADJUST on the decrement icon 
  944.       actually increases the value. This is normal RISC OS behaviour 
  945.       and is intended to avoid unnecessary mouse movements. 
  946.  
  947.       See the !VBase2 demo application for an example of its use. 
  948.  
  949.       4.15 Memory Management 
  950.  
  951.       A crucial element of the EventShell library is the use of memory 
  952.       management routines originally published in Risc User magazine 
  953.       and used with permission. Many library routines require some 
  954.       memory workspace and they obtain this by calling 
  955.       FNshell_HeapBlockFetch(bytes_required) which returns the address 
  956.       of the allocated memory and release it when they are finished 
  957.       with PROCshell_HeapBlockReturn. 
  958.  
  959.       This is vital for avoiding 'side effects' caused by using the 
  960.       same block of memory for different purposes as most WIMP programs 
  961.       tend to do. Equally important is the fact that as the routines 
  962.       are written in ARM code they are extremely fast. 
  963.  
  964.       Another point to note is that this memory is claimed from the 
  965.       current wimp slot and not the RMA (Relocatable Module Area). This 
  966.       ensures that all of the memory claimed by the application is 
  967.       released back to the free pool when the application quits - this 
  968.       is not the case if memory is claimed from the RMA. It is only 
  969.       possible to reclaim RMA memory if the free space is at the top of 
  970.       the RMA which leads to the RMA allocation gradually growing as 
  971.       you run and quit applications. 
  972.  
  973.       Unfortunately (in the authors view!) the MenuUtils module uses 
  974.       the RMA for storage of indirected data and menu structures. 
  975.       Hopefully this data gets put in any small available blocks so 
  976.       that the RMA allocation does not increase. 
  977.  
  978.       You are strongly advised to use the supplied memory management 
  979.       routines in the user application should you require storage for 
  980.       data, or temporary blocks for use with SWI calls for example. The 
  981.       time penalty for doing this is very small and in any case results 
  982.       in a more reliable and easier to maintain application. 
  983.  
  984.       4.16 Error Handling 
  985.  
  986.       The EvntShell library sets up a default error handler for you if 
  987.       you build the application with AppBuild. Since version 1.21 of 
  988.       the library support has been provided for Joe Taylor's !ThrowBack 
  989.       application which was on the September 1993 cover disk of 
  990.       Archimedes World. This traps errors in the program and opens a 
  991.       window showing the location and type of the error. Clicking on 
  992.       the error line then loads the file into your editor with the 
  993.       offending line highlighted which is a real timesaver. 
  994.  
  995.       It is not necessary to have !ThrowBack, if it is not present a 
  996.       standard error window will pop up instead. 
  997.  
  998.       The user application can generate errors on purpose as a way of 
  999.       aborting an operation. Control will then return to the wimp poll 
  1000.       loop. This is done with a call to PROCshell_OK which opens an 
  1001.       error box with a user defined message and an OK button. Note that 
  1002.       an error generated any other way will end the application without 
  1003.  
  1004.       further warning. 
  1005.  
  1006.       This will be improved in a later release of the library, 
  1007.       especially with regard to 'out of memory' errors from the heap 
  1008.       manager as at the moment running out of memory aborts the user 
  1009.       application instead of giving the user a chance to free up more 
  1010.       memory. 
  1011.  
  1012.       Also note that the MenuUtils module appears to set up its own 
  1013.       error handler while calling the MenuSelect routine (the one you 
  1014.       specify will be called when a selection is made for a particular 
  1015.       menu item). This means that any errors in this routine appear to 
  1016.       be ignored - in fact the routine just aborts at the error 
  1017.       location without giving a message. This makes debugging these 
  1018.       routines impossible unless you add the line: 
  1019.  
  1020.       
  1021.       ON ERROR OFF
  1022.       
  1023.       
  1024.       at the start of the routine, i.e 
  1025.  
  1026.       
  1027.       DEF FN_MenuSelect_TID(blk%)
  1028.       LOCAL str$
  1029.       ON ERROR OFF
  1030.       str$=$(blk%!12)
  1031.       PROCshell_IconPutData(newrec%,4,str$,TRUE)
  1032.       PROCget_entries(file_loc%,(blk%!0)+1)
  1033.       =0
  1034.       :
  1035.       
  1036.       
  1037.       4.17 Draw Files 
  1038.  
  1039.       The standard method of creating and displaying vector graphics on 
  1040.       the Archimedes is the DrawFile, as created by the Acorn Draw 
  1041.       application. It is also possible to create a DrawFile under 
  1042.       program control using the routines in the supplied DrawLib 
  1043.       library - this is seperate from the main shell library as the 
  1044.       creation of DrawFiles is a specialised requirement. 
  1045.  
  1046.       A good example of the use of program generated DrawFiles would be 
  1047.       the production of a graph which could be loaded into a DTP or 
  1048.       word processing package. If you want to do something like this it 
  1049.       makes sense to use the existing standard of DrawFiles, indeed if 
  1050.       you want other applications to be able to load the data there is 
  1051.       really no choice. 
  1052.  
  1053.       EvntShell handles the creation of DrawFiles by creating the 
  1054.       necessary data in memory (hence memory availability limits the 
  1055.       size of DrawFile that can be created), first adding a 
  1056.       'pre-header' to the data. The purpose of the 'pre- header' is to 
  1057.       store data such as the current drawing colour, the width of the 
  1058.       lines etc without using global variables. Each DrawLib routine 
  1059.       requires the address of the buffer holding the DrawFile, enabling 
  1060.       several DrawFiles to be created in different buffers at the same 
  1061.       time. 
  1062.  
  1063.       Existing DrawFiles may be loaded, modified by the user 
  1064.       application and re- saved. Full control is provided over line 
  1065.       thicknesses, patterns, end caps, path and fill colours (stored as 
  1066.       24 bit values which RISC OS displays using dithering). 
  1067.  
  1068.       DrawFiles can contain lines, boxes, circles, ellipses and outline 
  1069.       font text at the moment which is not an exhaustive list but 
  1070.       should suffice for most needs. 
  1071.  
  1072.       An example of the use of the DrawLib routines is as follows: 
  1073.  
  1074.       
  1075.       LIBRARY "EvntShellSystem:DrawLib"
  1076.       buffer% = 0 : REM Just declare the variable
  1077.       PROCshell_DrawCreateFile(buffer%)
  1078.       PROCshell_DrawBox(buffer%,100,100,25,25)
  1079.       
  1080.       
  1081.       which creates a DrawFile and then adds a square at the location 
  1082.       x100 y100 (relative to the bottom left of the paper) with sides 
  1083.       25mm long. By default millimetres are used for measurements, but 
  1084.       drawing units may additionally be specified in centimeters, 
  1085.       inches, OS units or points. Drawing units can be mixed within 
  1086.       each file. 
  1087.  
  1088.       A demonstration application called TestDraw should have been 
  1089.       supplied with EvntShell to enable you to experiment. 
  1090.  
  1091.       5 The Tools 
  1092.  
  1093.       Various programming tools have been written by myself and others 
  1094.       to make producing wimp applications easier and faster. If you 
  1095.       obtained the EvntShell library or updates thereof from the author 
  1096.       you will have received all of the tools described here. If you 
  1097.       obtained it from a PD library the author has little or no control 
  1098.       over what else is supplied on the disk, so you may have to obtain 
  1099.       the missing tools from other disks in the PD library, or better 
  1100.       still send me a blank disk. 
  1101.  
  1102.       Only one of the tools (one of the many Template editors 
  1103.       available) is vital to the EvntShell Library, the others you can 
  1104.       do without but they do make life easier. 
  1105.  
  1106.       The following is a brief description of the tools supplied on 
  1107.       APDL disk B122, and some other software which may be useful for 
  1108.       developing applications 
  1109.  
  1110.       5.1 !AppBuild 
  1111.  
  1112.       Creates new application shells as 'stand alone' applications for 
  1113.       distribution, or ones that depend on !ShellSys. You can specify a 
  1114.       name for the application, and choose whether or not to make it 
  1115.       'Stand Alone' i.e if all the files required are copied into the 
  1116.       new application directory. If it is not a stand alone application 
  1117.       then modules, message files etc will be loaded from the !ShellSys 
  1118.       directory. 
  1119.  
  1120.       This application supports Acorn's !Help application. 
  1121.  
  1122.       5.2 !ShellDBug 
  1123.  
  1124.       A very simple debugger that displays trace output from the user 
  1125.       application and the library code. Note that currently this 
  1126.       application must be running before the application you want to 
  1127.       debug. 
  1128.  
  1129.       The EvntShell library outputs a commentary on what it is doing 
  1130.       into a tracefile, providing that PROCshell_TraceInit and 
  1131.       PROCshell_TraceOn have been called. The user application can also 
  1132.       place output in this file using PROCshell_Tracef0. 
  1133.  
  1134.       Outputting trace information will slow the user application 
  1135.       noticeably, especially when starting up as a lot of trace info is 
  1136.       generated by the call to PROCshell_ResourcesInit. Therefore it is 
  1137.       best to only turn on tracing when necessary, and of course make 
  1138.       sure that tracing is off on any applications you distribute! 
  1139.  
  1140.       5.3 Other Tools 
  1141.  
  1142.       There follows a brief description of some other PD/ShareWare 
  1143.       /Copyrighted programs which I have found useful when developing 
  1144.       EvntShell applications. 
  1145.  
  1146.       5.3.1 !BasShrink/!BasShrink_PD 
  1147.  
  1148.       Is a BASIC program compressor which has been proved to work with 
  1149.       EvntShell applications. !BasShrink_PD is Public Domain and 
  1150.       available from various PD libraries, !BasShrink cost £5.00 and 
  1151.       can be obtained from: 
  1152.  
  1153.       John Wallace, Architype Software, 54 Parkes Hall Road, 
  1154.       Woodsetton, Dudley, West Midlands, DY1 3SR ENGLAND 
  1155.  
  1156.       See the section on compressing EvntShell programs for guidance on 
  1157.       the options that can be used. 
  1158.  
  1159.       5.3.2 !BLibII 
  1160.  
  1161.       A BASIC Linker program available on APDL Disk B138. This builds a 
  1162.       program from the user application and the EvntShell library 
  1163.       containing only the routines that are actually needed. This is 
  1164.       very useful for distributing the final application as !BLibII and 
  1165.       !BasShrink used together will produce the minimum program size 
  1166.       possible. 
  1167.  
  1168.       Full instructions are provided with !BLibII, so I won't go into 
  1169.       details here except to note that the ShellLib library already 
  1170.       contains the extra information that !BLibII requires, although 
  1171.       the conditional linking bits are not yet in place. This means 
  1172.       that the linked program is bigger than it should be, but an 
  1173.       improvement over just appending the library code to the end of 
  1174.       the user application. This will improve in future releases. 
  1175.  
  1176.       Note that you should use the ShellLib library for linking with 
  1177.       BLibII because ShellLibRT has had the BLibII commands removed to 
  1178.       save space. 
  1179.  
  1180.       5.3.3 !TemplEd 
  1181.  
  1182.       Also on APDL disk B138 this is I believe the best Template editor 
  1183.       available anywhere. Forget !FormEd2 which was on some APDL B122 
  1184.       disks, !FormEd (Risc Squad version 2.84b on B053 or 2.87 also on 
  1185.       B138) and any Acorn versions. 
  1186.  
  1187.       5.3.4 !StrongEd 
  1188.  
  1189.       A text editor which used to be in the public domain and is now a 
  1190.       commercial program available from Stallion Software. The big 
  1191.       advantage this has over any other editor is the accompanying 
  1192.       !StrongHlp application as pressing F1 over a word in a program 
  1193.       known to !StrongHlp causes an hypertext information window to 
  1194.       open. 
  1195.  
  1196.       The Archimedes World August 1993 cover disk contained a crippled 
  1197.       version of !StrongEd (as the commercial version is known) which 
  1198.       can be used for evaluation purposes, and this may be available 
  1199.       from PD libraries. The PD/Demo version cannot create files and 
  1200.       only allows two files to be open at any one time although this is 
  1201.       not much of a problem for evaluation purposes. 
  1202.  
  1203.       5.3.5 !StrongHlp 
  1204.  
  1205.       A hypertext type application which almost removes the need for 
  1206.       the Reference Manuals. Files supplied with it detail most of the 
  1207.       SWIs available and much more information is provided on BASIC, 
  1208.       VDU calls, Filetypes etc. The full version of !StrongHlp is only 
  1209.       available as a 'free' add on with the commercial version of 
  1210.       !StrongED from Stallion Software, although a new PD version is 
  1211.       now available. The PD version does not contain the help data from 
  1212.       the full version, however, it is sufficient for viewing the help 
  1213.       files supplied with EvntShell. 
  1214.  
  1215.       The Archimedes World August 1993 cover disk also contained the PD 
  1216.       version of !StrongHlp. 
  1217.  
  1218.       The EvntShell library also has a few PROCs to interface with 
  1219.       StrongHlp to enable user applications to register help systems. 
  1220.  
  1221.       When a request is sent to StrongHlp the active applications on 
  1222.       the icon bar are checked to see if StrongHlp is running. If it is 
  1223.       not and its !Boot file has been 'seen' by the Filer then it will 
  1224.       be started automatically. If StrongHlp has not been 'seen' then 
  1225.       an error will be generated. 
  1226.  
  1227.       Note that for the above to work it is vital that the help system 
  1228.       directory has the same name as the application (minus the '!'). 
  1229.  
  1230.       5.3.6 !ThrowBack 
  1231.  
  1232.       This application appeared on the September 1993 cover disk of 
  1233.       Archimedes World and is copyright that magazine. It provides a 
  1234.       'throwback' window when an error occurs, and clicking on the 
  1235.       throwback window opens your program editor at the line where the 
  1236.       error occured. This is very useful when debugging a program. 
  1237.  
  1238.       The EvntShell library contains the necessary support code for 
  1239.       this. Note that for this to work properly you need the DDEUtils 
  1240.       module and an editor that supports throwback (such as !DeskEdit 
  1241.       or !StrongEd), although it will work after a fashion with !Edit 
  1242.       as well. 
  1243.  
  1244.       6 Distributing EvntShell Applications 
  1245.  
  1246.       It is probably best to copy ShellLibRT, ShellMsgs and the modules 
  1247.       into your application directory, not forgetting to alter the !Run 
  1248.       file and the LIBRARY statement in the runimage file to point to 
  1249.       the new location. That way you are sure that all the necessary 
  1250.       files are in one place for ease of copying. 
  1251.  
  1252.       AppBuild will do this for you automatically if you drag the 
  1253.       application to the iconbar icon, turn the 'Standalone' switch in 
  1254.       the main window on and click OK. 
  1255.  
  1256.       7 Debugging 
  1257.  
  1258.       A simple debugger (!ShellDBug) is supplied with the library to 
  1259.       display trace messages. You can also do wonders with a few VDU7 
  1260.       calls to check which parts of the application are actually being 
  1261.       executed.. 
  1262.  
  1263.       8 The Credits 
  1264.  
  1265.       Quite a few people have been (however unwittingly) involved in 
  1266.       this project such as: 
  1267.  
  1268.       David Breakwell (the original idea), Robert Seago (for using it 
  1269.       for things I wouldn't dream of attempting!), Cy Booker (various 
  1270.       helpful suggestions - I won't rewrite it in C or Assembler though 
  1271.       - RISC-OS 3 Documentation and the FontWindow module), Risc User 
  1272.       magazine (for permission to use its heap manager code), Joris 
  1273.       Röling (FontMenu module), Simon Huntingdon (Interface module), 
  1274.       Alex Petrov (MenuUtils), Jan-Herman Buining (WASP application 
  1275.       from which I worked out how to do RAM file transfers) and lastly 
  1276.       the wife (Hilke) for putting up with me pounding away at a 
  1277.       keyboard for hours when we could have been looking for new 
  1278.       furniture instead. 
  1279.  
  1280.       9 Future Enhancements 
  1281.  
  1282.       The software will become faster and be able to leap tall 
  1283.       buildings with a single bound. Bugs and limitations will become 
  1284.       fewer as well. 
  1285.  
  1286.       
  1287.       - Support for automatic handling of more
  1288.         complicated icon types, for example
  1289.         sliders, rotating knobs etc
  1290.         (steady now don't get carried away)
  1291.       - Import and display of DrawFiles and
  1292.         Sprites
  1293.       - Inclusion of more debugging aids
  1294.       - More drag types
  1295.       - Autoscroll handler when object is
  1296.         dragged within a window
  1297.       - Colour pick dialogs
  1298.       - Automatic handling of non-icon text
  1299.  
  1300.         within a window (like C txt objects)
  1301.       - Playing of Maestro tunes (ArchWay does!)
  1302.       - Extending message file useage to icons/
  1303.         windows/menus
  1304.       - Replay Films (!!!)
  1305.       - Better multiple file buffers
  1306.       - Complete German message files
  1307.       - Choice of message file language from
  1308.         within program
  1309.       - Automatic attaching of 'hot key' events
  1310.         by examining menu text
  1311.       
  1312.       
  1313.       10 Changes Since V1.14 
  1314.  
  1315.       
  1316.       V1.20 - Now uses MenuUtils module for menu handling
  1317.             - Added routine PROCshell_IconSetSelected
  1318.             - Added routine PROCshell_IconSetUnselectable
  1319.             - Added routine FNshell_StrongHlpIsAvailable
  1320.             - Added routine FNshell_MenuNew
  1321.             - Added routine FNshell_MenuAdd
  1322.             - Added routine FNshell_MenuDelete
  1323.             - Added routine FNshell_MenuColours
  1324.             - Added routine FNshell_MenuDotted
  1325.             - Added routine FNshell_MenuWritable
  1326.             - Added routine FNshell_MenuTickOnly1
  1327.             - Added routine FNshell_MenuTickOnly2
  1328.             - Modified all other menu routines
  1329.             - Added routine FNshell_StrongHlpIsAvailable
  1330.             - Added routine PROCshell_AttachPreQuitHandler
  1331.             - Added routine PROCshell_AttachOpenWindowHandler
  1332.             - Added routine PROCshell_AttachCloseWindowHandler
  1333.             - Added routine FNshell_SpriteAreaLoad
  1334.             - Added routine PROCshell_SpriteAreaSave
  1335.             - Added routine FNshell_SpriteGetPtr
  1336.             - Added routine PROCshell_SpriteRename
  1337.             - Added routine FNshell_OSCheckVersion
  1338.             - Added routine FNshell_OSCheckModuleVersion
  1339.             - Added routine PROCshell_IconSetLeftJust
  1340.             - Fixed PROCshell_IconSetRightJust
  1341.             - Writable icon handler now ignores unselectable icons
  1342.               when moving caret
  1343.             - Added support for ResFind (internationalisation of
  1344.               messages etc)
  1345.              
  1346.       V1.21 - Added support for Joe Taylor's !ThrowBack error
  1347.               handler (see Archimedes World Sep 1993)
  1348.              
  1349.       V1.22 - Clicking on a 'bump' icon with ADJUST now has the
  1350.              opposite effect to clicking with SELECT
  1351.             - Improved error handling and messages
  1352.             - PROCshell_AttachDataSave now alters icon button
  1353.               type of file icon to click/drag and generates an
  1354.               error if the file icon is not a sprite
  1355.             - PROCshell_AttachMenu now sets button type of icon
  1356.               to 3 (Click)
  1357.             - Bug fix to menu attach routine (a menu could appear
  1358.               when another event occurs such as ClickSelect)
  1359.             - Added routine <FNhell_IconIsDraggable
  1360.             - Added routine FNshell_IconIsSprite
  1361.  
  1362.             - Added routine FNshell_GetString
  1363.             - Added routine PROCshell_Ensure
  1364.             - Added routine PROCshell_IconPutDataNow
  1365.             - Added routine PROCshell_MessageSendDataLoad
  1366.       
  1367.       V1.23 - Bug fix for auto press of icon 0 when RETURN is
  1368.               pressed in last writable icon
  1369.       
  1370.       V1.24 - Bug fix for pane handler (pane was not opening fully
  1371.               when wimp adjusts parent window coords - if title is
  1372.               changed for example). Pane handling is still not 100%
  1373.               when a mode change event occurs though
  1374.       
  1375.       V1.25 - Added routine FNshell_MenuMakeFromFile
  1376.             - Added routine FNshell_BinarySearch
  1377.             - Added routine FNshell_MenuGetNrItems
  1378.             - Added routine FNshell_MenuGetNrDotted
  1379.             - Added routine FNshell_MenuGetItemHandle
  1380.             - Added routine FNshell_MenuGetItemHeight
  1381.             - Added routine FNshell_MenuGetItemHandler
  1382.             - Added routine FNshell_MenuCalculateHeight
  1383.             - Added routine FNshell_MenuGetText
  1384.             - Added routine PROCshell_QuickSort
  1385.             - Added routine PROCshell_MenuSortItems
  1386.             - Added routine PROCshell_WindowCentreOnPointer
  1387.             - PROCshell_IconPutData now checks if the new text
  1388.               to put into the icon is the same as the existing
  1389.               text. If it is, no action is taken avoiding flickering
  1390.               of the icon
  1391.             - 'Popup' menus (menus attached to icons in windows other
  1392.               than the iconbar) now appear to the right of the icon,
  1393.               the pointer also being relocated. ADJUST no longer
  1394.               opens a 'popup' menu (Recommendations from the RISC OS
  1395.               3 Style Guide)
  1396.             - Bug fix to menu opening routine (MENU sometimes failed
  1397.               to open a 'popup' menu)
  1398.             - TAB/SHIFT TAB now move caret between writable icons.
  1399.               RETURN now only activates icon 0, it does not move the
  1400.               caret (Style Guide recommendations)
  1401.       
  1402.       V1.26 - Added routine PROCshell_WindowSetTitleRightJust
  1403.             - Added routine PROCshell_WindowSetTitleCentreJust
  1404.             - Added routine PROCshell_WindowCentreOnScreen
  1405.             - Added routine FNshell_GetLastMouseButton
  1406.             - Added routine FNshell_GetLastWindowClicked
  1407.             - Added routine FNshell_GetLastIconClicked
  1408.             - Running out of memory does not now cause a fatal error
  1409.               and shut down of the application
  1410.             - Double clicking on a file 'belonging' to an application
  1411.               now causes the application to start up and load the file
  1412.             - 'Sprites22' file containing hi-res sprites automatically
  1413.               detected and loaded if the program is started in a hi-res
  1414.               screen mode
  1415.             - Bug fix to PROCshell_WindowMoveToIcon (window was
  1416.               sometimes moved to wrong position because the scroll
  1417.               offset of the icon bar was not being taken into account)
  1418.               Note: This fix only for RISC OS 3 users
  1419.             - Bug fix to PROCshell_IconbarSetText (new text not always
  1420.               redrawn because the scroll offset of the icon bar was not
  1421.               being taken into account)
  1422.               Note: This fix only for RISC OS 3 users
  1423.  
  1424.             - Click on a radio icon with ADJUST selects icon to avoid 
  1425.       the
  1426.               situation where all radio buttons in a group are off
  1427.       
  1428.       V1.27 - Bug fix to writable icon handler (could cause a crash if
  1429.               more than 5 writable icons in one window)
  1430.             - Bug fix to template loading routine which sometimes did 
  1431.       not
  1432.               allocate enough buffer space
  1433.       
  1434.       V1.28 - Documentation updated for PROCshell_QuickSort and
  1435.               PROCshell_OpenMenu. Added documentation for DrawLib
  1436.             - Added routine PROCshell_FontGetHandle
  1437.             - Added routine PROCshell_FontSetColour
  1438.             - Added routine FNshell_FontForgetFont
  1439.             - Fixed problem with applications loading files on a double
  1440.               click in a Filer window when the files should have been
  1441.               loaded by another application e.g. !Draw
  1442.       
  1443.       V1.29 - Bug fix to dataload routine introduced in 1.28. Double
  1444.               click loads now ok
  1445.             - Fixed bug in FNshell_OSModuleCheckVersion
  1446.             - Improved StrongHlp initialisation code, now checks files 
  1447.               actually exist
  1448.  
  1449.       V1.30 - Added PROCshell_CaretPutFirstIcon
  1450.             - Added PROCshell_CaretPutLastIcon
  1451.             - Added PROCshell_CaretPutNextIcon
  1452.             - Added PROCshell_CaretPutPrevIcon
  1453.             - CTRL Cursor Up/Down move the caret to the first/last writable
  1454.               icons in a window respectively