Status of ExtP Toolkit

Contents

Introduction

The ExtP Toolkit provides four things:

1. FmToExtP command-line converter converts Delphi or Lazarus forms (.dfm/.lfm) to ExtPascal code. This is a simple way to preserve some of the forms' visual layout in a Web app. The converter can be run standalone to convert existing Delphi and Lazarus forms, or automatically from the Lazarus IDE when compiling an ExtPascal application. An easy-to-use GUI frontend for the converter is also included.

2. ExtP_Ctrls package of ExtPascal design controls for Delphi and Lazarus. This package adds an ExtPascal tab of basic controls to the IDE's component palette.

3. ExtP_Proj package that adds "ExtPascal Application" and "ExtPascal Form" to the Lazarus File | New list. Selecting ExtPascal Application creates a new ExtPascal project that can be used with the design controls.

4. Optional ExtP_Grid package of ExtPascal grid controls for Delphi and Lazarus.

You can contact the author at:  MacPgmr (at) fastermac (dot) net

Author:  Phil Hess.
Copyright:  Copyright (C) 2009-2010 Phil Hess. All rights reserved.
License:  All source code developed for the ExtP Toolkit is released under a modified LGPL license. See files COPYING.LGPL and COPYING.modifiedLGPL.

Requirements

1. ExtPascal source

   This source is generated by the ExtToPascal.dpr app included with ExtPascal. See the ExtPascal site for more information:

   code.google.com/p/extpascal

   The ExtP Toolkit was tested with ExtPascal 0.9.8 and Ext JS 3.2.0.

2. Pascal compiler

   You will need one of these compilers:

   • Delphi 7 or later (for Windows)

     www.codegear.com/products/delphi/win32

   • Free Pascal and Lazarus (for Windows, OS X or Linux)

     www.lazarus.freepascal.org

   The ExtP Toolkit was tested with Delphi 7 and Delphi 2006 on Windows and Free Pascal 2.4.0 and Lazarus 0.9.28 on Windows and OS X.

3. Web server

   You don't need a Web server to design and compile an ExtPascal app, but you will need a Web server to run the app. You can use a local Web server.

   • Windows. IIS is included on the Windows XP Pro installation CD. Apache can also be used with Windows, as follows:
     • Download the Apache 2.2 .msi file and install.
     • Initially don't make any changes to the httpd.conf file that the .msi installer creates in Apache's conf folder.
     • If you chose not to install Apache as a service, you can start it manually from the console by changing to the Apache bin folder and entering httpd. You will probably need to specify localhost:8080 to run your local apps if port 80 is not the default (see the httpd.conf file).

   • OS X. Apache 2 is included with Leopard (10.5). Apache 1.3 is included with Tiger (10.4). To start Apache, open System Preferences, click Sharing, then check Personal Web Sharing.

   • Linux. Apache may already be installed on your system.

Installation

Converter

1. Unzip the Toolkit source files in your ExtPascal folder, preserving the zipped subfolders. This will create several subfolders such as fmtoextp, extp_ctrls and extp_proj in your ExtPascal folder and allows Lazarus to set paths to them automatically (see discussion of paths below).

2. Open a terminal window and change to the fmtoextp folder, then compile the FmToExtP converter.

   With Delphi:  dcc32 fmtoextp.dpr

   With Free Pascal:  fpc fmtoextp.dpr

   Tip: You can also compile from the IDE. With Delphi, open file fmtoextp.dpr; with Lazarus, open file fmtoextp.lpi.

3. The compiled converter (fmtoextp.exe on Windows or fmtoextp on OS X and Linux) can then be placed along with its fmtoextp.ini configuration file anywhere you want. However, if you leave them in the fmtoextp folder, Lazarus can set the path to the converter automatically.

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

   With Windows:  fmtoextp

   With OS X and Linux:  ./fmtoextp

5. To compile the GUI converter, open FormsToExtPascal.dpr or FormsToExtPascal.lpi in the gui_converter folder in Delphi or Lazarus.

