### IDMSourceHandler

  The IDMSourceHandler class processes events occurring at the source of a direct manipulation. You must add an object of this class to a window so it can support source direct manipulation. Objects of this class do not allow objects to be dropped on a window. See IDMTargetHandler for information about dropping objects on a window.
  Note: An IDMSourceHandler object is added to a window if you initialize direct manipulation via the functions in Enabling Direct Manipulation.

### IDMSourceHandler - Member Functions and Data by Group

### Constructors & Destructor

You can construct and destruct objects of this class.

~IDMSourceHandler

      public:
      virtual ~IDMSourceHandler()

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

IDMSourceHandler

  Overload 1

      public:
      IDMSourceHandler()

  This is the default constructor.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

  Overload 2

      public:
      IDMSourceHandler(IContainerControl* containerControl)

  containerControl
    A pointer to the container control object.

  Creates an object of this class using a pointer to a container control object. The constructed handler is automatically attached to the specified container.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

  Overload 3

      public:
      IDMSourceHandler(IEntryField* entryField)

  entryField
    A pointer to the entry field object.

  Creates an object of this class using a pointer to an entry field object. The constructed handler is automatically attached to the specified entry field.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

  Overload 4

      public:
      IDMSourceHandler(IMultiLineEdit* multiLineEdit)

  multiLineEdit
    A pointer to the multiline edit object.

  Creates an object of this class using a pointer to a multiline edit (MLE) object. The constructed handler is automatically attached to the specified MLE.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

  Overload 5

      public:
      IDMSourceHandler(IWindow* window)

  window
    A pointer to the window object.

  Creates an object of this class using a pointer to an IWindow-based object that represents a control that is not supported by the default Open Class Library support for direct manipulation. These controls can be system-defined controls or custom controls. The constructed handler is automatically attached to the specified window.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

### Event Dispatching

These members dispatch the various events for a direct manipulation source.

dispatchHandlerEvent

      protected:
      virtual bool dispatchHandlerEvent(IEvent& event)

  Overrides the default handler's dispatcher. This function processes the direct manipulation events for the source.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

### Event Processing

These members are dispatched in response to specific direct manipulation events for the source.

sourceBegin

      protected:
      virtual bool
        sourceBegin( IDMSourceBeginEvent& event,
                     bool container = true )

  Called to process the start of a direct manipulation in response to the system's begin drag event. Initial processing invokes allocateOperation. Next, a pointer to the drag item provider is obtained by calling IWindow::itemProvider. Afterwards, IDMItemProvider::provideSourceItems is invoked to retrieve the items to be dragged. findRenderersFor is called to find appropriate source renderers for the items that were provided. If there are items to be dragged, IDMSourceOperation::begin is called to start the direct manipulation.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

sourceDiscard

      protected:
      virtual bool sourceDiscard(IDMSourceDiscardEvent& event)

  Called to indicate that a drag item or items have been dropped on a shredder object. The source response determines what deletes the items or if the discard operation is cancelled. The default implementation dispatches IDMSourceRenderer::sourceDiscard.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Ignored

AIX Considerations

  You will not receive IDMSourceDiscardEvents on AIX.

Windows Considerations

  You will not receive IDMSourceDiscardEvents on Windows.

sourceEnd

      protected:
      virtual bool sourceEnd(IDMSourceEndEvent& event)

  Called to indicate that a given item has been processed by the target. The default implementation for this class dispatches IDMSourceRenderer::sourceEnd on the corresponding drag item object.

  After all source end events are received, the IDMSourceOperation object is deleted.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

sourcePrepare

      protected:
      virtual bool sourcePrepare(IDMSourcePrepareEvent& event)

  Called to indicate to the source that rendering is ready to start. Requests for rendering preparation are made within the source item constructors. The default implementation in this class dispatches IDMSourceRenderer::sourcePrepare on the corresponding drag item object.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Ignored

sourcePrint

      protected:
      virtual bool sourcePrint(IDMSourcePrintEvent& event)

  Called to indicate that a drag item or items have been dropped on a printer object. The source response determines who prints the items or if the operation is cancelled. The default implementation dispatches IDMSourceRenderer::sourcePrint.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Ignored

sourceRender

      protected:
      virtual bool sourceRender(IDMSourceRenderEvent& event)

  Called to start the rendering of a drag item by the source renderer. The default implementation for this class dispatches IDMSourceRenderer::sourceRender on the drag item object.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Ignored

### Implementation

These members provide utilities used to implement this class. They are used by the Open Class Library.

allocateOperation

      protected:
      virtual IDMSourceOperation::Handle
        allocateOperation( IDMSourceBeginEvent& event,
                           DragImageStyle dragItemStyle ) const

  Creates a new IDMSourceOperation object.

  This function is called when the source handler is handling the processing of a new direct manipulation. Derived classes should override this function and return a class derived from IDMSourceOperation.

  This function returns a handle to the source operation object.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

