Drag and Drop

Tennis, Anyone ?

After it has been decided that a drag operation is necessary, the application needs to allocate and initialize three structure types: DRAGINFO, DRAGITEM and DRAGIMAGE. (There are actually four; the DRAGTRANSFER structure is used ones a target has been established.) The DRAGINFO structure contains information about the drag as an entity. The DRAGITEM structures describe each object being dragged. Finally, the DRAGIMAGE structures each describe the appearance of the object under the pointer while it is being dragged.
   typedef struct _DRAGINFO     /* dinfo */
   {
      ULONG    cbDraginfo;               /* Size of DRAGINFO and DRAGITEMs*/
      USHORT   cbDragitem;               /* size of DRAGITEM              */
      USHORT   usOperation;              /* current drag operation        */
      HWND     hwndSource;               /* window handle of source       */
      SHORT    xDrop;                    /* x coordinate of drop position */
      SHORT    yDrop;                    /* y coordinate of drop position */
      USHORT   cditem;                   /* count of DRAGITEMs            */
      USHORT   usReserved;               /* reserved for future use       */
   } DRAGINFO;
   typedef DRAGINFO *PDRAGINFO;
In the DRAGINFO structure, cbDraginfo is the size of the DRAGINFO structure in bytes. cbDragitem is the size of the DRAGITEM structure contained therein. usOperation is the default operation that can be, but is not required to be, set by the source and inspected by the target; it is a DO_ constant. hwndSource is the only field not initialized by DrgAllocDragInfo, and is the handle of the window initiating the drag-and-drop operation. xDrop and yDrop are the coordinates of the object as dropped. cdItem specifies the number of DRAGITEM structures stores along with the DRAGINFO structure. usReserved is reserved and must be set to 0.
   typedef struct _DRAGITEM     /* ditem */
   {
      HWND    hwndItem;                  /* conversation partner          */
      ULONG   ulItemID;                  /* identifies item being dragged */
      HSTR    hstrType;                  /* type of item                  */
      HSTR    hstrRMF;                   /* rendering mechanism and format*/
      HSTR    hstrContainerName;         /* name of source container      */
      HSTR    hstrSourceName;            /* name of item at source        */
      HSTR    hstrTargetName;            /* suggested name of item at dest*/
      SHORT   cxOffset;                  /* x offset of the origin of the */
      /*                                      image from the mouse hotspot*/
      SHORT   cyOffset;                  /* y offset of the origin of the */
      /*                                      image from the mouse hotspot*/
      USHORT  fsControl;                 /* source item control flags     */
      USHORT  fsSupportedOps;            /* ops supported by source       */
   } DRAGITEM;
   typedef DRAGITEM *PDRAGITEM;
In the DRAGITEM structure, hwndItem is the handle of the window with which the target should communicate to transfer the information necessary to complete the operation. The only time this would be different from the hwndSource field of the DRAGINFO structure is when an application contains many "standard" windows as a children of the main window. hstrType is the type of the item represented by the DRAGITEM structure. hstrRMF is the rendering mechanism used to transfer the information and format of data being transfered. hstrContainerName is the name of the container that holds the object being dragged. With a file object, for example, this would be the directory where the file resides. hstrSourceName and hstrContainerName is the names of the object at its original location and the suggested name of the object at the target location.  The target does not have to use the suggested name; it is up to the application programmer. cxOffset and cyOffet specify the offset from the hotspot of the pointer to the lower left corner of the image representing the object and is copied here by the system from the corresponding fields in the DRAGIMAGE structure. fsControl specifies one or more DC_ constants describing any special attributes of the objects being dragged. Finally, fsSupportedOps specifies the operations that can be performed as part of the drag - the object may be copied, moved, linked ("shadowed"), and so on.

In the DRAGIMAGE structure, cb specifies the size of the structure in bytes. fl specifies a number of DRG_ constants describing the type of data that is given in this structure.

Initialization Code for Drag and Drop Source.

Things Never Told to the Programmer That Should Have Been.

