What this means is entirely up to the way it is interpreted in the rest of the scripts. However, it is a poorly covered but extremely powerful feature of the ToolBook object model and developers should make every effort to learn how to use user properties - they can dramatically reduce the amount of scripting required.

There are several other ways of setting properties of objects apart from those shown above. The most useful of these is the right click menu which appears when you right click on any object with the mouse. This menu is context sensitive and is usually the quickest way of setting any property. It also has the advantage of being accessible from reader mode so that properties (including scripts) can be changed while the book is running . An example right click menu, for the same button as in the previous example, is shown below.

The row of graphics buttons along the top of this menu provide quick context sensitive access to the following six features.

• Property dialog box
• Script editor
• Autoscript selector
• Debugger
• Property editor (or a developer definable action)
• Open on-line help for this object

For beginners (and experienced ToolBook programmers) the last of these options is particularly useful as it opens up the on-line help with a task related list of activities possible with this object type. For example, the entry for a button is as follows.

ToolBook 3.0 (and 4.0) is a 16-bit, rather than a full 32-bit, Windows application and as such suffers from a number of memory related constraints. The following table, reproduced from the Asymetrix product information, lists the limits to which various ToolBook objects are constrained. Further information and comments added by the authors of this report are included in italics.

OpenScript

The OpenScript programming language has already been mentioned several times before in this report. It is in fact a proprietary programming language and far from open in the open standards sense. Every aspect of the language is under Asymetrix's direct control and they exercise their reserved right to make changes from version to version of ToolBook. Fortunately, backward compatibility has been mostly maintained and where newer versions do differ a script upgrade program, known as Script Walker, points out incompatibilities and suggests amendments. OpenScript in version 4.0 turned out to be almost entirely backward compatible with 3.0 unlike the upgrade from 1.5 to 3.0 where changes were frequently required.

OpenScript is a semi-object orientated language with message passing and containment inheritance. Scripts may be attached to any object on the object hierarchy. When events occur, such as a mouse button click on a graphic, then ToolBook sends a message (buttonClick in this case) to the target object - the graphic. If there is no script on the target object then the message automatically gets forwarded up to the parent of the object (e.g. the group or the page containing the graphic) and the same occurs for the parent (i.e. if there is no script the message automatically gets forwarded up to the parent of the object). However, if there is a script to handle the buttonClick message on the object, the script will run and it is then up to the script as to whether the message gets forwarded to the parent - the default is to not forward it and so an explicit "forward" command is required in the script to make the message continue its journey.

This scheme allows generalised behaviour to be factored out of individual object scripts and up into the script of parent objects, or even their parents. For example, placing a buttonClick handler in a book's script will provide a general behaviour when any object is clicked (provided objects do not intercept the message lower down the hierarchy and not forward it up the tree). In this way, generalisations can be scripted onto book, background and page scripts with exceptional cases scripted on individual or groups of objects. This is a remarkably powerful programming paradigm but there are problems. Firstly, it takes quite a while for new ToolBook programmers to really become comfortable with message forwarding and secondly, it is all too easy to forget to forward a message in which case the script handlers higher up the tree never even run.

There is also another down side to this "intuitively best" approach to ToolBook script structuring which should be considered by developers. Functionality distributed across multiple levels of the script hierarchy is extremely difficult to disentangle and isolate when trying to re-use scripts in another application or share scripts with other developers. To make scripts more re-usable they need to be self contained; which means that they are not split over several objects at different levels. Instead, re-usable scripts should be self contained and perhaps attached to a single object or group of objects. Of course, there is a down side to this approach too and that is the introduction of duplicate scripts and increased difficulty in maintaining copies of the same script duplicated on, possibly, hundreds of objects. Clearly there is no right and wrong approach to positioning scripts and developers must make a value judgement in the light of each project.

The range of commands, functions and properties supported in OpenScript can be seen in the Asymetrix product information reproduced and annotated in the appendices of this report. However, to give the reader a feel for the language and the way it works a simple example set of scripts are given below. Note that it will not easily be possible to understand these scripts if you have never written computer programs before - OpenScript is just as difficult to understand as Visual Basic or Delphi.

