RealICQClient/Includes/DRAGDROP

Drag and Drop Component Suite Version 4.0
Released 18-may-2001
� 1997-2001 Angus Johnson & Anders Melander

-------------------------------------------
Installation:
-------------------------------------------
1) Before you do anything else, read the "Known problems" section of this
document.

2) Install the source into a directory of your choice.
The files are installed into three directories:
DragDrop
DragDrop\Components
DragDrop\Demo

3) Install and compile the appropriate design time package.
The design time packages are located in the Components directory. Each
version of Delphi and C++ Builder has its own package; DragDropD6.dpk for
Delphi 6, DragDropD5.dpk for Delphi 5, DragDropC5.dpk for C++ Builder 5, etc.

4) Add the Drag and Drop Component Suite components directory to your library
path.

5) Load the demo project group: demo\dragdrop_delphi.bpg.
The project group contains all the demo applications. There are no demo
applications for C++ Builder at this time.

6) If your version of Delphi does not support text format DFM files (e.g. Delphi
4 doesn't), you will have to use the convert.exe utility supplied with Delphi
to convert the demo form files to binary format.

7) If upgrading from a previous version of the Drag and Drop Component Suite,
please read the document "upgrading_to_v4.txt" before you begin working on
your existing projects.


-------------------------------------------
Getting started:
-------------------------------------------
It is recommended that you start by running each of the demo applications and
then look through the demo source. Each demo application is supplied with a
readme.txt file which briefly describes what the demo does and what features
it uses. The demos should be run in the order in which they are listed in the
supplied project group.

Even if you have used previous versions of the Drag and Drop Component Suite it
would be a good idea to have a quick look at the demos. The library has been
completely rewritten and a lot of new features has been added.


-------------------------------------------
Known problems:
-------------------------------------------
* There appear to be sporadic problems compiling with C++ Builder 5.
Several user have reported that they occasionally get one or more of the
following compiler errors:

[C++ Error] DragDropFile.hpp(178): E2450 Undefined structure
'_FILEDESCRIPTORW'
[C++ Error] DropSource.hpp(135): E2076 Overloadable operator expected

I have not been able to reproduce these errors, but I believe the following
work around will fix the problem: In the project options of *all* projects
which uses these components, add the following conditional define:

NO_WIN32_LEAN_AND_MEAN

The define *must* be made in the project options. It is not sufficient to
#define it in the source.
If you manage to compile with C++ Builder (any version), I would very much
like to know it


-------------------------------------------
Support and feedback:
-------------------------------------------
Since these components are freeware they are also unsupported. You are welcome
to ask for help via email, but I cannot guarantee that I will have time to help
you or even reply to your mail.

You can also try asking for help in the Delphi newsgroups. Since the Drag and
Drop Component Suite is in widespread use, there's a good chance another user
can help you. I would recommend the following newsgroups for issues regarding
this library (or COM based Drag/Drop in general):

borland.public.delphi.winapi
borland.public.delphi.thirdparty-tools
borland.public.delphi.oleautomation
borland.public.cppbuilder.winapi
borland.public.cppbuilder.thirdparty-tools

Please choose the most appropiate newsgroup for your question. Do not cross
post to them all.

If you have suggestions for improvements please mail them to me.

Please include the words Drag Drop in the subject of any email regarding these
components.