Direct Manipulation Is a Real Drag

And Now a Word from Our Sponsor

1. Both the source and target must understand at least one common type of each object being dragged.
2. Both the source and target must understand at least one common RMF for each object being dragged.

   BOOL      APIENTRY DrgVerifyType(PDRAGITEM pditem, PCSZ  pszType);
   BOOL      APIENTRY DrgVerifyRMF (PDRAGITEM pditem, PCSZ  pszMech,  PCSZ  pszFmt);
   BOOL      APIENTRY DrgVerifyTrueType (PDRAGITEM pditem, PCSZ  pszType);
   BOOL      APIENTRY DrgVerifyNativeRMF(PDRAGITEM pditem, PSZ pszRMF);

Gotcha! Although the DRAGINFO structure is allocated in shared memory and the pointer is passed to the target, the target cannot access the structure until the DrgAccessDraginfo is called.

Data transfer

Gotcha! We have experienced trouble using the pdriv field of the pdosData field of the PRINTDEST structure passed in as a pointer in mpParm2 for the DM_PRINTOBJECT message; the printer consistently rejects the data as being invalid when we call DevOpenDC. Unfortunately, one cannot simply call DevPostDeviceModes (see Chapter 25  for more information) to get a good set of driver data, because the device name is not specified anywhere. The workaround is to call SplQueryQueue first using the queue name in pszLogAddress field of the pdosData field of the PRINTDEST structure to get the PRQINFO3 structure containing the device name.

A Concrete Example

A lot of material has been explained so far, and an example is sorely needed to cross the boundary from the abstract to the applied. The following  application can act as both source and target for direct manipulation. While it is a simple program, it demonstrates the concepts previously described. DRAG1.C DRAG1.MAK DRAG1.DEF Since main is fairly standard, we'll ignore it except for the fact that we're reserving space for a pointer in a call to WinRegisterClass. This will be used to store a pointer to the client's instance data, so that we can avoid global variables. This instance data is allocated and initialized in the WM_CREATE message and is freed in the WM_DESTROY message. typedef struct _CLIENTINFO { PDRAGINFO        pdiDrag;    BOOL             bDragging;    BOOL             bEmphasis;    CHAR             achLine[256]; } CLIENTINFO,*PCLIENTINFO; The pdiDrag field is used only by the source window and points to the DRAGINFO structure allocated via DrgAllocDraginfo. bDragging  and bEmphasis specify whether a dragging operation is in progress and whether the client is displaying emphasis, respectively. achLine  is used only by the target window and contains the line of text that was dropped on the window. for clarity, the processing of the direct-manipulation messages has been separated into those usually associated with the source and the target windows. (See doSource and  doTarget.)
What the program does is allow the dragging of text from the left half of the window into either the right half of this window or another instance of this window. (Try starting two copies of DRAG1.EXE to do this.)  Whenever the source receives a WM_BEGINDRAG message, the appropriate data structures are initialized and DrgDrag is called. The target adds emphasis whenever it receives a DM_DRAGOVER message and returns the appropriate DOR_ value. After the object  has been dropped, the target completely renders the data provided by the source and sends the source a DM_ENDCONVERSATION message to terminate the dragging operation.

Gotcha! It needs to be stated somewhere, and what a better place than here, that there appears to be a bug in OS/2  Warp when using DRG_BITMAP for the DRAGIMAGE to be displayed. The first time the drag and drop is performed, everything works fine; but if the application is exited and restarted, dragging the object using DRG_BITMAP leaves "mouse droppings" behind, making the display quite ugly. We have no information regarding the availability of a fix.

Gotcha! Another important item is that the cxOffset and cyOffset fields of the DRAGITEM structure cannot be used for the programmer's own purposes, since  DrgDrag copies the corresponding fields from the DRAGIMAGE structure here. Likewise,  hwndItem should specify a valid window handle, or unexpected results will occur. Any associated structures that need to be "attached" to a  DRAGITEM structure may do so safely by casting the structure to a ULONG and passing the pointer to the ulItemID field.