Example 1: Script on a button to show or hide a pop up consisting of a group (e.g. a help pop up).

	to handle buttonClick
		if visible of group "mypopup" then
			hide group "mypopup"
		else
			show group "mypopup"
		end if
	end buttonClick

Example 2: Script on a group object which consists of several buttons named "chapter 1" through to "chapter 7" to navigate to pages of the same name as the button when the user clicks on any of the buttons (e.g. clicking on button "chapter 2" will go to page "chapter 2"). Notice the technique of placing a single script on the group rather than a slightly different script on each of the buttons.

	to handle buttonClick
		local dest
		dest = name of target	-- target will be the button clicked
		go to page dest
	end buttonClick

Example 3: Script on a button to show or hide a pop up group but to also pass the buttonClick message up to the page script where a generalised action for all buttons is taken.

	to handle buttonClick
		-- pass the message up to page script by a "forward"...
		forward
		-- ...and return here after page's buttonClick handler has run
		if visible of group "mypopup" then
			hide group "mypopup"
		else
			show group "mypopup"
		end if
	end buttonClick

The script on the page for this example might then check to see if the object clicked (i.e. the target) was a button and if it was, make a beep sound. This effectively makes all buttons on this page beep when pressed (provided they included a forward in their scripts or if they had no script at all).

	to handle buttonClick
		if object of target is button then
			beep 1
		end if
	end buttonClick

If this script were moved up to the book script, rather than being in the page script, then every button in the book would make a beep sound when clicked.

Example 4: A complicated script fragment taken from the book script of a large ToolBook application (Note that OpenScript does not have to get this complicated, but it can). This script does not handle a system message like buttonClick, instead it is a custom handler to make an object move smoothly from where it is currently is to a specified position at a specified speed. If you are familiar with other programming languages you will see several features common to many languages such as parameter passing, global variables (known as system variable), local variables, typed and untyped variables, loop constructs and so on. Interestingly, an assembly language like accumulator called "it" is the default return location of functions of the for "get foo( )" and the pop command (also similar to assembly language pop/push stack instructions). However, the OpenScript versions are far more flexible and "it" is persistent across subroutine calls (i.e. send, get and forward).

to handle we_move obj,x,y,spd	-- spd is null,slow,medium,fast
	system xonepixel,yonepixel	-- global variables
	local stack lis,olist	-- local variables
	local object o
	local long dx,dy,nsteps,remx,remy,i
	get position of obj
	dx = x - item 1 of it
	dy = y - item 2 of it
	lis = obj
	get p_style of obj
	conditions
		when it = null
			break conditions
		when it = "s_popup"
			put p_objlist of obj into olist
			while olist<>null
				pop olist into o
				pop olist			--style
				get p_child of o
				if it<>null
					push it onto lis
				end
			end
		when it = "s_backdrop"
			get p_child of obj
			if it <> null
				push it onto lis
			end
		when it = "s_spreadsheet"
			if p_handle of obj <> null
				get position of obj
				get we_spread_position(p_handle of obj, \
					item 1 of it+dx,item 2 of it+dx)
			end
		else
			get p_child of obj
			if it <> null
				put ","&it after lis
			end
	end conditions
	remx = dx
	remy = dy
	if spd <> null
		conditions
			when spd = "slow"
				nsteps = 20
			when spd = "medium"
				nsteps = 10
			when spd = "fast"
				nsteps = 4
			else
				nsteps = 1
		end conditions
		dx = dx / nsteps
		dy = dy / nsteps
		step i from 1 to nsteps
			sysLockScreen = true
			move lis by dx,dy
			decrement remx by dx
			decrement remy by dy
			sysLockScreen = false
			if we_sync(1) > 0
				break step
			end
		end
	end
	sysLockScreen = true
	move lis by remx,remy
	sysLockScreen = false
end

