Status of ExtP Toolkit


Contents

Introduction
Requirements
Installation
Examples
Brief Overview
Brief Tutorial: A Simple Web App
Lazarus Tips
ExtPascal Equivalents to VCL/LCL Controls
Design Controls vs. Runtime Controls
Design Properties vs. Runtime Properties
File Types Used in a Lazarus ExtPascal App


Introduction

These notes describe the status of the ExtP Toolkit, a set of tools to assist in developing GUI Web apps with the open-source ExtPascal wrapper for the Ext JS JavaScript widgets (code.google.com/p/extpascal).

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.
For a list of versions and changes, refer to the changelog.txt file included with the toolkit source.

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:

    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.


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 one of these examples in Lazarus, choose File | Open and select the appropriate .lpi file, then choose Run | Build to compile it. You can also compile using a batch or script file similar to fpc-compile.bat or fpc-compile.sh in the hello_example subfolder.

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.


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:

  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

Note: This tutorial assumes you know how to create an app with Lazarus or Delphi. If you get stuck, please consult the source files for the tutorial project in the hello_example subfolder. If you haven't installed the ExtPascal design controls package and project wizard package in Lazarus, you can still compile the app using one of the .bat/.sh files in the hello_example subfolder (and to run your compiled app, see steps 1 and 6 below).

  1. Prepare your Web server

  2. Create a new project and the first form

  3. Add a second form

  4. Save and name the project's files

  5. Compile and run the app

  6. Summary and deploying the app


Lazarus Tips

  1. To make the Lazarus form designer work more like Delphi, choose Environment | Options and change the following:

  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:

ExtPascal Equivalents to VCL/LCL Controls

Note that in some cases, converter support for a VCL/LCL control is still rudimentary and has not been thoroughly tested.

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

In most cases, the name of the design control will be the same as the runtime control.

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

Because the design controls are descended from the VCL/LCL TControl, all properties that are published by TControl automatically appear in the Object Inspector. Since published properties cannot be renamed or "unpublished", some of these properties are renamed or ignored completely when the forms are converted to ExtPascal code, as follows:

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

File type Example Notes
.lpi project1.lpi Project information file; XML format.
.lpr project1.lpr Program source code file; like Delphi .dpr.
.pas unit1.pas
appthread.pas
Pascal unit source code file. Each form is in a separate unit.
App's thread unit created by converter.
.lfm unit1.lfm Form design file; like Delphi .dfm.
.lrs unit1.lrs Resource file created automatically by Lazarus from .lfm; not used in an ExtPascal app.
.inc unit1.inc Source code include file created by converter from .lfm file; creates form's ExtPascal objects; you can think of this as being like a Delphi .dfm or Lazarus .lrs at runtime.
.cfg extpascal.cfg Free Pascal configuration file created by converter; extpascal.cfg defines UseRuntime when project is compiled.

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.


Last updated: April 18, 2010