More Cement, Please

DRAG2.C
DRAG2.MAK
DRAG2.DEF

   PDRAGTRANSFER APIENTRY DrgAllocDragtransfer(ULONG cdxfer);

   typedef struct _DRAGTRANSFER     /* dxfer */
   {
      ULONG      cb;                     /* size of control block         */
      HWND       hwndClient;             /* handle of target              */
      PDRAGITEM  pditem;                 /* DRAGITEM being transferred    */
      HSTR       hstrSelectedRMF;        /* rendering mech & fmt of choice*/
      HSTR       hstrRenderToName;       /* name source will use          */
      ULONG      ulTargetInfo;           /* reserved for target's use     */
      USHORT     usOperation;            /* operation being performed     */
      USHORT     fsReply;                /* reply flags                   */
   } DRAGTRANSFER;
   typedef DRAGTRANSFER *PDRAGTRANSFER;

DrgDragFiles

   BOOL      APIENTRY DrgDragFiles(HWND hwnd,
                                   PCSZ  *apszFiles,
                                   PCSZ  *apszTypes,
                                   PCSZ  *apszTargets,
                                   ULONG cFiles,
                                   HPOINTER hptrDrag,
                                   ULONG vkTerm,
                                   BOOL fSourceRender,
                                   ULONG ulRsvd);

From the Top Now

Pickup and Drop

• The operation is initiated by holding down the Alt key in addition to using direct manipulation mouse button.
• Instead of receiving a WM_BEGINDRAG message, the potential source window receives a WM_PICKUP message.
• Whereas in modal operation all objects to be dragged must be selected before beginning the operation, in pickup and drop, objects can be added to the pickup set dynamically. In OS/2 Warp, however, all objects must originate from the same source window.
• Because the mouse is still usable after the pickup is initiated, the operation can not be ended by releasing the mouse button like the modal operation is ended in this fashion. The only way to end a direct manipulation operation is to call DrgCancelLazyDrag function. And since the user must communicate to the program that the operation is to be canceled, the most common method of indicating this is through a menu item.
• Another change that is related to using the mouse is the use of the DRAGIMAGE structures. Since the operation is modeless, the pointer displayed is still subject to the WinSetPointer function (via the WM_MOUSEMOVE and WM_CONTROLPOINTER messages). Thus, instead of displaying the DRAGIMAGEs provided by the application initiating the operation, the mouse pointer is only slightly augmented to indicate that the operation is in progress. The DRAGIMAGEs structures are still passed to the DrgLazyDrag function for "compatibility" with the parameter list given to DrgDrag but the are not used.
• Because the user could request help for any subject during a lazy drag, the DM_DROPHELP message will not be sent during a lazy drag. Help can only be provided via a menu item, for example, and it is the programmer's responsibility to code this support explicitly.
• Because the operation can potentially take a long time to complete, DrgLazyDrag returns immediately and the source window is sent a DM_DROPNOTIFY message whenever the user "drops" the objects on a target window via some interface (e.g. menu item). This is probably the most significant change of which the programmer needs to be aware.
  

Functions Used for Lazy Drag

   PDRAGINFO APIENTRY DrgReallocDraginfo (PDRAGINFO pdinfoOld,  ULONG cditem);

   PDRAGINFO APIENTRY DrgQueryDraginfoPtr( PDRAGINFO pRsvd );

   PDRAGINFO APIENTRY DrgQueryDraginfoPtrFromDragitem( PDRAGITEM pditem );

   PDRAGINFO APIENTRY DrgQueryDraginfoPtrFromHwnd( HWND hwndSource );

   ULONG APIENTRY DrgQueryDragStatus(VOID);

   BOOL APIENTRY DrgLazyDrag( HWND hwndSource,
                              PDRAGINFO pdinfo,
                              PDRAGIMAGE pdimg,
                              ULONG cdimg,
                              PVOID pRsvd );

   BOOL APIENTRY DrgLazyDrop( HWND hwndTarget,
			      ULONG ulOperation,                            
		              PPOINTL pptlDrop );   

  BOOL APIENTRY DrgCancelLazyDrag( VOID );

