Readme file for the Component TDataConnection
=============================================

Component version   1.0 - 27 April 1997
Readme file version 1.0 - 27 April 1997

(c) 1997 by Wolfgang Junker


Compuserve: 100734,275
Internet: 100734.275@compuserve.com  or  junker@hannover.sgh-net.de 
Snail mail: W. Junker, Brelinger Hof 19, 30625 Hannover, Germany, Earth


Contents
========

1.	Description
2.	Reference
2.1	Event types
2.2	Properties
2.3	Methods
3.	Installation
4.	Legal Stuff



1. Description
==============

TDataConnection is a non-visible component that can be dropped on any
form.

It is connected to a TDataSource and informs the form about changes in
the DataSource's DataSet. In this way, non DB-aware objects on the
form (like status bars, menues, edit controls) can react on dataset
modifications without the need for design flaws like DataModules having
to know about edit forms.

In addition, this component allows record based write permission
additional to table or field based privileges as supplied by the BDE. 


2. Reference
============

TDataConnection inherits from TComponent and adds the following methods
and properties:

procedure CheckReadOnly;
property DataSet: TDataSet;		// RunTime and ReadOnly
property Editing: Boolean;		// RunTime and ReadOnly
property ReadOnly: Boolean;		// RunTime and ReadOnly
property State: TDataSetState;		// RunTime and ReadOnly

property DataSource: TDataSource;
property OnEditingChange: TNotifyEvent;
property OnDataChange: TDataChangeEvent;
property OnReadOnlyChange: TNotifyEvent;
property OnCheckReadOnly: TCheckReadOnlyEvent;


2.1 Event types
---------------

TNotifyEvent is the well known OnAlmostEverything type:
procedure(Sender: TObject) of object;

TDataChangeEvent is also well known, the same as
TDataSource.OnDataChange: (procedure(Sender: TObject; Field: TField) of
object;

TCheckReadOnlyEvent is new. It is defined as:
procedure(Sender: TObject; var Value: Boolean) of object;


2.2 Properties
--------------

DataSet: TDataSet;		// RunTime and ReadOnly

For convenience. Basically the same as DataSource.DataSet, but returns
nil instead of an exception if DataSource is nil.


Editing: Boolean;		// RunTime and ReadOnly

Tells if the DataSource is in either dsEdit or dsInsert state. After
changes of this property, the OnEditingChange event is fired.


ReadOnly: Boolean;		// RunTime and ReadOnly

Tells if modifications of the dataset are permitted. After
changes of this property, the OnReadOnlyChange event is fired.
Always true if no active dataset is assigned. If a dataset is assigned
and active it reflects the dataset's CanModify property, but can be
changed in the OnCheckReadOnly event handler.


State: TDataSetState;		// RunTime and ReadOnly

For convenience. Basically the same as DataSource.State, but returns
dsInactive instead of an exception if DataSource is nil.


2.3 Methods
-----------

procedure CheckReadOnly;

This method gets called automatically on record changes, changes of the
datasource, the dataset or the dataset's Active property. If an active
dataset is assigned the OnCheckReadOnly event is fired, allowing for
record based write privileges. It fires the OnReadOnlyChanged event if
the value of the ReadOnly property changes.
This procedure should be called only when write permissions change for
reasons other than dataset or record changes.


Events
------

property OnEditingChange: TNotifyEvent;

Fired when the value of the Editing property has changed.


property OnDataChange: TDataChangeEvent;

Fired on record or field changes just like TDataSource's OnDataChange.
Field is nil if the cursor has moved to a new record.


property OnReadOnlyChange: TNotifyEvent;

Fired when the value of the ReadOnly property has changed. In this event
handler, controls should be activated or inactivated (or their ReadOnly
property modified) to reflect changes of write privileges. 


property OnCheckReadOnly: TCheckReadOnlyEvent;

Fired from CheckReadOnly (see above). The var parameter Value informs
about the CanModify property of the dataset. The event handler can
change Value to prevent the user from modifying the current record
(depending on user rights, lunar phases or anything one can imagine)
provided that an OnReadOnlyChange handler inactivates the respective
controls. The value of the ReadOnly property has NOT yet been changed 
when OnCheckReadOnly is fired, it is changed after OnCheckReadOnly 
returns. If an exception occurrs during OnCheckReadOnly, ReadOnly is
assigned the value Value had just before the exception occurred.

When OnCheckReadOnly is fired, DataSet is guaranteed to be assigned and
active.



3. Installation
===============

TDataConnection is intended to work with Delphi 2.x. I don't know which
changes to the code - if any - are necessary to make it work with D1 or D3.
 
TDataConnection is added to your component palette like any other
component. See Delphi help files for details on component installation.

You will want to replace the string 'Datenzugriff' in the Register
procedure by the name of the palette page you wish to have it installed
to if you are using a non-German version of Delphi.

TDataConnection does not come with a bitmap. Feel free to design one and
send it to me (address above) if you don't like Delphi's default
component's bitmap.



4. Legal Stuff
==============

This Component is free software; you can redistribute it and/or modify
it under the terms of the GNU Library General Public License as
published by the Free Software Foundation; either version 2 of the
License, or (at your option) any later version. This Component is
regarded as a Library in the terms of the License.

Diverging from Section 6 of the GNU Library General Public License, you
are permitted to distribute executables that use this Component even if
it is not possible for the user to modify the Component and then
recompile the executable, since a strict application of this Section is
not practicable for Delphi programs. You must, however, supply the
source code of the Component with your Executables according to Section
6 of the GNU Library General Public License.

This readme file is considered part of the source code of the Component.
A distribution of the Component in any form only legal if accompanied by
this file or a modified version of this file according to the GNU
Library General Public License.

This Component is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
Library General Public License for more details.

You should have received a copy of the GNU Library General Public
License (in the accompanying file Copying.lib) along with this
component; if not, write to the Free Software Foundation, Inc., 59
Temple Place - Suite 330, Boston, MA  02111-1307, USA.


