Copyright: Copyright © 1996, Michael Bate
Citation: This information is Copyright 1996, Michael Bate


AcceptArchivePopup
Select one of these radio buttons to either accept the archive location displayed in the above panel, or browse for a new folder.  If you choose Browse, you will be presented with a folder selection dialog that allows you to select a new folder.


ArchiveNewOldPopup
This line of text tells whether (a) the form will be checked into an existing VCS archive, or (b) a new archive will be created.


ArchivePathPopup
The archives path.  This is a list of folders that may contain archives for the forms in the current working folder.

When searching for an archive, the folders are searched in the order in which they appear in this box.


CancelPopup
Click this button to dismiss the dialog box and cancel what you were doing.


Checking a Delphi Form out of a VCS archive

Select the menu item VCS/Check Out to check a Delphi Form file out of a VCS archive. You will be presented with a dialog box:

If you do not specify a VCS Revision, the tip revision (the newest revision in the archive) will be obtained.

You will be asked if you want to lock the archive for editing.  If you do not, a read-only copy will be extracted.

If there already exists a writeable copy of the Delphi form in the working folder, you will be warned and asked if you want to overwrite it.  A writeable copy is assumed to be one that you may have edited since it was last checked out of the archive.


Checking a Form into a VCS archive

Delphi Form Inspector only allows you to check in forms that you have opened for viewing or editing (See Viewing & Editing).  The VCS/Check In menu item is only available when a form is open.  Select this menu item to check in the currently displayed form.  You will be presented with a dialog:

Delphi Form Inspector will search the current archive path for an archive file whose name corresponds to this form.  If one is found, the full pathname of the file will be displayed in this dialog, and you will be told that it is an existing dialog.  If no archive file is found, the dialog will inform you that a new archive is to be created in the first folder in the archive path.

The three choices at the right of the dialog determine whether or not a copy of the form is placed back in the working folder.  In the first case, a read-only copy is placed in the folder.  You should choose this option if the form is needed for your current project but you do not anticipate immediate changes to the form.  In the second case, a writeable copy is checked out of the archive, and a lock is placed on the archive revision that was just checked in.  In the third case, no copy of the form is checked out.  You must check the form out again before you can use it.

If you want to store the form archive in a different folder than the one selected by Delphi Form Inspector, select Browse for new Archive Folder.  You will be presented with a folder selection dialog:

You may select any folder in this dialog.  The first dialog will be displayed again, indicating a new or existing archive, depending on whether or not an archive for this form is found in the new folder.


Comments
How Delphi Form Inspector handles comments

The Delphi IDE does not allow you to include comments in the TXT files that it produces.  If you do, and you then attempt to store the file in native (.DFM) format, you will get an error.

Delphi Form Inspector allows leading comments - comments that precede the actual form description.  Any text is allowed as long as no line begins with the word "object" (spelled with any combination of upper and lower case letters).

Delphi Form Inspector considers all text preceding the first line that begins with "object" to be user comments.

Since the .DFM file itself cannot contain comments, Form Inspector saves these comments in a file named DFMFILES.INI that it creates in the same folder with the Delphi form files.  This file is maintained in the standard format for a Windows .INI file.  There is a different section for each form file.  The section has the same name as the form file, for example:

[CHILDWIN.DFM]

Following the section, the comment lines are spelled out as:

CM0001=Comment Line 1
CM0002=Comment Line 2

etc.

There is also a section in this file named [ArchivesPath] which specifies the directories or folders where the Version Control System archive files are to be found.  (See Interface to Version Control Systems).

Copying and Moving Form Files with Comments

Because comments are stored in a separate DFMFILES.INI file, they will be lost if you copy or move files to a different foler.  You should copy or move the DFMFILES.INI file along with the form files.  If you are copying or moving to a folder that already contains form files that have been commented using Delphi Form Inspector, you will have to manually edit the DFMFILES.INI file.  A future version of Delphi Form Inspector will address this issue.


Comparing two Delphi Form Files

Menu Item File/Compare presents you with a dialog box:

that allows you to enter the names of two Delphi form files that you want to compare.

If you have configured Delphi Form Inspector to interface with PVCS, you may enter PVCS archive file (formerly called logfile) names and, optionally, a revision number for each.  If you do not specify a revision number, the tip revision (the newest version in the archive) is used.

