User-Manual for Fabricate


Version 2.62 (01-Dec-05)


© Andrew Ayre 1996-98
© Ray Favre May 1999 onwards



See !!ReadMe!! file for distribution conditions.





INTRODUCTION...



When writing applications with DrWimp it is normal to make a copy of the 'empty' !MyApp application then start adding to it to turn it gradually into the wanted application.

But, once having done this a few times (and however easy it is with Dr Wimp) it can be a little boring having to add the line for the iconbar icon, the line to load in an 'Info' window, define an iconbar menu, find an 'Info' window template and check the icon numbers, fill in the details, change the application name in !RunImage and !Run, getting it to Quit properly, and so on ..... before being able to get on with the interesting bits.

Usually the lines that need to be added at this stage are almost exactly the same in every case, but not all of you want precisely the same pattern each time ..........

.......... so, here is !Fabricate. It does all these boring bits for you easily and automagically - and retains the flexibility for you to choose which bits you want and which bits you don't. The result is that the initial skeleton !MyApp has a lot of useful and customised flesh added to its bones so that you can start the serious stuff a lot further down the road.

One thing to remember is that everything produced via !Fabricate can easily be changed/supplemented subsequently in the !RunImage or other files produced. So, !Fabricate gets you started much more quickly but it doesn't restrict you.

Interactive help applications such as Acorn's !Help are supported - as well as the latest RISCOS/Castle suggestions for managing an application's Help documentation.

Please read (also!) the final part of this !Help file: I really would like to hear how you would want to see !Fabricate develop.



STARTING UP...



Load in the usual manner by double clicking on the !Fabricate icon. (You can also start !Fabricate by double-clicking on one of its data files - File type 'FabFile' (&1C4) see later.)

Click on the iconbar icon to bring up the main window. At first it will contain settings held in a default file (which you can change - see later)

The main window is where you enter/alter the details of how you want your new application to act initially. If you are used to using DrWimp then all the entry needs should be fairly self-explanatory.

If you are not familiar with DrWimp, then please read the DrWimp Manual in the Documents folder first. You will find explained there such essential things as handles, which feature in !Fabricate.



MAIN WINDOW ...



The main window is divided into several sections which can all be accessed by scrolling. They are:

It is best to work from the top of the window downwards.

The selection/deselection of some options affects choices available in other parts of the window. (e.g. if you decide not to have an iconbar icon, you will not be able to make any choices in the iconbar menu section, for obvious reasons!)





i) Application name, Dr Wimp Version number, WimpSlot size and Web-site



The most important bit, which you will probably want to change every time, is the application name right at the top. Enter the name of your new application in here, including the pling ”!• at the start.

The total length of the application name is restricted to 10 characters ( "!" + 9 ) - because !Fabricate also uses this name for the application's sprite names (and sprite names must not exceed 10 characters).

But note also the warning about it being best to keep the name to no more than "!" + 7 characters. The reason is that one of the sprites automatically produced for your new application is for the iconiser action and this one has a 3-character prefix "ic_" added - see Dr Wimp Manual "Iconiser" section.(This point will not produce fatal errors but will detract from the final 'polish' of your application.)



The DrWimp Version number shown in the next box down is the version number of the Dr Wimp package that this copy of !Fabricate came with. You cannot alter it here. This number will also automatically appear in the first REM line of your new !RunImage (as a reminder).



The next item in this section is the WimpSlot size, which you can set in the writable icon. (Note that the value chosen will be reflected into the !Run file of your new application - not into the !RunImage.)

The WimpSlot needs to be large enough to hold your complete !RunImage plus any libraries plus all the variables/arrays/memory blocks etc. that are created during the program run (not including 'dynamic areas' though).

So, when you start a new Dr Wimp application the WimpSlot needs to be large enough to hold all the DrWimp library as well as the !RunImage etc. Accordingly, the default value of 192k is certainly enough to cater for most initial needs - and !Fabricate will not let you set the value to lower than this.

But this default value is not over-generous and you need to keep an eye on it as you build up your application. If/when you want to change the value later, simply alter both number values in the !Run file line: WimpSlot -min 192k -max 192k (When your application is complete - and particularly if you then use !Linker and/or a Basic compactor - you can usually adjust the WimpSlot downwards - see Manual Section 2.34.)

Finally in this top section is the Web-site address. This is an optional item which is intended to hold the URL of your own web-site. At the moment, any address here will simply be copied automatically into the two skeleton Help files - see later.





ii) Iconbar icon section



This section deals with the iconbar icon of your new application.

If you want an iconbar icon to appear when you start your application then make sure the first option icon is ticked.