An example of how this script might be used is given below. This sample "call" of we_move is the script on a graphic which, when clicked, zooms to position 300,500.

	to handle buttonClick
		send we_move self, 300,500, "fast"
	end buttonClick

As with all interpreted languages, execution speed is often an issue. The degree to which this is a problem depends upon the application type but typical graphically intensive multimedia applications tend to be dominated by calls to the Windows display routines rather than running numerically complex iterative calculations. Therefore, the speed of the application can be more dependant upon the speed of the graphics card, the hard disk and the amount of free RAM. With this caveat in mind, the remainder of this section examines the execution speed of various activities in OpenScript.

Speed and efficiency issues.

Timing benchmarks.

Communicating with other Applications

Particularly in Computer Based Training applications of ToolBook it is useful to be able to communicate with other non-ToolBook applications. ToolBook is able to communicate with other applications using the following methods.

• Simple application launching
• Message sending and posting via Windows API
• Windows Dynamic Data Exchange (DDE)
• Object Linking and Embedding (OLE - but not OLE 2 or ActiveX)
• Direct access to other ToolBook books from OpenScript

A brief explanation of each of these is given below along with comments on the practicalities of using each approach.

Simple application launching

Starting up other applications from ToolBook is straight forward assuming that the location of the application on the user's machine is known. A single line of OpenScript will achieve this.

	run "c:\windows\notepad.exe"

Unfortunately, having launched an application no information on that application is passed back to OpenScript and so programmers are forced to write OpenScript code to search through the Windows list of windows in order to get a "window handle" which will allow ToolBook to manipulate that window (e.g. positioning it on screen or closing the application). This is a fairly low level operation which requires exactly the same degree of knowledge of Windows programming as would be required to do the same task in C/C++.

Message sending and posting via Windows API

ToolBook allows Dynamic Link Libraries to be linked into OpenScript to extend its functionality (see 4.5, "Extending ToolBook"). Importantly, this gives access to all the built in Windows DLLs one would normally access in C/C++ to send and post messages to applications.

This allows experienced Windows C programmers to communicate in a number of ways with other applications. The simplest of these would be to, for instance, close another application by sending the appropriate WM_ message. However, unless originally designed to communicate in this way, the level of communication with applications using this technique usually stops short of exchanging data or running tasks; communication is more at the level of the Window rather than the application.

ToolBook comes with redistributed Microsoft SDK API help files which list commands available through the built in Windows DLLs and the numeric constants corresponding to each of the WM_ and other Windows constants.

Windows Dynamic Data Exchange (DDE)

DDE is the Windows protocol for exchanging data between applications. Most mainstream Windows applications respond to DDE to a greater or lesser extent. Microsoft Excel for instance allows data to be transferred in and out of a spreadsheet using DDE; it is also possible to open, manipulate and close Excel spreadsheets remotely via DDE. Similar actions are possible in Word, Access, Netscape, Explorer and numerous other applications - including ToolBook.

It is therefore possible to control other applications from ToolBook and to transfer data between that application and ToolBook. The nature of the conversation between the programs can be client server or peer to peer (in the control sense rather than the networking sense).

While DDE is impressively easy to use in OpenScript (despite having non-standard names for the messages/commands compared to those used in Windows programming in general). For some applications of ToolBook a simple DDE conversation may be all that is required and that will work perfectly adequately. However, applications such as Access can be unusably slow in transferring data back to ToolBook. It is hard to tell where the blame lies but the net effect is that a DDE link between the two can be unbelievably sluggish. For example, a multiple choice question system which used Access to store the questions and ToolBook to display them on screen took up to 2 minutes to DDE transfer 15 short strings and an integer. The same information retrieved and displayed in Access itself appeared almost instantly.

The use of DDE should not be ruled out on these grounds but a commitment to use this channel of communication should not be made with undertaking a pilot study of the intended link in use.

Object Linking and Embedding (OLE - but not OLE 2 or ActiveX)

