Etudes for Microsoft Word Programmers

Home ] Up ] Etude 3.1. Working with Document Properties. ] Etude 3.2. Customizing Drag-n-Drop for Document Window ] Etude 3.3. Microsoft Word as Automation Server. ] Etude 3.4. Transcriber ]


Etude 3.2. Customizing Drag-n-Drop for Microsoft Word Document Window

"Drag and Drop", abb. DnD, is the name of a technique of working with objects in window interface. The user can drag selected text, selected files or other objects from one window to another as well as between the windows of different applications. It is quite clear that  the applications should support this technique, otherwise, dragging wonít work.

The simple implementation of Drag-n-Drop customization for Microsoft Word document window is studied in this etude. The etude implementation consists of the "AhCustomDragDrop.dot" (VBA) template and the "AhCustomDragDrop.dll" (C++) library. The source code of the library is not included.

Resources

"AhCustomDragDrop.dot" template and library "AhCustomDragDrop.dll"
  37 Kb, ZIP [download].

The AhCustomDragDrop.dll project source codes. (C++)  [later!].

The dynamic library "AhCustomDragDrop.dll" should be copied to the system folder before use of VBA template. (The system folder is usually here "C:\Windows\System32").

 

To restore the usual Microsoft Word Drag-n-Drop functionality after testing the given template don't forget to delete the "AhCustomDragDrop.dot"  template from the global templates folder to avoid its automatic run when Microsoft Word is started.

Functional Specification

Task

The necessity of Drag-n-Drop customization appears while using Microsoft Word as a part of a big programming system. It can be used, for instance, for dragging and dropping of objects specific to the system above.

The task is to create the "AhCustomDragDrop.dot" template and the "AhCustomDragDrop.dll" library, which together demonstrate the possibility of Drag-n-Drop customization for Microsoft Word document windows.

Toolbar "AhCustomDragDrop"

The "AhCustomDragDrop" toolbar looks like this:

The brief description of the toolbar buttons is given in the table below.

Button

Macro

Description

Help

AhCustomDragDrop2Help

Brief Prompt on the toolbar buttons.

Examine

AhCustomDragDrop2Examine

Information about the active window. In case of absence of open documents it shows the information about the main Microsoft Word window.

Brief Prompt

Brief Prompt on the toolbar buttons looks like this

Examining Window

On pressing the "Examine" button a message appears about whether the current window is registered or not. The message looks like this.

Document Window Message.
Main Microsoft Word Window Message.

Testing

To test the template you should drag and drop some object (a text from NotePad or a file from Windows Explorer) to the Microsoft Word window (no open documents) or the document window. Instead of ordinary action/performance/conduct (inserting of a dropped text or an object to the document or opening of a file) the following message should appear.

Dropping a text.
Dropping a file.
Dropping a custom object.

 

Implementation - AhCustomDragDrop.dll library

VBA programmers who are not familiar with C++ may easily omit this division.

Purpose

The library is designed for customizing Drag-n-Dropís behavior of Microsoft Word and is used together with the "AhCustomDragDrop.dot" template.

Since Drag-n-Drop event handlers are related to windows, the library supports the registration of Microsoft Word open document windows.

Description

The library exports the AhDropRegisterWindow, AhDropUnRegisterWindow, AhDropUnRegisterAll and AhDropIsRegisteredWindow functions. The library export file is given below.

;
; File AhCustomDragDrop.def
;
; © 2001-2008. Evgeny Akhundzhanov. All rights reserved.
;
LIBRARY      "AhCustomDragDrop"
DESCRIPTION  'AhCustomDragDrop Windows Dynamic Link Library'
 
EXPORTS
    ; Explicit exports can go here
      AhDropRegisterWindow
      AhDropUnRegisterWindow
      AhDropUnRegisterAll
      AhDropIsRegisteredWindow

C++ Source Code

The C++ source codes are not included in the current edition.

How It Works

In Drag-n-Drop implementation at least two windows take part Ė the source window and the target window. The user presses the mouse button in the source window and keeping the button pressed drags the cursor into the target window where he releases the mouse button. The target window may coincide with the source window. The dragged data is usually associated with the selected objects in the source window but it is not a must.

The source window reacts to the mouse button pressing and calls the DoDragDrop function. Besides, this window should provide the user with the pointer to the IDropSource and IDataObject interface realization.

The target window provides the user with the pointer to the IDropTarget interface realization. The pointer should be preliminarily  registered in the system by calling the RegisterDragDrop function.