-------------------------------------------
Bug reports:
-------------------------------------------
Bugs can either be reported at my home page (http://www.melander.dk/) or mailed
directly to me.

When reporting a bug, please provide the following information:

* The exact version of the Drag and Drop Component Suite you are using.
* The exact version of Delphi or C++ Builder you are using.
* The name and exact version of your operating system (e.g. NT4 SP5).
* The exact version of the Internet Explorer installed on your system.

If you can provide me with a minimal application which reproduces the problem,
I can almost guarantee that I will be able to fix the problem in very short
time. Please supply only the source files (pas, dfm, dpr, dof, res, etc.) and
mail them as a single zip file. If I need a compiled version I will ask for it.

If you mail a bug report to me, please include the words Drag Drop in the
subject of your email.


-------------------------------------------
Upgrades and bug fixes:
-------------------------------------------
Upgrades can be downloaded from my home page:

http://www.melander.dk/delphi/dragdrop/

Bug fixes will also be posted to the above page.

If you have registered for update notification via the installation program, you
will receive email notification when a new release is available. You will not be
notified of bug fixes.

You can use the installation program to check for and download new releases and
to check for known bugs.

Note: If a new release is made available and you are not notified even though
you registered for notification, you probably mistyped your email address during
installation. About 10% of all registrations supply an invalid email address.


-------------------------------------------
Missing in this release:
-------------------------------------------
* Delphi 3 & 4 and C++ Builder support.
Due to time constraints in getting this release ready for inclusion on the
Delphi 6 Companion CD, the release has only been tested with Delphi 5 and
Delphi 6. Support for Delphi 4 and C++ Builder 5 has been planned for the next
release. I have not yet decided if other versions of Delphi and C++ Builder
will be supported.

* On-line help has not been updated and included in the kit due to late changes
in the Delphi 6 help system and lack of time.
If time permits, I will update the help and include it in a future release.


-------------------------------------------
Release history:
-------------------------------------------
18-may-2001
* ContextMenuDemo and DropHandlerDemo application has been partially
rewritten and renamed.
ContextMenuDemo is now named ContextMenuHandlerShellExt.
DropHandlerDemo is now named DropHandlerShellExt.

* TDropContextMenu component has been rewitten.
The TDropContextMenu now implements a context menu handler shell extension.
In previous releases it implemented a drag drop handler shell extension.

* The DragDropHandler.pas unit which implements the TDropHandler component
has been renamed to DropHandler.pas.

* Added new TDragDropHandler component.
The new component, which lives in the DragDropHandler unit, is used to
implement drag drop handler shell extensions.

* Added DragDropHandlerShellExt demo application.

* Removed misc incomplete demos from kit.

* Fixed minor problem in VirtualFileStream demo which caused drops from
the VirtualFile demo not to transfer content correctly.

* Released as version 4.0.

11-may-2001
* Converted all demo forms to text DFM format.
This has been nescessary to maintain compatibility between all supported
versions of Delphi.

* Fixed a bug in GetPIDLsFromFilenames which caused drag-link of files (dtLink
with TDropFileSource) not to work.

* Added readme.txt files to some demo applications.

* Added missing tlb and C++ Builder files to install kit.

* Released as FT4.

6-may-2001
* Added missing dfm files to install kit.

* Tested with Delphi 5.
Fixed Delphi 5 compatibility error in main.dfm of DragDropDemo.

* Removed misc compiler warnings.

* The AsyncTransferTarget and OleObjectDemo demos were incomplete and has been removed
from the kit for the V4.0 release.
The demos will be included in a future release.

* Released as FT3.

3-may-2001
* Added missing dpr and bpg files to install kit.

* Updated readme.txt with regard to lack of C++ Builder demos.

* Released as FT2.

29-apr-2001
* Cleaned up for release.

* Released as FT1.


23-feb-2001
* Modified TCustomDropTarget.FindTarget to handle overlapping targets (e.g.
different targets at the same position but on different pages of a page
control or notebook).
Thanks to Roger Moe for spotting this problem.

13-feb-2001
* Renamed AsyncTransfer2 demo to AsyncTransferSource.

* Added AsyncTransferTarget demo.

* Replaced TChart in AsyncTransfer2 demo with homegrown pie-chart-thing.

* Modified all IStream based target formats to support incremental transfer.

* URW533 problem has finally been fixed.
The cause of the problem, which is a bug in Delphi, was found by Stefan
Hoffmeister.

* Fixed free notification for TDropContextmenu and TDataFormatAdapter.

27-dec-2000
* Moved TVirtualFileStreamDataFormat and TFileContentsStreamOnDemandClipboardFormat
classes from VirtualFileStream demo to DragDropFormats unit.

* Added TClipboardFormat.DataFormat and TClipboardFormats.DataFormat property.

* Added TDropEmptySource and TDropEmptyTarget components.
These are basically do-nothing components for use with TDataFormatAdapter.

* Rewritten AsyncTransfer2 demo.
The demo now uses TDropEmptySource, TDataFormatAdapter and
TVirtualFileStreamDataFormat to transfer 10Mb of data with progress
feedback.

* Rewritten VirtualFileStream demo.
The demo now uses TDropEmptySource, TDropEmptyTarget, TDataFormatAdapter and
TVirtualFileStreamDataFormat.

* Fixed memory leak in TVirtualFileStreamDataFormat.
This leak only affected the old VirtualFileStream demo.

* Added support for full File Descriptor attribute set to
TVirtualFileStreamDataFormat.
It is now possible to specify file attributes such as file size and last
modified time in addition to the filename. I plan to add similar features to
the other classes which uses FileDescriptors (e.g. TDropFileSource and
TDropFileTarget).

21-dec-2000
* Ported to Delphi 4.

* Added workaround for design bug in either Explorer or the clipboard.
Explorer and the clipboard's requirements to the cursor position of an
IStream object are incompatible. Explorer requires the cursor to be at the
beginning of stream and the clipboard requires the cursor to be at the end
of stream.

15-dec-2000
* Fixed URW533 problem.
I'll leave the description of the workaround in here for now in case the
problem resurfaces.

11-dec-2000
* Fixed bug in filename to PIDL conversion (GetPIDLsFromFilenames) which
affected TDropFileTarget.
Thanks to Poul Halgaard J�rgensen for reporting this.

4-dec-2000
* Added THTMLDataFormat.

* Fixed a a few small bugs which affected clipboard operations.

* Added {$ALIGN ON} to dragdrop.inc.
Apparently COM drag/drop requires some structures to be word alligned.
This change fixes problems where some of the demos would suddenly stop
working.

* The URW533 problem has resurfaced.
See the "Known problems" section below.

13-nov-2000
* TCopyPasteDataFormat has been renamed to TFeedbackDataFormat.

* Added support for the Windows 2000 "TargetCLSID" format with the
TTargetCLSIDClipboardFormat class and the TCustomDropSource.TargetCLSID
property.

* Added support for the "Logical Performed DropEffect" format with the
TLogicalPerformedDropEffectClipboardFormat class. The class is used
internally by TCustomDropSource.

30-oct-2000
* Added ContextMenu demo and TDropContextMenu component.
Demonstrates how to customize the context menu which are displayed when a
file is dragged with the right mouse button and dropped in the shell.

* Added TCustomDataFormat.GetData.
With the introduction of the GetData method, Data Format classes can now be
used stand-alone to extract data from an IDataObject.

20-oct-2000
* Added VirtualFileStream demo.
Demonstrates how to use the "File Contents" and "File Group Descritor"
clipboard formats to drag and drop virtual files (files which doesn't exist
physically) and transfer the data on-demand via a stream.

14-oct-2000
* Added special drop target registration of TCustomRichEdit controls.
TCustomRichEdit needs special attention because it implements its own drop
target handling which prevents it to work with these components.
TCustomDropTarget now disables a rich edit control's built in drag/drop
handling when the control is registered as a drop target.

* Added work around for Windows bug where IDropTarget.DragOver is called
regardless that the drop has been rejected in IDropTarget.DragEnter.

12-oct-2000
* Fixed bug that caused docking to interfere with drop targets.
Thanks to G. Bradley MacDonald for bringing the problem to my attention.

30-sep-2000
* The DataFormats property has been made public in the TCustomDropMultiTarget
class.

* Added VirtualFile demo.
Demonstrates how to use the TFileContentsClipboardFormat and
TFileGroupDescritorClipboardFormat formats to drag and drop a virtual file
(a file which doesn't exist physically).

28-sep-2000
* Improved drop source detection of optimized move.
When an optimized move is performed by a drop target, the drop source's
Execute method will now return drDropMove. Previously drCancel was returned.
The OnAfterDrop event must still be used to determine if a move operation
were optimized or not.

* Modified TCustomDropTarget.GetPreferredDropEffect to get data from the
current IDataObject instead of from the VCL global clipboard.

18-sep-2000
* Fixed bug in DropComboTarget caused by the 17-sep-2000 TStreams
modification.

17-sep-2000
* Added AsyncTransfer2 demo to demonstrate use of TDropSourceThread.

* Renamed TStreams class to TStreamList.

29-aug-2000
* Added TDropSourceThread.
TDropSourceThread is an alternative to Windows 2000 asynchronous data
transfers but also works on other platforms than Windows 2000.
TDropSourceThread is based on code contributed by E. J. Molendijk.

24-aug-2000
* Added support for Windows 2000 asynchronous data transfers.
Added IAsyncOperation implementation to TCustomDropSource.
Added TCustomDropSource.AllowAsyncTransfer and AsyncTransfer properties.

5-aug-2000
* Added work around for URW533 compiler bug.

* Fixed D4 and D5 packages and updated a few demos.
Obsolete DropMultiTarget were still referenced a few places.

* Documented work around for C++ Builder 5 compiler error.
See the Known Problems section later in this document for more information.

2-aug-2000
* The package files provided in the kit is now design-time only packages.
In previous versions, the packages could be used both at design- and
run-time. The change was nescessary because the package now contains
design-time code.

* Added possible work around for suspected C++ Builder bug.
The bug manifests itself as a "Overloadable operator expected" compile
time error. See the "Known problems" section of this document.

* Rewrote CustomFormat1 demo.

* Added CustomFormat2 demo.

* TDataDirection members has been renamed from ddGet and ddSet to ddRead and
ddWrite.

* All File Group Descritor and File Contents clipboard formats has been moved
from the DragDropFile unit to the DragDropFormats unit.

* File Contents support has been added to TTextDataFormat.
The support is currently only enabled for drop sources.

* Renamed TDropMultiTarget component to TDropComboTarget.
Note: This will break applications which uses the TDropMultiTarget
component. You can use the following technique to port application from
previous releases:
1) Install the new components.
2) Repeat step 3-8 for all units which uses the TDropMultiTarget component.
3) Make a backup of the unit (both pas and dfm file) just in case...
4) Open the unit in the IDE.
5) In the .pas file, replace all occurances of "TDropMultiTarget" with
"TDropComboTarget".
6) View the form as text.
7) Replace all occurances of "TDropMultiTarget" with "TDropComboTarget".
8) Save the unit.

