Image of Navigational Panel mapped to Home / Conetnts / Search Using VBXs in ToolBook 4.0

by Stephan Grieger - GUI Computing
Image of Line Break

Visual Basic Extensions, or VBXs, have become the backbone component of Microsoft's most popular development environments - such as Visual Basic (for obvious reasons) and C++. The latest development environment to provide VBX support is ToolBook 4.0 CBT edition.

It will allow you to add an 'Extension', and then use it from the toolbar like any control within ToolBook. Unfortunately ToolBook, at this stage, will only support Level 3 VBXs and will not support OCXs. However, we can expect OCX support in ToolBook 5.0, which is due in late 1996.

Now, before you say "Oh, Happy Happy, Joy Joy!", and run out to buy all those neat VBXs that Visual Basic programmers have been enjoying for the last four years, there are some issues that you need to be aware of and accommodate for.

The most important thing you will need to do is to get to know the custom control you are using. The best way of learning a custom control is to first use the control from within Visual Basic. This will then allow you to try out everything that you wish to do with the control, before you try implementing it into ToolBook. Once you have it working from within Visual Basic, you can then transfer that knowledge to ToolBook. Now, this may sound like a roundabout way of doing it, but take it from someone who has had to do this, it is by far the easiest method.

This does of course require you to be, or become, a Visual Basic programmer <of sorts>. This may not immediately appeal to you, but having had to go through this myself, I can tell you that the time spent was well worth it. And would that really be so bad? <See article on ToolBook DDE for clarification>

Let's now delve into what aspects you will need to be aware of when implementing custom controls into ToolBook.

Custom Events:

The first issue - and one of the more serious ones - is to do with responding to VBX events. Each custom control comes equipped with its own set of events, which are called when certain things happen to the control. These messages differ radically from the standard ToolBook events. Let's take the control Formula One as a good example.

Formula One is a spreadsheet control which can contain formulas in cells, and even export to the Microsoft Excel format. It contains a whole set of custom events for when Formulas change, Cell change, mouse clicks, etc. ToolBook has no control that performs the same function, and as a result does not inherently respond to the events that Formula One triggers.

ToolBook's approach to this is to have a flag that you can set at runtime, called sysSendToolBookMessages. This will allow ToolBook to respond to VBX events - but it can confuse the issue when trying to access standard methods for the custom control, that ToolBook will still generate. Basically the way it works is this. You set the sysSendToolBookMessages to False. ToolBook will then be able to respond to custom VBX messages, and all standard events (like ButtonClick) for that custom control will be disabled.

For example, let's say that the custom control that you are using has a message called SetArray, you would then write the handler as such;

  To Handle SetArray X, Y

    Your Code Here.


Now, Formula One has a property called KeyDown which takes the parameters Keycode and Shift. Compare this against the ToolBook KeyDown method which has Key, IsShift, and IsCtrl, as its parameters. If you have set the sysSendToolBookMessages flag to false, or if indeed if you have left it as true, you will run into problems when you are trying to respond to the message as each method has different parameters and parameter types. If you intend to use the KeyDown event for either Custom Controls or ToolBook controls, you will need to include code in all controls for this event. Even if the Event does nothing at all, it will need to be there otherwise ToolBook will pass the message on, and the first KeyDown method it strikes will be run and a failure is imminent.


One of the most useful features is, of course, the ability to modify properties of the controls which alter its appearance and/or behaviour. ToolBook controls come with a set of standard properties which you can set during run time and/or design time.

However, when you add an extension to the ToolBook environment, the control you are importing will come with its own set of properties. Most of these will be unique to that control only, and not standard ToolBook properties.

Whenever ToolBook encounters one of these unknown properties, it places 'vbx' in front of the property name. So, for the custom property 'Rows', ToolBook would rename it to be 'vbxRows'. Referencing these custom properties is identical to referencing any normal ToolBook property. For example, if you wanted to set the Rows property of the control class ssView with the name MyGrid to 10, you would type;

  Set vbxRows of ssView "MyGrid" of this page to 10

ToolBook will still add in its own properties such as Name, Object, Layer, Position, etc. These properties will be transferred to the ToolBook convention.

Controls that have their own DLLs:

The custom controls come shipped with DLLs which provide additional functions. These can be accessed via ToolBook in the same way that you would access a Windows API call. For example, Formula one has a function called ssObjGetItem. For ToolBook to be able to use the function, you will first need to link the DLL. The code;

    INT ssObjGetItem (Long, Long, INT, STRING, INT)
  End LinkDLL

will tell ToolBook where to find the function when called. This code is probably best placed into a system book and called whenever the application is opened. See Mark Trescowthick's article in this issue for an easy way to convert all those VB Declares.

In the above function, the String parameter is the variable where the result will be placed. The last Int parameter is the maximum length expected to be returned. As we are passing across a pointer to a variable, we will need to pad, with spaces, the variable with the maximum number expected to be returned. Failure to do this will result in a General Protection Fault.

For example;

  To Handle ButtonClick

    Local String Buffer

    Buffer = "          " –Ten Spaces.

    Get ssObjGetItem(36152, 1, 2, Buffer, 10)


Buffer will now contain the return result of the function, and IT will contain the error returned. If all went well, IT should be zero.

You will need to be aware of what data types are compatible between Visual Basic and ToolBook. For example, several of the Formula One functions require that you pass across type Double variables. ToolBook doesn't have a Double type so, after multiple GPFs, we finally discovered that type Float worked quite well. This will take some time and pain to sort out, so be patient. Again, see Mark's article...

Sum Up:

You may have noticed, in this edition of the AVDF, I have written more articles on ToolBook than I have ever published before. The reason for this is that we recently needed to develop an application that had ToolBook written all over it.

One of the requirements was to have grid functionality in the application. Our first attempt to emulate a grid failed in the opening moments. It was then that we discovered ToolBook had VBX support. Enter Formula One stage left.

Had it not been for our in depth knowledge of the control itself, obtained from Visual Basic development, we would have been chasing our tails for quite some time.

The most important thing to remember is to get to know your custom control well before attempting this.

Written by: Stephan Grieger
April 96

Image of Arrow linked to Previous
Image of Line Break