DESKTOP FRAMEWORKS CONCEPTS - Implementing a drop acceptor

Implementing a drop acceptor

Drop acceptance behavior can be added to any Workspace entity that's based on the document architecture. To add drop acceptance behavior to a Workspace entity:

Derive a scrap item acceptor for the Workspace entity from TDocumentScrapItemAcceptor.
Attach the document scrap item acceptor to the Workspace entity.

Deriving a document scrap item acceptor for a Workspace entity

TDocumentScrapItemAcceptor is an abstract base class that implements protocols for drop acceptance behavior. TDocumentScrapItemAcceptor instances are attribute objects that you attach to an entity in the Workspace. The acceptor attribute only applies to the instance to which it attached; however, if a stationery is created from that instance, all copies created from the stationery inherit the drop acceptor attribute.

When deriving from TDocumentScrapItemAcceptor, you override two functions: ChoosePreferredTypeForDocument, and AcceptScrapItemForDocument.

Overriding ChoosePreferredType ForDocument

ChoosePreferredTypeForDocument is called when the user releases the mouse button over the destination of the drag operation. It is part of the type negotiation process that takes place between the drag source and the drop acceptor. Typically, the drop acceptor is handed a set of available types, selects a preferred type, and returns True. If no matching type is found, ChoosePreferredTypeForDocument should return False.

  virtual Boolean ChoosePreferredTypeForDocument(
                  const TDocumentReference& representedDocument,
                  const TPlaceReference& placeContext,
                  TSequenceOf<TTypeDescription> availableTypes,
                  TTypeDescription& chosenType) const = 0;

ChoosePreferredTypeForDocument takes the following parameters:

representedDocument is the document that the item is being dropped on (the document that this acceptor behavior is working for)
placeContext indicates the place context within which this gesture is happening
availableTypes is the set of types that the acceptor has to choose from
chosenType is the preferred type as returned by this acceptor

Overriding AcceptScrapItem ForDocument

After the acceptor indicates its preferred type, AcceptScrapItemForDocument is called to perform the actual acceptance of the dragged document.

AcceptScrapItemForDocument takes the following parameters:

  virtual Boolean AcceptScrapItemForDocument(
                  const TDocumentReference& representedDocument,
                  const TPlaceReference& placeContext,
                  const TTypeDescription& type,
                  const TScrapItem& scrapItem) = 0;

representedDocument is the document that the item is being dropped on.
placeContext indicates the place context within which this gesture is happening.
type indicates the type of the scrap item handed to this function as the fourth parameter. This type matches the preferred type chosen by the acceptor in ChoosePreferredTypeForDocument.
scrapItem is the TScrapItem subclass representing the dragged item.

This function should perform whatever action is appropriate for the drag and drop gesture. For example, if the TScrapItem is a printable entity that was dragged onto a printer, this function should actually print the document; if the TScrapItem is a document that was dragged from one folder to another, this function should move the document into the destination folder.

Supporting streaming and dynamic casting

Instances of classes derived from TDocumentScrapItemAcceptor 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 TDocumentScrapItemAcceptor 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 scrap item acceptor to a Workspace entity

Once you've written a document scrap item acceptor, 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 the Tools guide for more information about using RunDocument.)

Once you have an object of the appropriate type in the Workspace, attach your drop acceptor to it using the utility program AddWorkspaceDropAcceptor:

  % cd $TaligentRoot/SharedLibs
  % AddWorkspaceDropAcceptor entityName -c dropAcceptorClassName dropAcceptorSharedLib

Note that you must be in $TaligentRoot/SharedLibs to run AddWorkspaceDropAcceptor.

AddWorkspaceDropAcceptor takes the following parameters:

entityName is the name of the entity in the Workspace to which you want to attach the drop acceptor
dropAcceptorClassName is the name of the class to use as the acceptor for that entity type
dropAcceptorSharedLib is the shared library into which dropAcceptorClassName 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 drop acceptor 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 drop acceptors to a Workspace entity with AddWorkspaceDropAcceptor. It attaches a new instance of a drop acceptor every time you run it. During the type negotiation that occurs during a drag and drop interaction, the drop acceptors 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 drop acceptor from a Workspace entity

To remove an acceptor, use the utility program RemoveWorkspaceDropAcceptor:

  % cd $TaligentRoot/SharedLibs
  % RemoveWorkspaceDropAcceptor entityName scrapType sharedLib

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

Viewing the current drop acceptors

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

  % cd $TaligentRoot/SharedLibs
  % WorkspaceDragAndDropInfo entityName ScrapType

This prints a list of the acceptors that can accept the specified scrap type.

[Contents] [Previous] [Next]

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

Generated with WebMaker