A Field Totaling Component: TDBFieldTotaliser (v1.14)

Table of Contents

    Overview

    Quick Start

    How it Works

    Properties
        FieldsList
        DataSource
        Totals

    Events
        AfterCancel
        AfterDelete
        BeforeDelete
        OnTotalsChanged

    Methods
        RefreshTotals
        ZeroTotals

    Pricing and Contact information

    Legal Stuff

Overview

TDBFieldTotaliser is a component for Delphi 3.0x, 4.0 and C++ Builder 3.0 that will provide a running total for any numeric field(s) in a dataset. The TDBFieldTotaliser component is completely dynamic. Once an edit on a field is complete then the total for that column is recalculated to reflect the new value. The component responds to all data events to ensure that the total for a monitored column is always up to date. The client application is notified of changes to any total via an event. TDBFieldTotaliser can monitor any number of fields in a dataset and will monitor any numeric type over 1 byte in size.

TDBFieldTotaliser will work in all circumstances. If the monitored dataset is involved in a master-detail relationship then TDBFieldTotaliser will re-calculate totals when the master dataset changes. The component is also aware of cached updates and will calculate values from a fields NewValue property when changes occur in the cached dataset.

TDBFieldTotaliser will install itself on to the Samples page of your component palette.

Quick Start

Assuming that you have already placed DataSources and DataSets on to your form or data module here's what you do:

1. Place a TDBFieldTotaliser component on the form or data module.
2. In the Object Inspector. Click on the DataSource property and from the drop down list select the DataSource of the dataset you what to total fields for.
3. Again in the Object Inspector, click on the FieldsList property and enter the names of the fields you want to generate totals for. If you want totals for more that one field in the dataset then separate the field names with a semi-colon. e.g: "thisField;thatField".
4. Click on the events tab at the top of the Object Inspector and then double click on the OnTotalsChanged event. You'll be taken to the editor where you can write the code that will be performed whenever a total is updated. You'll probably want to place code in here that makes the total visible to the outside world.
5. That's all there is to it.

How it works

Basically it works by digging its claws into the host dataset.

It is easy to monitor edits and inserts to records and provide an accurate running total.  The TDataSet.State property allows the developer to know when edits or inserts are taking place.  The TDataSet.State property does not cover conditions such as record deletions or the cancellation of a record edit or record insertion.  The TDBFieldTotaliser component needs to know about all operations carried out on the contents of the monitored dataset so that all totals are accurate.

As mentioned above monitoring edits and deletes is relatively easy to do, TDBFieldTotaliser finds out about deletions and cancellations by attaching its own event handlers to the host datasets BeforeDelete, AfterDelete and AfterCancel events.  If you have your own event handlers on any of the above events defined at design time then the TDBFieldTotaliser keeps a note of your event handlers and calls your event handlers before it does any of its own processing.  By calling your original event handlers first, any exceptions you may raise will cause the TDBFieldTotaliser event handlers to abort and leave any totals as they are. The down side to this approach is that  if you change any event handlers at runtime, by re-assigning the method pointer for instance, will cause TDBFieldTotaliser to lose its event handler connection to the monitored dataset and the totals will become inaccurate.  To get around this shortcoming TDBFieldTotaliser provides it own BeforeDelete, AfterDelete and AfterCancel events.  If you need to re-assign an event handler at runtime then you should do so via the event handlers provided by TDBFieldTotaliser.

Properties

• FieldsList : String
• 
  This is the list of fields within a dataset you want to total.  If you want to monitor more than one field then separate the field names with a semi-colon (;) e.g.: thisField;thatField
• DataSource : TDataSource
• 
  The data source of the dataset you want totaling.  Use this property to connect TDBFieldTotaliser to the dataset you want totaling (via the datasource).
• Tag : Longint
• 
  That spare thing that all components have.
• Totals[ FieldName : String ] : Variant; default
• 
  (Read Only) Returns the current total for the column FieldName as a variant. This is the default property for the component so the following two forms are equivalent:
      varV := totaliser1.totals[ 'field1' ];
      varV := totaliser1[ 'field1' ];
  Please note that the default notation dosen't work in C++ Builder

Events

• AfterCancel( DataSet : TDataSet )
• 
  Same as the TDataSet.AfterCancel event. Runtime only. Assign an AfterCancel event handler to this event only if you want to re-assign the monitored datasets AfterCancel event. By assigning the replacement event handler to this event instead of to event on the monitored dataset the TDBFieldTotaliser component can continue to monitor the cancellation of record edits and insertions and keep field totals up to date. See "How it works" above.
   
• AfterDelete( DataSet : TDataSet )
• 
  Same as the TDataSet.AfterDelete event. Runtime only. Assign an AfterDelete event handler to this event only if you want to re-assign the monitored datasets AfterDelete event. By assigning the replacement event handler to this event instead of to the event on the monitored dataset the TDBFieldTotaliser component can continue to monitor the deletion of records and keep field totals up to date. See "How it works" above.
   
• BeforeDelete( DataSet : TDataSet )
• 
  Same as the TDataSet.BeforeDelete event. Runtime only. Assign a BeforeDelete event handler to this event only if you want to re-assign the monitored datasets BeforeDelete event. By assigning the replacement event handler to this event instead of to the event on the monitored dataset the TDBFieldTotaliser component can continue to monitor the deletion of records and keep field totals up to date. See "How it works" above.
   
• OnTotalsChanged( Sender : TDBFieldTotaliser; const FieldName : String )
• 
  This event is triggered whenever any of the totals are changed and for whatever reason. The handler is passed the Field Totaliser where the changes occurred and the FieldName of the total that changed. If all the monitored totals have changed then FieldName parameter will be set to an empty string ('').

Methods

• Refresh
• 
  Causes the component to completely re-calculate all totals for fields monitored.
• ZeroFields
• 
  Sets all the monitored totals to 0

Pricing and Contact information

This component is shareware. You may evaluate it for 30 days and then either pay for it or stop using it. Purchasing this component entitles you to the source code and free updates via e-mail. The cost of this component is £10.00 or $15.00US.

Please note that the shareware evaluation verision has a nag dialogue built into it.

Comments and bugs may be reported via e-mail to: barry@arrakis.clara.net

Payments should by Cheque, for UK users, or International Money Order in sterling for overseas users. To be made to:
    Barry Carr
    9 Haddon Grove
    Sale
    Cheshire
    M33 7TT
    United Kingdom

Please ensure that you supply your address or e-mail address so that I can get the component to you.

Legal Stuff

TDBFieldTotaliser is the copyright (c) of Barry Carr July 1998

I, BARRY CARR,  MAKES NO WARRANTY OF ANY KIND, EXPRESSED OR IMPLIED, INCLUDING WITHOUT LIMITATION ANY WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
 

IN NO EVENT WILL I, BARRY CARR, BE LIABLE TO YOU OR ANY THIRD PARTY FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OF OR INABILITY TO USE THE SOFTWARE OR ANY SUPPLIED DOCUMENTATION.

By using this product, you agree to this.  If you do not agree, immediately return this product.