The result of the comparison is a text report showing the line-by-line differences.  If either of the files being compared is a VCS archive, then the PVCS compare program is used to generate the difference report.  Otherwise, Delphi Form Inspector's built-in comparator is used.  In either case, the report looks like this:

See Navigating a Report for instructions on how you can move around the difference report.


Configuring for VCS

Before you can use the Version Control Interface features of Delphi Form Inspector, you must first do a general configuration.  This configuration tells Form Inspector where to find the VCS executables.

Note that the current version of Delphi Form Inspector only supports PVCS.

The VCS/Configure menu item brings up the configuration dialog:

Delphi Form Inspector interfaces with PVCS by invoking DOS executables (which may be extended mode).  The executable names that you specify should be the same, except for the precise path, as the names given in the above screen image.  That is, Check Out should specify GET.EXE, Check In should specify PUT.EXE, etc.

Each of the five functions (Check Out, Check In, Reporter, Show Differences, and Manage Archives ) requires a separate DOS executable.  To locate the executable or assign a new location, click on the corresponding Find button.  A standard Windows File Open dialog box will appear so that you can navigate to the executable.

Configurating each working folder

For each foler where you want to check forms in or out of VCS, you must specify the archive location.  First you must select the working folder (where forms are stored), either by opening a form in the folder, or by selecting the VCS/Working Folder menu item.  If you select the latter, you will be presented with a dialog box that allows you to navigate to any folder:

You can have any number of folders with forms on your computer, but you can only work with one such folder at a time.  For each folder, there is a path of archive folders that contain VCS archives of the files in the working folder.

Select the VCS/Archives Path menu item:

Usually you should only assign one archive folder, for each working folder.  If you assign more than one, you may assign a search order using the arrow keys.

Once you have set an archive path for a working folder, Delphi Form Inspector will remember it, using a .INI file in the working folder, and all VCS functions are enabled for that working folder.


Contacting the Author

I can be reached via EMail at my account on Compuserve: 72077,1134 (Internet: 72077.1134@compuserve.com).

Comments, suggestions, and problem reports should be sent there.

I normally check my Compuserve account every few days.

- Michael Bate


Contents
Delphi Form Inspector

a utility for viewing, comparing, and archiving Delphi* forms

Copyright © 1996 by Michael Bate

Overview

Borland's Delphi, the most powerful application development environment available for Microsoft Windows, stores its forms in a binary format.  Delphi provides a limited but useful facility for viewing and storing forms in ASCII format.  Delphi Form Inspector provides a far more general facility for manipulating Delphi forms in ASCII.

There are many advantages to viewing a form in ASCII.  You can see the details of the properties and components that make up a form.  You can compare two forms, or - more importantly - two versions of the same form, to see the differences.  Source code version control systems, such as PVCS, work much better with ASCII source files.  This is because they store only one version of a file in its entirety and store the "deltas" necessary to generate the others.  An archive stored this way requires far less disk space.  Also it is simple to obtain reports of differences between different versions.

Introduction	Why you should use the Delphi Form Inspector.

Viewing and Editing	How to view and edit forms in ASCII.

Comparing	How to compare two Delphi Forms (or two different versions of the same form).

Converting	How to convert Delphi forms between ASCII and native format.

VCS interface	The Delphi Form Inspector provides a simple interface with PVCS, the most widely used source program Version Control System.

Comments	How the Delphi Form Inspector handles comments.

Registration	How to register your copy of Delphi Form Inspector.  Advantages of registration.

Legal Stuff	I have to say this and so does every other shareware author.

Contacting the Author	How to leave suggestions, comments, problem reports.

* Delphi is a trademark of Borland, International


Converting Form Files to/from ASCII

The Delphi IDE allows you to convert one form file at a time to text format, but has no provisions for mass conversions.

Delphi Form Inspector allows you to convert any number of files (in a single folder) between the native binary (.DFM) format and ASCII (.TXT).

The File/Convert menu item is only available when you have no files open for viewing or editing.  When you select this item, you are asked which conversion you want to perform:

After you make this selection, you are presented with a standard Windows open file dialog box, which will only allow you to select files with the extension (.DFM or .TXT) that you requested.  You may select any number of files in a single folder for conversion.

