list of chapters    previous chapter   next chapter

Ch 15 Customising Powerbase


Ch 15 - Customising Powerbase

NOTE This is the most technical chapter in the manual and can safely be ignored by anyone who wishes to use only the built-in features of Powerbase as described in previous chapters. If you have rather special requirements and if you have some experience of BASIC programming then read on!

Powerbase has many powerful and useful features but, as with any software, some users will have special requirements which aren't catered for. This is why many organisations produce their software in-house as the only way of ensuring that their specific needs are met. I first came across this situation in the F.E. college for which Powerbase was originally written and in which it was (and still is) used to maintain student records. I was asked if the program could be enabled to print students' personal timetables and, since Powerbase was used by so many other people for diverse purposes, was unwilling to include code for this very specialised function in the main program. The solution developed at that time was to provide the special feature in a subsidiary program file which was loaded as a library and to give Powerbase the "hooks" to enable it to recognise the library and create the controls which gave the user access to the extra facilities.

This method of adding features to Powerbase has never been fully documented until now but has been progressively refined to the point where it can be offered to users in general.

15.1 A demonstration

The directory Customise is provided for you to try out database customisation easily and painlessly. It doesn't do anything which is actually useful but it does show how non-standard features can be added to either an individual database or even to all the databases you use.

Take a Powerbase database, any database as long as it makes use of the tool-pane, open its directory with Shift-double-click and copy Customise into it. Now run Powerbase and open the database in the usual way. Straight away you'll notice something non-standard; a little window which appears for a second to tell you that the database is open. A corresponding message is displayed when you close the database. (You were warned not to expect the demo to do anything really useful!)

At the bottom of the tool-pane you will see three buttons which aren't normally present. One is a blue, square button resembling a house window. Next to it is a pop-up menu button, which you will have often seen elsewhere. Beneath these is an action button bearing the legend Click Me! Who could resist such an invitation? What it does is display a plain-text copy of this documentation.

Click on the "window" button and (surprise, surprise) a window opens. You won't have seen this window before because it forms no part of Powerbase even though it has been invoked from Powerbase's tool-pane. Clicking the three buttons on the new window causes incrementing values to appear in the icons above them. (Decrementing values if you click with ADJUST instead of SELECT.)

Click the menu button and you'll see choices which will clear the numbers in the icons on the special window. There's an item Print which produces a report showing the values of the three counters and allows it to be saved as a text file in the usual way. A submenu contains a single entry which, when chosen, calls up a validation table you didn't know you had.

15.2 How is it done?

If you look inside Customise you will see several objects. The Templates file producing the non-standard window is there, so is the validation table called up from the submenu. The text-file Doc is the one displayed by the Click me! button. The thing which does most of the work, however, is the BASIC file called Demo, all of whose FN/PROCs become accessible, when required, as if they were part of the !RunImage itself. It's now time to load Demo into your favourite editor (Zap or StrongEd but not Edit, I hope!) and have a good look at it.

Note first of all the frequent occurrence of the string "Demo" in the names of variables, functions and procedures. When assigning names to FN/PROCs and to variables specific to the library it is important to avoid clashes with names which are used within Powerbase itself and also with names in other libraries. You may have as many databases as you like, each with its own customisation library tailored to add specific features to that database, but no two libraries may contain identically named functions or procedures. Having identically-named variables is likely to be less serious but should still be avoided. Achieving the necessary uniqueness in naming isn't difficult if you start out with the Demo library and do the following:

(a) Choose a suitable name for the BASIC library file and rename Demo to that name. The choice of name isn't critical but do keep it to 10 or fewer characters - not everyone can use long filenames. Where a library provides facilities for one database exclusively it is good practice to use the database name (minus the initial "!") for the library.

(b) Globally replace all occurrences in the file of the string "Demo" with the same name as used in (a). By "same" we mean an exact match, including identical use of upper and lowercase letters. This will ensure that the following functions in particular are re-named in a fashion which Powerbase can recognise:

