DESKTOP FRAMEWORKS CONCEPTS - Implementing a drag source

Implementing a drag source

Drag sourcing behavior can be added to any Workspace entity that's based on the document architecture. To add drag sourcing behavior to one of your objects:

Derive a document scrap item source for the Workspace entity from TDocumentScrapItemSource.
Attach the scrap item source to the Workspace entity.
Once attached to an item of a specific type, your document scrap item source is used by all items of the same type to initiate a dragging operation.

Deriving a document scrap item source for a Workspace entity

TDocumentScrapItemSource is an abstract base class that implements protocols for Workspace drag sourcing behavior. TDocumentScrapItemSource objects are attribute objects that you attach to an entity in the Workspace. When deriving from TDocumentScrapItemSource, you override two functions: CopyAvailableTypesOfDocument and CreateItemOfDocumentMatchingDescription.

Overriding CopyAvailableTypesof Document

CopyAvailableTypesOfDocument is called when the user selects and begins to drag an item to which this drag source is attached. This function should place each possible data type for the dragged item into the provided sequence object. Possible types include those that indicate a printable document, a model, a piece of text, or a custom type. Note that more than one drag source can be attached to one document, with each drag source contributing a different set of types.

CopyAvailableTypesOfDocument takes the following parameters:

  virtual void CopyAvailableTypesOfDocument(
              const TDocumentReference& representedDocument,
              const TPlaceReference& placeContext,
              const TScrapInteractionModifier& modifier,
              TSequenceOf<TTypeDescription>& result,
              TMemoryHeap* whichHeap = NIL) const = 0;

representedDocument is the document being dragged
placeContext indicates the place context within which this gesture is happening
modifier contains modifiers for the drag operation including key board modifiers
result is the sequence object in which this function places the appropriate type descriptions
whichHeap is the heap in which the result should be placed.

Overriding CreateItemOfDocument MatchingDescription

Once the type negotiation between the drag source and the drag acceptor is complete, CreateItemOfDocumentMatchingDescription is called to provide the scrap item that matches the type chosen by the acceptor. This scrap item transfers information from the drag source to the drop acceptor.

CreateItemOfDocumentMatchingDescription takes the following parameters:

  virtual TScrapItem* CreateItemOfDocumentMatchingDescription(
                  const TDocumentReference& representedDocument,
                  const TPlaceReference& placeContext,
                  const TScrapInteractionModifier& modifier,
                  const TTypeDescription& requestedType,
                  TMemoryHeap* whichHeap = NIL) const = 0;

representedDocument is the document being dragged
placeContext indicates the place context within which this gesture is happening
modifier contains modifiers for the drag operation including key board modifiers
requestedType is the type description chosen by the drop acceptor
whichHeap is the heap in which the result should be placed

CreateItemOfDocumentMatchingDescription is only called with a TTypeDescription value that the drag source instance has published as available in the previous call to CopyAvailableTypesOfDocument. It is not called at all if the negotiation doesn't ask for any of the published types.

Supporting streaming and dynamic casting

Instances of classes derived from TDocumentScrapItemSource are copied and stored with a document's attribute set. When deriving a new class from TDocumentScrapItemSource, you also have to properly define streaming operators, a default constructor, and a copy constructor.

Classes derived from TDocumentScrapItemSource also need to support dynamic casting. See OS Services for more information about the dynamic casting mechanism supported by the CommonPoint runtime system.

Attaching a TDocumentScrap- ItemSource to a Workspace entity

Once you've written a document scrap item source, you attach it to a Workspace entity. To do this, the Workspace must be running, and a document instance of the appropriate type must be available. You can use the RunDocument utility to create a document instance from a stationery. (See Taligent Tools for AIX for more information about using RunDocument.)

Once you have an object of the appropriate type available in the Workspace, attach your drag source to it using the utility program AddWorkspaceDragSource:

  % cd $TaligentRoot/SharedLibs
  % AddWorkspaceDragSource entityName -c dragSourceClassName   dragSourceSharedLib

Note that you must be in $TaligentRoot/SharedLibs to run AddWorkspaceDragSource. This utility program takes the following parameters:

entityName is the name of the entity in the Workspace to which you want to attach the drag source
dragSourceClassName is the name of the class to use as the drag source for that entity type
dragSourceSharedLib is the shared library into which dragSourceClassName has been compiled

This operation only affects the specified document instance. If you use the Workspace user command to create a stationery from the specified instance, the drag sourcing behavior is inherited by all documents created from the stationery.

NOTE You can also use this technique to propagate other attributes. For example, if you attach an icon to a particular document instance, and then create a stationery from that instance, all documents created from the stationery will carry the icon of the original document.

You can attach multiple drag sources to a Workspace entity with AddWorkspaceDragSource. It attaches a new instance of a scrap item source every time you run it. During the type negotiation that occurs during a drag and drop interaction, the scrap item sources are processed in the order that they were added to the document. The system iterates through the list until the type negotiation succeeds.

Removing a scrap item source from a Workspace entity

To remove a drag source, use the utility program RemoveWorkspaceDragSource:

  % cd $TaligentRoot/SharedLibs
  % RemoveWorkspaceDragSource entityName scrapType sharedLib

This tool iterates backward through the list of scrap item sources and removes the first one that supplies the specified scrap type. The third parameter, sharedLib, indicates the name of the shared library where scrapType is defined.

Viewing the current drag sources

If you want to see what drag sources are currently attached to a Workspace entity, you can use the utility program WorkspaceDragAndDropInfo. To list the current drag sources for an entity:

  % cd $TaligentRoot/SharedLibs
  % WorkspaceDragAndDropInfo entityName

This prints a list of the drag sources that are attached to the specified entity to the standard output.

[Contents] [Previous] [Next]

Click the icon to mail questions or corrections about this material to Taligent personnel.

Generated with WebMaker