Official AddOn Development Doc from NeoSoft *

Creating NeoBook for Windows Add-Ons
This document is intended for use by experienced programmers.
Experience with Delphi, Visual Basic, C++ or similar 32-bit
Windows programming environment is recommended.

What's an Add-On?

Beginning with version 3.2, NeoBook for Windows provides third party developers with direct access to its internal command processor. By using Windows' Dynamic Data Exchange (DDE), external programs can interact with compiled publications to provide features and capabilities not available with NeoBook alone. These added capabilities may provide something as simple as the ability to select a file from a list or as complex as retrieving data from a database server.

An Add-On is basically nothing more than a stand-alone executable program (exe) created with Delphi, Visual Basic, C++ or any other similar 32-bit Windows programming environment. What makes an Add-On unique is its ability to communicate with compiled NeoBook publications. The Add-On communicates with a publication by sending it a list of action commands to execute. These action commands are the very same ones that NeoBook authors use to construct their publications. The publication, on the other hand, can only send instructions to the Add-On using NeoBook's ExecuteAddOn action.

For example, suppose we have created an Add-On that displays a Windows File Selector, allowing the user to find a file on their hard drive. Once the user has located and highlighted the desired file, the Add-On might send the NeoBook publication an action like the one below to indicate the name of the selected file:

SetVar "[FName]" "c:\Sample Files\Frogs.xyz"

The SetVar command instructs the publication to place the file name into a variable called [FName]. The variable can then be used internally within the publication to access the file.
 
 

Creating Your Own Add-On

The DDE commands used by the Add-On to communicate with a publication are actually quite simple. Most visual development environments like Delphi provide pre-built DDE components that simply can be dropped onto a project. These components contain all of the functionality needed to communicate via DDE.

Our example Add-On program was created in Delphi, but the principals are the same regardless of which programming environment you plan to use.

First, create a new project by selecting New Application from Delphi's File menu.

Next, click the System tab on Delphi's Component Palette and add a DDEClientConv and a DDEClientItemcomponent to your application's main form.

By design, NeoBook's Add-Ons are modal, which means that like Windows' dialog boxes, your publication will suspend operation until the Add-On terminates. In order to provide the user with a simple way to exit the Add-On, we need to add an OK button to the form.

We will use the OK button's OnClick event to execute the code necessary to pass information back to our NeoBook publication. The OK button's OnClick event should look something like this:

PROCEDURE TForm1.OKBtnClick( Sender: TObject );

BEGIN

{ establish a DDE link with the NeoBook publication }

IF (DdeClientConv1.SetLink( ParamStr( 1 ), 'NEOBOOKDDESERVER' )) AND ((DDEClientConv1.OpenLink)) THEN

BEGIN

DdeClientItem1.DdeItem := 'NEOBOOKDDEITEM';

{ send an action command to the NeoBook publication }

DDEClientConv1.ExecuteMacro( PChar( 'SetVar "[AddOnResult]" "It Worked!"' ), FALSE );

{ close the DDE link }

DdeClientConv1.CloseLink;

END

ELSE ShowMessage( 'Unable to establish DDE link.' );

{ close our Add-On }

Close;

END;

In the first line of the OnClick event you will notice that the first parameter of the DDEClientConv component's SetLink function is ParamStr( 1 ). This first item on the command line passed from NeoBook, contains the name of the compiled publication that launched the Add-On. This very important information is required in order to initiate the DDE conversation with the publication and should not be changed.

Any other information (which is optional) placed in NeoBook's ExecuteAddOn action will appear second, third, forth, etc. on the Add-On's command line. For example, using the following NeoBook action:

ExecuteAddOn "MyAddOn.exe" "X23 A27"

would place "X23" and "A27" in the second and third positions on the command line. From the Add-On, this information could be accessed like this:

C1 := ParamStr( 2 );

C2 := ParamStr( 3 );

The next item in the OK button's OnClick event sets the DdeClientItem's DdeItem property to "NEOBOOKDDEITEM". This also cannot be changed and should remain the same for any NeoBook Add-Ons that you create.

The DDEClientConv's ExecuteMacro is the method that actually sends data back to your NeoBook publication. This data is always sent back in the form of a NeoBook action command. The action you use most often will probably be SetVar, which you can use to set variables in your publication. You may use the ExecuteMacro method as many times as you like to set multiple variables or execute other NeoBook actions. In our example, we're merely setting a variable called [AddOnResult] to "It Worked!"

After sending our action commands back to NeoBook, it's time to end the DDE conversation by calling the DdeClientConv.CloseLink method.

Finally, we terminate our Add-On application by calling the Close method.

Don't forget to save and compile your Add-On.
 
 

Using the Add-On with NeoBook

Next, we will use NeoBook's ExecuteAddOn action to call your compiled Add-On.

Start NeoBook and open a new publication window. Create a button object with the following action command:

For this example, we have assumed that your Add-On has been named MyAddOn.exe and is located in the "c:\Delphi 2.0\Add-On\" folder. If this is not the case then change the first parameter to reflect the correct name and location of your Add-On.

The second parameter of ExecuteAddOn is not used in our example, but (as explained earlier) can be used to send data or instructions to your Add-On.

Once you have completed your button, add a title text object to the publication. Make the title object large enough to hold the phrase "It Worked!" which our Add-On will return. In the text field of the Title object's Attributes screen enter the following:

Now for the moment of truth: select the Run command from NeoBook's Book menu. Click the button. After a few seconds, you should see the Add-On program's main window. Click the Add-On's OK button and the words "It Worked!" should appear inside the NeoBook publication's title text object.

Of course, the only thing this sample Add-On does is set a NeoBook variable called [AddOnResult] to "It Worked!" This isn't terribly exciting, but you easily can expand this to do many things, like display a Windows file selector, retrieve information from a database, perform complex mathematical calculations, and more.
 


* This document is used with the permission of NeoSoft Corporation
Copyright 1999 NeoSoft Corporation

[ Return to NeoDezign Tips & Trix ]