If the iconbar option is ticked then the rest of that section will be enabled and you must take some additional actions. Firstly, a name for the iconbar handle is needed. A default name is provided but you can alter it if you wish. The percentage ”%• can be missed off the end but it is best included as the handle is always an integer.

If you want some text underneath the iconbar icon then enter it in the next box. If you choose to have text under the iconbar icon it will be made 'indirected' so that you can change it later in the program (with PROCwimp_iconbartext). Do not make the iconbar text too long as it will occupy too much space on the iconbar and look unbalanced.

If you set the value of 'max length' to be greater than the length of the text you have entered in the step above, then the iconbar icon will reserve enough space for this longer length (and display it) and you will be able to change the iconbar text up to this extra length in your application coding, if you want.

If you want to be able to add text to the iconbar icon later in your programming but do NOT want any showing at the start, then you simply set the initial text to, say, " " i.e. at least one space - and set the 'max, length' to the max. size you will need later. The (empty) full space will be occupied on the iconbar, so the above warning about length is still relevant.

If you set the initial iconbar icon text to a null string then a 'sprite only' iconbar icon will be created and the value in 'max. length' will be ignored (and you will not be able to add text to it later).

Finally in this section, click on the radio icons to choose whether you want the iconbar icon to be on the left or the right of the iconbar.





iii) Iconbar menu



The next section concerns the iconbar menu. Firstly you need to choose whether or not you want an iconbar menu. If you do then ensure that the first box is ticked.

An iconbar menu handle then needs to be specified and a default one will be shown - unless you have replaced the supplied 'default' file (see later).

If you choose to have an iconbar menu, then you need to decide whether to opt for the 'standard 3-item menu' (with your application name as the menu title and just "Info", "Help" and 'Quit' as the items) or to opt for a customised menu, which !Fabricate will construct for you. The radio icons toggle between these two options.

If you choose the standard 3-item menu then that is all there is to do in this section.

If you opt for a custom menu then you firstly need to specify the maximum number of items you want (up to 16) - remembering that a 'Quit' item will always be added as an extra, last item. The default maximum value here is 2 - which will therefore produce a 3-item menu with 'Quit' as the second (last) item. (The same as the Standard menu, in fact.)

After specifying the maximum number of items you want, click on the bottom button of this section to open a window ready for you to enter the iconbar menu item names you want. There are additional instructions in this window. Note that you do not have to complete all item names at this stage. If you leave any empty they will be ignored in the initial menu created but the menu will allow you to re-create it later in your listing (with, say, FNwimp_recreatemenu) up to the maximum number of items that you have specified (+1 for 'Quit').

You may wish to note that if you choose to use a custom iconbar menu it will be implemented in your new application via FNwimp_createmessagemenu and a corresponding textfile called "CustomMenu" will be created and copied into your new application folder. The 'tag' will be "Ibarmenu" - see Section 2.15 of the Dr Wimp Manual.

(Please note that a *temporary* Messages file called 'TempMess' will also be created if you choose to have a custom menu. It will appear in the 'Resources' folder of !Fabricate and will automatically be deleted when your new application has been created. So, if you happen to run across this file whilst exploring, don't worry and DON'T DELETE IT!)

The supplied default text for the first two items of the custom menu are "Info" and "Help", because most applications follow the Style Guide and use the first item to lead to the usual 'Info' window and the second item to lead to a Manual - see later. However, !Fabricate does not insist on these and you can put "Info" and "Help" (not case sensitive) at any other menu item positions, or you can leave them out altogether (but see later before you decide this).

Please note that if you enter new menu item text into the writable icons it does not immediately become protected and it is possible to lose all or some of this text if you subsequently make certain option changes and then return to the menu item window. However, if you click on the 'Hold menu text' button the items will be preserved - at least until you choose to reset or load another FabFile (see later).

The purposes of the 'Clear menu text' button and the 'Restore deafult menu text' button are self-explanatory.





iv) Window template loading



Most wimp applications use more than one window, normally held in a Templates file. From !Fabricate Version 2.00 onwards you can specify such a file and cause all its windows to be loaded automatically when your skeleton application is started. Further, you can choose one of these windows to be opened when the iconbar icon is clicked by the user - another standard feature of many applications.

So, if you want your skeleton application to have this feature, ensure that the first option of this section is ticked, which will enable the 'drag box'. Then drag your required templates file to this box....

..... which, in turn, will enable the following box and show the full path of the dragged file and also enable the 'Iconbar click .....' option. (Your dragged file will not be harmed: it will later be copied into your new skeleton application folder under the name "Templates2")

