Overview
Published Properties
AlwaysKeepControls
CheckUserDefined
Database
DFM
DFMBlobFieldName
DFMFieldName
FileName
IsActiveForm
LoadFromDB
LoadFromFile
SaveSingleRecord
SQL
Public Properties and Methods
Create
Destroy
Execute
ExecSQL
Form
RecordCount
SaveToFile
Markosoft
|
|
TADODFMMerger
|
Published Properties
ADOConnectionString
LoadFromADO
OVERVIEW
The ability to allow users to customize forms to suit their needs is a valuable feature for any application and with the TObjectInspector, TDFMMerger,
and TADODFMMerger components you can decide what level of customization you want to allow for your applications.
The TObjectInspector can be made to allow users to do as little as change a few select
control properties or as much as allow users to add entirely new controls to forms.
Because of this flexibility, a way was needed to insure that changes made by
software developers were not always overridden by changes made by end-users.
The primary reason that the TDFMMerger was created was to provide end-users with the power of the TObjectInspector's customization features while keeping the overall control of application development in the hands of the software developers.
If your goal for the TObjectInspector functionality is merely to allow end-users
the ability to alter label captions or hide unused controls, then the TDFMMerger may not seem like a big deal to you. These are relatively benign operations that have very little effect
upon ongoing software development. However, if you want to allow your users to access
some of the other properties and perhaps go so far as to even allow users to add new controls to your form, the TDFMMerger is invaluable.
Consider this scenario. You have written a form that simply has a "Last Name" and a "First Name" edit box. You have also written in some fancy generic code whereby once your users invoke the
TObjectInspector, they are allowed to add new edit box fields of their own choosing (if you are pretty good at writing generic code, these special user controls could be created to "know" how to automatically save their data to a database table or a file). Your user decides to add an "Age" field to the form and then saves the DFM. Now, whenever the form is viewed, it displays the "Last Name" and "First Name" fields as well as the new user-defined "Age" field.
At this point, everything is okay. The problem comes when you decide that you
(as a developer) want to change your form and add a "Phone" field to it. If the TDFMMerger only looked at the saved DFM file when it redrew the form, the new field would not be present because the user-defined settings override the design-time settings. But, thanks to the
TDFMMerger, any new controls that have been added by software developers are automatically "merged" with the corresponding DFM saved by the end-user.
Another consideration for allowing users to add generic "auto-save" controls to your forms is to build controls that contain a
boolean property called UserDefined. If this property is present in your controls (and set to True), the
TDFMMerger can distinguish between controls that have been added by end-users and those added by developers. This knowledge can help to expand the
TDFMMerger's feature set. If you want to use the functionality provided by the UserDefined property, just set the CheckUserDefined property to True. As an aside, it is also possible to use
a control's Tag property to identify user-defined controls (which can easily be achieved by utilizing the
Bitmask Creator utility provided).
Finally, it should be noted that in order for the TDFMMerger to merge a
form with a text DFM, a temporary copy of the form must be created under the hood
and converted to text in order to facilitate the merging of the DFMs for the
final output. This process is completely transparent to the end-user and
has very little (if any) impact on program performance. No actions are
taken on the temporary copy of the form (such as anything
occurring in the form's OnCreate event), but the copy's OnDestroy event could
fire (if set) unless it is explicitly disabled. For this reason, if an
object is explicitly created in the OnCreate event of a form and
then freed in the OnDestroy event of the form, the objects being freed
in the OnDestroy event should be wrapped in a conditional statement as such:
if Assigned(MyObject)then
MyObject.Free;
PUBLISHED PROPERTIES
ADOConnectionString
property
ADOConnectionString : String;
Description
Set ConnectionString to specify the information needed to connect the
ADODFMMerger to the data store.
The value used for ConnectionString consists of one or more arguments ADO uses to establish
the connection. Specify multiple arguments as a list with individual arguments separated
by semi-colons.
ConnectionString := 'Provider=YourProviderName;Remote Server=YourServerName;
AlwaysKeepControls
property
AlwaysKeepControls: Boolean;
Description
Set AlwaysKeepControls to
True to ensure that no controls on the original Form are discarded when the DFM
is merged with the Form. Set AlwaysKeepControls to False to make the Form
assume only the controls found in the DFM property.
CheckUserDefined
property
CheckUserDefined: Boolean;
Description
It may be desirable to
identify the controls that end users have defined within your applications. Set
the CheckUserDefined property to
True to provide for special processing within the DFMMerger when your controls
contain a boolean property called UserDefined. Set
CheckUserDefined to False to make the DFMMerger treat all controls as if they
were created by the end user.
Database
property
Database :TDatabase;
Description
Set Database to specify the name
of the database to associate with the DFMMerger. Database should match the name of a
database component used in the application.
DFMMerger1.Database := DataBase1;
DFM
property
DFM : TStrings;
Description
Load DFM with a Delphi form
DFM that you want to merge with a Form. The DFM property can be loaded manually (hard
coded or via the TStrings editor), from a file, from a database table, or from a database
table using *ADO. (*only with the TADODFMMerger).
DFMBlobFieldName
property
DFMBlobFieldName : String;
Description
Set DFMBlobFieldName to the
fieldname in a database table that the DFM will be loaded from if it is to
be loaded from a Memo or Blob data type field using ODBC. The
DFMBlobFieldName should not be used when using the ADODFMMerger. If LoadFromDB
and LoadFromADO are both False, DFMBlobFieldName is ignored.
DFMFieldName
property
DFMFieldName : String;
Description
Set DFMFieldName to the
fieldname in a database table that the DFM will be loaded from. If
LoadFromDB and LoadFromADO are both False, DFMFieldName is ignored.
FileName
property
FileName: String;
Description
Set FileName to the local filename that the DFM will be
loaded from. If LoadFromFile is False, FileName is ignored.
DFMMerger1.FileName := 'C:\MyDFM.txt'
IsActiveForm
property
IsActiveForm:Boolean;
Description
Set ActiveForm to True if the
Form property is loaded with a TActiveForm rather than a TForm object.
LoadFromADO
property
LoadFromADO: Boolean;
Description
Set LoadFromADO to True if
you will be using an ADO connection to load the DFM from a database table.
LoadFromADO only applies to the TADODFMMerger component.
LoadFromDB
property
LoadFromDB: Boolean;
Description
Set
LoadFromDB to True if you will be using a standard database connection to load
the DFM from a database table.
LoadFromFile
property
LoadFromFile:Boolean;
Description
Set LoadFromFile to True if
you will be using a local file to load the DFM.
SaveSingleRecord
property
SaveSingleRecord:Boolean;
Description
Set SaveSingleRecord to True
to save and load the DFM to and from a single record in a database table.
If the DFMFieldName is set to a Memo Field, it may be possible to save the DFM
into a single record.
Set SaveSingleRecord to False to load and save the DFM to mulitple records in
a database table. When SaveSingleRecord is False, the select statement
found in the SQL property will be looped and the DFM will be built line by line
and record by record until EOF marker is found.
Note:
Some standard database connections will truncate after a set number of
characters, which can cause problems. The ADODFMMerger may be better
suited for saving as a single record because it does not appear to truncate Memo
fields.
SQL
property
SQL: TStrings;
Description
Use SQL to provide the SQL statement that
the DFMMerger component executes when its LoadFromADO, LoadFromDB, and ExecSQL methods
are called. At design time the SQL property can be edited by invoking the String List editor
in the Object Inspector.
PUBLIC PROPERTIES AND METHODS
Execute
function Execute: Boolean;
Description
Execute causes the DFM
found in the DFM property to merge with the Form found in the Form
property. If LoadFromDB or LoadFromADO is set to True, an attempt will be
made to load the DFM from a database using the SQL found in the SQL property and
the fieldname found in the DFMFieldName property. If the LoadFromFile property
is set to True, an attempt will be made to load the DFM from the file specified
in the Filename property. Otherwise, the DFM property is used "as is"
to merge to the Form. Execute returns True when the operation is successful.
ExecSQL
function ExecSQL: Boolean;
Description
Executes an SQL command
such as an INSERT, UPDATE, or DELETE statement.
Form
property Form: TCustomForm
Description
Set Form to the form that
will be merged with the DFM. Upon executing the DFMMerger, the form in the
Form property will take on the additional controls and/or characteristics found
in the DFM property. The Form property must be assigned before the DFMMerger
is executed in order to avoid errors.
RecordCount
propertyRecordCount: Integer;
Description
Use RecordCount to find
the number of records returned from a select statement loaded in the SQL
property.
SaveToFile
function
SaveToFile: Boolean;
Description
Use SaveToFile to save the
DFM to the filename specified be the FileName property.