| TDragDropEx |

| Description
| TDragDropFilesEx is a comfortable and powerful component for COM/OLE drag&drop operations with files and supports completely the namespace of Windows (PIDL). The component is a child-class from TDragDrop.

| Important for Use
| This file (index.htm) contains more information about restrictions, the disclaimer, remarks etc.

| History
| Version 1.30 published on 17-Dec-1999
| Implementation of shell extensions (drop- and drag&drop-handler) Changes in the FileList; but no code breaking
| Version 1.22 published on 13-Nov-1999
| Small bug in RenderDropped fixed; instead of GlobalFree I use ReleaseStgMedium for releasing resources The TFileList has changed, because the items' type was adjusted; now, you don't need any longer to do type-casting on accessing the items in the list; this modification should make the use of the list a little bit easier; in order of this change, TSortedList won't be any longer used
| Version 1.21 published on 09-Jul-1999
| Small bug with property FileNamesAreMapped fixed Bug with mapped filenames under WinNT fixed
| Version 1.20 published on 06-Jul-1999
| Code re-design in result of modifications in TDragDrop; handling hasn't changed
| Version 1.10 published on 30-May-1999
| Is now able to handle mapped filenames Some bugs fixed with filelist
| Version 1.02 published on 06-Jul-1999
| New property added: CompleteFileList
| Version 1.01 published on 03-Oct-1999
| Small invisible bugs fixed
| Version 1.00 published on 06-Aug-1998
| First official release

| Properties

| inherited properties
| Click here ...
| CompleteFileList published
| Here you can determine, if the FileList should be automaticly completed or not on calling Execute and CopyToClipBoard. This was added the increase the performance on some actions.
| FileList public
| For Target: Use this list in OnProcessDropped, if you want to get the dropped files. For Source: Add the files to this list, that you want to drag&drop, before calling Execute. Only if the pidl is available, the drag&drop target can create a shortcut. Attention: FileList is an instance of TFileList!
| NeedValid published
| Here, you can determine, if the drag&drop data must have a filename (set includes nvFilename) or pidl (set includes nvPIDL). This property applies to receiving AND transmitting data. For Source: Only if the pidls are available, you can make a shortcut e.g. to the desktop!
| ShellExtensions published
| This property has two sub-properties: DragDropHandler DropHandler If the user drops data with right mousebutton and the property TargetPopUpMenu and the sub-property DragDropHandler is set to true, this component checks for a available drag&drop-handler. For this you must specify a drop-target in the event-handler OnSpecifyDropTarget. The drop-target must be a directory. If a drag&drop-handler is available for the dropped data, there will be corresponding items added to to context-menu. If the user e.g. drops ZIP-Files and Winzip is installed, items like "Extract to ..." will added to the context-menu. If the user selected such an item, the dropped files will be extracted and you are notified by the event OnMenuSucceeded, that the extension was successfully executed. Was the extension successfully executed, the events OnDrop and OnProcessDropped won't be triggered. If the user drops files on an other file and the sub-property DropHandler is set to true, the drop-handler will be executed, if available. The drop-handler will only executed, if you specify in the event OnSpecifyDropTarget a file, for that is a drop-handler defined in the registry. You can determine during a drop with the method TargetHasDropHandler in the event OnDragOver, if the file has a drop-handler. If the drop-handler was successfully executed, the event OnDropHandlerSucceeded will triggered. A drop-handler will be executed, if the user drops a file/directory on a ZIP-File and Winzip is installed. The dropped file/directory will be added to ZIP-file.

| Events

| inherited events
| Click here ...
| OnSpecifyDropTarget published
| This event will be triggered by the sub-properties of the property ShellExtensions. You must specify a drop-target (file/directory) by the filename or pidl. You don't need to specify both values, but it doesn't harm. If no drop-target is specified, the shell extensions won't be executed.

| Methods

| inherited methods
| Click here ...
| Execute public
| Call this method, if you detect that the user wants to start a drag&drop operation (e.g. MouseDown+MouseMove). Also look: FileList. For drag detection you can also use the inherited property AutotDetectDnD or the method StartDnDDetection. IMPORTANT: If you use the drag-detection, it's high recommended to check the section "Problems With The Drag-Detection".
| TargetHasDropHandler published
| You can use this method to determine, if a drop-target (file) has a drop-handler or not. Normally, you will use this method in the event OnDragOver to determine, if visual updates are necessary (e.g. selecting a file etc.).

