home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / drgfil.zip / drgfiles.doc < prev    next >
Text File  |  1993-07-31  |  8KB  |  147 lines
  1. DRGFILES.EXE is a sample program for OS/2 Drag/Drop facilities (aka Direct
  2. Manipulation). It implements the DrgDragFiles and DrgAcceptDroppedFiles API's
  3. which together provide the simplest way to implement Drag and Drop. Of course
  4. with simplicity comes limitations. The following are the limitations of using
  5. these API's to implement Drag and Drop:
  6.  
  7.  
  8.   1. Only filenames can be dragged/dropped. Therefore anything you drag must
  9.      be able to be represented by a file name.
  10.   2. Source printing of dragged files is not supported. When you drag a file
  11.      to the printer using DrgDragFiles, the printer is in full control of the
  12.      printing of the file. Therefore the filename that is being dragged must
  13.      be in a format that can be printed native by the printer objects. When the
  14.      user drops the icon on the printer, the printer will ask the user what
  15.      type of file it is, etc. if that information is not embedded in the drag
  16.      info or attached to the file's EA's. Under normal Drag/Drop, your window
  17.      can choose to do the printing itself. With DrgDragFiles your window
  18.      doesn't have that option.
  19.   3. Source shredding of dragged files is not supported. Again, the shredder
  20.      will try and delete your file. There is no way for your program to take
  21.      part in the delete. This is important because your program's window will
  22.      not be able to remove the bitmap representing the file since it doesn't
  23.      know that the object was dropped on the shredder.
  24.   4. Only 1 image is allowed under the mouse pointer during the drag. Usually
  25.      on a multiple-item drag the user expects more than one icon to be under
  26.      the mouse pointer during the drag. You can't do that using DrgDragFiles.
  27.      This API allows only one icon handle.
  28.   5. There are currenty many bugs in this API pair that cause PMDRAG.DLL to
  29.      trap (as of 2.1GA in September 1993) if more than 1 file is dropped or
  30.      rendering is done. Therefore I've only been able to get it to work
  31.      reliably by dragging one file at a time and not rendering. These are of
  32.      course major limitations but they are bugs and will hopefully be fixed.
  33.  
  34. The most obvious advantage to using these API's is their simplicity.
  35.  
  36. A MAJOR advantage to using these simple API's is that you are excused from
  37. the duties of freeing the drag/drop structures when the drag/drop is done. So
  38. if your app can live with the above limitations, you should seriously consider
  39. using these API's.
  40.  
  41. DRGFILES creates 2 frame windows. One of the windows plays the role of a 'drag'
  42. window, the other plays the role of a 'drop' window. Their roles are not
  43. interchangeable. The 'Drag' frame window has a container control as its client
  44. window and that container has 5 icons that can be dragged to the 'drop' window.
  45. The 'Drop' frame window has a normal client window. The client window has a
  46. container control as a child and the container takes up the right half of the
  47. client window. The left half is where you will drop the icons from the drag
  48. container. When the icon is dropped on the client area, it is added to the
  49. 'Drop' container. If it was a 'move' operation, it is removed from the 'drag'
  50. container.
  51.  
  52. There are currently 2 major OS/2 bugs that impact this sample program:
  53.  
  54.  1. When dropping more than one icon on the 'drop' window's client area,
  55.     PMDRAG.DLL traps when processing the second file. Therefore the 'drag'
  56.     container was implemented with CCS_SINGLESEL, meaning only one item can
  57.     be selected at any given time. DRGFILES.C has a global variable named
  58.     flSelType that is currently set to CCS_SINGLESEL. You can change it to
  59.     CCS_EXTENDSEL if you want to see the trap or if you want to test it after a
  60.     new release of OS/2 comes out. All the code is in the program to allow more
  61.     than one item to be dragged. The only thing stopping it is that CCS_ flag.
  62.  
  63.  2. When rendering is enabled, PMDRAG.DLL traps when the source sends the
  64.     target a DM_FILERENDERED message after doing the rendering. Therefore
  65.     rendering is disabled, yet all the code remains if you choose to re-enable
  66.     it. To enable rendering, set the fRender global variable in drgfiles.c to
  67.     TRUE. It is currently set to FALSE.
  68.  
  69. The reason that containers are used is not to make the program more complex. On
  70. the contrary, containers make Drag/Drop easier to program because the app does
  71. not have to draw representations of things that can be dragged and dropped. The
  72. container provides simple facilities to place draggable icons into its window.
  73.  
  74. To run this sample program, type DRGFILES on the command line. The 2 windows
  75. will appear on the bottom of your display. The left-hand container is the 'drag'
  76. container, the right one is the 'drop' container. Drag one or more icons from
  77. the 'drag' container to the 'drop' window and drop on the part of the 'drop'
  78. window that says 'DROP IT HERE'. When you do, the icon will appear
  79. in the 'drop' window's container. The default is to 'copy' the file. If you
  80. press the Shift key while dragging, the default will change to be a 'move'. In
  81. that case, the icon will be removed from the source container at drop time.
  82.  
  83. When the target window first comes up it calls DrgAcceptDroppedFiles to
  84. 'register' with PMDRAG.DLL so that PMDRAG can do all the low-level Drag/Drop
  85. stuff. When the source window's container gets a WM_BEGINDRAG message, it sends
  86. a WM_CONTROL/CN_INITDRAG message to its owner, the frame window. At that time
  87. the frame calls DrgDragFiles and they're off and running.
  88.  
  89. Here is the message flow:
  90.  
  91.     SOURCE                                    TARGET
  92.     ──────                                    ──────
  93.                                               call DrgAcceptDroppedFiles
  94.  
  95.     CN_INITDRAG...call DrgDragFiles.........
  96.     ..................( user drops files )... DM_DRAGFILECOMPLETE
  97.     DM_DRAGFILECOMPLETE......................
  98.  
  99. There is one DM_DRAGFILECOMPLETE message for each file that was dropped.
  100.  
  101. Very simple, no?
  102.  
  103. If rendering is enabled there is just slightly more to it:
  104.  
  105.  
  106.     SOURCE                                    TARGET
  107.     ──────                                    ──────
  108.                                               call DrgAcceptDroppedFiles
  109.  
  110.     CN_INITDRAG...call DrgDragFiles.........
  111.     ..........( user drops files )..........
  112.     DM_RENDERFILE.. (source renders file)...
  113.     source sends DM_FILERENDERED to target..  DM_FILERENDERED
  114.                                               DM_DRAGFILECOMPLETE (from PMDRAG)
  115.     DM_DRAGFILECOMPLETE (from PMDRAG).......
  116.  
  117. DM_RENDERFILE happens for each file, as does DM_FILERENDERED and
  118. DM_DRAGFILECOMPLETE.
  119.  
  120. This is basically it. PMDRAG knows that filenames are being dragged so it can
  121. do all the move/copy/delete file operations for you. If you use rendering,
  122. you do those operations. If an error happens during a file operation, the
  123. appropriate window gets a DM_DRAGERROR message.
  124.  
  125.  
  126. DRGFILES.EXE is built from 3 source modules:
  127.  
  128. DRGFILES.C - base code that has the message queue and supporting functions.
  129. SRCWIN.C   - creates the source window and handles the Drag/Drop for it.
  130. TRGWIN.C   - creates the target window and handles the Drag/Drop for it.
  131.  
  132. Hope this sample program helps someone.
  133.  
  134. ===============================================================================
  135. GLOBAL HISTORY
  136.  
  137. 7-31-93 - Completed coding.
  138.  
  139. ===============================================================================
  140.  
  141. Rick Fishman
  142. Code Blazers, Inc.
  143. 4113 Apricot
  144. Irvine, CA 92720
  145.  
  146. CIS ID: 72251,750
  147.