If you tick this last option the final box will be enabled and clicking over it will bring up a menu of the window names in the template file you dragged. Select one of these and it will appear in the box. This will then be the window opened when you click on the iconbar icon of your new application.

If your dragged file contains a window called "Info" (not case sensitive) you will notice that it is 'greyed out' on this menu, so you will not be able to choose that window to be opened by clicking on the iconbar icon of your new application - an unlikely requirement anyway. This is to prevent possible clashes with the use of the standard 'Info' window supplied by !Fabricate. (See later.) However, please note that it will still be copied across into "Templates2". (The decision on whether or not your own 'Info' window is loaded by your new !RunImage is determined by your choices in the following section.)

Finally in this section, please note that in the resulting !RunImage listing, the window handle names for the windows of your dragged template file will be the lower-case versions of the template names, each with "%" added to the end. For example a window template called "Main" will be loaded with a handle called "main%".





v) Info window



An 'Info' window (or 'box') is a feature of virtually all wimp applications and is recommended by the Style guide. If you wish to follow this practice your first step is to ensure that the first option in this section is ticked - and then to enter your choice of a handle name.

You then have the option of automatically linking the display of the info box with the "Info" item on the iconbar menu. (Obviously, this option will be 'greyed out' if you have already chosen not to have an iconbar menu or an icon bar icon.) If the already-chosen iconbar menu does not have any item with "Info" as its text, you will be warned and be unable to tick this option.

!Fabricate then offers you the choice of using your own 'Info' window design or a standard/default version provided by !Fabricate. The two radio icons in this section allow you to make this choice.

If you choose the 'Standard Info window' then the remaining parts of the section are enabled and need to be completed as normal. Default 'Info' box contents are offered.

(Also in this case, a separate template file containing only a standard 'Info' window will be included in your skeleton application as a "Templates1" file - to distinguish it from a possible "Templates2" file, see Section (iv) above.)

If you attempt to choose the 'Custom Info window' then you will only be allowed to do so if you have already dragged a templates file into Section (iv) AND it contains a window definition named "Info" (not case sensitive). If a successful selection is made here, the default info box contents will be 'greyed out'.

Finally, please note that, in order to give you the flexibility to make changes to the main window in any order, it is not practical to provide completely water-tight cross-checking that all the options are consistent at the entry stages. However, a final set of checks takes place when you click on the OK button and !Fabricate will warn you and prevent the process from continuing until corrections have been made - see below.





vi) Custom sprites



As stated later, all applications produced by !Fabricate are provided automatically with !Sprite and !Sprites22 sprite-files containing a default 'application sprite' (the sprite that normally represents your application in the filer window and on the iconbar) and a default iconiser sprite (see Section 2.31 of Dr Wimp Manual) - both with names matched to your chosen new application name. (A Dr Wimp logo sprite is also included and is used in the standard 'Info' window.)

However, you may want to use your own sprites (in addition or instead) and this section allows you to include them automatically.

First make sure that your sprites are contained in a single sprite-file (which we will call the 'custom sprite-file').

You can choose simply to copy your custom sprite-file into the new application folder - or you can go further and ask !Fabricate to 'merge' your custom sprites with the default !Sprite/!Sprite22 sprite-files. Whichever you choose, !Fabricate will include your custom sprites in the new application folder and, in the usual way, cause them to be loaded into the wimp sprite pool when the new application is run or when it is 'seen'.

So, if you want to use your own sprites, tick the option 'Include a custom sprites file?' This will also enable the two icons below the option.

Then drag your custom sprite-file to the icon indicated. You will see that the full path of your custom sprite-file is captured into the yellow icon below and also the final icon of this section - the 'merge' option - is enabled.

Tick the merge option if you wish.

The practical advantage of merging is realised if you wish to use your own sprite(s) for the application and/or iconiser sprites - because the process of merging WILL REPLACE THE DEFAULT SPRITES WITH YOUR OWN SPRITES IF THEY HAVE THE SAME NAME.

For example, let's assume that you have chosen to call your new application "!Clever". !Fabricate will therefore automatically produce default sprites called "!clever" and "ic_clever" in both a !Sprites and !Sprites22 file in the new application folder.

But if you design your own application sprite (and include it in your custom sprite-file) and also call it "!clever" - then, if you choose 'merge', your custom sprite "!clever" will REPLACE the default sprite "!clever" in both the !Sprites and !Sprites22 files (and similarly if you do the same for "ic_clever").

Merging therefore saves a lot of messing around when you want to use your own application sprite.