findRendererFor

      protected:
      virtual unsigned
        findRendererFor( const IDMItem::Handle& item )

  Finds the appropriate source renderer for the drag item. Returns the position of the renderer or 0 if a renderer cannot be found.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

findRenderersFor

      protected:
      virtual bool
        findRenderersFor( const IDMSourceOperation::Handle& sourceOperation )

  Finds the appropriate source renderers for the specified source operation.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

### Renderer Processing

These members override the rendering functions defined in the base IDMHandler class. Use them to access the IDMSourceRenderer objects involved in a direct manipulation. Objects of this class render the drag item objects that are compatible with the rendering mechanisms and formats that the Open Class Library supports.

addRenderer

      public:
      virtual IDMSourceHandler&
        addRenderer( const IDMSourceRenderer& newRenderer )

  Adds the specified renderer to the set of candidates maintained by this handler and uses it to render objects dragged from a source window where this handler is attached. The renderer is added to the end of the renderer collection.
  Note: Renderers are maintained by position, which are 1-based.

  newRenderer
    A reference to the renderer object.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

numberOfRenderers

      public:
      virtual unsigned numberOfRenderers()

  Returns the number of renderers associated with the source handler.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

removeRenderer

      public:
      virtual IDMSourceHandler&
        removeRenderer( const IDMSourceRenderer& rendererToRemove )

  Removes a specified renderer from this handler.
  Note: Renderers are maintained by position, which are 1-based.

  rendererToRemove
    A reference to the source renderer object to remove from the renderer collection.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

renderer

      public:
      virtual IDMSourceRenderer* renderer(unsigned position)

  Returns the renderer with the specified position.
  Note: Renderers are maintained by position, which are 1-based.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

replaceRenderer

      public:
      virtual IDMSourceHandler&
        replaceRenderer( unsigned position,
                         const IDMSourceRenderer& replacement )

  Replaces the given renderer with another specified renderer.
  Note: Renderers are maintained by position, which are 1-based.

  position
    A value that represents the location of the source renderer to replace in the renderer collection.
  replacement
    A reference to the replacement renderer object.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

setRenderer

      public:
      virtual IDMSourceHandler&
        setRenderer( const IDMSourceRenderer& newRenderer )

  Sets the source renderer for this handler. Removes any pre-existing source renderers.

  newRenderer
    A reference to the source renderer object.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

### IDMSourceHandler - Inherited Member Functions and Data

#### Inherited Public Functions

  IHandler

  -     virtual ~IHandler()

  -     virtual IString asDebugInfo() const

  -     virtual IString asString() const

  -     virtual IHandler& disable()

  -     virtual IHandler& enable(bool enable = true)

  -     virtual IHandler& handleEventsFor(IWindow* window)

  -     IHandler()

  -     bool isEnabled() const

  -     virtual IHandler& stopHandlingEventsFor(IWindow* window)

  IDMHandler

  -     static IDMDragHandler& defaultDragHandler()

  -     static IDMDropTargetHandler& defaultDropTargetHandler()

  -     static IDMSourceHandler& defaultSourceHandler()

  -     static IDMTargetHandler& defaultTargetHandler()

  -     static void
          enableDragDropFor( IToolBarButton* toolBarButton )

  -     static void enableDragDropFor(IEntryField* entryField)

  -     static void enableDragDropFor(IWindow* window)

  -     static void enableDragDropFor(IContainerControl* container)

  -     static void enableDragDropFor(IMultiLineEdit* mle)

  -     static void enableDragFrom(IEntryField* entryField)

  -     static void enableDragFrom(IContainerControl* container)

  -     static void enableDragFrom(IMultiLineEdit* mle)

  -     static void enableDragFrom(IWindow* window)

  -     static void enableDropOn(IToolBar* toolBar)

  -     static void enableDropOn(IContainerControl* container)

  -     static void enableDropOn(IMultiLineEdit* mle)

  -     static void enableDropOn(IWindow* window)

  -     static void enableDropOn(IEntryField* entryField)

  -     static void
          setDefaultSourceHandler( IDMSourceHandler& source )

  -     static void
          setDefaultTargetHandler( IDMTargetHandler& target )

#### Inherited Public Data

  - None

#### Inherited Protected Functions

  IDMHandler

  -     virtual ~IDMHandler()

  -     IDMHandler()

  -     bool isContainerControl(const IWindow* window) const

  -     virtual IDMRenderer* renderer(unsigned position)

  -     static void setItemProvider(IToolBar* toolBar)

  -     static void setItemProvider(IContainerControl* container)

  -     static void setItemProvider(IEntryField* entryField)

  -     static void setItemProvider(IToolBarButton* toolBar)

  -     static void setItemProvider(IMultiLineEdit* mle)

  IHandler

  -     virtual IEventResult defaultProcedure(IEvent& event)

  -     virtual bool dispatchHandlerEvent(IEvent& event) = 0

#### Inherited Protected Data

  - None