The RegisterDragDrop function has the following prototype.

WINOLEAPI  RegisterDragDrop(HWND hwnd, LPDROPTARGET pDropTarget);

To delete the window registration the RevokeDragDrop function is used which has the following prototype.

WINOLEAPI  RevokeDragDrop(HWND hwnd);

Tracking Microsoft Word Document Windows

To track the Microsoft Word document windows you should trace the processes of document windows creation and removal. The new windows creation coincides with the new document creation and with the opening of existing documents. The window deletion coincides with the 'close document' operation.

The simplest way of tracking the mentioned processes is the interception of the application events. That is the document opening event (_DocumentOpen), the new document creation event (_NewDocument) and the document closure event (_DocumentBeforeClose).

To intercept the events the class module is necessary. It should contain the object of the Word.Application class declared with the "WithEvents".

Public WithEvents AhWordApp As Word.Application

Automatic macros AutoExec and AutoExit are the best way for automatic creation and removal of an application object.

Interface IDropTarget

Information on this page is from Microsoft MSDN http://msdn.microsoft.com.

Brief description of the IDropTarget interface functions is given in the following table.

Function

Description

DragEnter

Determines whether a drop can be accepted and its effect if it is accepted.

DoDragDrop calls IDropTarget::DragEnter when it detects the mouse has moved over a window that is registered as a drag target.

DragOver

Provides target feedback to the user through the DoDragDrop function.

Once the mouse has entered a drag-target window, DoDragDrop calls DragOver as the mouse moves through the window.

DragLeave

Causes the drop target to suspend its feedback actions.

DoDragDrop calls IDropTarget::DragLeave if the mouse leaves the target window or if the user cancels or completes the drag-and-drop operation.

Drop

Drops the data into the target window.

DoDragDrop calls IDropTarget::Drop if the drop finally occurs.

You do not call the methods of IDropTarget directly.

The DoDragDrop function calls the IDropTarget methods during the drag-and-drop operation.

Implementation - Template AhCustomDragDrop.dot

The template contains the "AhCustomDragDrop" toolbar and the corresponding macros.

Module "AhCustomDragDrop"

'
' File AhCustomDragDrop.dot|AhCustomDragDrop
'
' Etudes for Microsoft Word Programmers.
' Etude 3.2. Customizing Drag-n-Drop.
'
' First published on http://www.transcriber.ru
'
' © 2000-2008. Evgeny Akhundzhanov. All rights reserved worldwide.
'
Option Explicit
 
'
' Globals
'
Dim xxx As New AhWordApplication ' Word "With Events" Application
Dim bIsActivated As Boolean
 
'
' External
'
Private Declare Function AhDropRegisterWindow Lib "AhCustomDragDrop.dll" (ByVal strTitle As String) As Long
Private Declare Function AhDropUnRegisterWindow Lib "AhCustomDragDrop.dll" () As Long
Private Declare Function AhDropUnRegisterAll Lib "AhCustomDragDrop.dll" () As Long
Private Declare Function AhDropIsRegisteredWindow Lib "AhCustomDragDrop.dll" () As Long
 

Subroutine AutoExec

Pay attention to the fact that the template should be in the Startup Microsoft Word folder before Microsoft Word is launched. If not, user should run the AutoExec macro manually.

 

'
' AutoExec
'
Sub AutoExec()
    If bIsActivated = True Then Exit Sub
   
    Set xxx.AhWordApp = Word.Application
    bIsActivated = True
   
    '
    ' register active window
    '
    AhRegisterCurrentWindow
   
End Sub

Subroutine AutoExit

'
' AutoExit
'
Sub AutoExit()
    On Error Resume Next
    Set xxx.AhWordApp = Nothing
   
    AhDropUnRegisterAll
End Sub

Subroutine AhCustomDragDrop2Help

'
' AhCustomDragDrop2Help
'
Sub AhCustomDragDrop2Help()
MsgBox "Etudes for Microsoft Word Programmers." & vbCrLf & vbCrLf & _
"Etude 3.2. Customizing Drag-n-Drop." & vbCrLf & _
" © 2000-2008. Evgeny Akhundzhanov. All rights reserved worldwide." & vbCrLf & _
"http://www.transcriber.ru" & vbCrLf & vbCrLf & _
"Template 'AhCustomDragDrop.dot' - " & vbCrLf & vbCrLf & _
"Examine - examines whether current active window is registered or not." & vbCrLf & vbCrLf & _
"For testing just drop something (text or file) to the Microsoft Word document window."
End Sub