Delphi Form Inspector gives the newly converted file the same timestamp as the original file.  If you attempt to overwrite a previously existing file with the same or newer time stamp, you will be warned and asked if you want to proceed:

If you decide not to overwrite the file, Delphi Form Inspector will proceed to convert the remaining files, if any.

When the conversions are complete, Delphi Form Inspector will notify you via a message box such as:

If you have previously added comments to any .DFM being converted, those comments will be included in the output .TXT file.  If you add comments at the beginning of a .TXT file and then convert to .DFM, those comments will be saved and appear when you convert back again.  See How Delphi Form Inspector Handles Comments.


CopyPopup
This button is only enabled when text is selected.  Click on this button to copy selected text to the Windows Clipboard.

WARNING: In Windows 3.1 and 3.11, only 64K of text may be copied to the clipboard.


CurrentDirPopup
VCS Current Working Folder

This is the folder where the version control system expects to find working files.  That is, files that the user views or edits.  When you request a Checkout from a  VCS archive, the file is always placed in this folder.

Note that the term folder replaces the term directory used in earlier versions of DOS and Windows.  folder and directory mean the same thing.


CurrentFolderPopup
The name of the current working folder for which you are setting the archives path


FindNextPopup
This button is only enabled after you have performed a Find.  Click this button to search for the next occurrence of the string you were searching for before.


FindPopup
Click this button to search for text in the report.  The first occurrence after the cursor will be highlighted.

To search from the beginning of the report, first move the cursor to the beginning by pressing Ctrl-Home.


FolderOrderPopup
Clicking one of these buttons changes the search order of the folders in the archives path by moving the currently selected folder up or down.


FormDisposeAfterArchivePopup
Click one of these radio buttons to choose what to do with the form after check-in.  You may either:

Check out a read-only copy,

Check out a copy for further editing.  A lock will be placed on the new archive revision.

Erase the form file and close the window.


HelpPopup
Click this button for context sensitive help.


Interface to Version Control Systems

Delphi Form Inspector provides an interface to Version Control Systems (VCS).  This interface allows you to store Delphi forms in VCS archives as ASCII text.  Storing the forms as ASCII has several advantages:

The VCS archives require less disk space, since only one revision (usually the "tip" or most current revision) is stored in its entirety and other revisions are stored as "deltas" relative to adjacent revisions.

The VCS can report differences between revisions in a meaningful way.

You can insert keywords, that the VCS will expand, as comments at the beginning of the form.  These keywords, when expanded, identify what revision this is, who the author is, the reason for the change since the last revision, the date, etc.

The current version of Delphi Form Inspector supports only PVCS.  Other version control systems will be supported in future releases.

Configuration

Before you can use the VCS interface, you must first configure Delphi Form Inspector to use VCS.  Basic configuration involves telling Form Inspector where to find the VCS executables.

Whenever you use the VCS interface, you must specify the working folder where Delphi forms are stored.  You can do this simply by opening a form in the folder, or by invoking the VCS/Working Folder menu selection.

For each working folder, you must tell Delphi Form Inspector where to find the VCS archive files for that folder.  You do this by invoking the VCS/Archive path menu item.  You only need to do this once for each folder.  Delphi Form Inspector will remember the archive locations that correspond to each folder.

VCS Tasks

Once you have configured for VCS, the following menu options become available:

Check In	Store the currently displayed Delphi form in a VCS archive.

Check Out	Obtain a specified revision of a Delphi form from a VCS archive.

Report	Generate a report describing a VCS archive.

Lock an Archive	Place a lock on a Delphi form archive that you are about to edit.

Unlock an Archive	Rmove a lock from a Delphi form archive.

Compare	The form compare screen can be used to compare archive revisions, or to compare an archive revision with a Delphi form.

Note on Workfile Names

PVCS associates a workfile name with each archive that it creates.  The "workfile" is the editable source file (such as a Delphi form) associated with the archive.  When a form archived using Delphi Form Inspector, the workfile name will be the name of the temporary file created by Form Inspector.  Therefore it will not be a useful file name.


Introduction

Delphi stores its forms in a binary format.