It is possible to embed OLE objects, such as an Excel graph, in a ToolBook page. However, this approach to linking applications is seriously flawed if the end-user does not have the same version of the embedded software on their machine or if it is not in the same directory. Certainly this is not viable for ToolBook books produced for general circulation.

An OLE object has a set of properties associated with it just like any other ToolBook object and these can be manipulated in OpenScript.

Direct access to other ToolBook books from OpenScript

Unlike DDE links, directly accessing any objects or data in another ToolBook book does not require that the other book is open and requires no special protocol. For instance, it is not widely known that a second ToolBook book set to read/write access may be used as a simple but effective log file (or to record user preferences or similar persistent data) which may be read and written by multiple users in the same way that an ANSI text file would be. From a book which is read-only and opened simultaneously by multiple users, a separate read/write book can be opened, written to and closed for each and every log operation. ToolBook itself will take care of any back-off and retry upon collision of more than one user trying to access the log book simultaneously. The ease1 of this operation can be seen from the shortness of the following code fragment which writes a user's name and score to a text box (i.e. field) in a ToolBook book called "scorelog.tbk".

put username & SPACE & userscore & CRLF after text of \
field "scores" of page 1 of book "scorelog.tbk"
save changes to book "scorelog.tbk"

Note that the book is not actually opened in the sense that no one has opened it explicitly anywhere on the network; however, it is opened implicitly when data is written to it as in the above "put" command. To see the logged results, the instructor could later open the log book (scorelog.tbk) and scroll through the text in the field called "scores" on the first page of the book.

Extending Toolbook

There are two ways of extending the functionality of ToolBook and OpenScript.

• System Books
• Dynamic Link Libraries (DLLs)

In fact Asymetrix have used both these methods to extend the core ToolBook engine and much of what developers perceive as ToolBook is in fact a system book written in ToolBook or a supplementary DLL.

System Books

System books have been briefly mentioned before in this report. They extend the inheritance hierarchy, which normally stops at the book, up another level. So, after a message has risen up to the book script it then passes on up to the first system book (if there is one) and then up to the second system book (if there is one) and so on. By placing the sort of scripts one might normally expect to place in a book script into a system book, these scripts can then be used by several applications. Any changes and bug fixes to scripts in the system book will therefore automatically apply to all applications using that script. Two common uses of system books are to construct libraries of re-usable scripts and to extend the functionality of ToolBook by adding extra menu items or authoring features.

A system book is actually only a normal ToolBook book and any book can be nominated as a system book simply by adding it to the sysBooks list in an application (normally as the application starts up). Adding a book to the sysBooks list places its book script in the inheritance hierarchy but does not open or load the rest of the system book.

By default, ToolBook starts up with either TOOLS30.SBK or MTB30.SBK. These system books add the Tools menu to the author level menu bar and are a good example of what is possible with system books. It is possible to examine and modify the scripts of these books as all the OpenScript code is there.

Dynamic Link Libraries (DLLs)

One of the most flexible ways of extending OpenScript is through the use of Windows DLLs. A number of these are always available on any Windows PC. Several are also supplied with ToolBook and it is possible to develop your own in C/C++, Delphi, Turbo Pascal and any other language capable of generating Windows 16-bit DLLs. However, it should be noted that writing DLLs to extend ToolBook is time consuming and requires a good understanding of the way both Windows and ToolBook work; it is not an activity which can easily be picked up by a non-programmer without much hard work.

Assuming that a suitable DLL already exists then it may be used in OpenScript by using the linkDLL command to add routines from the DLL as extra commands to ToolBook. The linked command can then be used just like a built in OpenScript command. Before the application closes it must unlink all linked DLLs or Windows will not release them from memory.

An example of linking to one of the DLLs shipped with ToolBook is given below. This example button script opens a standard Windows file open dialog box (with all the directory changing, drive selecting, filtering normally found in Windows open dialogs). It does this by linking in a function from TB30DLG.DLL, using it and then unlinking the DLL again straight away (an alternative would have been to have linked the DLL at the start of the application and to only close it at the end of the application - developers are free to choose). The file name returned is then used to open the file and read it into a text field.