These seven functions are called from Powerbase and must not have their names changed once you have made the changes described in (b) above. If you have made those changes, try out your database again. All the non-standard features should work exactly as before. If the database and Powerbase are in the same directory you will notice no difference whatsoever. If, however, they are in different directories you will, on opening the database, see a message recommending you to move it into the directory containing Powerbase. The reason for this will be explained later.

Note that although you should not use the same name for different libraries (you're likely to get program crashes and strange error messages if you do) it is possible to use the same library in more than one database, which is useful where a library provides general facilities not geared to one specific database.

15.3 What happens when Powerbase is run?

All the objects in a designated directory are examined to see whether they are databases containing a Customise directory. If any such are found, the pathnames of the BASIC libraries they contain are placed in a string array which is then used with the OVERLAY command. When any function is called which is not found in the !RunImage each library is loaded in turn until the required function is found and executed. Since all the libraries use the same area of memory, only one being paged in at any given time, this system makes economical use of RAM. The memory area used must be large enough to accommodate the biggest library, which is why it is advisable to have all your customised databases in a single directory (the "designated directory" referred to at the beginning of the paragraph) so that the maximum size of library can be found before any database is opened. This directory is specified in !Powerbase.Resources.Config by means of the entry CustDir (see 14.8). As supplied this entry has the value "Default", which means the same directory as that which contains Powerbase itself, but you may replace "Default" with the pathname of any directory you wish. Another relevant Config entry is MaxLibs; the maximum number of libraries which can be handled. The default setting is 10 but you may increase this if necessary. You can obtain a list of the libraries recognised by choosing Utilities=>Libraries from the iconbar menu. Double-clicking on a line of the displayed list will open the relevant Customise directory.

15.4 What happens when a database is opened?

If the database has a Customise directory, Powerbase looks at the list of libraries which it knows about to see whether the database's library is one of them. If not the new library is added to the list, allowing you to use the customised features of databases outside the directory specified by CustDir but, if the new library is larger than any of the known ones, some memory will be wasted. For this reason you will see a message advising you to move the database into the same directory as the others. The message only appears the first time you open the database during a given session. Once the correct library has been identified Powerbase calls the function FN_<name>_setup (where <name> is either the database name or "Demo"). This, the first function in the library, is only called once while the database remains open and does the following:

(a) Create buttons on the tool-pane, keypad or record window. These may be the "window" and menu buttons already seen in the demo, action buttons like Click me! (which may be called anything and can be made to do just about anything), square option switches and groups of radio buttons.

(b) DIMension global arrays for the library's especial use.

(c) Declare important variables which the library might require.

(d) Load validation tables which haven't been loaded by the opening of the database.

(e) Anything else which is an essential, "one-off", task for the functioning of the library.

15.5 Creating buttons

As can be seen from DEF FN_<name>_setup, the special buttons are created via a function FNadd_button. This function is part of Powerbase itself and takes seven parameters, returning as its result the icon-number of the newly-created button:

button%=FNadd_button(wi%,S$,type$,grey%,x%,y%,W%)

The meaning of the parameters is as follows:

wi%  The handle of the window on which the button is to be created. This must be either mainW% (for the record window) or keypadW% (even if the tool-pane, rather than the keypad, is being used).

S$  The text which is to appear on the button (if an action button) or adjoining it (if a radio or option button). It may also be used in menu and "window" buttons on the record screen (but not on the keypad/tool-pane) to supply a descriptor for the button.

type$  This may be "menu", "window", "option" or "radio". Any other value is understood as an action button.

grey%  A boolean variable which determines whether the button is shaded (TRUE) or not (FALSE) on first appearance.

x%,y%  Co-ordinates specifying the position of a button on the record window. They refer to the lower left corner of the button icon, the origin being the upper left corner of the window. y%, therefore, is always negative. Buttons on the keypad/tool-pane are positioned by Powerbase and any values supplied by the user are ignored.

W%  The width of the button icon in OS units. It does not apply to "window" or menu buttons on the keypad/tool-pane (these are always 44 OS units square) but is relevant for all other types. For action buttons it is the width of the button itself, for all others it is the width of the button plus accompanying text. A value of W%=0 causes Powerbase to set the button width for you. You should normally do this for buttons on the keypad/tool-pane. These should be 144 OS-units wide and you should adjust the text so that it can be displayed within this width using the current desktop font. Buttons on the record window may be wider than this and, if W%=0, Powerbase will increase the width to accommodate the text. You can override this action by supplying your own value to make the button either wider than the automatic setting or narrower than the normal minimum of 144 OS units. This is useful if you wish to standardise the width of a group of record window buttons.

15.6 What goes inside the IF...THEN structure?

It will be seen that most of the setting-up in FN_<name>_setup occurs in the body of the IF...THEN structure, i.e. in lines 22-31 incl. Anything which must/should be done only once during a given Powerbase session with a particular database goes in here. Obvious examples are the DIMensioning of a global arrays and the reading of window definitions from a Templates file. Don't put calls to FNadd_button in here because the custom buttons are removed from the tool-pane when the database is closed and all icons (including buttons) on the record window are created from scratch on the empty window on opening.

15.7 Detecting events

Section 15.2 listed seven functions within a customisation library which are called from the main Powerbase code. FN_<name>_setup has already been described. The others are called under the following circumstances:

FN_<name>_button(wi%,ic%,b%)
This is called whenever the user clicks on one of the custom buttons. wi% contains the handle of the window which owns the button. This will either be mainW% (button on record window) or keypadW% (button on tool-pane or keypad).

b% gives the state of the mouse buttons and the user can test the bits to see which button was pressed and whether double-clicked or not. ic% is the icon number of the button. and all such numbers will be known to the programmer because s/he will have set them up using FNadd_button.

There will usually be at least one CASE statement to determine which button was pressed and take the appropriate action, such as opening a menu or window.

FN_<name>_select(menu%)
Called when the user chooses from a menu which is not recognised by Powerbase and must therefore be one created by the customisation library. menu% is the handle of the menu and the item chosen is present, in textual form, in choice$(1). If the choice was from a 1st-level submenu the submenu choice will be in choice$(2) and so on down to choice$(4).

FN_<name>_click(wi%,ic%,b%)
Called when a button is clicked in a window which Powerbase doesn't recognise and which must therefore be a window created within the customisation library.

FN_<name>_press(wi%,ic%)
Called when a keypress occurs and the window having the input focus is not known to Powerbase. The key code is in key_pressed%.

FN_<name>_drop(wi%,ic%)
Called when a file is dropped on a window not known to Powerbase.

FN_<name>_function(func%)
Called when certain events apart from the above occur in Powerbase. These events are only reported if the associated flag special%(n) has been previously set to TRUE by the customisation library. There are eleven of these flags and not all have been assigned. Those which have been assigned are described below. There is no reason why the number shouldn't be increased in future if users make use of customisation and report their requirements to Powerbase Support.

0   Database opening has been completed.

1   A record has just been read into the record window. The array Rf%() holds pointers to the icon text-buffers for the fields. A copy of the record is held in field$(). Scrollable lists and External fields have been read and all keys are now present in key$().

2   A record has been read into array F$(). This is the array used when printing reports and for some other operations, so that the displayed record is not affected. Only "normal" text and numeric fields are read: where field n is a scrollable list, external or button, F$(n)="".

3   The displayed record has been written, including the writing of Scrollable lists and Externals and the insertion of keys into indexes.

4   The record held in F$() has been written back to Database.

5    A "tree-walk" or file-scan of the current key has begun. The keys will be accessed in order until the end of the subfile is reached. If more than one subfile is involved the subfiles are or scanned in sequence.

6   The aforementioned file-scan has finished.

7   A record has been matched to a search formula in the course of a file-scan

10   Database is about to close. The global variable Postpone% can be set to TRUE if you want to put off closing.



top of page   list of chapters    previous chapter   next chapter