jpsReg - Delphi registry aware components
=========================================

Introduction
------------
Most applications require their current state to be stored to the
registry for later use when the application is restarted. Accessing
the registry is not specifically difficult, but it can be tedious.
The jpsReg component package simplifies the process by providing
sub-classed versions of the common components, which can be linked
directly to registry based settings. The whole process is co-ordinated
using a container class component (TIniSource) which provides a
centralised means of loading and storing registry setting for a whole
collection of registry aware components. Typically the OnCreate method
of a form would initiate the load from registry process (with a single
method call), and the Destroy method would initiate a store to registry
process. While the application is running any user parameter setting
using a Preferences… dialog, for example, can be made to update the
registry entries when the OK button is pressed.

The registry aware components simply specify four extra properties in
the object inspector. These specify a registry key (Section) and value
name (Item), a default value (if the value is not in registry initially)
and the TiniSource which is co-ordinating the registry access. The
actual value stored under a key is the components usual data property
(e.g. Text for a T(Ini)Edit).

Groups of registry aware components can be linked to different TIniSource
object, allowing co-ordination of registry access at a lower level than
the entire Registry hive for the application. A TIniSource object has
only one property (IniFile) which specifies a master key under
HKEY_CURRENT_USER. All components contained by the TIniSource will add to
a hierarchy of Keys and Values, under this key, based on their Section
and Item properties.

TIniSource has two public methods (ReadValues and WriteValues). These
trigger the registry load and store mechanism for all contained registry
aware components.
    
Components
==========   

TIniSource
----------
    The registry aware component container

TIniEdit
--------
    Registry aware TEdit which stores its Text property to 
    the registry

TIniMaskEdit
------------
    Registry aware TMaskEdit which stores its Text property to
    the registry

TIniCheckbox
------------
    Registry aware TCheckbox which stores its Checked property to
    the registry

TIniRadioButton
---------------
    Registry aware TRadioButton which stores its Checked property to
    the registry

TIniRadioGroup
--------------
    Registry aware TRadioGroup which stores its ItemIndex property to
    the registry

TIniSpeedButton
---------------
    Registry aware TSpeedButton which stores its Down property to
    the registry

Component Interface and use
===========================

TIniSource
----------
  TIniSource = class(TComponent)
    public
      procedure ReadValues;
      procedure WriteValues;
    published
      property INIFile : String;
  end;

This can be dropped onto any form in the application or be created
dynamically at run-time. Since it inherits behaviour directly from
TComponent make sure you construct and parent the object correctly
if using dynamic creation. In most circumstances you will just drop
the component on the main form, or a user preferences dialog.

Simply rename the component as required (e.g. iniSrcMine) and
provide a value for the INIFile property. It makes sense to use the
same name as the application for INIFile, but there is no 
restriction other than it must be a valid registry key name. Add
code to the OnCreate method of the form to cause the registry values
to be loaded (e.g. iniSrcMine.ReadValues;). Put the command to write
new values to the registry in the event handlers for those actions
that require the registry to be updated. (e.g. the OnClose method for
the form may have the command 'iniSrcMine.WriteValues;' in it.

TIniEdit
--------
  TIniEdit = class(TEdit)
    published
      property Section: String;
      property Item: String;
      property Default: String;
      property IniSource: TIniSource;
  end;

This component and all the following components behave exactly like
their immediate ancestors during normal use within an application.
The only difference is that when its container TIniSource component
executes its ReadValues or WriteValues methods it causes the registry
values to be transferred. A design time select the INISource property
using the property editor in object inspector. Set appropriate 
Section and Item properties.

TIniSource.ReadValues will cause the registry key HKEY_CURRENT_USER/<TIniSource.INIFile>/TIniEdit.Section to be accessed
and the value of TiniEdit.Item to be read (if it exists) into its Text
property. If the key does not exist, the Text value is replaced by the
value of the Default property.

TIniSource.WriteValues will cause the registry key HKEY_CURRENT_USER/<TIniSource.INIFile>/TiniEdit.Section to be accessed
and the value of TiniEdit.Item to be replaced with its Text property.

By building a default value into the object at design time it supersedes
the necessity to provide a registry value during the installation
process.

TIniMaskEdit
------------
  TIniMaskEdit = class(TMaskEdit)
    published
      property Section: String;
      property Item: String;
      property Default: String;
      property IniSource: TIniSource;
  end;

This behaves exactly like a TMaskEdit component except that the registry
aware properties are added and work in exactly the same way as the
TIniEdit component.

TIniCheckBox
------------
  TIniCheckBox = class(TCheckBox)
    published
      property Section: String;
      property Item: String;
      property Default: Boolean;
      property IniSource: TIniSource;
  end;

As before, this is basically a TCheckbox, but the registry aware element
allows you to specify a default registry setting for the Checked
property.

TIniRadioButton
---------------
  TIniRadioButton = class(TRadioButton)
    published
      property Section: String;
      property Item: String;
      property Default: Boolean;
      property IniSource: TIniSource;
  end;

As before, this is basically a TRadioButton, but the registry aware
element allows you to specify a default registry setting for the
Checked property.

TIniRadioGroup
--------------
  TIniRadioGroup = class(TRadioGroup)
    published
      property Section: String;
      property Item: String;
      property Default: Integer;
      property IniSource: TIniSource;
  end;

As before, this is basically a TRadioGroup, but the registry aware
element allows you to specify a default registry setting for the
ItemIndex property.

TIniSpeedButton
---------------
  TIniSpeedButton = class(TSpeedButton)
    published
      property Section: String;
      property Item: String;
      property Default: Boolean;
      property IniSource: TIniSource;
  end;

As before, this is basically a TSpeedButton, but the registry aware
element allows you to specify a default registry setting for the
Down property.
   
Other Information 
=================

Hints for using jpsReg
----------------------
* Replace your standard components with the registry aware versions
  for those controls that need their state storing to the registry.
  It is best to do this during the application development process.
  It is not straightforward to change a TEdit component for a TIniEdit
  component after the application is completed, as all event handlers
  and properties will have to be patched in manually.

* Do split your registry values into logical groups for your
  application using the Section property to make them easier to 
  manage within the application.

* Consider using TIniSource components on every form that has a need
  to interact with the registry so that registry changes are localised.
  jpsReg allows all your registry aware components to be linked to one
  TIniSource component, but inter-form linking requires some management
  of the uses clauses in your units, and you have to be careful that all
  forms with registry aware components on them are constructed before
  calling the ReadValues method.

Terms and Conditions
====================
You may dowload jpsReg for personal use for free, but should you find the
product useful you are required to register with JPSGraphics for a fee
of £20 sterling. Payment should be made by cheque in sterling to 
John P Scott at 30 Adder Hill, Great Boughton, CHESTER, CH3 5RA, UK. 
Folding money is welcome in any currency at the current exchange rate
plus 5% for handling.

The term useful means that you use jpsReg regularly for your own personal
programming projects or you distribute applications incorporating jpsReg,
whether or not those applications are distributed for profit.

JpsReg is provided ‘as is’ and JPSGraphics makes no warranty as to the
suitability or fitness for any particular purpose of jpsReg. JPSGraphics
accept no liability for damage or loss caused by the use of jpsReg
howsoever that loss or damage might be caused.