Subroutine AhCustomDragDrop2Examine

'
' AhCustomDragDrop2Examine
'
Sub AhCustomDragDrop2Examine()
    AhDropIsRegisteredWindow    ' displays message box
End Sub

Subroutine AhRegisterCurrentWindow

'
' AhRegisterCurrentWindow
'
Sub AhRegisterCurrentWindow()
    Dim strTitle As String
    If Documents.Count = 0 Then
        strTitle = "MS_Word_Frame" ' special name, window will not be registered.
    Else
        strTitle = ActiveDocument.Name
    End If
   
    AhDropRegisterWindow strTitle
   
End Sub

Subroutine AhUnRegisterCurrentWindow

'
' AhUnRegisterCurrentWindow
'
Sub AhUnRegisterCurrentWindow()
If Documents.Count = 0 Then Exit Sub
    AhDropUnRegisterWindow
End Sub

 

Class Module "AhWordApplication"

'
' File AhCustomDragDrop.dot|AhWordApplication
'
' Etudes for Microsoft Word Programmers.
' Etude 3.2. Customizing Drag-n-Drop.
'
' First published on http://www.transcriber.ru
'
' © 2000-2008. Evgeny Akhundzhanov. All rights reserved worldwide.
'
'
Option Explicit
'
Public WithEvents AhWordApp As Word.Application
 

Subroutine Class_Initialize

'
' Constructor
'
Private Sub Class_Initialize()
End Sub

Subroutine Class_Terminate

'
' Destructor
'
Private Sub Class_Terminate()
End Sub

Subroutine AhWordApp_Quit

'
' Quit handler
'
Private Sub AhWordApp_Quit()
End Sub

Subroutine AhWordApp_DocumentBeforeClose

'
' DocumentBeforeClose
'
Private Sub AhWordApp_DocumentBeforeClose(ByVal Doc As Document, Cancel As Boolean)
    Debug.Print "DocumentBeforeClose"
    AhUnRegisterCurrentWindow
End Sub

Subroutine AhWordApp_DocumentBeforeClose

'
' DocumentBeforeSave
'
Private Sub AhWordApp_DocumentBeforeSave(ByVal Doc As Document, SaveAsUI As Boolean, Cancel As Boolean)
    Debug.Print "DocumentBeforeSave"
End Sub

Subroutine AhWordApp_DocumentBeforeClose

'
' DocumentOpen
'
Private Sub AhWordApp_DocumentOpen(ByVal Doc As Document)
    Debug.Print "DocumentOpen"
    AhRegisterCurrentWindow
End Sub

Subroutine AhWordApp_DocumentBeforeClose

'
' NewDocument
'
Private Sub AhWordApp_NewDocument(ByVal Doc As Document)
    Debug.Print "NewDocument"
    AhRegisterCurrentWindow
End Sub

Subroutine AhWordApp_DocumentBeforeClose

'
' WindowActivate
'
Private Sub AhWordApp_WindowActivate(ByVal Doc As Document, ByVal Wn As Window)
    Debug.Print "WindowActivate"
    AhRegisterCurrentWindow
End Sub

Subroutine AhWordApp_DocumentBeforeClose

'
' WindowDeactivate
'
Private Sub AhWordApp_WindowDeactivate(ByVal Doc As Document, ByVal Wn As Window)
    Debug.Print "WindowDeactivate"
End Sub

 

Conclusion

The simple implementation of Microsoft Word Drag-n-Drop customization is given in this etude. It consists of the "AhCustomDragDrop.dot" (VBA) template and the "AhCustomDragDrop.dll" (C++) library.

Tasks

Task 1 (for C++ programmers)

Write the program containing the DnD source window. Implement the IDropSource and IDataObject interfaces. Check whether your program works together with the "AhCustomDragDrop.dot" template.

 

Questions

1. Is it possible to customize Drag-n-Drop behavior for Microsoft Word document window using VBA only?

2. For what personal purpose you may need to change standard Microsoft Word document window Drag-n-Drop behavior?

 


Etudes for Microsoft Word Programmers.
Etude 3.2. Customizing Drag-n-Drop for Microsoft Word Document Window


Unless otherwise noted, all materials on this site are
© 2000-2009 Evgeny Akhundzhanov, All Rights Reserved Worldwide
Microsoft is in no way affiliated with, nor offers endorsement of, this site.
www.transcriber.ru | E-mail the Author