P R I M I T I V E I T C H
tsxFactory home

Tutorial 1 - Creating a trueSpace plugin with tsxFactory for Delphi

Creating a plugin from scratch with tsxFactory is very easy. It may seem a little complicated from the steps below, but only because we've tried provide all the details.

1) Create the DLL project.

• Open Delphi and create a new DLL project.
• Make sure you select a DLL project and not a standard application. trueSpace plugins (TSX) are really just Windows DLLs.

• Make a folder and save your project into it.

2) Set project options

• Go to the Delphi menu and select Project|Options...
• Select the Application tab and enter TSX into the Target File Extension box.
  

  

• (Optional) Go to the Directories/Conditionals tab and specify your TSX folder as the output folder for your project.

2) Add a main form.

• Add a form to your project. Call it whatever you like, for this example, we'll call it MainForm and save it as Main.pas
• Add a TTsx object to the form.
  

  

• Make the form a subclass of TTsOwnedForm (by simply changing class(TForm) to class(TTsOwnedForm), see the listing below).
• Add a command to your project so that the MainForm is created when the DLL is executed. Here is the command:

  	MainForm := TMainForm.Create(Application);
  

I like to add this line to the initialization section of my main form. If you prefer, you could instead add this command to the application's .PAS file.

Now my Main.pas unit looks like this:

unit Main;

interface

uses
	Windows, Messages, SysUtils, Variants, Classes, Graphics, Controls, Forms,
	Dialogs, tsxPlug;

type
	TMainForm = class(TTsOwnedForm)
		Tsx1: TTsx;
	private
		{ Private declarations }
	public
		{ Public declarations }
	end;

var
	MainForm: TMainForm;

implementation

{$R *.dfm}

initialization
	MainForm := TMainForm.Create(Application);
end.

3) Add events.

Select the Tsx component on your form, and use the Object Inspector to create an event for OnLeftClick. This event will fire when the user clicks your plugin icon with the left mouse button. Add the following code to the event:

procedure TMainForm.Tsx1LeftClick(var plugStyle: Integer);
begin
	if WindowState = wsMinimized then WindowState := wsNormal;
	if Visible then Hide else Show;
end;

The above code is just a simple example that will show or hide the main window in response to clicks on the plugin icon. By changing the code in this event, you can create any behavior you like.

4) Compile and run your plugin.

• Select the Run|Parameters... menu item. For Host Application, use the Browse... button to select your trueSpace executable file (TSx.EXE).
• Select Run|Run. Delphi will compile your project and start trueSpace. If Delphi complains about errors in your program, check your code and try to fix them.
• Use the trueSpace plugin system to install your newly created plugin.
• Note that you can now set breakpoints and use the other Delphi debug tools on your plugin.

5) Customize plugin resources.

trueSpace gets the plugin name (aka, help string) and bitmap image from the resources stored in the TSX (tsxFactory includes a default bitmap and plugin help string). To replace the default resources, do the following steps.

• Create a text file in your project folder and save it as TsxResources.RC. Put this text into the file (obviously, you can change the string text to whatever you like):

STRINGTABLE DISCARDABLE 
BEGIN
    0                       "My TsxFactory Plugin"
END

100 BITMAP Tsx.bmp

• Add the TsxResources.RC file to your Delphi project.
• Create a bitmap for your plugin, name it Tsx.bmp, and put it in the project folder.
• Change the resource properties of the Tsx1 object. Set ResBmpId to 100 and ResStringId to 0.
• Rebuild your project (compiling sometimes does not install the new resources, so I suggest doing a build at this point.)

Copyright © 2001 Primitive Itch