| How Do I Use It As Drag&Drop Source
| 1. | Drop a TWinControl on the form (e.g. a listbox).
| 2. | Choose the TWinControl (listbox) in DragDropControl.
| 3. | Choose the drag&drop effects under SourceEffects which the DragDropControl (listbox) should support. If you don't want any longer that the DragDropControl serve as drag&drop source all items must be set to false.
| 4. | Now, your DragDropControl (listbox) must detect, if the user wants to start a drag&drop operation. You can use the event "OnMouseDown" of your DragDropControl (listbox). Add following to the event: `DragDropFiles1.FileList.AddItem(<absolute pidl of file, if available, or nil>, <selected item in` `DragDropControl``(listbox)>);` You must add the filenames including the WHOLE PATH!!!
| 5. | Tell Windows that there is a drag&drop operation to handle: Just call the method Execute of this component.
| 6. | You may use the events OnGiveFeedback and OnQueryContinueDrag, but often you need not.
| Hints:
| Drag&drop operations cannot be done at design-time! IMPORTANT: If you use the drag-detection, it's high recommended to check the section "Problems With The Drag-Detection".

| How Do I Use It As Drag&Drop Target
| 1. | Drop a TWinControl on the form (e.g. a listbox).
| 2. | Choose the TWinControl (listbox) in DragDropControl.
| 3. | Choose the drag&drop effects under TargetEffects which the DragDropControl (listbox) should support. If you don't want any longer that the DragDropControl serve as drag&drop target all items must be set to false.
| 4. | Now, you have to program what happen, if the user drops files on your DragDropControl (listbox). For this, the best is to use the event OnProcessDropped. At first, you should check what drag&drop effect was chosen by the user. You get the effect from method's parameter dwEffect. You get the files from this component with following line: `... :=DragDropFiles1.FileList[<Index>]^.Name;` `// returns the filename; if not available, the result is an empty string``` `... :=DragDropFiles1.FileList[<Index>]^.pidlFQ;` `// returns the pidl; if not available, the result is nil` FileList is an instance of TFileList. For more info check below. Now, do with the files what you have to do, e.g. copy, move, delete, etc.
| 5. | You may use the events OnDragEnter, OnDragOver and OnDragLeave, but often you need not.
| Hints:
| Drag&drop operations cannot be done at design-time!

| Details about TFileList
| TFileList is a child of TList. Therefore, I don't explain the list, again. You can find a documentation in the online-help. Now, the new features of TFileList: You add items to the list with the function AddItem (or AddItemEx, if you want to use mapped filenames). The function make itself a copy of the pidl (absolute needed!) to relieve you of this dirty job. If you don't know the pidl, set the parameter to nil. If you don't know or have the filename (including the whole path), set this parameter to a emtpy string. You can delete items or clear as common to lists. You needn't care about releasing resources - the TFileList cares about itself! Besides, there are the functions RenderPIDLs and RenderNames. RenderPIDLs tries to get the according pidls to the filenames in the list. RenderNames tries to get the according filenames (including full path) to the pidls in the list. If the functions succeed the result is true else false. You need not to call them before a drag&drop operation. This will be automaticly done by the component itself, if you set the property CompleteFileList to true. But it may be useful to call them after receiving data to complete the list.

| Details about PIDLs
| Since Win95 the file-system is more difficult. It is object orientated and is named "namespace". Every file, folder, etc. is an object in the object-tree of the namespace. Every object is an instance of the class IShellFolder (more info in the online-help). If you have the instance of the object, you can many do. E.g. you can determine the properties (attributes) of the object (is it a file?, is it a folder?, can I copy it?, ...). Every object can be identified by an ID: the pidl. By the pidl you can determine the IShellFolder-instance (use the enclosed unit "pidl"; description only in the code available). Pay attention about relative and absolute pidls. The instance itself has only a relative pidl (sometimes named as "item pidl"). The path of concatenated pidls from the root-object (desktop) to the child-object is the absolute pidl! Pay attentions about this difference. You can quickly fooled! Very important: Shortscuts are only possible, if the pidl is available.

| Details about mapped filenames
| If a mapped filename is set, the source inform you, that you have to rename the received name into the mapped name after to d&d-operation. The mapped filenames are used, if you drag files from the "RecycleBin".

| FAQ
| Q: My application supports only some special file-formats. How can I forbid the other formats during the drop? A: Set the property RenderOn to rdoDropEnterAndDropSync and check out the Filelist in the event OnDragEnter. Set the parameter Accept in this event to true, if your application support the files in the Filelist otherwise set the parameter to false. If you only use the first file, check only the first item in the Filelist.

| Known Bugs
| Shortcuts are only possible, if the pidl is available (not really a bug)

© 1998,99 by Dieter Steinwedel

Back to index