* Renamed a lot of demo files and directories.

* Added work around for yet another bug in TStreamAdapter.

* Added TCustomStringClipboardFormat as new base class for
TCustomTextClipboardFormat.
This changes the class hierachy a bit for classes which previously
descended from TCustomTextClipboardFormat: All formats which needs zero
termination now descend from TCustomTextClipboardFormat and the rest descend
from TCustomStringClipboardFormat.
Added TrimZeroes property.
Fixed zero termination bug in TCustomTextClipboardFormat and generally
improved handling of zero terminated strings.
Disabled zero trim in TCustomStringClipboardFormat and enabled it in
TCustomTextClipboardFormat.

23-jul-2000
* Improved handling of long file names in DropHandler demo.
Added work around for ParamStr bug.

* Added TDataFormatAdapter component and adapter demo.
TDataFormatAdapter is used to extend the existing source and target
components with additional data format support without modifying them. It
can be considered an dynamic alternative to the current TDropMultiTarget
component.

17-jul-2000
* TDropHandler component and DropHandler demo fully functional.

14-jul-2000
* Tested with C++ Builder 5.

* Fixed sporadic integer overflow bug in DragDetectPlus function.

* Added shell drop handler support with TDropHandler component.
This is a work in progress and is not yet functional.

1-jul-2000
* Tested with Delphi 4.

