PMGuide - Direct Manipulation
Direct manipulation is the act of moving graphical representations such as OS/2 icons around the screen using a pointing device, such as a mouse. This chapter explains how to use direct manipulation in PM applications.
About Direct Manipulation
The direct manipulation protocol enables the user to select an object in a window, drag it to another location, and drop it on another object or in another window. Dragging is the act of moving an object as though it were attached to the pointer; it is performed by pressing and holding the drag button and moving the pointer. Dropping is the act of fixing the position of the dragged object by releasing the drag button on the pointer. This causes interaction (data exchange) between the window from which the selected object is dragged and the window containing the object on which the selected object is dropped.
The window containing the dragged object is the source. The window containing the object that was dropped on is the target. The source and target can be the same window, different windows within the same application, or windows belonging to different applications. The dragged object can be either the only visible object in the source window or one of many objects. The target object can be either the only visible object in the target window or one of many objects. A source or target window that contains multiple objects is a container window.
The data exchange that occurs between the source and target after a direct manipulation operation enables applications that support the protocol to integrate easily, while providing a simple user interface.
Application-Defined Drag Operations
At times it may be useful for an application to define its own drag operation to facilitate functions between two windows in the same application or between closely related applications. For example, an application implementing a keyboard remapping function may want to provide a method of redefining keys with direct manipulation. This application could define an operation whereby dragging one key to another exchanges the definitions of the two keys. The protocol provides the extendability to enable this kind of function.
Rendering Mechanism and Format
The rendering mechanism represents the way in which you want to exchange the data, for example, dynamic data exchange (DDE). The rendering format identifies the actual type or true type of the data, for example, text. To exchange data, both the source and target must know how to communicate with each other through the rendering mechanism and understand the particular format of the data.
The native rendering mechanism and format of the object is the mechanism that most naturally conveys the data, either where it is now, or where it can be put most easily. The format conveys all information about the data. For example, a spreadsheet cell has a location in a row and column of a spreadsheet. Rendering the spreadsheet cell in a simple text format would cause this information to be lost, so a more appropriate format should be chosen for its native rendering format.
A source application may be able to exchange data with a target through several mechanisms, such as:
- Dynamic Data Exchange (DDE)
- OS/2 File
Additionally, the source application might be able to render the data in various formats, that is, into various types. For example, a spreadsheet application could render its contents in a spreadsheet format or into a simple text format. The ability of the source application to render the data in some format might, itself, depend on the exchange mechanism used. The rendering mechanisms and formats that a source application can support, for each object dropped, are provided to the target through the hstrRMF field in the DRAGITEM data structure.
The target application may also be able to exchange data with the source through several different combinations of mechanism and format. The target is responsible for obtaining the data from the source in the format that they both support and that provides the highest level of information about the data.
While making this determination, the target must consider the exchange capabilities offered by the mechanism. For example, an OS/2 File exchange mechanism can provide only a snapshot of the data at the time the direct manipulation operation occurred. An exchange using DDE, on the other hand, offers the target an opportunity to remain informed about changes to the data.
Non-Standard Rendering Mechanisms
Some standard rendering mechanisms are already defined, but the system lets the set of rendering mechanisms be expanded, allowing for:
- Additional standard rendering mechanisms to be defined in the future
- Application definition of private or nonstandard rendering mechanisms
An application can elect to support some, all, or none of the standard rendering mechanisms defined by the system. Applications that do not support any of the standard rendering mechanisms are not precluded from using direct manipulation. However, support of the standard rendering mechanisms and formats increases the chances of a successful data transfer between applications.
An application that supports a particular rendering mechanism, whether or not it is a rendering mechanism defined by the system, must follow a specific set of guidelines defined by that rendering mechanism, including conversation-initiation procedures and naming conventions.
Responsibilities of a Source Application
The source is responsible for starting a direct manipulation operation. Startup can be accomplished only with a pointing device, such as a mouse. The operation starts when the application detects that a drag button has been pressed and the pointing device has moved. Dragging continues until terminated, which is usually when the button is released.
Although the direct manipulation protocol lets the application use any button for dragging, it is recommended that the system-defined drag button be used for direct manipulation operations.
The source has the following responsibilities in preparing for the actual drag of the objects across the screen:
- Allocate and initialize the DRAGINFO data structure that conveys the necessary information about each object to the target.
- Initialize a set of DRAGIMAGE data structures that describe the image to be displayed during the drag operation.
- Make the following information known to the system:
- The type of each object being directly manipulated
- The rendering mechanism and format for each object
- The suggested name of the object at the target
- The name of the container or folder containing the source object
- The name of the object at the source
- The true type of each object being directly manipulated
- The native rendering mechanism and format for each object
Responsibilites of a Target Application
The target in a direct manipulation operation is responsible for determining whether a particular set of objects can be dropped on it, and for providing the user with visible cues regarding the operation. A target is informed of the operation through messages sent to it as the pointer, provided by the source, is dragged across the screen.
When a set of objects is dropped on the target, the target is responsible for establishing the appropriate conversations with the source to accomplish the data transfer. The type of conversation for each object is based on the rendering mechanism and format of the object being dropped.
The target application is responsible for:
- Determining if data can be exchanged between source and target by verifying that both applications share knowledge of at least one rendering mechanism and format
- Providing visible feedback, or target emphasis, on whether a drop is allowed
- Defining the default state of a direct manipulation operation
- Initiating conversations with the source for data transfer
Messages Sent to a Target Application
The following table describes the messages that are sent to each window whose boundaries are crossed as the user drags the object around the screen:
┌────────────────────┬────────────────────────────────────────┐ │Message Name │Description │ ├────────────────────┼────────────────────────────────────────┤ │DM_DRAGOVER │Sent to the window under the pointer as │ │ │the pointer is dragged across it. A │ │ │single DM_DRAGOVER message is sent each │ │ │time the pointer moves and each time a │ │ │key is pressed or released, and it │ │ │contains a pointer to the DRAGINFO data │ │ │structure. The target can access this │ │ │data structure with DrgAccessDraginfo. │ ├────────────────────┼────────────────────────────────────────┤ │DM_DRAGLEAVE │Sent whenever the DM_DRAGOVER message │ │ │has been sent to a window, and the │ │ │pointer is moved outside the bounds of │ │ │that window. If the target or an object │ │ │in the window had been emphasized as a │ │ │target, it should be de-emphasized. │ ├────────────────────┼────────────────────────────────────────┤ │DM_DROP │Sent to the target to provide it with │ │ │the information necessary to establish a│ │ │conversation for data exchange with the │ │ │source. The target should immediately │ │ │remove any target emphasis. The data │ │ │transfers must not be done before │ │ │responding to the DM_DROP message. │ ├────────────────────┼────────────────────────────────────────┤ │DM_DROPHELP │Posted to a target to indicate that the │ │ │user requested help for the drag │ │ │operation while over that target. │ └────────────────────┴────────────────────────────────────────┘
Response to Messages Sent to a Target Application
The following table shows the four possible responses available to the target when it receives a DM_DRAGOVER message. The target sends these values to the window handle specified in the DRAGINFO data structure.
┌────────────────────┬────────────────────────────────────────┐ │Message Name │Description │ ├────────────────────┼────────────────────────────────────────┤ │DOR_DROP │Sent if the objects being dragged are │ │ │acceptable. A drop does not occur unless│ │ │DOR_DROP is returned. │ ├────────────────────┼────────────────────────────────────────┤ │DOR_NODROP │Sent if the objects being dragged are │ │ │acceptable and the target supports the │ │ │current operation, but the objects │ │ │cannot be dropped on the current │ │ │location in the target window. For │ │ │example, a list box might return │ │ │DOR_NODROP if it contains objects that │ │ │can be dropped on, but the pointer is │ │ │over an object that cannot be dropped │ │ │on. │ │ │If the target response is DOR_NODROP, │ │ │the DM_DRAGOVER message continues to be │ │ │sent to the target when: │ │ │o The pointer is moved │ │ │o A keyboard key is pressed │ │ │o The pointer is moved out of │ │ │ and back into the window. │ ├────────────────────┼────────────────────────────────────────┤ │DOR_NODROPOP │Sent if the objects being dragged are │ │ │acceptable, but the target does not │ │ │support the current operation. This │ │ │response implies that the drop may be │ │ │valid if the drag operation changes. For│ │ │example, copying a file to a shredder │ │ │would not be valid, but moving a file to│ │ │a shredder would be. │ │ │Once the target has sent DOR_NODROPOP, │ │ │no further DM_DRAGOVER messages is sent │ │ │to the target until: │ │ │o A keyboard key is pressed │ │ │o The pointer is moved out of │ │ │ and back into the window. │ ├────────────────────┼────────────────────────────────────────┤ │DOR_NEVERDROP │Sent when the objects being dragged are │ │ │not acceptable, and the target will │ │ │never accept them. │ │ │Once the target has sent DOR_NEVERDROP, │ │ │no further DM_DRAGOVER messages are sent│ │ │to that target until the pointer is │ │ │moved out of and back into the target │ │ │window. │ └────────────────────┴────────────────────────────────────────┘
If a reply other than DOR_DROP is received from a target, the augmentation emphasis is automatically changed to indicate that no drop is allowed. This gives the user a visible cue that a drop cannot occur. The emphasis is reverted to drop allowed when a DOR_DROP reply is received from some target.
Two-Object Drag Operation
The following diagram represents the sequence of functions and message flows for a typical direct manipulation operation. The flow shows a two-object drag from App1 to App3, dragging over App2.
The direct manipulation operation is started by the source window procedure after the user selects the objects to be manipulated and the source receives a WM_BEGINDRAG message.
Two-Object Drag
┌─────────────────────────────────────────────────────────────────────────────┐
│ App1 App2 App3 │
└─────────────────────────────────────────────────────────────────────────────┘
. . .
(user select) . . .
────────────────�. . .
. . .
WM_BEGINDRAG . . .
────────────────�. . .
. . .
. . .
DrgAllocDraginfo . .
. . .
DrgAddStrHandle . .
. . .
DrgAddStrHandle . .
. . .
DrgSetDragitem . .
. . .
DrgSetDragitem . .
. . .
DrgDrag . .
. . .
. DM_DRAGOVER . .
.─────────────────────�. .
. . .
. DrgAccessDraginfo .
. . .
. DrgSetDragImage (optional) .
. . .
. (Verify that drop can be accepted) .
. . .
. (Target emphasis on) .
. . .
. DrgFreeDraginfo .
. . .
. . .
. DOR_DROP . .
.�─────────────────────. .
. . .
. DM_DRAGLEAVE . .
.─────────────────────�. .
. . .
. (Target emphasis off) .
. . .
. . .
. . .
. . .
. DM_DRAGOVER .
.─────────────────────────────────────────────�.
. . .
. . DrgAccessDraginfo
. . .
. . DrgSetDragImage (optional)
. . .
. . (Target emphasis on)
. . .
. . .
. . .
. DOR_DROP .
.�─────────────────────────────────────────────.
(WM_ENDDRAG) . . .
────────────────�. . .
. . .
. . .
. DM_DROP .
.─────────────────────────────────────────────�.
. . .
. . .
. . (Target emphasis off)
. . .
(DrgDrag returns) . (Perform operation)
. . .
DrgFreeDraginfo . DrgDeleteDraginfoStrHandles
. . .
. . DrgFreeDraginfo
. . .
. . .
Conversation after the Drop
The following diagram represents the sequence of message flows for a typical direct manipulation data-transfer operation. The flow describes a single-object move from source to target. The user dropped on white space in the target container.
For this example, assume that the rendering mechanism selected is DRM_OS2FILE and that the source does not initially provide the target with the source item's file name. Also assume that the source and target items exist on different drives.
┌───────────────────────────────────────────────────────────────────┐
│ Source Target │
└───────────────────────────────────────────────────────────────────┘
. .
. .
. DrgAllocDragtransfer
. .
. DrgSendTransferMsg
. .
. DM_RENDER .
.�────────────────────────────────────.
. .
Verify the rendering mechanism and format .
. .
DrgAddStrHandle .
(hstrSourceName) .
. .
. DM_RENDER(reply) .
.────────────────────────────────────�.
. .
DosCopy .
. .
DrgFreeDragtransfer .
. .
. DM_RENDERCOMPLETE .
.────────────────────────────────────�.
. .
. DM_ENDCONVERSATION .
.�────────────────────────────────────.
. .
DosDelete DrgFreeDragtransfer
. .
DrgFreeDraginfo DrgDeleteStrHandle
. .
. DrgFreeDraginfo
. .
. .
Canceling a Drag Operation
The user can end a direct manipulation operation in one of the three following ways:
- Pressing the Esc key to cancel the operation
- Releasing the drag button when the pointer is over a target that cannot accept the drop
- This action is equivalent to pressing the Esc key. When the pointer is over a target that can accept the drop, the target is informed of the drop, and the source is given the window handle of the target.
- Pressing the F1 key to request help
- A DM_DROPHELP message is posted to the target. This enables the target to provide the user with assistance regarding:
- What would happen if the user dropped the object on that target
- Why the target cannot accept a particular drop
- The source sees this termination of the direct manipulation operation as a cancelation.
About Pickup and Drop
Pickup and Drop (also known as Lazy Drag) enables a drag operation to occur without requiring that the drag button be pressed for the duration of the operation (as in the standard direct manipulation operation). Pickup and Drop is non-modal in nature, allowing the user to interrupt the drag operation with other processes, and eliminating the requirement that both the source and target objects be visible prior to initiation of the drag operation (as in standard protocol). Pickup and Drop does not replace the standard, modal direct manipulation operation; it offers a more flexible alternative data transfer option.
Pickup and Drop is composed of one or more source object Pickup operations followed by a single Drop operation on a target object. Pickup and Drop is initiated by the first Pickup and is terminated by a Drop or Cancel Drag operation. When Pickup and Drop is initiated, the mouse pointer is augmented with the system Pickup pointer icon.
The drag images seen in a standard direct manipulation operation are not displayed. As additional items are selected, they are added to the system Pickup set, and pickup emphasis is displayed for each item. The Pickup set is currently limited to a single source window or folder. While the operation is in progress, all other operations are valid with the exception of a standard direct manipulation operation.
Pickup and Drop is initiated by DrgLazyDrag in response to a WM_PICKUP message generated when the user presses Alt+mouse button 2 on a source object. As the pointer moves over a potential target, DM_DRAGOVER and DM_DRAGLEAVE messages are sent when the user presses a key indicating the intention to drop the object. The target emphasis is not displayed until the user attempts to drop the object. Each time items are added to the Pickup set in response to a WM_PICKUP message, DrgReallocDraginfo must be called to reallocate the DRAGINFO data structure. The Pickup and Drop operation is then re-initiated by another DrgLazyDrag call. DrgLazyDrag returns upon initialization for the operation. The pointing device remains active during the operation and may be used as if no drag operation were in effect. If the pointer is over a valid target when a Drop is invoked, a DM_DROP message is sent to the target, and a DM_DROPNOTIFY message posted to the source window.
DrgCancelLazyDrag is called to cancel the operation, and similarly posts a DM_DROPNOTIFY message to the source window, but with a target window handle of zero in the mp2 parameter.
DrgLazyDrop can be used to programmatically invoke a drop operation; for example, from a menu choice.
DrgQueryDraginfoPtrFromHwnd and DrgQueryDraginfoPtrFromDragitem are called to query the DRAGINFO pointer at any time during the course of the operation.
DrgQueryDragStatus is called to determine whether a Pickup and Drop operation is currently in progress.
Data Structure Handling
Pickup and Drop (also known as Lazy Drag) enables a drag operation to occur without requiring that the drag button be pressed for the duration of the operation (as in the standard direct manipulation operation). Pickup and Drop is non-modal in nature, allowing the user to interrupt the drag operation with other processes, and eliminating the requirement that both the source and target objects be visible prior to initiation of the drag operation (as in standard protocol). Pickup and Drop does not replace the standard, modal direct manipulation operation; it offers a more flexible alternative data transfer option.
Pickup and Drop is composed of one or more source object Pickup operations followed by a single Drop operation on a target object. Pickup and Drop is initiated by the first Pickup and is terminated by a Drop or Cancel Drag operation. When Pickup and Drop is initiated, the mouse pointer is augmented with the system Pickup pointer icon.
The drag images seen in a standard direct manipulation operation are not displayed. As additional items are selected, they are added to the system Pickup set, and pickup emphasis is displayed for each item. The Pickup set is currently limited to a single source window or folder. While the operation is in progress, all other operations are valid with the exception of a standard direct manipulation operation.
Pickup and Drop is initiated by DrgLazyDrag in response to a WM_PICKUP message generated when the user presses Alt+mouse button 2 on a source object. As the pointer moves over a potential target, DM_DRAGOVER and DM_DRAGLEAVE messages are sent when the user presses a key indicating the intention to drop the object. The target emphasis is not displayed until the user attempts to drop the object. Each time items are added to the Pickup set in response to a WM_PICKUP message, DrgReallocDraginfo must be called to reallocate the DRAGINFO data structure. The Pickup and Drop operation is then re-initiated by another DrgLazyDrag call. DrgLazyDrag returns upon initialization for the operation. The pointing device remains active during the operation and may be used as if no drag operation were in effect. If the pointer is over a valid target when a Drop is invoked, a DM_DROP message is sent to the target, and a DM_DROPNOTIFY message posted to the source window.
DrgCancelLazyDrag is called to cancel the operation, and similarly posts a DM_DROPNOTIFY message to the source window, but with a target window handle of zero in the mp2 parameter.
DrgLazyDrop can be used to programmatically invoke a drop operation; for example, from a menu choice.
DrgQueryDraginfoPtrFromHwnd and DrgQueryDraginfoPtrFromDragitem are called to query the DRAGINFO pointer at any time during the course of the operation.
DrgQueryDragStatus is called to determine whether a Pickup and Drop operation is currently in progress.
Message Handling
In the standard direct manipulation protocol, DrgDrag does not return until the drag set is dropped on a target window. Pickup and Drop is slightly different, and requires a change in the handling of a Drop. Because the operation is non-modal, DrgLazyDrag returns as soon as it has completed drag initialiation and before a drop is performed. In the Pickup and Drop protocol, DM_DROPNOTIFY is posted to the source window as notification of a drop. The parameters of this message contain the pointer to the DRAGINFO data structure allocated by the source window and the handle of the target window. The source window should examine the mp2 parameter to determine if the target window and the source window are the same; if not, the source should free the DRAGINFO upon receipt of this message. Where the target and source are the same, the target window frees DRAGINFO after completing the post-drop conversation. The implementation of Pickup and Drop does not affect any of the existing post-drop conversation messages.
The DM_DROPHELP message is not supported for the Pickup and Drop protocol, because help could be requested for any subject at any point during the operation. If the application is to provide Drop help, it must do so from a menu choice and explicitly code the support to be provided.
About Rendering Mechanisms
The following sections describe the standard rendering mechanisms used by various containers and applications for direct manipulation.
OS/2 File Rendering Mechanism
This rendering mechanism can be used by various containers, including file folders and trash cans. These containers allow objects to be dragged and dropped on white space in the container to accomplish a Move or Copy operation. They also can allow objects in the same or another container to be dragged and dropped on objects within the container to accomplish an operation.
Mechanism Name
The string for this rendering mechanism is DRM_OS2FILE.
Messages
The following messages are used by the DRM_OS2FILE:
- DM_RENDER
- This message is sent by a target to a source to request a rendering for an object. When this message is received, the source determines if it understands the rendering mechanism and format selected by the target for the object. It also confirms that it allows the operation selected by the user for that object. The source must respond to this message before proceeding with the rendering operation.
- DM_RENDERCOMPLETE
- This message is posted by a source to a target to notify the target that the rendering operation has been completed by the source, either successfully or unsuccessfully. The source can elect to let the target retry a successful or an unsuccessful operation. In this case, it should return to its state at the time of the drop for that object and indicate, in the message, that a retry is allowed.
- Support for this message by a source is optional. If this message is not supported, then:
- The source must convey all necessary information to the target in order to allow it to handle the rendering operation.
- It must always indicate that native rendering is allowed when replying to a DM_RENDER message.
- DM_ENDCONVERSATION
- This message is sent by a target to a source to notify the source that the rendering operation is complete and that the conversation is terminated. When this message is received, the entire drop operation for the object is complete. The source can now release any resources it had allocated to the drop and rendering operations. When the reply is received, the target can release the resources it had allocated to the operation.
Native Mechanism Actions
If the target understands the native rendering mechanism and format of the object, it may be possible to render the object without any involvement on the part of the source, provided the source has given the target sufficient information to do so. In order for the rendering to be performed by the target, the source must fill in, at a minimum, the hstrContainerName and hstrSourceName fields. The hstrContainerName field represents the subdirectory that the file indicated by hstrSourceName is in. For the target to do the rendering on its own, the true type of the object must be DTYP_OS2FILE. When these conditions are met, the target may proceed with the operation. When the operation is complete, the target must send a DM_ENDCONVERSATION message to the window indicated by hwndItem in the DRAGITEM data structure.
Preventing a Target from Rendering an Item
A source can prevent a target from doing the rendering operation on its own by not providing the source name for the object. This may be a necessary action for sources that implement some type of security, or that may not allow particular operations to be performed for an object move. When a source takes this course, it must fill in the hstrSourceName in the DRAGITEM data structure before replying to a DM_RENDER message. The target deletes the hstrSourceName string handle prior to freeing the DRAGINFO data structure, just as it would if the information had been passed to it at the time of the drop.
Requesting the Source to Render the Item
Whenever the conditions for a target to do the rendering operation without source participation are not met, the target must request the source to carry out the rendering by posting a DM_RENDER message to the source. Of course, the target can do this even if it is able to carry out the rendering mechanism on its own.
Allocating and Freeing a DRAGTRANSFER Data Structure
The data in a drag transfer message is carried in a DRAGTRANSFER data structure. DRAGTRANSFER data structures are allocated when the target calls DrgAllocDragtransfer.
When the conversation is completed, both the source and the target must call DrgFreeDragtransfer to free the shared memory. The target should do it immediately after sending a DM_ENDCONVERSATION message. The source should do it immediately after sending a DM_RENDERCOMPLETE message.
Operation Specifics
Regardless of the operation being performed, the target must fill in the hstrRenderToName field in the DRAGTRANSFER data structure before sending a DM_RENDER message. This is the fully qualified drive, path, and file name of the file that will contain the data when the rendering operation is complete. When the source has completed the operation, it must post a DM_RENDERCOMPLETE message to the target. The target then must complete the direct manipulation operation for that object by posting a DM_ENDCONVERSATION message to the source. Once the conversations for all of the objects involved in the drop are complete, the target can delete the string handles and free the DRAGINFO data structure.
Non-Native Mechanism Actions
The target may select the DRM_OS2FILE rendering mechanism when it is not the native rendering mechanism for an object, as long as the source supports it. In this case, the target must always request that the source carry out the rendering operation as described above. The source should render the data in the requested format to the file specified by the hstrRenderToName field. If the requested operation is a Move, the source should take whatever action is necessary to remove its knowledge of the object as long as no information regarding the object was lost in the transfer.
Naming Conventions
The naming conventions for this rendering mechanism are as follows:
- hstrContainerName
- Contains the fully qualified drive and path name for the source file, for example:
C:\ C:\MYSUBDIR\ A:\SUBDIR1\SUBDIR2\ \\NETWORK\SHARED\SUBDIRA\SUBDIRB\
- hstrSourceName
- Contains the name of the source file or subdirectory, for example:
MYSOURCE.C MYSOURCE.H MYSOURCE IS A LONG FILE NAME SUBDIR3
If you specify a subdirectory, the action is applied to all files in the subdirectory.
- hstrRenderToName
- Contains the fully qualified file or subdirectory name that is to be used at the target, for example:
C:\MYSUBDIR\MYSOURCE.C \\NETWORK\SHARED\SUBDIRA\SUBDIRB\MYSOURCE.H C:\SUBDIR1\SUBDIR2\SUBDIR3
Types
Any type that is allowed as a .TYPE extended attribute is allowed in the hstrType field of the DRAGITEM data structure. The type for a file can be obtained using DosQFileInfo; the type can be set by using DosSetFileInfo.
Print Rendering Mechanism
A common object that might be provided by a container is a printer. This object would allow objects to be dragged and dropped on it to accomplish a print operation.
Mechanism Name
The string for this rendering mechanism is DRM_PRINTOBJECT.
Messages
To support this rendering mechanism, a source must be able to receive and process a DM_PRINTOBJECT message. The target posts this message to the source. When the message is received, the source prints the current view of the object identified in the message to the printer. The second message parameter (of type PRINTDEST) gives all the parameters necessary to call DevPostDeviceModes and DevOpenDC.
Native Mechanism Actions
There are no native mechanism actions for this rendering mechanism, because the act of printing an object is considered a transform from the native rendering mechanism to the print mechanism.
Naming Conventions
None.
Dynamic Data Exchange (DDE) Rendering Mechanism
This rendering mechanism can be used by various containers and applications. The containers allow objects to be dragged and dropped on white space in the container to accomplish a Move or Copy operation. They can also allow objects in the same or another container to be dragged and dropped on objects within the container to accomplish some operation.
Mechanism Name
The string for this rendering mechanism is DRM_DDE.
Messages
To support this rendering mechanism, a source must be able to receive and process the following messages:
- WM_DDE_REQUEST
- This message is posted by the target to the window indicated by the hwndItem field in the DRAGITEM data structure to request information regarding the object. Note that WM_DDE_INITIATE is not required because the target already has the handle of the window it wants to converse with. This message is sent for all Move and Copy operations.
- WM_DDE_ADVISE
- This message is posted by the target to the window indicated by the hwndItem field in the DRAGITEM data structure order to maintain a hot link to the object.
- WM_DDE_UNADVISE
- This message is posted by the target to the window indicated by the hwndItem field in the DRAGITEM data structure to terminate a hot link to the object.
- WM_DDE_TERMINATE
- This message is posted by the target to the window indicated by the hwndItem field in the DRAGITEM data structure to terminate a conversation.
To support this rendering mechanism, a target must be able to receive and process the following messages:
- WM_DDE_DATA
- This message is posted to the target by the source to deliver the requested information regarding the object.
- WM_DDE_ACK
- This message is posted to the target by the source to acknowledge a WM_DDE_ADVISE or WM_DDE_UNADVISE message.
- WM_DDE_TERMINATE
- This message is posted to the target by the source to end a conversation.
Native Mechanism Actions
Prior to establishing a DDE conversation, the target should determine the source-supported formats in which it wants to have the object rendered. It should register this format in the system atom table and use the resulting atom in the usFormat field of the DDESTRUCT used in the conversation.
The target should establish the DDE conversation by posting a WM_DDE_REQUEST message to the window indicated by the hwndItem field in the DRAGITEM data structure. The target acts as the client, and the source acts as the server in the conversation.
Operation Specifics
The following actions should be taken by the source, depending on the operation being performed:
- Copy
- Send the data to the target.
- Move
- Remove knowledge of the object after receiving confirmation that the target has successfully completed its portion of the rendering operation.
Non-Native Mechanism Actions
The target and source proceed in the same way, regardless of whether DDE was the native rendering mechanism or an alternate rendering mechanism.
Naming Conventions
The naming conventions for the DRM_DDE rendering mechanism follow:
- hstrSourceName
- Contains the object name to be used in the DDE conversation.
- hstrRMF
- The format portion of the list of ordered pairs in the format <DRM_DDE,format> identifies the formats supported by the source for the object. The non-standard DDE formats that these formats map to must be registered in the system atom table by both the source and the target.
Types
Any type that is allowed as a .TYPE extended attribute is allowed in the hstrType field of the DRAGITEM data structure.
Application-Defined Rendering Mechanisms
Mechanism Name
Native Mechanism Actions
Naming Conventions
Performance Considerations
Using Direct Manipulation
Allocating Memory for the Drag Operation
Initializing DRAGITEM Data Structure
Type
True Type
Rendering Mechanism and Format
Native Rendering Mechanism and Format
Suggested Name at Target
Container Name
Source Name
Sample Code for Initializing DRAGITEM Data Structure
Initializing DRAGIMAGE Data Structure
Starting the Drag Operation
Responding to the DM_DRAGOVER Message
Providing Target Emphasis
Providing Customized Images
Responding to the DM_DRAGLEAVE Message
Responding to the DM_DROP Message
Exchanging Data
Performance Considerations
Using Pickup and Drop