ExtPascal Basic Design Controls (Delphi)

1. Open file extp_ctrls.dpk in Delphi and compile it, then close the package.

2. Choose Components | Install Packages, then click Add in the dialog and navigate to where Delphi created the compiled .bpl file. For example, with Delphi 7, this is its Projects\Bpl folder. With Delphi 2006, this is its Borland Studio Projects\Bpl folder under My Documents.

ExtPascal Basic Design Controls (Lazarus)

1. Skip this step with Lazarus 0.9.28 or later. In order to use TCustomForm as the ancestor for the TExtWindow design control, you need to make a small change to the Lazarus IDE code. In file customformeditor.pp in the Lazarus ide folder, find this line in TCustomFormEditor.DeleteComponent:

     if (AForm<>nil) and (not (AForm is TCustomNonFormDesignerForm)) then
   

   Change the line to this by inserting the code that's in bold:

     if (AForm<>nil) and (not (AForm is TCustomNonFormDesignerForm)) and (not (AForm is TCustomForm)) then
   

   Then save the file. The IDE will be recompiled in the next step.

2. Choose Package | Open package file and select extp_ctrls.lpk.

3. Click Compile in the Package dialog.

4. Click Install in the Package dialog to rebuild Lazarus. Restart Lazarus if it doesn't restart on its own after rebuilding.

ExtPascal Project "Wizard" (Lazarus only)

1. Repeat the previous steps 2-4 for the extp_proj.lpk package.

ExtPascal Grid Design Controls (optional)

1. These grid design controls require that the Orpheus package be installed first.

   Delphi Orpheus package: sourceforge.net/projects/tporpheus

   Lazarus Orpheus package: wiki.lazarus.freepascal.org/OrphPort

2. Once you've installed Orpheus, you can install the extp_grid.dpk (Delphi) or extp_grid.lpk (Lazarus) package as described above for the basic design control package.

3. Note that if you don't install the grid package, you can still create ExtPascal grids in code (that is, not visually). Also, no Orpheus code is compiled in at runtime - Orpheus is used only for designing grids visually in the IDE.

Examples

To compile an example in Delphi, use a batch file similar to delphi-compile.bat in the hello_example subfolder.

To run one of these examples, first review the tutorial below.

• hello_example project - this simple Web app is covered in the tutorial below.

• multiselect_example project - this simple Web app shows how to use the TExtUxFormMultiSelect control (list box).

• grid_example project - this simple Web app shows how to program a TExtGridEditorGridPanel.

• fishfacts_example project - this is a Web version of the Delphi FishFact demo app.

Brief Overview

1. You can use FmToExtP to convert either standard VCL/LCL controls or ExtPascal design controls.

2. To use the design controls in either Delphi or Lazarus, just create a normal application and drop controls from the ExtPascal tab on the form. This assumes that you will then convert the app's forms using FmToExtP external to the IDE, perhaps from the command line or the IDE's Tools menu, then compile the ExtPascal source files that the converter creates. With this approach, you will have both a design project and a runtime project.