* Support for Windows 2000 inter application drag images.

* TRawClipboardFormat and TRawDataFormat classes for support of arbitrary
unknown clipboard formats.
The classes are used internally in the TCustomDropSource.SetData method to
support W2K drag images.


-------------------------------------------
New in version 4.x:
-------------------------------------------
The following are some of the new features in version 4. The list is not
complete.

* Completely redesigned and rewritten.
The new design separates the library into 3 layers:
1) Clipboard format I/O.
2) Data conversion and storage.
3) COM Drag and Drop implementation and VCL component interface.
The first two layers are shared between the source and the target components.
Backward compatibility has been maintained.
Two units are provided for legacy support of custom drag/drop components based
on the V3.x architecture.

* Support for Windows 2000 inter application drag images.
On Windows 2000 drag images are now displayed when dragging between
applications.

* Support for Windows 2000 asynchronous data transfers.
Asynchronous data tranfers allows the drop source and targets to perform slow
transfers or to transfer large amounts of data without blocking the user
interface while the data is being transfered.
For platforms other than Windows 2000, the new TDropSourceThread class can be
used to provide similar (but more limited) asynchronous data transfer
capabilities.

* Support for optimized and non-optimized move.
When performing drag-move operations, it is now possible to specify if the
target (optimized move) or the source (non-optimized move) is responsible for
deleting the source files.

