TRANSFER ARRAYS -- A C++ REPLACEMENT FOR OWL 2.0 TRANSFER BUFFERS
=================================================================

Introduction
------------

One of the most common problems encountered by novice and experienced users
alike is with the use of transfer buffers.  Although in theory transfer
buffers simplify the coding interface, in practice they can be a nightmare
to set up and maintain, as even a 1-byte alignment problem within the buffer
is usually enough to crash an application.

With this in mind I have developed an extremely easy to use set of classes
that provide a completely order and size independent way of transferring
data to and from a dialog box.  Called "transfer arrays", it provides an
implementation based solely on the ID and is independent of the length of
text in the control.


How to set your dialogs up to use transfer arrays
-------------------------------------------------

The transfer array mechanism built around two simple classes:

  TTransferArray        the actual transfer array itself
  TfElement         	an element in the array (corresponding to a control)

To add transfer array support to your application you can derive all of your
dialog's from TTransferDialog.

To add transfer array support to an existing dialog, you need to add just one
line of code to the dialog.  If you are using a number of dialogs derived
from one base dialog you only need to add this one line in the base class.

	// in the dialog's .H file
	class TMyDialog : public TDialog
	{
	public:
		TMyDialog (TWindow *wnd, TResId resID);

		DECLARE_USETRANSFERARRAYS (TMyDialog, TDialog);	// add this line
	};

The syntax of this macro is:

  DECLARE_USETRANSFERARRAYS (thisClass, parentClass);

This macro is used to provide a definition for the TransferData function
which is the function which initiates the transfer.  It also adds an
TTransferArray variable called 'transfer' into the public section of the
class.

The use of the TransferData function makes transfer arrays appear 100%
compatible with transfer buffers as far as OWL is concerned, but by using a
transfer array you are guaranteed a way to avoid the positioning nightmares.


So what do I need to do?
------------------------

As stated earlier, you will need to add the one line macro to your dialog
class definition, or alternatively derive all of your dialogs from
the TTransferDialog class which already includes this class.

You will then want to perform the following steps:

- make sure every control that will transfer has an OWL object defined for
  it (this is in common with OWL transfer buffers)
- set up every control.  You do this by modifying the TfElement object
  associated with the control.  The public data member 'transfer' is the
  actual TTransferArray object which can contain TfElements.  To get a
  reference to the TfElement object for a particular control you use the
  normal array subscript mechanism (ie. use []) on the 'transfer' object.

	TfElement&	elem = dlg.transfer[IDC_EDIT1];

The TfElement class contains a number of methods for modifying the nature
of the control to which it refers:

	SetTransferBuffer	- define the transfer object to use for specific
						  types of control (eg. TListBoxData for listbox)

	GetText				- return the text of the control
	SetText				- set the text of the control

	GetCheck			- get the check-state of a radiobutton or checkbox
	SetCheck			- set the check-state of a radiobutton or checkbox

Of course, because the [] operator function returns a reference you can also
say things like:

	dlg.transfer[IDC_EDIT1].SetText ("My text");

	TComboBoxData	cbData;
	dlg.transfer[IDC_COMBOBOX1].SetTransferBuffer (&cbData);
	cbData.AddString ("combo string #1");

	dlg.transfer[IDC_CHECKBOX1].SetCheck (TRUE);


Things to try
-------------

TTransferArray contains a function called GetRadioChecked which takes a
"from" and a "to" control ID.  GetRadioChecked will go through every
control in the dialog in this ID range and return the ID of the first checked
control.  This provides a really great way to use radiobutton groups, because
the return value can then be used in a "switch" statement.


Limitations in this version
---------------------------

There are none as far as I'm aware (except perhaps Unicode on NT, but I
don't know too much about that at the moment)


Corrections/Amendments in this version
--------------------------------------

As at 20th September:

- DEFINE_USETRANSFERARRAY removed.  TTransferArray is now held as an public
  object called 'transfer' inside the class
- SetTransferArray modified to now assign a variable in a separate class so
  that this pointer-based mechanism can still be used instead of using the
  'transfer' variable
   

Getting in touch with the author
--------------------------------

I am distributing this as CharityWare.  If you find this code of great
use and you feel you'd like to make a financial contribution you can
send your contributions to:

	Steve Saxon
	Flat 2, 4a Grange Park
	Ealing
	London W5 3PL
	England

I'm afraid you'll have to send cash (preferably not coins!) as it isn't
worth my paying 15 pounds to have cheques cleared (unless you are
sending hundreds of dollars!).  Please can you use registered post to reduce
the chance of your contribution getting 'lost' in the mail

Steve Saxon
London, England.
CIS: 100321,2355