3. With Lazarus you can also automatically convert and compile from within the IDE using a single project, as follows:
   • Choose File | New and select ExtPascal Application.

   • A message box will be displayed to remind you to check the path to the ExtPascal units and the path to the FmToExtP converter. If you unzipped the Toolkit files in your ExtPascal directory and preserved the Toolkit's directory structure, these should already be set for you based on paths relative to the ExtP_Ctrls package. Use Project | Compiler Options to see the paths.

     If you need to change the paths and ExtPascal or FmToExtp is somewhere under your "home" folder, you can use the $(Home) macro in your paths to avoid hardwiring the actual user folder name. Lazarus does not appear to be able to expand the "~" home shortcut (OS X and Linux).

     If you get a warning about a non-existent "nogui" directory when you close the Compiler Options dialog, this is because the Lazarus "nogui" widgetset has not been compiled yet. You can click Ignore. If you want to eliminate this warning, just rebuild the LCL with the NoGUI widgetset (Tools | Configure).

     Note that the ExtPascal app is set by default to compile with the "nogui" widgetset in order to eliminate most of the LCL and native widgetset code from the compiled app.

   • Instead of starting with a normal TForm, an ExtPascal app starts with a TExtWindow. However, you can think of this as a "form" when designing. To create additional TExtWindow units, choose File | New and select ExtPascal Form.

   • The ExtPascal project employs a trick that allows Lazarus to handle both the design control classes and the actual ExtPascal runtime classes in the same project. This involves a couple of conditionals that it adds to each unit. The converter then creates a little Free Pascal configuration file (extpascal.cfg) that defines UseRuntime. The Lazarus IDE never "sees" this define and so uses the ExtP_Design_Ctrls unit while you're working in the IDE. However, when you compile the app, Free Pascal does see the define and uses the ExtPascal runtime units instead of the ExtP_Design_Ctrls unit.

   • Before compiling, you need to save and name your project files so that the converter knows what files to convert. If you try to compile a project whose files have not been named yet, the converter should catch this and Lazarus will display the converter's error message.

   • The first time you compile your app, the converter will create these files for your project:
     • appthread.pas
     • extpascal.cfg
     • .inc file for each form unit

     The appthread.pas file creates the app's main thread and contains the thread's "global" form objects. The .inc file contains the code that actually creates the ExtPascal user interface objects. On subsequent compiles, the converter will update the appthread.pas file if any form file (.lfm) has been modified since the last compile. It will also create a new .inc file for any modified form file. Naturally, this means you should never make any edits to the .inc files. If you need to customize the ExtPascal controls at runtime, add your code at the bottom of the form unit's Create constructor.

   • For more information about why the ExtPascal project's settings are set the way they are, refer to the comments in file ExtP_Proj_Intf.pas.

4. When designed properly, an ExtPascal app will have no dependencies on the VCL/LCL, the ExtP_Ctrls package of design controls, or the converter itself and can be compiled by either Delphi or Free Pascal (see the .bat/.sh files in the hello_example subfolder for command-line examples). Be sure you don't accidentally try to use VCL/LCL controls in your app or include VCL/LCL units like Forms, etc. These don't make sense at runtime and will only increase the size of your app's executable file. However, you can use most of the non-GUI units like SysUtils, StrUtils, Classes, Math, etc.

Brief Tutorial: A Simple Web App

1. Prepare your Web server
   • Make sure you've unzipped the Ext JS files and placed them where your Web server can find them. For example, with OS X this would be a folder named ext under /Library/WebServer/Documents. With Apache on Windows and Linux, this folder should be under Apache's htdocs.

   • If you're using CGIGateway.dpr (see the ExtPascal site for more information), make sure you've compiled this program, renamed the executable file with a .cgi extension, and copied the executable file to where your Web server can find it. For example, with OS X this would be into the /Library/WebServer/CGI-Executables folder. With Apache on Windows and Linux, copy the executable into Apache's cgi-bin folder.

2. Create a new project and the first form
   • Start Lazarus and choose File | New, then select ExtPascal Application from the list. This will create a new project and a new form for the project.

   • Select the form and change these properties:
     • Change Name to MainWindow.
     • Change Title to Hello.

   • Select the ExtPascal tab on the component palette and click TExtButton, then draw a button on the form.

   • Change the button's Text property to Click Me.

   • Add an event handler for the button's Click event.

   • In the TMainWindow.ExtButton1Click handler that Lazarus creates, type this code that will display the form that we'll create in the next section:

       with CurrentThread do
         begin
         AboutWindow.Free;
         AboutWindow := TAboutWindow.Create;
         AboutWindow.Show;
         end;
     

     Note that form objects are not global the way they are in VCL/LCL apps. Instead, they're declared in your app's thread class, which you can access via CurrentThread.

     Also note that Show is not the same as the VCL/LCL ShowModal, which waits for the form to be closed. Show returns immediately, so you can't call a modal form's Free after Show. Instead, to start with a new instance of the form each time you need to display it, call Free before creating it.

   • Even though we haven't created the next form yet, add its unit to the implementation uses clause in anticipation. It should look like this:

       uses
         AppThread, aboutunit;
     