* Support for delete-on-paste.
When data is cut to the clipboard, it is now possible to defer the deletion of
the source data until the target actually pastes the data.

* All formats and components (both source and target) now support clipboard
operations and the VCL clipboard object.

* Support for shell drop handlers.
The new TDropHandler component can be used to write drop handlers. A drop
handler is a shell extension which is executed when a user drags and drops one
or more files on a file associated wth your application.

* Automatic re-registration of targets when the target window handle is
recreated.
In previous versions, target controls would loose their ability to accept
drops when their window handles were recreated by the VCL (e.g. when changing
the border style or docking a form). This is no longer a problem.

* New components:
- TDropComboTarget: Swiss-army-knife target. Accepts text, files, bitmaps,
meta files, URLs and file contents.
- TDropMetaFileTarget: Accepts meta files and enhanced meta files.
- TDropImageTarget: Accepts bitmaps, DIBs, meta files and enhanced meta files.
- TDragDropHandler: Shell Drag Drop Handler target.
- TDropHandler: Shell Drop Handler.
- TDragDropContext: Shell Context Menu Handler.
- TDataFormatAdapter: Extends the standard source and target components with
support for extra data formats. An alternative to TDropComboTarget.
- TDropEmptyTarget and TDropEmptySource: Target and source components which
can be extended with TDataFormatAdapter.

* New clipboard formats:
- File contents stream and storage formats.
- Meta file and enhanced meta file format.
- Netscape Bookmark format.
- Netscape image format.
- V-Card format.
- HTML format.
- RFC822 email format.
- RTF, Unicode, OEM and CSV text formats.
- Locale format.
- Others...

* New source events:
- OnGetData: Fired when the target requests data.
- OnSetData: Fired when the target writes data back to the source.
- OnPaste: Fired when the target pastes data which the source has placed on
the clipboard.
- OnAfterDrop: Fired after the drag/drop operation has completed.

* New target events:
- OnScroll: Fires when the target component is about to perform auto-scroll on
the target control.
- OnAcceptFormat: Fires when the target component needs to determine if it
will accept a given data format. Only surfaced in the TDropComboTarget
component.

* 7 new demo applications.

* Support for run-time definition of custom drag formats.
You can now add support for new clipboard formats without custom components.

* Support for design-time extension of existing source and target components.
Using the new TDataFormatAdapter component it is now possible to mix and match
data formats and source and target components at design time. E.g. the
TDropFileTarget component can be extended with URL support.

* It is now possible to completely customize the target auto-scroll feature.
Auto scroling can now be completely customized via the OnDragEnter,
OnDragOver, OnGetDropEffect and OnScroll events and the public NoScrollZone
and published AutoScroll properties.

* Multiple target controls per drop target component.
In previous versions you had to use one drop target component per target
control. With version 4, each drop target component can handle any number of
target controls.

* It is now possible to specify the target control at design time.
A published Target property has been added to the drop target components.


-------------------------------------------
TODO (may or may not be implemented):
-------------------------------------------
* Async transfer demo (with and without IAsyncOperation support).

* Scrap file demo.

* Outlook message format.

* Structured storage support (IStorage encapsulation).