Gotcha! With the DrgQueryDraginfoPtr, DrgQueryinfoPtrFromHwnd and DrgQueryDraginfoPtrFromDragitem functions, the application must still call DrgAccessDragInfo to get access to the structure returned.

Gotcha! Be sure that if you initiate a lazy drag operation it is  either completed or canceled before your application terminates. The authors noticed that when the sample application (see below) was terminated without doing this that the direct manipulation subsystem seemed to get confused and no longer worked correctly.

Gotcha! The Workplace Shell seems to be able to correctly determine if a lazy drag operation is in progress because it offers a "Cancel drag" menu item on context-sensitive menus. However, selecting the menu item has no apparent effect. We cannot determine why this happens. (?)

Lazy Drag Sample

      case  WM_PICKUP :
      case  DM_DROPNOTIFY :
      case  DM_ENDCONVERSATION :
         return  doSource(hwndClient, 
                          ulMsg, 
                          mpParm1, 
                          mpParm2);

      case  DM_DRAGOVER :
      case  DM_DRAGLEAVE :
      case  DM_DROP :
      case  DM_DROPHELP :
      case  MYM_DEWDROP :
      case  WM_CONTEXTMENU :
      case  WM_MENUEND :
      case  WM_COMMAND :
         return  doTarget(hwndClient, 
                          ulMsg, 
                          mpParm1, 
                          mpParm2);

      case  WM_PICKUP :
         {
            RECTL            rclWindow;
            FILE             *pfFile;
            DRAGITEM         diItem;
            DRAGIMAGE        diImage;
            BOOL             bSuccess;

            if (DrgQueryDragStatus() == DGS_LAZYDRAGINPROGRESS)
            {
               return  MRFROMSHORT(FALSE);
            }                          /* endif                */

            bSuccess = DrgLazyDrag(hwndClient, 
                                   pciInfo->pdiDrag, 
                                   &diImage, 
                                   1L, 
                                   NULL);

      case  WM_CONTEXTMENU :
         {  POINTL           ptlPoint;
            RECTL            rclWindow;
            HWND             hwndMenu;

            if (DrgQueryDragStatus() == DGS_LAZYDRAGINPROGRESS)
            {  WinQueryPointerPos(HWND_DESKTOP, 
                                  &ptlPoint);

               WinQueryWindowRect(hwndClient, 
                                  &rclWindow);

               if (ptlPoint.x < rclWindow.xRight/2)
               {   return  MRFROMSHORT(FALSE);
               }                       /* endif                */

               hwndMenu = WinLoadMenu(HWND_OBJECT, 
                                      NULLHANDLE, 
                                      M_LAZYDRAG);

               WinPopupMenu(HWND_DESKTOP, 
                            hwndClient, 
                            hwndMenu, 
                            ptlPoint.x, 
                            ptlPoint.y, 
                            0, 
                            PU_MOUSEBUTTON1|PU_KEYBOARD);
            }                          /* endif                */
         } 
         break;
      case  WM_MENUEND :
         if (SHORT1FROMMP(mpParm1) == FID_MENU)
         {   WinDestroyWindow(HWNDFROMMP(mpParm2));
         }                             /* endif                */
         break;
      case  WM_COMMAND :
         switch (SHORT1FROMMP(mpParm1))
         {     case  MI_DROP :
               {  POINTL           ptlPoint;
                  WinQueryPointerPos(HWND_DESKTOP, 
                                     &ptlPoint);
                  DrgLazyDrop(hwndClient, 
                              DO_DEFAULT, 
                              &ptlPoint);
               } 
               break;
            case  MI_CANCELDRAG :
               DrgCancelLazyDrag();
               break;
            default  :
               return  WinDefWindowProc(hwndClient, 
                                        ulMsg, 
                                        mpParm1, 
                                        mpParm2);
         }                             /* endswitch            */
         break;

      default  :
         break;

   }                                   /* endswitch            */