The Delphi IDE provides a limited but useful facility for viewing and storing forms in ASCII format.

Delphi Form Inspector provides a far more general and less restricted facility for manipulating Delphi forms in ASCII.

The Delphi IDE (Integrated Development Environment) allows you to save an individual form in ASCII by using the "Save As" menu item and selecting ".TXT" as the file extent.  You must do this for every file that you want to view this way.  There is no interface with a version control system,, no means for converting more than one form at a time, and no means for comparing two forms.  If you attempt to add comments to a form, the Delphi IDE will reject it.

Delphi Form Inspector provides all this missing functionality.


Legal Stuff

Important

By using this software you accept the following terms of this License Agreement.

Ownership

Michael Bate retains the ownership of this copy of the software package.  It is licensed to you on a non-exclusive basis.

You are encouraged to freely copy and distribute the shareware version of the software.

You May Not

You may not distribute, rent, sub-license or lease the software or documentation, including translating, decompiling, disassembling, or creating derivative works. You may not reverse-engineer any part of this software, or produce any derivative work.

Termination

This license and your right to use this software automatically terminates if you fail to comply with any provision of this license agreement.

Rights

Michael Bate retains all rights not expressly granted.  Nothing in this license agreement constitutes a waiver of Michael Bate's rights under the copyright laws or any other law.

License Agreement

Michael Bate excludes any and all implied warranties, including warranties of merchantability and fitness for a particular purpose and limits your remedy to return the software and documentation for replacement.

Although Michael Bate has tested the software and reviewed the documentation, Michael Bate MAKES NO WARRANTY OF REPRESENTATION, EITHER EXPRESSED OR IMPLIED, WITH RESPECT TO THIS SOFTWARE OR DOCUMENTATION, ITS QUALITY, PERFORMANCE, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE.  AS A RESULT, THIS SOFTWARE AND DOCUMENTATION ARE LICENSED "AS IS" AND YOU, THE LICENSEE, ARE ASSUMING THE ENTIRE RISK AS TO ITS QUALITY AND PERFORMANCE.

IN NO EVENT WILL Michael Bate BE LIABLE FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE OR DOCUMENTATION, even if advised of the possibility of such damages. In particular, Michael Bate shall have no liability for any data stored or processed with this software, including the costs of recovering such data.

THE WARRANTY AND REMEDIES SET FORTH ABOVE ARE EXCLUSIVE AND IN LIEU OF ALL OTHERS, ORAL OR WRITTEN, EXPRESSED OR IMPLIED.  No dealer, agent, or employee is authorized to make any modifications or additions to this warranty.

Information in this document is subject to change without notice and does not represent a commitment on the part of Michael Bate.  The software described in this document is furnished under this license agreement.

 Some countries do not allow the exclusion of implied warranties or liability for incidental or consequential damages, so the above limitation or exclusion may not apply to you.  This warranty gives you specific legal rights, and you may also have other rights which vary from country to country.


Locking and Unlocking Archives

If you have archive-locking enabled on your PVCS installation, you can use Delphi Form Inspector to lock or unlock an archive.

See the PVCS documentation for a full explanation of archive locking and unlocking.

The purpose of locking an archive is to notify other developers that you have checked out a copy of the file for editing and other developers should not be attempting to make simultaneous changes.  If locking is enabled, then you are not allowed to check in a new version of a file unless you have a lock on the archive.

When you lock or unlock an archive from Delphi Form Inspector, a DOS window comes up to show you the result of the operation.  You must close the DOS window before you proceed further.


Navigating a Report

Delphi Form Inspector displays various reports.  This is an example of a VCS Archive Report:

Delphi Form Inspector uses the Orpheus text editor, from TurboPower software, so that it can handle any size report.

There is always a cursor, or caret, in the text window.  You can move this around using the mouse or the arrow keys. You can move through the report using the scroll bar, or the PgUp and PgDown keys.  Ctrl-Home moves you to the beginning of the report.  Ctrl-End moves you to the end.

You can select text using standard Windows techniques (holding the mouse key down and dragging).  The Select All button selects the entire report.  When text is selected, the Copy button is enabled.  When you click the Copy button, selected text is moved to the Windows clipboard.