If you choose to use a custom sprite-file but do not take the 'merge' option then !Fabricate will simply copy your custom file to the new application folder (with the name "CustomSpr") - alongside the default !Sprites and !Sprites22 files - and cause all three sprite-files to be loaded into the wimp sprite pool when the application is run or 'seen'. Your custom sprite-file will therefore be conveniently available for you to use during your later application coding.





vii) 'Save' window



Many applications have a need to save data using the RISCOS 'Style Guide' standard method involving a 'Save' window - and Dr Wimp provides specific facilities for this (see Section 2.7 of Dr Wimp Manual).

If you intend to use a Save window somewhere in your new application then this section allows you to tell !Fabricate to provide a standard Save window - and to load the window (with the handle of your choice) on application start-up. It also allows you to choose which file-type is shown in the window and the default save path/leaf name.

If you want to a Save window, tick this option - which will enable the remaining icons in this section.

The handle for the Save window and the default path/leafname that will be displayed can then be changed to your own choice by editing the corresponding writable icons.

The file-type can be changed by pressing <select> when over the yellow 'Default save file-type' icon. This brings up a menu with a selection of standard file-types. Selecting one of these will change the entry and the corresponding sprite-icon to its right.

The contents of this menu is controlled by a Messages file (called "FileTypes") in the UserFiles directory. You can edit this to add other file-types if you wish. Be sure to keep to the same format and end the list with a <return>. Also, ensure that there is a corresponding "file_xxx" sprite already loaded into the wimp sprite pool. (If there isn't, it will not be 'fatal' but the file-type icon in the !Fabricate window - and in the eventual Save window - will be displayed as empty/invisible.)





CONTROL BUTTONS



The buttons in the control window to the right of the main window allow you to make decisions about what you want to do with the options/choices you have made in the main window - and to reset the window to choices in pre-saved files in the folder 'UserFiles'.

They are:

(A) 'OK'



If you are happy with your choices and wish to proceed to make a skeleton application with them, then simply click 'OK'. This will do some validity checking (quite a lot, in fact) which may result in warning messages which will return you to correct an omission etc.

However, when all is well, a save box will open and you can drag the usual sprite icon to wherever you wish.

You will be warned if an existing application of the same name already exists. Note that IF YOU CHOOSE TO OVERWRITE, THE EXISTING APPLICATION WILL BE COMPLETELY ERASED BEFORE THE NEW APPLICATION IS CREATED. So if you wish to retain any items from the existing application rename it (or the new one) first or drag the !Fabricate save box icon to a different directory.

In a few seconds your complete new working skeleton application will appear, ready to use. Try it and see!

The application folder will contain:

Inside the !RunImage file will be your customised listing. It will be based on the 'empty' skeleton as supplied in !MyApp with added/altered lines to some or all of the following:
in order to carry out the options you exercised in the main window - plus some REM comments to help you further.

You may notice that the line numbering of the output !RunImage is a little odd e.g. mostly using 100 increments but some using 10 and other parts using 1. This is just the result of the way !Fabricate works. You can renumber it if you wish. (BUT DO NOT ALTER the numbering of the !RunImage file in the !Fabricate 'Resources' directory!!)

DON'T FORGET!! The resulting application is intended to 'get you off the ground' quickly when you start a new application. It doesn't set anything in concrete. The !RunImage listing - and any of the application files - can be altered, deleted, etc. to your precise wishes as you develop the program. Or, of course, you can use !Fabricate again from scratch.



(B) 'Reset to default'



Does what it says, the main window (plus menu items window if appropriate) is returned to the settings held in the FabFile called 'default' - see later.



(C) 'Reset to Last OK'



Each time you successfully produce a new application the settings used are automatically saved in a FabFile called 'LastOK'. Clicking this button causes the main window (plus menu items window if appropriate) to return to these settings.





(D) 'Save current settings'



Clicking on this button allows you to save the current settings in the main window (and menu items window, if appropriate) as a 'FabFile'. A save box appears with a default path+filename, which you can alter as normal. The default path is the 'UserFiles' directory of your !Fabricate application - see below - and this is the best place to keep all your FabFiles.

You will see that this button is 'greyed out' when you select the 'Custom iconbar menu' radio icon. It will be enabled again as soon as you click on the 'Click here to enter custom menu items' button.

The fact that you save a FabFile does NOT necessarily mean that the saved settings will pass the validation checks when you load the file and press 'OK'. Saving the window settings just does what it says. (The best way to ensure you have a validated set of contents is to complete the process to produce a new application and then immediately use 'Save current settings' - or immediately copy the 'LastOK' FabFile with a name of your choice. The same point needs to be noted if you create a new 'default' file from another FabFile i.e. it will load without a problem but that does not, in itself, mean that the settings have been validated.)

E) 'User files'



