home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Professional / OS2PRO194.ISO / os2 / prgramer / wf_expl / wfdrag.doc < prev    next >
Text File  |  1992-05-02  |  13KB  |  601 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.                                                                     WORKFRAME/2
  14.                                                           DRAG/DROP CONVENTIONS
  15.  
  16.                                                                         DRAFT 2
  17.  
  18.  
  19.  
  20.  
  21.  
  22.  
  23.  
  24.                                                                     May 2, 1992
  25.  
  26.  
  27.  
  28.  
  29.                                                                             LTC
  30.                                                              Toronto Laboratory
  31.                                                        VNET  - KEHM at TOROLAB6
  32.                                                  email - workframe@vnet.ibm.com
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.  
  71.  
  72.  
  73.   CONTENTS
  74.   ________
  75.  
  76.  
  77.  
  78.  
  79.  
  80.  
  81.  
  82.  
  83.  
  84.  
  85.  
  86.  
  87.  
  88.  
  89.  
  90.  
  91.  
  92.  
  93.  
  94.  
  95.  
  96.  
  97.  
  98.  
  99.  
  100.  
  101.  
  102.  
  103.  
  104.  
  105.  
  106.  
  107.  
  108.  
  109.  
  110.  
  111.  
  112.  
  113.  
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.  
  130.                                                                    Contents  ii
  131.  
  132.  
  133.  
  134.  
  135.  
  136.  
  137.  
  138.  
  139.  
  140.   FIGURES
  141.   _______
  142.  
  143.  
  144.  
  145.  
  146.  
  147.  
  148.  
  149.  
  150.  
  151.  
  152.  
  153.  
  154.  
  155.  
  156.  
  157.  
  158.  
  159.  
  160.  
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.  
  196.  
  197.                                                                    Figures  iii
  198.  
  199.  
  200.  
  201.  
  202.  
  203.  
  204.  
  205.  
  206.  
  207.   WORKFRAME/2 EXTERNAL DRAG CONVENTIONS
  208.   _____________________________________
  209.  
  210.  
  211.  
  212.  
  213.  
  214.   WorkFrame/2 will use the OS/2 provided Drag/Drop API's as both a source and a
  215.   target for Dragging operations.
  216.  
  217.   WorkFrame/2 supports the dragging of files and of compiler error messages.
  218.   The first chapter of this document discusses the conventions for dragging
  219.   files to and from Workframe/2 windows. The second chapter discusses the drag-
  220.   ging of error messages from a monitor window to an external tool.
  221.  
  222.  
  223.  
  224.  
  225.  
  226.  
  227.  
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.  
  262.  
  263.  
  264.                                        WorkFrame/2 External Drag Conventions  1
  265.  
  266.  
  267.  
  268.  
  269.  
  270.  
  271.  
  272.  
  273.  
  274.   DRAGGING FILES
  275.   ______________
  276.  
  277.  
  278.  
  279.  
  280.  
  281.   TARGET CONVENTIONS
  282.   __________________
  283.  
  284.  
  285.   VALID TARGET WINDOWS:
  286.  
  287.   1.  Project File List
  288.  
  289.       This semantic is to copy the file into the directory associated with the
  290.       project.
  291.  
  292.   2.  File Control
  293.  
  294.       This semantic is to copy the file or directory into the directory indi-
  295.       cated as the current directory in that window.
  296.  
  297.   WorkFrame/2 will support operations (as contained in the DRAGINFO structure)
  298.   of DO_COPY or DO_DEFAULT. Any other operations will be flagged as
  299.   DOR_NODROPOP in response to DM_DRAGOVER messages.
  300.  
  301.   For each item provided, WorkFrame/2 will only accept a drag if all items are
  302.   DO_COPYABLE, if not DOR_NODROPOP will be returned.  WorkFrame/2 will only
  303.   support a rendering mechanism of DRM_OS2FILE with a format of either DRF_TEXT
  304.   or DRF_UNKNOWN. Any others will return DOR_NEVERDROP to DM_DRAGOVER messages.
  305.   WorkFrame/2 will examine the control flags and reject the drag if DC_REF or
  306.   DC_GROUP is on. It will interpret a DC_CONTAINER request as a directory. That
  307.   is the container name plus the source name will be a directory name.
  308.   WorkFrame/2 will eventually issue a DosCopy for the source file or directory.
  309.  
  310.   If a drag structure passes the criteria described above, WorkFrame/2 will
  311.   assume the following conventions with respect to the contents of each
  312.   DRAGITEM structure.
  313.  
  314.  
  315.   TARGET RENDERING
  316.  
  317.   If the source handle is provided, WorkFrame/2 will attempt to build a fully
  318.   qualified name for the source and target of the file copy operation. If the
  319.   container handle is not NULL, the source name will be concatenated to the
  320.   container name to create a fully qualified source name, otherwise the
  321.   sourcename will be assumed to be fully qualified. If the target name is pro-
  322.   vided it will be assumed to be unqualified and it will be concatenated to the
  323.   directory name associated with the target window.  If it is not provided,
  324.   then the sourcename will be assumed to be unqualified and used as the target
  325.   name. This string will be concatenated to the project directory name to
  326.   create a fully qualified name.  A copy operation will take place. After the
  327.   copy completes, a DM_ENDCONVERSATION message will be sent to the source, MP1
  328.   containing the item number supplied in the DRAGITEM structure and MP2 will
  329.   contain DMFL_TARGETSUCCESSFUL or DMFL_TARGETFAIL as appropriate.
  330.  
  331.  
  332.                                                               Dragging Files  2
  333.  
  334.  
  335.  
  336.  
  337.  
  338.  
  339.  
  340.  
  341.  
  342.   SOURCE RENDERING
  343.  
  344.   If the source handle is not provided, WorkFrame/2 will attempt to communicate
  345.   with the source to complete the rendering.  WorkFrame/2 will make this deter-
  346.   mination by examining the first item in the array of DRAGITEM structures. If
  347.   the first item requires source rendering then it will be assumed that all
  348.   items require source rendering. That is, WorkFrame/2 will NOT support a
  349.   mixture of source and target rendering items in the same DRAGINFO structure.
  350.  
  351.   A transfer structure will be build with a rendering mechanism of
  352.   DRM_OS2FILE,DRF_UNKNOWN. The rendertoname will be the current project direc-
  353.   tory name concatenated with the target name, if one is provided.  If one is
  354.   not provided then the directory name followed by a backslash will be pro-
  355.   vided.  The operation will be DO_COPY.  If the source requested DC_PREPARE a
  356.   DM_RENDERPREPARE message will be sent first. If the DM_RENDERPREPARE message
  357.   returns FALSE then the DM_RENDER message will not be sent (a
  358.   DM_ENCONVERSATION message will NOT be sent either).  A DM_RENDER message will
  359.   be sent. If the reply flags are set WorkFrame/2 will not support retry.
  360.   Therefore in this case if DMFL_RENDERRRETRY is set, a DM_RENDERCOMPLETE fol-
  361.   lowed by a DM_ENDCONVERSATION message will be sent. If the DMFL_NATIVERENDER
  362.   bit is set alone, then a WorkFrame/2 will attempt a NATIVERENDER if the
  363.   source file handle has now been provided. In anycase a DM_ENDCONVERSATION
  364.   message will be sent to the source with DM_TARGETSUCCESSFUL or DM_TARGETFAIL
  365.   as appropriate.  If the flags are not set then the WorkFrame/2 will send a
  366.   DM_ENDCONVERSATION message.
  367.  
  368.   To net it out, if DM_RENDER returns TRUE, the WorkFrame will expect a
  369.   DM_RENDERCOMPLETE message. If DM_RENDER returns FALSE WorkFrame/2 will take
  370.   the appropriate action based on the flags BUT will NOT expect a
  371.   DM_RENDERCOMPLETE message.  In any rendering scenario BOTH sides must free
  372.   their access to the Drag transfer structure. WorkFrame/2 will do it when
  373.   receiving a DM_RENDERCOMPLETE message or when FALSE is returned from
  374.   DM_RENDER.
  375.  
  376.   WorkFrame/2 will keep track of a count of the items being rendered (either
  377.   natively or with cooperation) and will free the drag structures once all are
  378.   processed.
  379.  
  380.  
  381.   MESSAGES PROCESSED BY SOURCE
  382.  
  383.   1.  DM_DRAGOVER
  384.  
  385.       Workframe/2 will determine if the objects are droppable (as described
  386.       above). Only if all operations and all rendering mechanisms are supported
  387.       will DOR_DROP be returned.
  388.  
  389.   2.  DM_DROP
  390.  
  391.       Workframe/2 will support rendering as described above, both Target and
  392.       Source rendering are supported.
  393.  
  394.   3.  DM_DROPHELP
  395.  
  396.  
  397.  
  398.                                                               Dragging Files  3
  399.  
  400.  
  401.  
  402.  
  403.  
  404.  
  405.  
  406.  
  407.  
  408.       A message box will be displayed describing what kind of operation is sup-
  409.       ported.
  410.  
  411.   4.  DM_RENDERCOMPLETE
  412.  
  413.       This will occur only when the source has not provided a source file name.
  414.       WorkFrame/2 will examine the source handle, if the handle is NULL it will
  415.       assume that the file has been completely processed by the source and will
  416.       simply return a DM_ENDCONVERSATION. If it is provided then it is assumed
  417.       that the source has updated the container and source string fields and
  418.       WorkFrame/2 will perform the copy operation as described above.
  419.  
  420.  
  421.  
  422.   SOURCE CONVENTIONS
  423.   __________________
  424.  
  425.  
  426.   VALID SOURCE WINDOWS
  427.  
  428.   1.  Project File List
  429.  
  430.   2.  File Control
  431.  
  432.   WorkFrame/2 will build a Draginfo structure containing one dragitem structure
  433.   for each file selected on the project file list.  The DRAGINFO structures
  434.   operation field will be set to DO_COPY.  WorkFrame/2 will not support a move
  435.   operation, that is it will assume its list of files is still valid after a
  436.   successful drag operation.
  437.  
  438.   Each Dragitem structure will be set up as follows:
  439.  
  440.   o   item
  441.  
  442.       Handle of the file list window. Parent is the desktop, owner is the
  443.       WorkFrame primary window.
  444.  
  445.   o   itemid
  446.  
  447.       listbox item being dragged (number in listbox for future deselection).
  448.  
  449.   o   type
  450.  
  451.       Will always be DRT_UNKNOWN
  452.  
  453.   o   rendering mechanism and format
  454.  
  455.       DRM_OS2FILE,DRF_UNKNOWN
  456.  
  457.   o   containername
  458.  
  459.       Workframe/2 will place the handle of the source directory of the file
  460.       being dragged. The directory name will always contain a trailing back-
  461.       slash.
  462.  
  463.  
  464.  
  465.                                                               Dragging Files  4
  466.  
  467.  
  468.  
  469.  
  470.  
  471.  
  472.  
  473.  
  474.  
  475.   o   sourcename
  476.  
  477.       Workframe/2 will place the handle of the UNQUALIFIED source filename.  To
  478.       fully qualify the filename concatenate sourcename to containername.
  479.  
  480.   o   suggested targetname
  481.  
  482.       Workframe/2 will place the sourcename handle here. As a result the
  483.       targetname = sourcename = unqualified name.
  484.  
  485.   o   control
  486.  
  487.       Will always be zero.
  488.  
  489.   o   supported operations
  490.  
  491.   o   DO_COPYABLE only.
  492.  
  493.  
  494.   MESSAGES PROCESSED BY SOURCE
  495.  
  496.   For each file processed by the Target, WorkFrame/2 will expect a
  497.   DM_ENDCONVERSATION message. MP1 must contain the item number provided by
  498.   WorkFrame2 in the DRAGITEM structure.  MP2 will contain DMFL_TARGETSUCCESSFUL
  499.   if the operation worked or DMFL_TARGETFAIL if the operation failed.
  500.  
  501.  
  502.   INTERNAL DRAG/DROP
  503.   __________________
  504.  
  505.   All other windows that participate in drag/drop will only accept internally
  506.   defined types and rendering mechanisms.  These will not be documented and
  507.   will only work intra-application.
  508.  
  509.  
  510.   PRINTING
  511.   ________
  512.  
  513.   WorkFrame/2 will NOT support a DRM_PRINT rendering mechanism and it will not
  514.   handle a DM_PRINT message. The assumption that if the user drives files
  515.   (DRM_OS2FILE,DRF_UNKNOWN) to a target that only supports the print operation.
  516.   That target should perform the print operation without any source inter-
  517.   action. The rationale for this is the elimination of the requirement for all
  518.   participating sources to provide code that prints files.
  519.  
  520.  
  521.  
  522.  
  523.  
  524.  
  525.  
  526.  
  527.  
  528.  
  529.  
  530.  
  531.  
  532.  
  533.                                                               Dragging Files  5
  534.  
  535.  
  536.  
  537.  
  538.  
  539.  
  540.  
  541.  
  542.  
  543.   DRAGGING COMPILER ERROR MESSAGES
  544.   ________________________________
  545.  
  546.  
  547.  
  548.  
  549.  
  550.   When a drag operation is started from a monitor window, WorkFrame/2 will
  551.   invoke the compiler-provided error parsing interface. If the parsing is suc-
  552.   cessful, WorkFrame/2 will begin a drag operation setting up the Draginfo
  553.   structure to specify DO_DEFAULT and to contain exactly one DRAGITEM struc-
  554.   ture. The DRAGITEM structure will be set up as follows:
  555.  
  556.   ITEM                Monitor window handle
  557.  
  558.   ITEMID              0
  559.  
  560.   TYPE                DRT_TEXT
  561.  
  562.   RMF                 <DRM_DDE,DDE3ERRORS>
  563.  
  564.   CONTROL             0
  565.  
  566.   SUPPORTEDOPS        DO_COPYABLE
  567.  
  568.   CONTAINERNAME       handle of string containing project directory with a
  569.                       trailing backslash.
  570.  
  571.   SOURCENAME          handle of string containing file in error, this name may
  572.                       or may not be fully qualified depending on the compiler.
  573.                       It is the name extracted from the error message and is
  574.                       the name the receiver of the drag should use as the topic
  575.                       for the subsequent DDE handshaking.
  576.  
  577.   TARGETNAME          0
  578.  
  579.   XOFFSET             Not set
  580.  
  581.   YOFFSET             Not set
  582.  
  583.   Once the target accepts the drag, it should post itself a message to perform
  584.   the DDE conversation. That is the DDE conversation should not be started
  585.   until you return from receiveing the DM_DROP message.  For information on the
  586.   DDE protocols required please refer to the WorkFrame/2 Programming Interface
  587.   Document. A sample program using drag and drop of error messages and handling
  588.   the DDE protocols is available from the author.
  589.  
  590.  
  591.  
  592.  
  593.  
  594.  
  595.  
  596.  
  597.  
  598.  
  599.  
  600.                                             Dragging Compiler Error Messages  6
  601.