WARNING: The Windows 3.1 clipboard cannot hold more than 64K of text, and attempts to copy more than that will result in an error.  However, Delphi Form Inspector reports should not be anywhere near that large.

Clicking the Print button will cause the report to be printed.  You will first be presented with a standard Windows Print dialog box, from which you can select print options.

The Find and Find Next buttons may be used to search for text in the report.  A standard Windows Find dialog box is presented.  All searching extends from the current cursor position to the end of the report.  To search the entire report, first move the cursor to the beginning of the report (by pressing Ctrl-Home).

You can set up to 10 markers in the text, at the current cursor position, by pressing Ctrl-Shift-0:9.  A visible marker will be displayed.  You can return the cursor to a marked position by pressing Ctrl0:9.


NewFolderPopup
Click this button to add a new folder to the archives path.  You will be presented with a folder selection dialog box.  The new folder will be added at the end of the path, but you can change the path order by clicking the arrow buttons.


OkPopup
Click this button to accept the information in the dialog box and proceed.


PrintPopup
Click this button to print the report.  A standard Windows Printer dialog will be presented, allowing you to select printer options.


Registration

Delphi Form Inspector is shareware.  The unregistered version may be run for 30 days, after which it will cease to function.

Registration is $15.00 per user.  For this fee, you may run your personal copy of Delphi Form Inspector on any number of computers, provided there is no reasonable possibility that it will be run on more than one computer at the same time.

When you register, you will receive a registration code that is keyed to your name.  When you enter this code into the registration dialog box, your copy of Delphi Form Inspector will become registered.

Registered users are entitled to free technical support, via EMail, or regular mail.

The simplest way to register is via the SWREG shareware registration forum on Compuserve (GO SWREG, Registration ID is 11416).

You may also register by mail.  Send a check  for $15.00 in US funds to:

Michael Bate
89 Massachusetts Ave.
Suite 176
Boston, MA 02115

Be sure to specify the name under which you would like to register the program.  If possible, specify an EMail address to which I can send your registration code.


RemoveFolderPopup
Click this button to remove the currently selected folder (in the archives path box) from the archives path.


ReportDonePopup
Click this button when you are done viewing the report.


ReportTextPopup
This is the text of the report.  Use the scroll bars, or the PgUp and PgDown keys to move through the text.  Ctrl-Home will take you to the start of the text.  Ctrl-End will take you to the end.


Reporting on a VCS archive

This is only available if you have configured Delphi Form Inspector for VCS.

Menu item VCS/View Log presents you with a standard Windows open-file dialog box, from which you may select a PVCS archive file (formerly called a logfile).  A standard archive report (produced by the PVCS program VLOG) is then displayed:

This is shown as a modal dialog box, which means that you must dismiss the report (by clicking Cancel) before you do anything more in Delphi Form Inspector.

See Navigating a Report for instructions on what you can do in this dialog box.


SelectAllPopup
Click this button to select the entire report text.


This Archive Location
The full path name of the archive file where this form will be stored.  This may be either a new or existing archive.


Using the Built-in Editor

Delphi Form Inspector uses the Orpheus text editor, from TurboPower software, so that it can handle very large forms..

There is always a cursor, or caret, in the text window.  You can move this around using the mouse or the arrow keys. You can move through the report using the scroll bar, or the PgUp and PgDown keys.  Ctrl-Home moves you to the beginning of the report.  Ctrl-End moves you to the end.

Ctrl-Left Arrow and Ctrl-Right Arrow move you forward or back one word at a time.

Insert text at the cursor position by typing, just as with any Windows editor.

The Backspace and Del keys work as with any Windows editor.

You can select text using standard Windows techniques (holding the mouse key down and dragging).

The Edit/Copy and Edit/Cut menu items are only enabled when text is selected.  They copy or cut the selected text to the Windows clipboard.  The Edit/Delete menu item simply deletes the selected text.  The Edit/Paste menu item is only enabled when the Windows clipboard contains text.  Selecting it causes the clipboard contents to be inserted at the current cursor position.

WARNING: The Windows 3.1 clipboard cannot hold more than 64K of text, and attempts to copy more than that will result in an error.  However, Delphi Form Inspector reports should not be anywhere near that large.