3. Add a second form
   • Choose File | New, then select ExtPascal Form from the list. This will add another form to the project.

   • Select the form and change these properties:
     • Change Modal to True.
     • Change Name to AboutWindow.
     • Change Title to About.

   • Add a button from the ExtPascal tab to the form.

   • Change the button's Text property to Close.

   • Add an event handler for the button's Click event.

   • In the TAboutWindow.ExtButton1Click handler that Lazarus creates, type this code:

       Close;
     

4. Save and name the project's files
   • Choose File | Save All, then save the project's files in their own folder, using these names:
     • Save the first form unit as mainunit.pas.
     • Save the second form unit as aboutunit.pas.
     • Save the project as myproject1.lpi.

   • Now that you've named the unit files, change the {$I} include statements in the Create constructors to reflect the new names (only needed if you're not using FPC 2.4.0 or later):
     • In mainunit.pas, change it to {$I mainunit.inc}
     • In aboutunit.pas, change it to {$I aboutunit.inc}

     Note that this step is necessary because Free Pascal 2.2.x does not support the {$I *.inc} syntax that Delphi and FPC 2.4 do. But it's a one-time change that doesn't need to be made again unless you rename a form unit.

   • Choose Project | View Source to see the project's program file and make sure the port is set to what your CGIGateway.dpr port is expecting (unless you edited CGIGateway.dpr, this will be 2014).

5. Compile and run the app
   • Choose Run | Build to compile the project. Correct any mistakes that Lazarus or the Free Pascal compiler find.

   • Once you've compiled the project successfully, choose Run | Run. After a bit you'll see that the app is running in the debugger by the display of "(debugging...)" in the Lazarus title bar. You've now started your Web app's server side app.

   • Now switch to your browser and enter this into the URL box:

       http://localhost/cgi-bin/cgigateway.cgi
     

     This starts your Web app's browser side client app, which executes the JavaScript code that your Lazarus server app sends it.

   • Once the page has loaded you should see your main form's window. Click the Click Me button, which will display the About window. Click the Close button or press the Esc key to close the About window.

   • To stop the server app, switch back to Lazarus and choose Run | Stop.

6. Summary and deploying the app
   • Think about what you've just done: Through the power of Ext JS, ExtPascal, Lazarus, Free Pascal and your Web server, you've visually created a Web app completely in Pascal with very little programming effort.

   • To deploy and run your server app outside of Lazarus, rename the compiled myproject1 executable file (for example, to cgigateway.fcgi or cgigateway.exe) and copy it to where your Web server can find it. Now shut down Lazarus and reload your app's browser page. You can also name the .cgi and .fcgi/.exe files to something more meaningful.

   • To shut down an app that is not running in the IDE, use Task Manager (Windows) or Activity Monitor (OS X).

   • You can also compile the app with an embedded Web server that can be run "standalone" without the need for Apache or IIS. Choose Project | Compiler Options and enter the path to the Indy source files in Other Units Files and enter -dWebServer on the Other tab in Custom options, then choose Run | Build. Now start the app from the command line and enter http://localhost/Home in your browser. For more information, see the ExtPascal Web site.

Lazarus Tips

1. To make the Lazarus form designer work more like Delphi, choose Environment | Options and change the following:
   • Environment | Form Editor: Uncheck "Show component captions".
   • Codetols | Class Completion: Select "Last" (two places) and uncheck "Header comment for class".

2. With a "runtime" project that you've created using the FmToExtP converter from a normal Delphi or Lazarus project, you can create a Lazarus project file for it as follows:
   • Open the newly-created .dpr or .lpr file in Lazarus.
   • Select ExtPascal Application from the list when prompted.
   • Choose Project | Compiler Options and blank out the "Execute before" Command on the Compilation tab.
   • You can also choose Project | Project Inspector and remove ExtP_Ctrls from Required Packages.

