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 three
lines of code to the dialog.  If you are using a number of dialogs derived
from one base dialog you only need to add the code in the base class.

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

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

	// in the dialog's .CPP file
	DEFINE_USETRANSFERARRAYS (TMyDialog);		// add this line

	TMyDialog::TMyDialog (TWindow *wnd, TResId resID)
	{
		SetTransferArray (NULL);				// add this line

		:
	}

The DEFINE.. and DECLARE.. macros (which are also used by TTransferDialog)
provide the following two functions:

	SetTransferArray	- define the transfer array object for this dialog
	TransferData 		- transfer data in and out of this dialog via the
						  array object specified in SetTransferArray

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 three lines of code to your dialog
or derive from TTransferDialog.  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)
- make a call to SetTransferArray passing the address of a TTransferArray
  to define the transfer array object to use
- set up every control.  You do this by modifying the TfElement object
  associated with the control.  To get a reference to the TfElement object
  you use the normal array subscript mechanism (ie. use [])

	dlg.SetTransferArray (&transfer);
	TfElement&	elem = 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 thing like:

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

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

	transfer[IDC_CHECKBOX1].SetCheck (TRUE);

The supplied demo application TEST.CPP contains examples of all of these.


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
--------------------------------------

None as yet


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!)

Steve Saxon
London, England.
CIS: 100321,2355