Introduction:
While reading the articles over at this site I realised there are no articles concerning Delphi and the possibilities of making dll's to use with Blitz. There are two major reasons I decided to write this article. First, I've seen a lot of people mentioning Delphi in the discussions sections wich should mean there are many users of Delphi around. Second, it's easy creating userlibs with Delphi but I have no idea how many of you who really takes advantage of this nifty feature. So, you might ask why in the world you would care about creating a userlib when all the functions and methods you need allready exists within Blitz. Well actually, allthough Blitz is a great language it lacks of some methods that would make game development easier. As an example, let me tell you about me. When I’ve created a level editor for a game and I have come to the part of saving the map to file I have wanted a standard windows save dialog so bad. In fact I could kill for one. That’s why I haven’t released any leveleditors made in Blitz, cause all of them saves the map to “level1.lev”, wich means I have to rename that file before I save the next one. Userfriendly heh? Ok, so what we will be doing in this article is creating a userlib in Delphi containing methods to display a standard “open file dialog” and a standard “save file dialog”, and if you’ve created dll’s in Delphi before this will be like a stroll in the park. And even if you’ve never touched userlibs or Delphi before this article, I suppose it won’t be very hard to follow (if my poor english skills doesn’t screw things up for you:) Before we begin, let’s have a short briefing on what user libraries and dll’s really are.
Userlibs
Userlibraries were introduced in one of the most recent product updates for Blitz, so in case you have a demo or coverdisk version of Blitz this document won’t apply for your version of Blitz. Userlibraries allows you to create extensions to the Blitz command set, using a programming language of your own choice. All you need is an external dll and a file describing the methods that should be available from within Blitz. Theese description files has to have the same name as the dll, but with a file extension of “.decls” instead of “.dll”. The “.decls” file is placed in the “userlibs” folder of the Blitz installation folder together with a copy of the dll.
Dlls
A dll (dynamic link library) is easiest to describe as a pack of functions that can be called from any other program. Later when you distribute your software you also have to supply the dll, preferably you put the dll in the same folder as the executable, but many other software companies prefer to put their dlls in the windows\system folder. The advantage of this is that it can not be different versions of the same dll on your computer. The disadvantage is that your windows\system folder will eventually look like a can of garbage because many software companies do not care to remove their dlls in the uninstallation process.
What you need
For this article to work for you, you need
Chapter 1 –Creating the Save Dialog
Ok, let’s start creating the dll. Fire up your Delphi version and press File->New->Other… In the listview quite far down you can see an item called “DLL Wizard”, select it and hit Ok. Now you get the source code for an empty dll, with no methods at all. But before we begin adding methods we should save the project, so lets just hit “File->Save As…” and save the project in any folder you like, and name it “dialog.dpr”. Now locate the section that says:And change the section so it looks like this:
The reason we added “dialogs” is because the methods we need to create the dialogs are stored in another delphi unit called dialogs. Anyway, the only thing missing in the dll right now is two methods. One for displaying the open dialog and one for showing the save dialog. Here’s the full code for the save dialog, I will decribe the code a bit more in detail later.
The first line, starting with “function “ is the declaration of the method, and as you have noticed we didn’t use the string data type, instead we used the Pchar to manage parameters. Now why did we do that? Well, if you use strings in delphi dlls you need to distribute another dll called borlandmm.dll wich is a memory manager that makes it possible to exchange strings using the Delphi type of string. In windows it’s actually Pchar that is used as strings, a Pchar is simply an array of characters, ending with a null character to show that it’s the end of the string. Another thing to note is that the line is ending with “stdcall;”, that is to tell wich calling convention the dll uses, so that the calling application handles the in and out data the same way. Ok, enough of that, the parameters we’ll be accepting is title wich is simply the title of the save dialog. Defaultext is the default file name extension and finally the filter is the type of files to show in the savedialog. Next thing we did on line two and three was declaring a variable called dlg of type TsaveDialog. Then after the begin line we created the TsaveDialog and assigned the parameters to the different properties of the dlg variable. What we do next is simply showing the dialog, and if the user presses the Ok button we return the filename, else we simply return an empty string. The last thing we do is freeing the memory used by the dlg variable. So, that’s all we need to do to create a nice little savedialog.
Chapter 2 –Creating the Open Dialog
This code is actually quite similliar to the save dialog and it will accept the same parameters. I will present the code below, followed by a more detailed description.As you can see the first line is completely identical as the savedialog method, except is has a different name. An other difference it that instead of declaring a variable of type Tsavedialog we here have the variable as a type Topendialog. Other than that theese two methods are very identical to eachother.
Chapter 3 –Finnishing the dll
Well, allthough this code compiles fine with no errors there are three more lines that must be inserted in the code before we can call it from a Blitz program. We need to tell wich methods are exported and usable outside the dll, this is done using the keyword exports. So what we should do is to place the cursor above the “begin…end.” Section, but below the “executeOpendialog” method we wrote, and insert the code below:All you need to do now is to build your project by selecting Project -> Build project and copy the resulting dialog.dll file to the Blitz userlib folder (usually c:\program files\blitz3D\userlibs or something like that).
The full source of the dll
If I haven’t made myself clear on how the source of the dll file should look when it’s done, here it is, all you have to do is to paste it in a delphi code editor.Chapter 4 – The declaration file
The dll is finnished and placed in the correct folder, all that’s missing now for the possibility of calling it from your Blitz program is a declaration file containing the name of the dll and descriptions of the methods that we should be able to call. Open up Notepad and add theese lines:Then save the plain text file in the same folder as you placed the dll in (the userlib folder, remember?) and name it “dialog.decls”. If you look at the text you can see it’s rather simple, the first line tells the name of the dll, and the following two lines shows the way the methods are called from within Blitz. Now close notepad.
Chapter 5 – Testrun
Everything is done, and all we need to do is to test it to make sure it works well. Fire up Blitz and create a new file. Simply add theese lines to test the newly created userlib:The code above is quite self explanatory, the only thing you need to know is the way to pass the filter parameter. In the standard open and save dialog you can select a file type, that’s the filter. The way to pass this parameter is to separate the different filters with “|”, to the following format: “file type description|file mask|file type description|file mask” e.t.c.
Chapter 6 – Conclusion
As you can see, it’s very easy to create userlibraries with Delphi, and it’s even easier to call them from Blitz, so why haven’t I seen many more usefull libraries in the showcase? I hope that will change soon. And I hope this article have given you an usefull introduction on how to create your own userlibraries. Feel free to contact me at metallicas_world@hotmail.com Cheers /MetalManFor a printable copy of this article, please click HERE.