ExtPascal Equivalents to VCL/LCL Controls

VCL/LCL control	ExtPascal equivalent	FmToExtP converter supports?	ExtPascal design control?	Notes
TBevel	?
TBitBtn	TExtButton	Yes	Yes
TButton	TExtButton	Yes	Yes
TChart	TExtExtChart?
TCheckBox	TExtFormCheckbox	Yes	Yes
TCheckListBox	?
TColorBox	TExtColorPalette	Yes
TComboBox	TExtFormComboBox	Yes	Yes
TDateTimePicker	TExtDatePicker	Yes
TDBGrid	TExtGridEditorGridPanel	Yes
TEdit	TExtFormTextField	Yes	Yes	TExtFormNumberField, TExtFormDateField, TExtFormTimeField design controls are also included.
TForm	TExtWindow	Yes	Yes
TGroupBox	TExtPanel	Yes	Yes
TImage	TExtFormLabel	Yes	Yes	Set Html property to load image (<img src=... />) and leave Text property blank.
TImageList	?
TLabel	TExtFormLabel	Yes	Yes
TLabeledEdit	TExtFormTextField	Yes	Yes
TListBox	TExtUxFormMultiSelect	Yes	Yes	Works best if on a container that converts to TExtPanel.
TListView	?
TMainMenu	TExtMenuMenu
TMaskEdit	TExtFormTextField	Yes	Yes
TMemo	TExtFormTextArea	Yes	Yes
TMenuItem	TExtMenuItem
TMonthCalendar	TExtDatePicker	Yes
TPageControl	TExtTabPanel	Yes	Yes
TPaintBox	?
TPanel	TExtPanel	Yes	Yes
TPopuMenu	?
TProgressBar	TExtProgressBar	Yes
TRadioButton	TExtFormRadio	Yes
TRadioGroup	TExtFormRadioGroup	Yes	Yes
TRichEdit	TExtFormHtmlEditor	Yes	Yes
TScrollBar	TExtSlider	Yes
TShape	?
TSpeedButton	TExtButton	Yes	Yes
TSplitter	TExtSplitBar
TStaticText	TExtFormLabel	Yes
TStringGrid	TExtGridEditorGridPanel	Yes
TTabSheet	TExtPanel	Yes	Yes	TExtPanel_Tab design control converts to TExtPanel.
TTimer	?
TToolbar	TExtToolbar	Yes
TTrackBar	?
TTreeView	TExtTreeTreePanel	Yes
TUpDown	?
TOvcTable	TExtGridEditorGridPanel	Yes	Yes	Orpheus table column design controls (see below) convert to TExtFormTextField, TExtFormNumberField, TExtFormDateField, TExtFormTimeField, TExtFormCheckboxField and TExtFormComboBoxField in-cell editors.
TOvcTCBitMap	TExtFormDisplayField?	Yes	Yes?
TOvcTCCheckBox	TExtFormCheckbox	Yes	Yes
TOvcTCColHead		Yes	Yes	Converts to Header property for each table column.
TOvcTCComboBox	TExtFormComboBox	Yes	Yes
TOvcTCGlyph	TExtFormDisplayField?	Yes	Yes?
TOvcTCIcon	TExtFormDisplayField?	Yes	Yes?
TOvcTCMemo	TExtFormTextField	Yes	Yes
TOvcTCRowHead	TExtFormTextField	Yes	Yes
TOvcTCSimpleField	TExtFormTextField	Yes	Yes
TOvcTCString	TExtFormTextField	Yes	Yes
TO32TCFlexEdit	TExtFormTextField	Yes	Yes
TOvcLabel	TExtFormLabel	Yes	Yes
TOvcURL	TExtFormLabel	Yes	Yes
TOvcVirtualListBox	TExtUxFormMultiSelect	Yes	Yes	Works best if on a container that converts to TExtPanel.
TOvcSimpleField	TExtFormTextField	Yes	Yes
TO32FlexEdit	TExtFormTextField	Yes	Yes