to handle buttonClick
	local fname

	linkDLL "TB30DLG.DLL"
		STRING openDlg(STRING,STRING,STRING,STRING)
	end
	fname = openDlg(".","*.txt","Choose a text file...","Open")
	unlinkDLL "TB30DLG.DLL"

	if fname is null
		break	-- was an error so quit handler
	end if
	openFile fname
	readFile fname until EOF
	text of field "myfield" = it
	closeFile fname
end buttonClick

Graphics

This section describes graphics features of ToolBook which are common to both ToolBook 3.0 and Multimedia ToolBook 3.0. Video and other graphics features exclusive to Multimedia ToolBook are described in the next chapter.

Built in Primitives

ToolBook has a number of built in primitive drawing elements which occupy relatively little memory (compared to bitmap graphics), are quick to display and easy to manipulate. The supported types of primitive are listed below.

• line
• angled line
• curve
• rectangle
• rounded rectangle
• ellipse
• regular polygon
• irregular polygon
• pie

Imported Vector Graphics

ToolBook allows vector image file formats such as WMF to be imported into the current page where they become a ToolBook object type known as "picture". By default, these pictures always appear with a border around them but this can be removed by selecting a different line style from the Lines palette. The picture may be made transparent, resized, repositioned, shown/hidden and have a script assigned to it.

On slower machines or with complex pictures picture files pictures take a long while to draw and can be unusably slow. It is important to test the redraw speed on a representative delivery machine.

Large and complex files, particularly EPS files it seems, fail to import correctly.

Imported Bitmap Graphics

Bitmap graphics for all popular file formats can be imported in the same way as vector file formats. ToolBook uses conventional Windows graphic import filters and so as graphics packages installed on the developer's machine add extra formats, these become available to ToolBook. Once a graphic is imported into ToolBook the filter is no longer required so end-users do not need to have software to support these extra formats; the image is stored in ToolBook's own internal format.

An imported bitmap usually becomes a ToolBook paintObject. A paintObject can be manipulated just like a picture object except that it can not be resized - instead it is clipped at the right and bottom edges. However, some formats such as PCX are imported as picture objects and can be resized just like a vector image file format.

Bitmap Resources

A feature new to ToolBook 3.0 was the addition of bitmap resources (not compatible with standard Windows bitmap resources in the way they are stored in the ToolBook file). By importing a bitmap as a resource it can be used throughout the book. Each instance of the image shares the same bitmap rather than each one duplicating the same bitmap as would occur if they were imported directly into the page.

Bitmap resources can only be used on buttons or in text fields and so it is common practice to use a borderless button to display a bitmap resource as a (seemingly) standalone object.

Storage Options

Small images, about the size of a typical Windows button, if imported as paintObjects consume a relatively large amount of the scarce 64K memory available for a page's objects and are best stored as bitmap resources. Larger paintObjects are stored outside the 64K and so, ironically, are less of a problem.

If bitmaps are to be used more than once in a book they should be stored as bitmap resources rather than paintObjects.

An option exists for complex pages and backgrounds to be converted to a single image to speed up page redraw. However, in practical terms this appears to make little difference and commits to a specific screen format for delivery.

Palettes

256 colour screen displays use palettes, a selection of 256 from the range of colours possible, because only 256 colours can be displayed simultaneously on such hardware display modes. The precise choice of which 256 colours to display is a complex process when different bitmaps may each require a different set of colours. This can result in image degradation and a flashing of incorrect colours when ToolBook pages are displayed. The issue is further complicated by different priorities for bitmaps at different screen depths and between foreground and background images.

There is no simple fix for this problem which will work in all cases. The simplest fix is to remap or originate all the bitmaps so that they share the same palette - even using sub-256 colour images does not entirely avoid the problem. ToolBook allows a single palette to be specified for the entire book and this prevents any palette flash at the cost of restricting the colour range to a fixed set of 256 colours.