DrgDragFiles
This function begins a direct manipulation operation for one or more files.
Syntax
DrgDragFiles(Hwnd, pFiles, pTypes, pTargets, cFiles, hptrDrag, vkTerm, fSourceRender, ulReserved)
Parameters
- Hwnd (HWND) - input
- Handle of calling window.
- pFiles (PAPSZ) - input
- The names of the files to be dragged.
- pTypes (PAPSZ) - input
- The file types of the files to be dragged.
- pTargets (PAPSZ) - input
- Target file names.
- cFiles (ULONG) - input
- Number of files to be dragged.
- hptrDrag (HPOINTER) - input
- Icon to display during the drag.
- vkTerm (ULONG) - input
- Button that ends the drag.
- Possible values:
- VK_BUTTON1 - Release of button 1 ends the drag.
- VK_BUTTON2 - Release of button 2 ends the drag.
- VK_BUTTON3 - Release of button 3 ends the drag.
- VK_ENDDRAG - Release of the system-defined direct manipulation button ends the drag. This is the recommended value if the DrgDrag function call is invoked in response to a WM_BEGINDRAG message.
- Possible values:
- fSourceRender (BOOL) - input
- Flag indicating whether the source must perform the move or copy.
- TRUE - The caller will receive a DM_RENDERFILE message for each file.
- FALSE - All file manipulation is performed by DrgDragFiles.
- ulReserved (ULONG) - input
- Reserved.
Returns
- rc (BOOL) - returns
- Success indicator.
- TRUE - The drag operation was initiated successfully.
- FALSE - An error occurred.
Remarks
This function begins a direct manipulation operation for one or more files. DRAGINFO and DRAGITEM structures are allocated and initialized, and are then used as input to DrgDrag. All of the post-drag conversation required to complete the direct manipulation operation is handled by an object window created by this function.
The caller should set fSourceRender to TRUE if it must perform the file manipulation for any of these files. When fSourceRender is TRUE, the caller receives a DM_RENDERFILE message as the drag-object window receives a DM_RENDER message. The caller should move or copy the file after receiving the DM_RENDERFILE message. The caller should then send a DM_FILERENDERED message to the drag-object window, and the drag-object window should send a DM_RENDERCOMPLETE message to the target.
When pTypes is NULL, the .TYPE EA is interrogated to determine the type for each file in pFiles. When pTypes is not NULL, the size of the array is expected to be the same as the size of pFiles. When any individual pointer in the array is NULL, the .TYPE EA for the corresponding file is read. When .TYPE EA does not exist for any file for which it is needed, a type of DRT_UNKNOWN is used.
When pTargets is NULL, the target name for a file will be the same as the source file name with the path information removed. If pTargets is not NULL, the size of the array is expected to be the same as the size of pFiles. If any individual pointer in the array is NULL, the target name for the corresponding file will match the source name minus the path information.
The rendering mechanism and format for each file is: <DRM_OS2FILE,DRF_UNKNOWN>.
When an error occurs during the move or copy, the caller is sent a DM_DRAGERROR message. The caller can take corrective action.
As the operation is complete for each file in the list, a DM_DRAGFILECOMPLETE message is sent to the caller of DrgDragFiles. The caller is thus notified that resources can be freed for a particular file.
This function returns TRUE if the drag operation was initiated successfully and FALSE if an error occurred.
Example Code
#define INCL_WINSTDDRAG
#include <os2.h>
HWND Hwnd; /* Handle of calling window. */
PAPSZ pFiles; /* The names of the files to be dragged. */
PAPSZ pTypes; /* The file types of the files to be dragged. */
PAPSZ pTargets; /* Target file names. */
ULONG cFiles; /* Number of files to be dragged. */
HPOINTER hptrDrag; /* Icon to display during the drag. */
ULONG vkTerm; /* Button that ends the drag. */
BOOL fSourceRender; /* Flag indicating whether the source must perform the move or copy. */
ULONG ulReserved; /* Reserved. */
BOOL rc; /* Success indicator. */
rc = DrgDragFiles(Hwnd, pFiles, pTypes, pTargets,
cFiles, hptrDrag, vkTerm, fSourceRender,
ulReserved);
This example calls the DrgDragFiles function to begin direct manipulation for a single file object, using the same source and target name, and determining the file type based on the file's type EA.
#define INCL_WINSTDDRAG /* Direct Manipulation (Drag) Functions */
#define INCL_WININPUT /* Window Input Functions */
#include <os2.h>
BOOL fSuccess; /* Indicate success or failure */
HWND Hwnd; /* Handle of calling window */
PSZ pFiles[1]; /* The names of the files to be dragged */
PSZ pTypes[1]; /* The file types of the files to be */
/* dragged */
PSZ pTargets[1]; /* The target file names */
HPOINTER hptrDrag; /* Icon to display during drag */
pFiles[0] = "FILENAME.EXT"; /* Copy file name to string array */
pTargets[0] = NULL; /* Use source name as target name */
pTypes[0] = NULL; /* Query type EA to determine file type */
fSuccess = DrgDragFiles(Hwnd, pFiles, pTypes, pTargets, 1,
hptrDrag, VK_BUTTON2, FALSE, 0L);