The File/Print menu item can be used to print the form in ASCII.  You will first be presented with a standard Windows Print dialog box, from which you can select print options.

The Edit/Find and Edit/Find Next menu items may be used to search for text in the report.  A standard Windows Find dialog box is presented.  All searching extends from the current cursor position to the end of the report.  To search the entire report, first move the cursor to the beginning of the report (by pressing Ctrl-Home).

The Edit/Replace menu item may be used to replace occurrences of a specified string with a new string.  The search for the requested string starts at the current cursor position.

You can set up to 10 markers in the text, at the current cursor position, by pressing Ctrl-Shift-0:9.  A visible marker will be displayed.  You can return the cursor to a marked position by pressing Ctrl0:9.

The Edit/Undo and Edit/Redo menu items may be used to undo change you have made to the form, and then to redo what you have undone.

If the form is read-only, none of the commands which change the text are enabled.


VCS Error Messages

These messages are displayed in a "report" format.  See Navigating a Report for instructions on  how to move around this screen.

A common cause of otherwise unintelligible errors is incorrect setup.  Ensure that you are invoking the correct VCS executable for the function that you are attempting to perform See Configuring for VCS for detailed instructions.

You are responsible for handling and enabling locking and unlocking of VCS archives.  Enabling is performed by VCS tools that are not part of Delphi Form Inspector.  If archive locking is enabled and you do not have a lock for an archive for which you are attempting to check in a new version, you will get an error message.

Anothe source of errors is an attempt to refer to a VCS revision that does not exist.


Viewing and Editing

To view or edit a Delphi Form, choose File/Open from the menu, or click on the open folder icon.  You will be presented with a standard Windows open-file dialog box.  When you select a file, a window will be opened showing the file in ASCII text format.

You may only open Delphi forms with a .DFM extension.

If you check the Read-Only check box, OR if the file that you open has the read-only attribute set, then the caption for the window will indicate that the file is read only and you will not be able to make changes.

When you open a new Delphi form, the VCS current working foler is set to the folder containing the file you just opened.

Delphi Form Inspector is a Multiple-Document-Interface (MDI) Windows program, and allows you to open and view any number of Delphi forms at one time.  However, they must all be in the same folder.  To open a file in another folder, you must first close all the files in the current folder.

If the file is not read only, you may edit it freely, using standard text editing commands.  Delphi Form Inspector uses the Orpheus text editor, from TuroboPower software.  This editor is easy to use and can handle an very large block of text.

Insert new text at the current cursor position

Select blocks of text.

Delete text.  If text is selected, pressing Del deletes the block of selected text.  Otherwise a single character at the current cursor position is deleted.

Cut, copy, and paste text to and from the Windows clipboard.

Search for a string of text.

Replace any or all occurrences of a specified string of text with new text.

Undo changes you have made to the form, and redo changes that you have undone.

See Using the built-in editor for specific keystroke instructions.

Comments

You may add comments before the beginning of the form description.  You may not add comments at any other place.  The comments may be free form, but they must not begin with the word "object" at the start of any line.  This is because Delphi Form Inspector looks for this word to determine the beginning of the actual form description (and the end of your comments).  Note that this restriction applies to the word "object" spelled with any combination of upper and lower case letters.

This ability to add leading comments is especially useful if you are using a version control system.  These systems allow you to specify "keywords," such as $Revision$ (to cite an example from PVCS) which the version control system expands with information about the current revision - information such as revision number, date, author, etc.  See Interface to Version Control Systems for more information.

If you want to copy or move the form files to a different folder, you should be sure to also copy the DFMVIEW.INI file that Delphi Form Inspector places in the folder with your form files.  See How Delphi Form Inspector Handles Comments.

Saving your changes - a warning

You may save a file that you have edited as either a text file (.TXT) or a Delphi form (.DFM).

When you save as a form, possibly overwriting an existing form by the same name, Delphi Form Inspector performs simple checks on the validity of your new form.  These tests are not exhaustive, and it is possible that you may corrupt an already existing form.  For this reason, you should back up your work before overwriting a form.

Note that this warning also applies if you edit forms in ASCII using the Delphi IDE.


current archive path
The set of folders that you have defined that will contain archives for forms found in the current folder.  Typically this path will contain only one folder.  See Configuring for VCS.