Status of XDev Toolkit

Contents

Introduction

  MacPgmr (at) fastermac (dot) net

Note: You can also post to the Lazarus forum if you want your bug reports and suggestions to be seen by the entire Lazarus community.

The XDev Toolkit source code is here: http://web.fastermac.net/~MacPgmr/XDev/downloads

All source code included in the XDev Toolkit is released under the Modified LGPL license.

Installation

1. Unzip the source files into their own folder.

2. Open a terminal window and compile each utility and test program with FPC. For example:

   fpc -Sd DfmToLfm.pas

3. To see a utility's syntax, simply run it in a terminal window without any parameters or switches. For example:

   dfmtolfm

MakePasX & DfmToLfm: Delphi converters

Once you've converted a Delphi app to Lazarus you can continue to develop the app with Delphi on Windows and use Lazarus to compile the app on other platforms. This type of app can provide the best of both worlds: taking advantage of the Windows-specific features of Delphi while utilizing Free Pascal and Lazarus to add cross-platform capability to the app.

1. Use the MakePasX utility to make the Delphi project file (.dpr) and form code files (.pas) cross-platform. This is a one-time conversion that results in a set of source files that can be compiled by both Delphi and Lazarus.

2. Use the DfmToLfm utility to create Lazarus form files (.lfm) from the Delphi form files (.dfm).

3. Use the Lazarus lazres utility to create the Lazarus resource file (.lrs) from the form file (.lfm) Repeat steps 2 and 3 whenever you make changes to the Delphi form files. If your project has a number of forms, run these utilities for each form in a batch or shell file to automate the conversion.

4. Compile the resulting files with Lazarus on Windows to test the converted code and form files.

5. Move the Lazarus project's files over to OS X or Linux and compile and test them there with that platform's version of Lazarus.

MakeVer: Create a version info file

CvtHelp & HelpUtil: Convert WinHelp RTF to HTML

1. Use Word to save the WinHelp RTF file to a "Web Page, Filtered" HTML file. For example, open myapp.rtf and save it as myapp.htm.

2. Run CvtHelp on the resulting HTML file and the WinHelp help project (.hpj) file. For example:

   cvthelp myapp.htm myapp.html

3. Add the HelpUtil unit to the uses section of your Lazarus app's main form.

4. In your main form's FormCreate handler:

   Application.HelpFile := ChangeFileExt(ParamStr(0), '.html');

   HelpManager := THelpUtilManager.Create;

5. In your main form's FormDestroy handler:

   HelpManager.Free;

6. To invoke help, add something like this to a menu command or button OnClick handler:

   Application.HelpContext(1);

OS X scripts: Create an app bundle

• Before using this script, make sure you've made it executable:

  chmod +x create_app_mac.sh

• Example: Your executable is file myapp and you want to create an .app bundle for it named My Application.app:

  ./create_app_mac.sh myapp "My Application"

RtfDoc & ViewDoc: RTF document creation and viewing

TRichEdit is a handy control for creating or displaying simple reports, but if you try to use it for more than that you will be quickly disappointed because TRichEdit has serious limitations. For one thing, Borland never added support to TRichEdit for newer versions of the Rich Edit library (RICHED20.DLL). And although it's possible to hack the Delphi ComCtrls unit to add support for RICHED20.DLL, Microsoft never fixed some of the bugs in this library or supported more than just a subset of RTF.

Since Lazarus is a cross-platform tool, it doesn't provide a TRichEdit control. And even if it did, this type of control might not meet your needs. After all, TRichEdit is trying to be a word processor, something the creators of Word and OpenOffice.org have spent many years developing. Wouldn't it make more sense just to use an actual word processor to create and display reports?

Using TRtfParser to create RTF documents

Fortunately Free Pascal includes a unit named RtfPars that includes the TRtfParser class. While this class was designed to parse and proof existing RTF documents, you can also run it "backwards" to create RTF documents as well.

To simplify use of the TRtfParser class, the XDev Toolkit includes unit RtfDoc, which introduces a TRtfParser descendant, TRtfDoc, which can be used to create RTF files without knowing how TRtfParser works. For information on how to use it, look at the RtfDoc.pas file and TestRtfDoc.pas example program. You'll also want to look at the Free Pascal rtfdata.inc file for a list of constants that you'll need to use with TRtfDoc.

For more information on the RTF specification, refer to Microsoft's documentation.

Using Word and OpenOffice.org to display RTF documents

• Determine that the word processor exists and the location of its executable.
• Start the word processor by shelling to it, passing it the name of the RTF report document.
• Clean up.

Why would you need to clean up after launching the word processor? Usually this step is necessary because the report document will be a temporary file that you'll want to delete. You probably shouldn't require your users to name each report document that your program creates. This will quickly annoy them; it also forces your users to clean up the clutter of saved report documents. Instead, you should use the GetTempFilename function (in the Lazarus FileUtil unit) to get a file name to use for your temporary file, then delete this file yourself at some point after launching the word processor. (Don't use the same file name for all reports since this will restrict your users to viewing only one report at a time.)

But how can you delete a file if it's open in another program? Remember, your word processor is running externally to your program and locks the file as long as it's open. The file and the word processor won't be closed until the user decides to close them. And even if the file has already been closed, are you sure you want to delete it? What if your user made changes to the report and saved it?

The solution that ViewDocument uses is to start the word processor with a switch that tells it to create a new document based on the report file (that is, using it as a template). ViewDocument can also add the report file to a list of temporary files to be deleted when your program shuts down. Even though your program still can't delete the temporary file as long as the new document based on it is open in the word processor, this does mean that if the user saves the new document, it won't be with the report file's name.

To delete the temporary files created by your program, call the DeleteViewedDocs function in your main form's FormCloseQuery handler. If DeleteViewedDocs returns False, you can remind your user to save or close any reports still open in the word processor. DeleteViewedDocs is also called by the ViewDoc unit's finalization code to clean up whatever it can when the program finally does shut down.

One final note: With OS X, the normal way to start a program from a terminal command line or when shelling is to use the Open command. Unfortunately, the only parameter that Open passes along to the program is the name of the file to open, so there's no way to pass any switches to Word or NeoOffice. With OS X, ViewDocument instead sets the temporary report file to read-only, thus forcing the user to use a different name when saving the report. A disadvantage of this approach is that the word processor shows the name of the temporary file in the title bar (for example, rpt1.tmp) rather than Document1 or Untitled1 as it normally does with a new document. ViewDocument also uses this approach with AbiWord, which doesn't appear to support a command line template switch.

To Do

1. Generalize MakeVer so it can use a Delphi .bdsproj file as input and also be able to output version information to a Lazarus .lpi file.

2. Review Free Pascal's rtfdata.inc file for additional bugs.

Other Resources

http://wiki.lazarus.freepascal.org/Multiplatform_Programming_Guide

http://wiki.lazarus.freepascal.org/OS_X_Programming_Tips

http://wiki.lazarus.freepascal.org/Deploying_Your_Application