When you move the pointer over this icon it will change to the 'menu pointer' shape and if you then click with <select> a menu will appear listing the names of all the files of file-type 'FabFile' (&1C4) - see below - currently stored in the folder 'UserFiles' in the !Fabricate application directory.

Selecting any one of these menu items in the usual way will cause that file to be loaded in place of the current settings - exactly as if you had dragged that file to the window or iconbar icon as described under 'FabFiles' below.

Do not move the folder 'UserFiles'!

'FABFILES'



'FabFile' is the name given to the file type (&1C4) of !Fabricate's user-data files. On delivery the directory 'UserFiles' will contain only two FabFiles, namely 'Default' and 'LastOK' (the latter being only a copy of 'Default' at this stage).

You can save as many FabFiles as you wish, by using the facility in D) above.

Once saved, you can double-click on any FabFile to load its settings - or drag it to the iconbar icon or one of the main windows.

If you want a different default file you simply need to rename/copy any other FabFile to the name 'Default' - not case sensitive - and locate it in the 'UserFiles' directory.

(If you have FabFiles produced from an earlier version of !Fabricate they will still load successfully into this version, but they may not immediately pass the validation checks when you press 'OK'. When/if you save them again from this version they will be automatically upgraded.)

Always ensure that you have at least two files named, respectively, 'Default' and 'LastOK', located in the 'UserFiles' directory.

Don't forget that the 'LastOK' file is somewhat ephemeral: it will change its contents every time you successfully create a new application.

Finally, file type &1C4 ('FabFile') is in the non-protected 'user' range of filetypes, so it is possible that other applications may use the same type number. To prevent potential problems each FabFile uses an unusual word ("Fabulous") as its first text line and this is checked on loading. Other files will not load, but will produce an error telling you they are not in the right format.

HELP FACILITIES



Version 2.60 of !Fabricate incorporates the latest standard management facilities for Help files automatically into your new application.

These can be seen in the following places in your new applicaton's folder:

- The Folder 'Documents' - this contains two files 'index/html' and 'index/txt' whose names are those recommended by RISCOS/Castle. On creation by !Fabricate they are only customised skeleton files and the intention is that you should expand these files to become your user-manual for your application - in both text and HTML formats respectively.

- The Obey file !Help contains commands which will run one of the above files (the HTML version by default). The !Help file is Run by one of two ways: from the Filer menu when <menu> is pressed over your application icon - and from the iconbar menu of your running application, assuming that menu contains a "Help" item.

- As a separate facility, the !Run file also contains commands to set various standard system variables as suggested by RISCOS/Castle. These allow other applications to interrogate your application to extract basic information about its purpose etc. On creation by !Fabricate, the system variables are set to the text extracted from your 'Info' window.

"APPLICATION IS RUNNING"



One of the special system variables suggested by RISCOS is:

$Running e.g. "MyApp$Running"

This can be set to "Yes" to show that the application is running - and it can also be used, if required, to prevent more than one copy of the application from being run at the same time.

While an application is being developed this facility might be an inconvenience, so !Fabricate automatically provides the necessary code to use this system variable (in the !Run file and in PROCuser_error, PROCuser_initialise and FNuser_quit in the !RunImage file) but on creation this code is deliberately de-activated with REMs.

(N.B. Depending on your Basic editor, the REMmed lines in PROCuser_error, PROCuser_initialise and FNuser_quit may well show as:

REM˙("Set .......") or similar.

Do not worry about this. If you remove the REM the "˙" character will change to "OSCLI".

LAST BITS...



In order to assist newcomers in particular, some effort has been taken to make the !RunImage coding produced as a result of using !Fabricate's default settings line up very closely with the tutorial material in Section 2 of the Dr Wimp main Manual - even down to using the same default variable names and order of actions etc. It is not a perfect match but it is hoped that it is close enough to make it easier for newcomers to read, compare and understand the listings.

There has been considerable interest in !Fabricate from Dr Wimp users. In particular, it has been suggested that it could become a sort of 'Visual DrWimp' - and it has received considerable recent development along that line.

I would love to take it further, so please try it out and (Please, Please!) let me know how you feel it could/should be improved and/or expanded.



CONTACTS



The latest version of Fabricate can be obtained from the Dr Wimp web page below or direct from:

Email: ray-at-rayfavre-dot-me-dot-uk

World Wide Web: http://www.rayfavre.me.uk/

Alternatively try your local PD library or send a HD disc and return postage to:

Snail mail: Ray Favre 26 West Drayton Park Avenue West Drayton Middlesex UB7 7QA U.K.



EOF262