Design Controls vs. Runtime Controls

IDE design control	VCL ancestor	LCL ancestor	ExtPascal runtime control	Notes
TExtWindow	TCustomForm	TCustomForm	TExtWindow
TExtButton	TButtonControl	TCustomButton	TExtButton	Not quite right yet in Delphi IDE.
TExtFormLabel	TCustomLabel	TCustomLabel	TExtFormLabel
TExtPanel	TCustomGroupBox	TCustomGroupBox	TExtPanel
TExtFormTextField	TCustomEdit	TCustomEdit	TExtFormTextField
TExtFormNumberField	TCustomEdit	TCustomEdit	TExtFormNumberField
TExtFormDateField	TCustomEdit	TCustomEdit	TExtFormDateField
TExtFormTimeField	TCustomEdit	TCustomEdit	TExtFormTimeField
TExtFormTextArea	TCustomMemo	TCustomMemo	TExtFormTextArea
TExtFormHtmlEditor	TCustomMemo	TCustomMemo	TExtFormHtmlEditor
TExtFormCheckbox	TCustomCheckBox	TCustomCheckBox	TExtFormCheckBox
TExtFormComboBox	TCustomComboBox	TCustomComboBox	TExtFormComboBox
TExtFormRadioGroup	TCustomRadioGroup	TCustomRadioGroup	TExtFormRadioGroup
TExtUxFormMultiSelect	TCustomListBox	TCustomListBox	TExtUxFormMultiSelect	Works best if on a TExtPanel.
TExtTabPanel	TPageControl	TCustomNotebook	TExtTabPanel	Not right yet in Delphi IDE.
TExtPanel_Tab	TTabSheet	TCustomPage	TExtPanel	No special TTabSheet-like control, so defined one; converts to TExtPanel; not right yet in Delphi IDE.
TExtGridEditorGridPanel	TOvcCustomTable	TOvcCustomTable	TExtGridEditorGridPanel	Orpheus table used as basis for grid design control.
TExtFormTextField_Grid	TOvcTCCustomString	TOvcTCCustomString	TExtFormTextField	TExtFormTextField used for in-cell editor.
TExtFormNumberField_Grid	TOvcTCCustomString	TOvcTCCustomString	TExtFormNumberField	TExtFormNumberField used for in-cell editor.
TExtFormDateField_Grid	TOvcTCCustomString	TOvcTCCustomString	TExtFormDateField	TExtFormDateField used for in-cell editor.
TExtFormTimeField_Grid	TOvcTCCustomString	TOvcTCCustomString	TExtFormTimeField	TExtFormTimeField used for in-cell editor.
TExtFormCheckbox_Grid	TOvcTCCustomCheckBox	TOvcTCCustomCheckBox	TExtFormCheckbox	TExtFormCheckbox used for in-cell editor.
TExtFormComboBox_Grid	TOvcTCCustomComboBox	TOvcTCCustomComboBox	TExtFormComboBox	TExtFormComboBox used for in-cell editor.

Design Properties vs. Runtime Properties

Design property	Runtime property	Notes
Cursor		No ExtPascal equivalent.
HelpContext		No ExtPascal equivalent.
HelpKeyword		No ExtPascal equivalent.
HelpType		No ExtPascal equivalent.
Hint	Tooltip	Not yet fully supported by converter.
Left	X	Note that Left is less ambiguous than X.
Name	Id
Tag		No ExtPascal equivalent.
Top	Y	Note that Top is less ambiguous than Y.

File Types Used in a Lazarus ExtPascal App

Lazarus and Free Pascal create several other files each time you compile your project. Files in your project folder with an .o, .ppu, .bak or .compiled extension don't need to be backed up and can be deleted.

Although required for compiling your project, the .inc and extpascal.cfg files will automatically be created again by the converter the next time you compile if you accidentally delete them.