MouseEvent.DragState Property

Returns information about the state of mouse movement as it relates to dragging and dropping a shape. Read-only.

Version Information
 Version Added:  Visio 2007

Syntax

expression.DragState

expression   An expression that returns a MouseEvent object.

Return Value
Long

Remarks

The DragState property extends the MouseMove event by returning detailed information about the state of mouse movements and actions throughout the course of a drag and drop operation. You can use the DragState property in conjunction with the EventList.AddAdvise method to determine whether a drag and drop operation is beginning, or whether the mouse is entering a drop-target window, moving over the window, dropping an object in the target window, or leaving the window.

Note
You can specify exactly which drag-states extensions you want to listen to by using the Event.SetFilterActions method.

To handle event notifications, create a class module that implements the VisEventProc method of the IVisEventProc interface and then create an instance of this class to pass as an argument to the AddAdvise method. Get the value of the DragState property of the pSubjectObj parameter of the VisEventProc function.

At any time you can return VisEventProc = False to cancel the drag and drop action, for example if you receive an event notification that the user is attempting to drop an object in an inappropriate target window.

The example that accompanies this topic provides sample code that shows how to get drag-state information.

Possible values returned by the DragState property are shown in the following table and declared in the VisMouseMoveDragStates enumeration, which is declared in the Microsoft Office Visio type library.

When the DragState property returns visMouseMoveDragStatesBegin a drag and drop action is beginning. The DragState property returns visMouseMoveDragStatesBegin just once for each drag and drop action. At this point, you can cancel the drag and drop action entirely; if you do so, Visio fires no additional MouseMove events for any target windows.

When the DragState property returns visMouseMoveDragStatesEnter, an end-user is dragging an object into a drop-target window. This event is fired once per drop-target window. At this point, you can cancel the drag and drop action for that specific drop-target window.

When the DragState property returns visMouseMoveDragStatesOver, the user is dragging an object over a drop-target window. You can cancel the drag action, based on the type of window or on an x,y range within a window, as specified in your code. Canceling a drag action over the drop-target window prevents the end-user from completing the drag and drop action.

When the DragState property returns visMouseMoveDragStatesDrop, the drop-target window is receiving a drop. You can cancel the drop action, thus preventing the drop from occurring. When this occurs and you do not also cancel the drag action over the drop-target window, the end-user does not get any visual feedback to indicate that the drop action has been prevented.

When the DragState property returns visMouseMoveDragStatesLeave, the end-user is moving the mouse out of the drop-target window. There is no way for you to cancel this operation at this point, but there would also be no logical reason to do so.

Example

This example shows how to create a class module that implements the IVisEventProc interface to handle events fired by the MouseEvent object. The module consists of the function VisEventProc, which uses a Select Case block to determine if the event that fired was a MouseMove event. If so, the code uses an If...Else block and the DragState property to determine the particular MouseMove event extension that fired.

Events other than MouseMove fall under the default case (Case Else). In both cases, the Case block constructs a string (strMessage) that contains the name and event code of the event that fired, including the drag-state extension and the x- and y- values of the location where the event fired, derived from the values of the MouseEvent.X and MouseEvent.Y properties. Finally, the function displays the message in the Immediate window.

Copy this sample code into a new class module in VBA or Visual Basic, naming the module clsEventSink. You can then use the event-sink module that follows to create an instance of the clsEventSink class and an Event object for the MouseMove event that sends notifications of event firings to the class instance.

  Implements Visio.IVisEventProc
'Declare visEvtAdd as a 2-byte value
'to avoid a run-time overflow error
Private Const visEvtAdd% = &H8000
Private Function IVisEventProc_VisEventProc( _
ByVal nEventCode As Integer, _
ByVal pSourceObj As Object, _
ByVal nEventID As Long, _
ByVal nEventSeqNum As Long, _
ByVal pSubjectObj As Object, _
ByVal vMoreInfo As Variant) As Variant
Dim strMessage As String

'Find out which event and event extension fired
Select Case nEventCode
    Case visEvtCodeMouseMove
        Dim strInfo As String
        If (pSubjectObj.DragState = visMouseMoveDragStatesOver) Then
            strMessage = "MouseMove - dragOver (" + Str(pSubjectObj.x) + "," + Str(pSubjectObj.y) + ")"
        ElseIf (pSubjectObj.DragState = visMouseMoveDragStatesBegin) Then
           strMessage = "MouseMove - dragBegin (" + Str(pSubjectObj.x) + "," + Str(pSubjectObj.y) + ")"
           If (pSubjectObj.Window.Index <> 1) Then
                IVisEventProc_VisEventProc = True       ' cancel for all windows except first one
           End If
        ElseIf (pSubjectObj.DragState = visMouseMoveDragStatesLeave) Then
            strMessage = "MouseMove - dragLeave"
        ElseIf (pSubjectObj.DragState = visMouseMoveDragStatesEnter) Then
            strMessage = "MouseMove - dragEnter*******************************************"
        ElseIf (pSubjectObj.DragState = visMouseMoveDragStatesDrop) Then
            strMessage = "MouseMove - dragDrop"
        End If
    Case Else
        strMessage = "Other (" & nEventCode & ")"
End Select

'Display the event name and the event code
If (Len(strMessage)) Then
    Debug.Print strMessage
End If       

End Function

The following VBA module shows how to use the AddAdvise method to sink events. The module contains two public procedures.

The CreateEventObjects procedure creates an instance of a sink-object (event-handling) class named clsEventSink that gets passed to the AddAdvise method, and that receives notifications of events. In addition, the procedure creates a single Event object to send notifications of firings of the MouseMove event sourced by the Application object to the sink object.

The Initialize procedure calls the CreateEventObjects procedure to start listening to events.

The clsEventSink class implements the IVisEventProc interface.

  Public Sub Initialize()    
CreateEventObjects    

End Sub
Option Explicit
Private mEventSink As clsEventSink
Dim vsoApplicationEvents As Visio.EventList
Dim vsoMouseMoveEvent As Visio.Event
'Declare visEvtAdd as a 2-byte value
'to avoid a run-time overflow error
Private Const visEvtAdd% = &H8000
Public Sub CreateEventObjects()
'Create an instance of the clsEventSink class
'to pass to the AddAdvise method.
Set mEventSink = New clsEventSink 

'Get the EventList collection of the current instance of the Visio Application object
Set vsoApplicationEvents = Application.EventList 

'Add an Event object that sends notifications of the MouseMove event.
Set vsoMouseMoveEvent = vsoApplicationEvents.AddAdvise(visEvtCodeMouseMove, mEventSink, "", "Mouse moved...")
End Sub

See Also

• MouseEvent Object
• MouseEvent Object Members