Word’s Task Panes VBA Reference

Disclaimer    Terms of Use

By Steve Hudson

Version 1.2 – Published Sept 11, 2004

This reference explains how Task Panes work and, to the best of our ability, shows how to control the Word ones using VBA in Word 2002 and Word 2003.

Table of contents

Taming the Work Pane

How To

What is it?

CommandBar of name Task Pane

CommandBarControl of type msoControlWorkPane

Developer References

Objects

Registry Hacks

Common Error Messages

Avoiding errors

New Built-in Word Commands

Taming Task Panes

How To

All Task Panes

Controlling Nice Task Panes

Controlling Bad Task panes

Disable / intercept / replace the Task Panes

What is it?

Technical Overview

Known Task Panes in 2003

A Collection of TaskPanes

Developer References

Known Task Pane VBA Summary

List all Nice Task Panes

Collaboration Task Panes

How To

New Document

Protect document

Shared Workspace

Getting Started

What is it?

Introduction

Application.NewDocument

Permission

SharedWorkspace

DocumentLibraryVersion

Editor

RecentFiles

New methods and properties

Developer References

Application.NewDocument

Range.Editors

Editor

Document.Permission

Shared WorkSpace Task Pane

Events

Properties and Methods

XML Task Panes

How To

XML Structure

XML Options dialog

XML Document

What is it?

Application.XMLNameSpaces

Document.XMLSchemaReferences

Range.XMLNodes

Developer References

Events

Properties and Methods

Reformatting Task Panes

How To

Reveal Formatting

Styles and Formatting

What is it?

Developer References

Properties

Enumerations

Mail Merge Task Panes

How To

What is it

Developer References

New Events

Properties and Methods

Other Docked dialogs

How To

Clipboard

Fax Service

Help

What is it?

The untouchables

Clipboard

Fax Service

Help

Developer References

Clipboard

Fax Service

Getting Started

Help

Ramifications and Ravings

The sound of a dialog not opening

So take me to task over it

God helps those who help themselves

It is all just a variant on Word Happens anyway

Smart marketing documents

The distant light

 Introduction

Office XP introduces a new paradigm to our interface, the Task Panes. Ever since, developers have tried to get programmatic access to use them. Unfortunately for us, Microsoft has minimally exposed the objects and your control over them is very limited. Essentially, they have made this task a pain. However, this IS a known issue that has some strong pressure being applied already, so there is a small hope for whatever comes after 2003 IF you are using .Net.

This reference is purely about the shadowy Word Task Panes themselves in Word 2002 and 2003. It does not describe the use of other pane objects. Examples of these include the comments, endnotes and footnotes, headers and footers and so on. It also does not describe the new feature sets that are supported by the presence of a Task Pane. For example, it does not describe the use of the Translation tool nor the use of any SharePoint based services. It does not describe specific Task Panes from other Office applications.

There are new secondary objects that interact with the Task Panes with many features and methods. Most of them are incompletely described in this reference, which instead concentrates on those methods and properties that directly modify the Task Panes themselves. For example, this article does not teach you how to play with XML or what XML is.

It does not overly duplicate information from the Word Help System. Thus, to fully teach yourself everything you must also look up the help topics on the various objects, methods and properties discussed. The closer to the core topic of Task Panes, the less looking elsewhere is required.

Warning

The author gleefully notes at this point that the human race has enough intelligence to get itself into cauldrons of boiling water that it cannot climb out of and that means you and me both! If you like to be ultra-safe, stay way from this reference and wait for MS to hand over full functionality. You will end up crashing Word many times and you can really damage your user interface.

If you are not careful, you can get Word into a state where you cannot use it properly. If you do, rename Normal.dot and kill the Word data key in the registry, for more information see http://word.mvps.org/FAQs/Customization/DataKeySettings.htm. This might help. If it does not, well, we warned you mate!

None of this information is guaranteed to be future compatible or even advisable. It is tested for Word 2002 and Word 2003. At the very best, this is a set of workable band-aids for a final solution beyond our means and well over due-already. Patience grasshopper…

Target Audience

This reference requires intermediate level VBA skills. If you have happily completed the VBA tutorial on the MVP web site, you should be capable of utilising this reference.

There are several advanced VBA topics required to fully master Task Panes in Word 2002 or Word 2003. These are not described other than to provide the advanced reader enough information to pursue the solution. Examples include reading Registry keys and handling the new events.

Terminology

Task Panes are a new interface method. In the same way as the old Styles and Formatting pane supported the Styles object, the Task Panes support various Word objects. Rather than deal with the Task Panes, as developers we deal directly with the objects behind the interface.

Unfortunately, the MS reference on them is poor and has several mistakes and some glaring omissions. Do not waste your time trying to find it; this reference more than covers the subject, avoids several bad practices and has less mistakes.

To avoid confusion and get the new terminology right, what we see is a Work Pane area showing a specific Task Pane from a small, informal collection of the beasts. The MS documentation is not as specific as this and the vagueness can cause some confusion. For example, View > Task Pane should really be View > Work Pane. You cannot show the Work Pane without a Task Pane, the same as you cannot show a document window without a document.

Task Panes have two loose categories as far as we VBA developers are concerned. There are those with a WdTaskPanes type, and there are those without. This reference uses the terms Nice Task Panes for those with a type and Bad Task Panes for those without.

Definitions

IRM

Information Rights Management, programs that agree to play nice will deny access to documents with conflicting IRM information. It does not necessarily mean you have actually protected the information in any meaningful way as it is not encrypted. Mind, even encryption has limits – whatever a computer can read, a computer can write!

Word 2002

The version of Word that comes with Office XP.

 

Document Layout

This document is designed to quickly satisfy the three types of reader that this site attracts: If you want to be the guru on Task Panes, read the whole thing, but be warned it is a long, wide load. You will have difficulty emailing this document as standard server filters erroneously detect the presence of VBScript in the body of the document and fail the message. Send the URL instead.

For those readers seeking information on Task Panes generally, rather than Word’s Task Panes, the first two chapters have great relevance, the third chapter has some relevance and the XML chapter has some extended notes on creating your own Task Pane using a compiled language.

The rest of the chapters are fairly Word specific and are organised based on the feature sets supported by the Task Panes.

The last chapter, Ramifications and Ravings is a ramble. It discusses the ramifications of the appearance of the Work Pane into our GUI. Each other chapter deals with a single facet of the Word Task Panes. Each of these chapters is then broken into three major sections:

How to

These major sections contain the basics for controlling that facet of the Task Panes. They are mainly example VBA6 code samples demonstrating each of the available commands and objects. These sections make little attempt to explain things and are structured by Task Pane. For explanations, see the What is it? section. To extend the samples in this section, see the Developer References section.

What is it?

These major sections contain longer descriptions of the topic and its context in a workflow in an ideal world. It tries to tie all the information from the other two sections together. It describes the objects behind each Task Pane and how to use them to affect the Task Panes or simulate their actions. For examples of the knowledge from this section, see the How to section. For full extensions of all the objects described, see the Developer References section.

Developer References

These major sections contain matrices cross-referencing all the VBA bits and pieces that assemble into the Task Panes. If you want to seriously muck about with code as an advanced user, these sections are the condensed guide to life, Task Panes and everything. You can use Word’s table sort feature to use these tables for many purposes in the document version of this reference. For example implementations, please see the How to section. For explanations, please see the What is it? section.

Background

Microsoft planned to release programmatic control once they had finished the interface properly in a future release of Office. They forgot they have whole newsgroups full of deviant code fiends. I am not sure though whether their surprise equals mine at the size of this document. This was originally supposed to be a two page blurb which said things like “If you wanna know what control id is necessary, work it our yourself now I’ve told you where to look.” Then the Word MVP terrorists attacked, God bless their souls, and encouraged me to finish this reference before publication.

The title picture is my chosen visual metaphor for people involved in a painful task, trying to clear a space to work.

Acknowledgements

All up, this reference is well over a month’s solid work, so thanks must first go to my perpetually persevering wife, Natnitta. Thanks also go to Beth Melton for providing a whack of data for the initial FindControl ID’s table, Cindy Meister for nailing the Styles and Formatting Task Pane modification solution, Doug Robbins for code fragments, Santa Klaus for continually prodding me to add another dozen topics and finally Mr McGhie for identifying the need for this reference and striving to get the best out of me.

Inspiration, information, support and blessings were in bountiful supply the whole way through from many MVPs. So, after these fine folk have had a say, things can only get bigger and better. My thanks to them all for their constructive and encouraging comments.

Yes, I am truly sick of Task Panes for the moment. I am blaming Klaus because John buys me beer :-)

Bibliography

Most of this information is from repeated experimentation with the VBE. Some information was located in:

·       Microsoft Word’s Help system

·       MSDN Online

Related Articles

http://word.mvps.org/faqs/customization/ShowTaskPane.htm
A practical tool to control the startup behavior of the Task Panes that implements some of the knowledge from this reference.

Taming the Work Pane

 

How To

For explanations please see What is it?.

 

Hide the Work Pane at start up

Application.ShowStartupDialog = False

 

Show the Work Pane at start up

Application.ShowStartupDialog = True

 

Hide the Work Pane

To hide the entire Work Pane area no matter which actual Task Pane is displaying, use

CommandBars("Task Pane").Visible = False

 

Show the Work Pane

Avoid this method:

CommandBars("Task Pane").Visible = True

 

It only works if the Task Pane has been visible for that document before. You are much better off displaying a specific Task Pane using the FindControl method, as described in the next chapter.

 

Resize the Work Pane

This example sizes it to a nice width.

CommandBars("Task Pane").Width = 200

 

Reposition the Work Pane

If you just cannot live without it being up the top where you are used to your menus being, run this:

CommandBars("Task Pane").Position=msoBarTop

 

This reference assumes the Task Pane is docked to the right, as per default.


 

What is it?

Task Panes display within a Work Pane’s area. A Work Pane is created by the combination of two objects. These objects are shrouded in misery and thwart most attempts to play with them. The whole area is hidden away from the Kill Cursor invoked with Ctrl+Alt+-, which changes to a hand when waved over a Work Pane. Functions are hidden away from the macro recorder. To make it easier, if it is not in this reference, it is hidden. It is like when a spy is caught and the government disavows all knowledge of their actions. The Task Panes are spies from Microsoft that are known to only a few objects, in these versions of Office anyway.

Word tracks whether the Work Pane appears on startup or not. It is nice to see Microsoft giving us this option as not everyone is going to like having 1/3 of their screen disappear. Unfortunately, there are still other automatic behaviors of the Work Pane area beyond our reach in this way, such as the XML document view.

 

CommandBar of name Task Pane

Yes, The Work Pane is just a locked-down CommandBar with a single nifty exploded MsoControl on it. It is referenced in the registry in the Word Data key along with the descriptions of the other built-in toolbars.

If you look at the Work Pane area carefully, you notice the top strip is quite thin and sits on a bordered area. This bordered area is the CommandBar. It seems blended into the expanded control area for showing Task Panes because MS have negatively offset the vertical start of the Work Pane area up and over the bottom of the CommandBar. The thin strip is the control’s face on the bar. The rest of the Work Pane is the auto-exploded control area – similar to the space a dropdown menu creates when it is activated – for the Task Panes to use for a display area.

The only properties of this CommandBar that you can use are the visibility, position and width methods – you cannot add nor modify controls. As all Task Panes faces sit on the control on this bar, you hide whatever Task Pane is shown when you hide the bar. If you really want to ruin the use of the Task Pane, set it to floating rather than its default of docked.

As it is a CommandBar, it competes with other CommandBars in the same docking space for precedence. In its default, right-hand-side docking there are no other competitors.

 

CommandBarControl of type msoControlWorkPane

The nifty exploded control on the CommandBar is of type msoControlWorkPane. It manages the display space and displays the contents of the Task Panes. The built-in Task Panes shown on this Work Pane are HTML files built from XML controls by a new component called InfoPath, but they are hard-compiled into the InfoPath executable so there is no editing them. There are no descriptions of the control type Work Pane to use, and there is no such object to declare and assign. This control is beyond the reach of VBA and is useless to us.


 

Developer References

 

Objects

All these objects are old ones put to new uses.

 

Parent Object

Property / Method / Item

Type

Application

ShowStartupDialog

Boolean

CommandBars("Task Pane")

Visible

Boolean

CommandBars("Task Pane")

Width

Long

CommandBars("Task Pane")

Position

MsoBarPosition

 

Read Only properties

CommandBars("Task Pane").Controls(1)

   .Id=5746

   .Type= msoControlWorkPane = 25

   .Caption= Task Pane Name

   .Left is 3 plus the screen width (to allow for 3d highlighting and border space) minus the CommandBars("Task Pane").Width

   .OLEUSage = msoControlOLEUsageServer = 1

   .Top = Document window top

   .Width = six less than the CommandBar

 

 

Registry Hacks

HKEY_CURRENT_USER\Software\Microsoft\Office\10.0\Common\General\DoNotDismissFileNewTaskPane

A Value of 1 prevents the Task Pane from dismissing when it creates or opens a new document.

 

SP-3 uses

HKEY_CURRENT_USER\Software\Microsoft\Office\10.0\Word\Options\StartupDialog

A Value of 1 addresses the issue of the Task Pane being unintentionally dismissed when add-ins are present.

 

Notes

The DoNotDismissFileNewTaskPane came before the StartupDialog and a side effect of the hack was to prevent the Task Pane from dismissal when add-ins are present. Adobe used the former as an attempt to workaround this issue. This was not the best method as this hack disregards the Tools > Options > Show task pane at startup option which is still an issue in both Word 2002 and Word 2003. MS are still working on fully correcting this issue as of May 2004.

Common Error Messages

Shame Microsoft! Shame shame shame! Two errors, two messages, one error number. This list spans the whole set of Task Panes. It is not complete as Microsoft were far less than helpful when asked for more information. These errors are not listed in the Office Resource Kit errormsgs.xls spreadsheet. The problem is they come from external libraries, the main one being an InfoPath library.

 

Number

Description

Caused by

4605

This command is not available.

Out of context showing of wdTaskPaneDocumentActions

4605

This method or property is not available because the current document has been modified or does not have an XML transform associated with it.

Out of context showing of wdTaskPaneXMLDocument

5941

Method 'Item' of object 'TaskPanes' failed

Using a TaskPanes() id that does not exist

6134

XML Expansion Pack is invalid or cannot be loaded.

Attempting to programmatically add XML from VBA.

6162

This command is not available outside of the fax mail envelope.

Out of context showing wdTaskPaneFaxService

-2147467259

Automation error. Unspecified error.

Trying to change Read Only properties of msoControlWorkPane or the Task Pane CommandBar or make it visible when it hasn’t been shown for that document

 

 

Avoiding errors

There are two schools of thought on programming methodology. One is to handle the errors; the other is to avoid them. I subscribe to the latter, so thus this topic.

 

Feature

Test with

SharePoint

ActiveDocument.SharedWorkspace.Connected

XML

ActiveDocument.XMLNodes.Count>0

XSL

Application.ArbitraryXMLSupportAvailable

ActiveDocument.XMLSchemaReferences.Count>0

Online Fax Service provider

Read Chapter 10 of the VBA Developer’s Handbook by Ken Getz et al on how to use registry keys. ProfileString is frustratingly one path off being usable. If this key exists, there is an online provider:

HKEY_CURRENT_USER\Software\Microsoft\Office\11.0\Common\Services\Fax

 

New Built-in Word Commands

You can access these from the Tools > Macro > Macros… dialog, change Macros in to Word Commands. These built-in Word commands either call a new WordBasic function of the same name or display a Task Pane or Dialog to do the real work. For example:

 

Sub ViewTaskPane()

'

' ViewTaskPane Macro

' Shows or hides the Task Pane

'

   WordBasic.ViewTaskPane

 

End Sub

 

Some of these commands, when created through the Macros dialog, come up empty, but are using the WordBasic commands, unless otherwise noted.

 

DocumentActionsPane

Requires a SharePoint environment. Can be triggered by WordBasic.FileNewContext and other routines that open SharePoint documents. The Document Actions Task Pane is not necessarily at the front.

EditOfficeClipboard

Shows the Clipboard Task Pane

FaxService

Shows the Fax Service Task pane.

FileCheckIn

Requires a SharePoint environment.

FileCheckOut

Requires a SharePoint environment.

FileFind

This also shows a dialog, wdDialogFileFind, but the functionality of this dialog has changed from the File > Open dialog to the File > Save As dialog. It is now useless for finding a file to open.

FileNewContext

Creates a new document based on the active document.

FilePermission

Displays the wdDialogPermission dialog.

FileSearch

Shows the Basic File Search Task Pane by displaying the wdDialogSearch dialog.

FileVersionServer

Requires a SharePoint environment.

FormatStyleByExample

Creates a new style based on the selected formatting.

FormatStyleVisibility

Displays the Format Settings dialog, wdDialogFormatStylesCustom.

FormattingPane

Displays the Styles and Formatting Task Pane.

FormattingProperties

Displays the Reveal Formatting Task Pane.

FormattingRestrictions

Shows the wdDialogFormattingRestrictions dialog.

MailMergeWizard

Displays the Mail Merge wizard using the Mail Merge Task Pane.

MicrosoftOnTheWeb1-17

Various MS web pages to support the online links through the Task Panes.

Research

Target of Tools > Research, displays the Research Task Pane.

ResearchLookup

Target of right-click a word and select Lookup…, displays the Research Task Pane.

SelectSimilarFormatting

Performs a multiple-select on all formatting identical to the selection.

ShowSmPane

Shows the Document Updates Task Pane.

ToggleXMLTagView

Does a ActiveWindow.View.ShowXMLMarkup = wdToggle

ToolsThesaurusRR

Displays the thesaurus results in the Research Task Pane.

Translate

Target of Tools > Translate, displays the Research Task Pane.

TranslatePane

Target of right-click a word and select Translate, displays the Research Task Pane.

ViewTaskPane

Target of View > TaskPane.

XMLDocument

Target of selecting XML Document from the list of available Task Panes.

XMLOptions

Displays the wdDialogXMLOptions dialog.

 

Taming Task Panes

This chapter describes the generic use of Task Panes rather than specific Task Panes themselves. These solutions apply to all or most Task Panes.

 

 

How To

For explanations please see What is it?.

 

All Task Panes

There are several useful commands available to every Task Pane, regardless of its niceness.

 

Determine the displayed Task Pane

In this example solution, TheTaskPane contains the name of the active Task Pane after running the code.

Dim TheTaskPane as String

TheTaskPane = CommandBars("Task Pane").Controls(1).Caption

 

Show a particular Task Pane on startup

This code should be placed in an add-in for best effect. It can cause a runtime error if it is in a document that is double-clicked from Explorer. This example shows the Styles and Formatting Task Pane on startup; see the Developer References to display other Task Panes. As it uses the OnTime command, it is not compatible with other add-ins using this command because Word can only support one OnTime command at a time. We use a 5 second delay because we are executing this during the starting of Word which can take some time with a few add-ins loaded. Any less than this can occasionally cause the problem of the OnTime not executing.

 

Public Sub AutoExec()

Application.OnTime Now + TimeValue("00:00:05"), "AutoPart2"

End Sub

 

Public Sub AutoPart2()

Application.TaskPanes(wdTaskPaneFormatting).Visible = True

End Sub

 

Update a Task Pane

If you update the controls or settings on a Task Pane using any of the specialized hooks into the new feature sets, you might have to refresh the display of the Task Pane. To do this, you hide the Work Pane and show it again.

With CommandBars("Task Pane")

  .Visible = False

  .Visible = True

End With

 


 

Controlling Nice Task Panes

It is a simple job to handle Task panes with a Type, by using the TaskPanes collection.

 

Show/hide a specific Task Pane

To specifically show any of the Nice Task Pane, use the Application.TaskPanes() object. You do not have to do a CommandBars("Task Pane").Visible = True first. For example, to show the Styles and Formatting Task Pane:

Application.TaskPanes(wdTaskPaneFormatting).Visible = True

 

To hide just that Task Pane again

Application.TaskPanes(wdTaskPaneFormatting).Visible = False

 

 

Controlling Bad Task panes

There are varieties of GUI tricks we can use to invoke the functions that summon the Task Pane. They work with some of the Nice Task Panes as well. To hide these Task Panes again is impossible, you can either show another one over the top, or hide the entire set.

Using the Developers References at the end of this chapter to obtain the ID for those Task Panes that have an associated control in the menu structure, you can generically use

CommandBars.FindControl(ID:=<Num>).Execute

 

For example, to show the Insert Clip Art Task Pane use

CommandBars.FindControl(ID:=682).Execute

 

 

Disable / intercept / replace the Task Panes

We can intercept and disable most of the Task Panes using Word’s built-in commands. Where possible, a sensible alternative to the Task Pane is presented as a replacement.

 

View > Task Panes

To disable the feature entirely for the GUI user:

 

Sub ViewTaskPane()

End Sub

 

Basic File Search

Sub FileSearch()

SendKeys "%L", False

Application.FileDialog(msoFileDialogOpen).Show

End Sub

 

This comes as close as possible to having a decent find file dialog without using the Task pane. You still have to press Enter to go into the search dialog.

 

Clipboard

Sub EditOfficeClipboard()

End Sub

 

Document Actions

Some customization is available from:

Tools > Options > General > Service Options > Shared Workspace

 

To disable the feature entirely for the GUI user:

 

Sub DocumentActionsPane()

End Sub

 

Document Updates

Some customization is available from:

Tools > Options > General > Service Options > Shared Workspace

 

To disable the feature entirely for the GUI user:

 

Sub ShowSmPane()

End Sub

 

Fax Service

To disable the feature entirely for the GUI user:

 

Sub FaxService()

End Sub

 

Getting Started

To show / hide the recently used files list:
Tools > Options > General > Recently Used Files List

To show / hide the help link:
Tools > Options > General > Service Options > Online Content.

 

To disable the feature entirely for the GUI user, use
Tools > Options > View > Startup Task Pane,

 

Help

This is a poor substitute:

 

Sub Help()

WordBasic.MicrosoftOnTheWeb2

End Sub

 

Sub HelpAW()

WordBasic.MicrosoftOnTheWeb2

End Sub

 

Insert Clip Art

No can do.

 

Mail Merge

Sub MailMergeWizard()

Dialogs(wdDialogMailMerge).Show

End Sub

 

New Document

Public Sub FileNew()

Dialogs(wdDialogFileNew).Show

End Sub

 

Public Sub FileNewDefault()

Dialogs(wdDialogFileNew).Show

End Sub

 

Protect Document

Sub ToolsProtect()

Dialogs(wdDialogFormattingRestrictions).Display

End Sub

 

This would see you using the Forms toolbar to lock / unlock forms, Tools > Track Changes to toggle protected for changes and Tools > Protect… to alter the editing restrictions. You lose the ability to set user-based editing restrictions, but you could either set a shortcut to FilePermission or call your own macro to display the dialog.

 

Research

To disable the feature entirely for the GUI user:

 

Sub Research()

End Sub

 

Sub ResearchLookup

End Sub

 

Reveal Formatting

Sub FormattingProperties()

Dialogs(wdDialogFormatFont).Show

End Sub

 

Search Results

See Basic File Search.

 

Shared Workspace

Some customization is available from:

Tools > Options > General > Service Options > Shared Workspace

 

Styles and Formatting

Sub FormattingPane()

Dialogs(wdDialogFormatStyle).Show

End Sub

 

Thesaurus

Sub ToolsThesaurusRR()

Dialogs(wdDialogToolsThesaurus).Show

End Sub

 

Translate

To disable the feature for the GUI user:

 

Sub Translate()

End Sub

 

Sub TranslatePane()

End Sub

 

XML Document

See Disable the default XML document view on page 22.

 

XML Structure

To disable the feature for the GUI user:

 

Sub ViewXMLStructure()

End Sub

 

 

For those with no simple trigger (marked No can do), you can customize the toolbars to have the menu entries and shortcuts call your own replacement routines, or simply banish the toolbar buttons altogether.


 

What is it?

Some of the Bad Task Panes can be found on the dropdown of Task Panes in the Work Pane. The Nice Task Panes are easily determined from inside of your VBE, just load up the Object Explorer (F2) and search for wdTaskPanes.

 

Technical Overview

If you go to your VBE > Tools > References and add in the Microsoft Smart Tags library, you can use the Object Explorer (F2) to list the C_TYPE enumeration. This defines the control types available for use in a Task Pane: ActiveX, Button, Checkbox, Combo, DocumentFragment, DocumentFragmentURL, Help, HelpURL, Image, Label, Link, ListBox, RadioGroup, Separator, TextBox.

If you are compiling a DLL from another language, you can then use these controls to build a custom Task Pane that appears on the Document Actions Task pane. Each of these controls then has corresponding method in the ISmartDocument interface. The controls themselves are created using HTML and the page itself is HTML. As these features are called in by XML, the XML Task Panes chapter contains more information.

The reason there is little functionality exposed in the Task Panes to the programmer is that the Task Panes are just a GUI interface into the new objects. Thus, as is the case with many GUI features, you are far better off using the object itself rather than going through the GUI. Using the appropriate object sometimes helps to interface with the GUI.

 

Known Task Panes in 2003

Basic File Search 1

The new File > Search dialog to find files. There is also an Advanced File Search Task Pane that is only accessible through the Basic File Search Task Pane.

Clipboard

The clipboard manager, reasonably useful as a docked dialog.

Document Actions 2

Supports the new 2003 collaboration feature. This is a place for external solutions developed using Smart Document technology to place their controls.

Document Updates

Supports the new 2003 collaboration feature to synchronize the local copy to the SharePoint server.

Fax Service 2

If you have signed up for an Internet Fax Service Provider this interfaces to them.

Getting Started

If you are using Online Content it displays a bunch of links, and always provides the recently used files list. There is no way to display this programmatically. It also provides a link for selecting how much Online content you want. This has no VBA equivalent.

Help

The help system has been through an Assistant, HTML and now finally, why not a Task Pane as well. Show help, up it comes. The attempt at a tri-pane view is poorly implemented and forced. Unfortunately, context sensitive help is outdated.

Insert Clip Art

Why this became a Task Pane, I will never know. The thumbnail dialog worked wonderfully. We pick the insertion point before calling this option, so we do not need to see it. Mind you, it was never a built-in dialog anyway.

Mail Merge

The old Mail Merge wizard on a dose of steroids. A proper task.

New Document

Gives you many more choices for sourcing documents. 2002 is extremely cluttered as a default, 2003 is much nicer with the Recent files making their way to the Getting Started Task Pane.

Protect Document

Supports the new document protection features. You can lock down a document so that the only allowable formatting is style selection with no manual formatting. This is heavenly, late and well worth the upgrade. The old tracked changes / comments /forms protection feature is here as well but is dressed up to also include users for a given set of protection settings. Users can be nominated by email address or windows login name.

Research

Limited web search tool that only searches in online encyclopedias, thesauri, dictionaries and so on.

Reveal Formatting

Works well as a docked dialog to let you scan around document for specific, detailed settings.

Search Results

The old file search dialog in a new home.

Shared Workspace

Supports the collaboration feature set that works only in conjunction with SharePoint. This feature is outside the scope of this reference.

Styles and Formatting

Nice docked dialog usage. The Styles and Formatting Task Pane is a clear winner of the move to a docked Work Pane. This is the first essentially the rudiments of a document reformatting wizard to accelerate document cleanups. Everyone who has used it loves it. 2002 has some quirky problems in the styles implementation, requiring many sets and resets of Track manual formatting to get full use out of it without ruining your document, but these are addressed both in a 2002 Service Pack and in 2003. The one big problem you are stuck with is the large size of the styles in the list, thus showing less than a desirable number of entries at once. It would also be nice to see a Sort by frequency of appearance list. Still nicer would be to see the provided hooks for this object actually work!

It works in conjunction with several settings in Tools > Options > Edit.

Translate

A simple translation interface that uses an online engine. 2003 cheats mildly and actually uses the Research Task Pane retargeted to the translation interface. MS have obviously made a standard control for this one and have exposed it internally. Would have been fine as a dialog.

XML Document 2

Only applicable to XSLT / schema based documents; it lets you select from multiple data views of the document. To see this in action, open the file xsl-mappings.xml from within C:\WINDOWS\system32\wbem. This Task Pane automatically displays whenever you open an XML document with an associated XML transform within it (XSL). This would be better off as a dropdown on a standard toolbar rather than chewing up a whole Task Pane with it.

XML Structure 2

Only applicable to XML documents, it shows the hierarchy of XML nodes (instanced XML elements) in an exploded tree form. It makes a luscious docked dialog.

It also contains one of the annoyingly buried links to the XML Options dialog. Everyone repeat after me: The XML Options dialog belongs in Tools > Options > XML! The XML options change the way the XML information operates and displays in the document content, this Task Pane and Word’s functionality, such as saving XML files.

 

1 Is not in the GUI dropdown.

2 Supports a feature that makes little sense to have evocable from the GUI without the presence of the required secondary features. When these secondary features are present, these Task Panes join the list in the GUI.

 

A Collection of TaskPanes

The Nice Task Panes are a formal collection – Application.TaskPanes. Word is the only Office Application to have Nice Task Panes so try to feel privileged – I tried but failed. The Bad Task Panes live in binary cyberspace, locked away behind private addresses in isolation wards. Unfortunately, this sanitarium is in a not the same one where the MVPs are locked up so no one can get to them.


 

Developer References

 

Known Task Pane VBA Summary

This hard-core table quickly references the known Task Panes to their VBA partners in slime. My many thanks to Beth Melton, Microsoft Office MVP, for doing the hard yards in the VBE to provide some of the initial raw data for this table.

Those task panes with a wdTaskPanes type are Nice Task Panes as described in Definitions. For alternative means of calling many of the Task panes, see also New Built-in Word Commands on page 5.

 

Name

wdTaskPanes type

Value

Ctrl ID

Word

Clip Art

Null

Null

682

2002

Clipboard

Null

Null

809

2002

Document Actions

wdTaskPaneDocumentActions

7

Null

2003

Document Updates

wdTaskPaneDocumentUpdates

13

7423 1

2003

Fax Service

wdTaskPaneFaxService 2

11

Null 3

2003

Getting Started

Null

Null

Null

2003

Word Help

wdTaskPaneHelp

9

984 4

2003

Mail Merge

wdTaskPaneMailMerge

2

6070 5

2002

New Document

Null

Null

18

2002

Protect Document

wdTaskPaneDocumentProtection

6

7116

2003

Research

wdTaskPaneResearch

3

7343

2003

Reveal Formatting

wdTaskPaneRevealFormatting

1

6094

2002

Basic File Search

WdTaskPaneSearch

4

5905

2002

Shared Workspace

wdTaskPaneSharedWorkspace

8

7710

2003

Styles and Formatting

wdTaskPaneFormatting

0

5757

2002

Translate

wdTaskPaneTranslate

10

7021

2003

XML Document

wdTaskPaneXMLDocument 6

12

Null

2003

XML Structure

wdTaskPaneXMLStructure

5

7171 7

2003

 

 1 Generates runtime error 91 Object variable or With block variable not set if the document is not associated with a workspace. Using wdTaskPaneDocumentUpdates does not.

 2 If used out of context it always displays message box that tries to take the user to the site for signing up for this service. Well done Microsoft, just ignore Application.DisplayAlerts whenever you feel like it, it is a poorly implemented standard at best anyway.

 3 You can also use ActiveDocument.SendFaxOverInternet.

 4 You can also use Application.Help.

 5 Use ActiveDocument.MailMerge.ShowWizard instead.

 6 Generates runtime error 4605 if the document has no associated XSL transform.

 7 Generates runtime error 91 if the document is not XML.

 

Key

Name

The string used in CommandBars(“Task Pane”).Controls(1).Caption

If no Task Pane is shown, this returns Tas&k Pane.

wdTaskPanes type

The enumerated constant used in Application.TaskPanes()

Value

The value of the wdTaskPanes constant

Ctrl ID

The Long used as the ID parameter in
CommandBars.FindControl(ID:=<nnn>).Execute

Word

The earliest version of Word supporting that Task Pane.


 

List all Nice Task Panes

This code was used as input to some of this reference. Run it on your version of Word to determine what is available. It appears to do nothing for a short while as it checks all the unused Task Pane types. It loves making Word 2003 crash shortly afterwards. You can use Ctrl+Break to stop it anytime you like; so after text has stopped appearing, just kill it. To be safe, save the results and exit Word.

 

Public Sub ShowAllTaskPanes()

'Author Steve Hudson, Word Heretic

Dim Report As Document

Dim Insertion As Range

 

Dim Name As String

Dim OldName As String

Dim k As Long

 

Set Report = Application.Documents.Add

Set Insertion = Report.Content

Insertion.Collapse wdCollapseStart

Application.DisplayAlerts = wdAlertsNone

On Error GoTo ErrorHandler

For k = 0 To 2 ^ 16 - 1

   Application.TaskPanes(k).Visible = True

   Name = CommandBars("Task Pane").Controls(1).Caption

   If Name <> OldName Then

      Insertion.InsertAfter k & vbTab & Name

      Insertion.InsertParagraphAfter

      OldName = Name

   End If

Next

Insertion.ConvertToTable AutoFit:=True, _

 AutoFitBehavior:=wdAutoFitContent, _

 DefaultTableBehavior:=wdWord9TableBehavior

 

ErrorHandler:

 

With Err

  If.Number > 0 Then

    If.Number <> 5941 Then

 

      Insertion.InsertAfter k & vbTab & "Err # " &.Number & "(" &.Description & ")"

      Insertion.InsertParagraphAfter

 

    End If

    .Clear

    Resume Next

  End If

End With

 

Application.DisplayAlerts = wdAlertsAll

Set Insertion = Nothing

Set Report = Nothing

End Sub

 

Collaboration Task Panes

 

How To

For explanations please see What is it?.

 

New Document

Add / remove items

If you want to change what documents and templates appear on this Task Pane you can use these wrappers for the NewDocument object instead of calling the functions directly. The wrappers merely add some extra safety checks in before calling the functions, thus preventing several annoying problems at once. The poor built-in functions are then safely wrapped up inside these code segments.

 

To call the wrappers, only refresh the Task Pane when you have finished adding to it. For example:

 

NewDocumentAdd "C:\Temp\SillyFilename.doc", msoBottomSection, "Silly Stuff",,False

NewDocumentAdd "C:\Temp\SillyFilename2.doc", msoBottomSection, "Silly Stuff2",,False

NewDocumentAdd "C:\Temp\SillyFilename3.doc", msoBottomSection, "Silly Stuff3",,True

 

 

The wrapper to add an item

Sub NewDocumentAdd( _

 Filename As String, _

 Optional FileSection As MsoFileNewSection = msoOpenDocument, _

 Optional DisplayName As String, _

 Optional Action as msoFileNewAction = msoEditFile, _

 Optional Refresh As Boolean = True)

 

 

'Prevent duplicate entries

 

NewDocumentRemove Filename, FileSection, DisplayName, Action, False

 

 

'Add it

 

With Application

 

   .NewDocument.Add Filename, FileSection, DisplayName, Action

 

 

   If Refresh Then

      With .CommandBars("Task Pane")

        .Visible = False

        .Visible = True

      End With

   End If

  

End With

End Sub

 


 

The wrapper to remove an item

Sub NewDocumentRemove( _

 Filename As String, _

 Optional FileSection As MsoFileNewSection = msoOpenDocument, _

 Optional DisplayName As String, _

 Optional Action as msoFileNewAction = msoEditFile, _

 Optional Refresh As Boolean = True)

 

Dim FileStart As Long

 

With Application

 

   'Create display name

 

   If Len(DisplayName) = 0 Then

      FileStart = InStrRev(Filename, .PathSeparator)

      If FileStart = 0 Then

         DisplayName = Filename

      Else

         DisplayName = Mid$(Filename, FileStart + 1)

      End If

   End If

 

 

   'Remove

 

   .NewDocument.Remove Filename, FileSection, DisplayName, Action

 

 

   If Refresh Then

      With .CommandBars("Task Pane")

        .Visible = False

        .Visible = True

      End With

   End If

 

End With

End Sub

 


 

Protect document

Protect the document against changes

ActiveDocument.Protect wdAllowOnlyRevisions

 

Unprotect the document

ActiveDocument.Protect wdNoProtection

 

Allow someone to edit the selection range

This only makes sense if the document is protected against changes.

Selection.Range.Editors.Add "steve@SPAMSLAMwordheretic.com"

 

Add to the Available Individuals list

The list tracks recently used Editors. So to add to the list without adding Editors, call this function with the User Id to add. For example:

AvailableIndvidualsAdd "steve@SPAMSLAMwordheretic.com"

 

The function:

Public Sub AvailableIndvidualsAdd(UserId as String)

Dim Ed as Editor

 

Set Ed = Selection.Editors.Add UserId

Ed.Delete

 

Set Ed = Nothing

End Sub

 

Force user to format using styles

ActiveDocument.EnforceStyle = True

 

Allow user to manually format

ActiveDocument.EnforceStyle = False

 

 

Shared Workspace

Detect whether SharePoint is present

You can use this code to avoid using SharePoint features in documents that are not part of a SharePoint shared workspace.

If ActiveDocument.SharedWorkspace.Connected then

   'SharePoint is present

Else

   'SharePoint is not present

End If

 


 

Getting Started

These old solutions used to only apply to the File menu but now also apply to this Task Pane.

 

Add the active document to the recent files list

Application.RecentFiles.Add ActiveDocument

 

Remove the most recent file from the recent files list

Application.RecentFiles(1).Delete

 

 

What is it?

 

Introduction

There are many basic requirements for collaboration, including but not limited to: grouping files in folders for open and creation by host applications, checking different versions of the edits in and out and allowing user groups allowed to edit or read various parts of these files. Thus, we have several new objects in Word for providing hooks into these functional requirements.

The new Task Panes that directly or indirectly support collaboration are: New Document, Protect Document, Shared Workspace and Document Updates.

The New Document Task Pane is the easiest to use out of all of these. It provides the GUI interface for the NewDocument object to hold its entries. The NewDocument object is Word’s implementation of an office-wide object called NewFile. If you like, it is fairly close to Word containing the equivalent of this VBA statement:

Public NewDocument as NewFile

Therefore, this Task Pane was an easy way out of redoing the Open File dialog to tie into this new object. As a secondary side effect, it is a neat feature to allow an easily programmed display of common files, which is a blessing for corporate implementations. However, the purpose of manually opening a document is almost completely exclusive to requiring a clear, uninterrupted view of the active document and its implementation as a Task pane is a poor choice – a clear case of feature envy in a development group.

The Protect Document Task Pane provides the GUI interface to the Editors collection. This allows you to assign editing rights to any portion of the document you like, to anyone with an MS Passport or a login on your domain. Of course, this only makes sense if the document is protected against changes. This is a fantastic new feature for corporate implementations right through to lone authors undergoing review processes with their peers. If you are going to allow for collaboration, this is a required feature. It does need to be a docked dialog, so from that perspective it makes sense for it to be a Task Pane. It also supports protection for formatting, so there is a new document property for that.

The Shared Workspace and Document Updates Task Panes are concerned with interacting with the SharePoint collaboration server. They support the virtual, shared folders that files, such as documents and spreadsheets, sit in as well as the various check-in, check-out and other versioning commands.

There are also some small extensions to existing objects to add in some required linkages to these new features.

 


 

Application.NewDocument

This is Word’s implementation of the office-wide object called NewFile. Each application calls it something different based upon their base file format. For example, Excel calls its version NewWorkBook.

It allows you to customize the entries on the New Document Task Pane. The sorts of actions you use with the files are generic across the applications, so the action type remains the same for every application. This is where we see MS making an effort to standardize application usage as much as possible, which simplifies cross-application development and allows meta-objects. If you instance a NewFile object, you can use it across all the applications.

To understand its purpose in collaboration you need to read between the lines. SharePoint does not want to know what the individual application methods are to create a new file. It just wants to ask to create a new file, open an existing file and so on. As this NewFile object must be capable of executing the items on it – that is, when you select something it opens or creates a new file – it is also therefore the main mechanism, though hidden from VBA, for SharePoint to access the files belonging to the application. It just asks the Host Application to perform the appropriate NewFile action.

 

The wrappers

The functional wrappers provided in How To for the main methods of this object help prevent irremovable entries and duplicates. If you add an item with no display name, you cannot remove it later – other than by destroying the Word data key in the registry and maybe renaming Normal.dot. If you have not provided a display name, the wrappers automatically provide one the same as the file name.

You cannot get the names or the count of the items on this pane – MS have hidden the Item property, so you cannot see what is there already. As duplicates occur when you re-add the same item, the easiest way to prevent is to attempt to delete any existing item with the same details, which is exactly what the Add wrapper does.

The parameters are:

Filename As String

The full path and filename of the document or template to add to this pane.

Optional FileSection As MsoFileNewSection

There are five possible areas on the New Documents pane to place the item. The Recently used templates section of the Task Pane retains the last four templates used via the Task Pane. However, if you add a template to that section of the Task Pane by using msoNewFromFile, it appends as an addition to the four recently used templates and stays there permanently until removed by use of NewDocumentRemove. If you fill the Task Pane by adding templates by one of these methods, a scroll arrow appears at the bottom of the Pane.

Optional DisplayName As String

The label for the Task Pane to identify this file to the GUI user.

Optional Action as msoFileNewAction

There are the three generic FileNew actions of type msoFileNewAction.

Optional Refresh As Boolean = True

This extra functionality updates the display of the Task Pane.

 


 

Permission

This is an office wide object. Through the GUI, you can only set global permissions, but through VBA, you can set them on a per-user basis with expiry dates. This affects the available options for the document in the collaboration Task Panes. You can only set this programmatically from inside a Shared Workspace, however the GUI allows you to add the permissions and creates a dummy Shared Workspace for it to sit in.

Groups referenced by Permissions are added to the list of available groups in the Protect Document Task Pane.

 

SharedWorkspace

This is an office wide object. It represents the online folder for the file to be stored in, hosted by a SharePoint server. It is rich in properties and methods, to reflect the wealth of actions and information available for working with files in a collaborative environment. The methods are used by many of the Task Pane functions.

If you want to play in a small simulation, set the File > Permissions on a blank file.

 

DocumentLibraryVersion

Each DocumentLibraryVersion represents a saved version of a document stored with versioning enabled on a SharePoint server. This feature allows you to programmatically regress or compare versions and affects the available options for the document in the collaboration Task Panes.

 

Editor

An Editor is someone who has been given explicit permission to edit a part of the document. These people are listed in the Available Individuals list on the Protect Document Task Pane. It is impossible to really tell the current user’s rights in this document from looking at this object.

Consider this trivial function:

Public Function UserWinLoginName() As String

Dim Ed As Editor

 

Set Ed = Selection.Editors.Add(wdEditorCurrent)

UserWinLoginName = Ed.Name

Ed.Delete

 

Set Ed = Nothing

End Function

 

We get the Windows Login name for the user. However, IRM is also assigned by way of email addresses, so this is almost useless to us. To get the email name, you need to create a document inside a shared workspace to get its Permission.DocumentAuthor property.


 

RecentFiles

This is an existing Word object that is used by the Getting Started Task Pane.

 

New methods and properties

These are new extensions to old objects.

Document.CanCheckIn

For this to be true, you must have the document checked out from the SharePoint server.

Document.CheckIn

Checks the document back into the SharePoint server. Use the CanCheckIn property to determine if this can be done or not.

Document.DeleteAllEditableRanges

Useful for resetting the users work area on some document types.

Document.EnforceStyle

Whether to allow manual formatting or force the use of styles only.

Document.GotoEditableRange

Range.GoToEditableRange

Useful for programmatically addressing the available content

Document.SelectAllEditableRanges

Limited uses on some document types for saving the edits elsewhere.

Document.Sync

Updates the local copy of the document from the SharePoint server. Triggers the two sync events after the sync.

View.ShadeEditableRanges

Helps the user to see what is for them to play with or not.

 


 

Developer References

 

Application.NewDocument

Methods

These native methods are problematic, wrappers are provided in preceding topics.

 

.Add FileName, Section, DisplayName, Action

Adds a new item to the New Document Task Pane.

FileName

Required String. The name of the file to add to the list of files on the task pane.

Section

Optional Variant. The section to which to add the file. Can be any msoFileNewSection constant.

DisplayName

Optional Variant. The text to display in the task pane.

Action

Optional Variant. The action to take when a user clicks on the item. Can be any msoFileNewAction constant.

 

.Remove FileName, Section, DisplayName, Action

 

Removes an item from the Task Pane with the exact matching properties. No error or warning on fail. The parameters are the same as .Add.

 

msoFileNewSection

0          msoOpenDocument

1          msoNew

2          msoNewFromExistingFile

3          msoNewfromTemplate

4          msoBottomSection

 

msoFileNewAction

0          msoEditFile

1          msoCreateNewFile

2          msoOpenFile

 


 

Range.Editors

A collection of Editor objects.

 

Methods

.Add(EditorID) as Editor

 

EditorID

Required Variant. One of:

·       A String that represents the user's e-mail alias / login from the same domain

·       An e-mail address as validated from MS Passport

·       A WdEditorType that represents a group of users.

 

wdEditorType

wdEditorCurrent

The current user of the document.

WdEditorEditors

Represents the entire Editors group for documents that use IRM.

WdEditorEveryone

Represents all users who open the document.

WdEditorOwners

Represents the Owners group for documents that use IRM.

 

Properties

.Count

Long

The number of Editors for this range.

.Item

Editor

The Editor object.

 

Editor

A single user allowed to edit a single range.

 

Methods

.Delete

Deletes this Editor.

.DeleteAll

Deletes all Editors for the range.

.SelectAll

Select all the ranges the Editor is allowed to use.

 

Properties

.ID

String

A name to use when converting to the web

.Name

String

The user id of the Editor.

.NextRange

Range

The next range they are allowed to edit.

.Range

Range

The range for this Editor.

 


 

Document.Permission

Methods

.Add(UserId As String, [Permission as MsoPermission], [ExpirationDate as Date]) As UserPermission

 

MsoPermission can be one or a combination of these constants. However, do not use msoPermissionChange in combination with anything below it.

1     msoPermissionRead

1     msoPermissionView

2     msoPermissionEdit

4     msoPermissionSave

8     msoPermissionExtract

15    msoPermissionChange

16    msoPermissionPrint

32    msoPermissionObjModel

64    msoPermissionFullControl

 

.ApplyPolicy(FileName As String)

 

Properties

.Count

Long

.DocumentAuthor

String

.Enabled

Boolean

.EnableTrustedBrowser

Boolean

.Item

UserPermission

.PermissionFromPolicy

Boolean

.PolicyDescription

String

.PolicyName

String

.RemoveAll

Method

.RequestPermissionURL

String

.StoreLicenses

Boolean

 


 

Shared WorkSpace Task Pane

This list shows the VBA equivalents for the information and functions available from this Task Pane.

Status

A summary of some of the secondary objects and properties, for example Permissions.

Members

ActiveDocument.SharedWorkspace.Members

Tasks

ActiveDocument.SharedWorkspace.Tasks

Documents

ActiveDocument.SharedWorkspace.Files

Links

ActiveDocument.SharedWorkspace.Links

Document Information

ActiveDocument.DocumentLibraryVersions(n).ModifiedBy

Document Workspace name

ActiveDocument.SharedWorkspace.Name

Location for new workspace

ActiveDocument.SharedWorkspace.SourceURL

Create

ActiveDocument.SharedWorkspace.CreateNew

 

 

Events

New Event

Object

Notes

DocumentSync

Application

When finished synchronizing a local copy against the SharePoint server source.

Sync

Document

Same as DocumentSync

 

 

Properties and Methods

Parent Object

Feature

Property / Method

Type

Document

SharePoint

CanCheckIn

Boolean

Document

SharePoint

CheckIn

Method

Document

SharePoint

Sync

Method

Document

Protect Document

DeleteAllEditableRanges

Method

Document

Protect Document

SelectAllEditableRanges

Method

Document

Protect Document

GotoEditableRange

Method

Document

Protect Document

EnforceStyle

Method

Document

Protect Document

Protect

Method

View

Protect Document

ShadeEditableRanges

Method

Range

Protect Document

GoToEditableRange

Method

 

XML Task Panes

 

 

How To

For explanations please see What is it?.

 

XML Structure

To determine if a document is XML

With ActiveDocument

   If .XMLNodes.Count>0 then

      'It is an XML doc

   Else

      'It is not an XML doc

   End If

End With

 

Disable the default XML document view

This example solution not only disables the entire Work Pane for just that document, it also turns off the Document Map feature. The OnTime only needs a second delay as it fires during document open, which is much faster than application open.

 

Public Sub AutoOpen()

If ActiveDocument.XMLNodes.Count > 0 Then Application.OnTime Now + TimeValue("00:00:01"), "XMLViewKiller"

End Sub

 

Public Sub XMLViewKiller()

CommandBars("Task Pane").Visible = False

ActiveWindow.DocumentMap = False

End Sub

 

 

XML Options dialog

This dialog is accessed from the XML Structure Task Pane and modifies the Task Pane’s appearance.

 

Save data only

ActiveDocument.XMLSaveDataOnly=True

 

Apply custom transform

ActiveDocument.TransformDocument "c:\path\filename.xsl"

 

Validate document against attached schemas

ActiveDocument.XMLSchemaReferences.AutomaticValidation = True

 

Hide schema violations in this document

ActiveDocument.XMLSchemaReferences.HideValidationErrors = True

 

Ignore mixed content

ActiveDocument.XMLSchemaReferences.IgnoreMixedContent = True

Allow saving as XML even if not valid

ActiveDocument.XMLSchemaReferences.AllowSaveAsXMLWithoutValidation = True

 

Hide namespace alias in XML Structure task pane

ActiveDocument.XMLHideNamespaces = True

 

Show advanced XML error messages

ActiveDocument.XMLShowAdvancedErrors = True

 

Show placeholder text for all empty elements

ActiveDocument.XMLSchemaReferences.ShowPlaceholderText = True

 

Schema Library

This list displays the entries in Application.XMLNamespaces.

 

To select a filtered list of nodes

ActiveDocument.SelectNode AnXPath,Prefix

 

To select the first node matching the filter

ActiveDocument.SelectSingleNode AnXPath,Prefix

 

 

XML Document

Determine whether you can use schemas at all

Use this check before any XSL support to ensure it is available on that machine. Standard Word installations may not come with a full XML package.

If Application.ArbitraryXMLSupportAvailable then

   'we can use schemas

Else

   'we cannot use schemas

End If

 

Determine if the active document has any attached schemas

Do not forget to also include the code block directly above.

If ActiveDocument.XMLSchemaReferences.Count>0 then

   'There are attached schemas

Else

   'There are no attached schemas

End If


 

What is it?

To describe how to use the displays of these Task Panes is to describe using XML in a document, so it is out of scope. There are several major objects involved here, see the Developer References for more information.

Unfortunately, you will get errors trying to use many of the new XML objects from VBA, as they are not fully supported from VBA. For more information see http://msdn.microsoft.com/library/default.asp?url=/library/en-us/odc_wd2003_ta/html/odc_wdsimplesd.asp.

Essentially, you can read, but not add. Of course, opening the document as a text file and processing away is still available, but a poor substitute.

Using these Task Panes is like using the Document Map or Outline View, instead of examining headings and linked templates; you examine Nodes and linked Schemas instead.

XML documents have several properties that standard documents do not. The XML tags in the document are structured, so we have an XML structure of XML Nodes not unlike the outline map of headings. XML can be transformed and validated, so there are collections of new objects to support these requirements.

The XML Structure Task Pane brings together the XML objects, the XML Options dialog sets many of the new properties and the XML Document Task Pane for now only brings in the XML schemas. The Document Actions Task Pane is for solutions written in non-VBA languages to place controls using Smart Document technology. You compile a DLL that includes a class that implements the ISmartDocument interface from the Smart Tags library and refer to it from the schema.

 

Application.XMLNameSpaces

A collection of XML Name Spaces to hold the known XML Name Spaces for the Application.

 

Document.XMLSchemaReferences

Holds the list of validating schemas for the document. This library is found in the GUI using the XML Schema tab in the Templates and Add-ins dialog box. This library is used to source schemas for XML documents.

 

Range.XMLNodes

Holds the tree structure of the nodes in an XML file. This is used to populate the XML Structure Task Pane. Any range in the document has an XMLParentNode to get the Node that fully surrounds it. You can either add to the Nodes collection or use Range.InsertXML.

You can also use SelectNode or SelectSingleNode to find specific nodes throughout the document.

Adding to, removing or modifying the collection triggers various XML events. This allows more detailed Smart Document solutions.


 

Developer References

 

Events

New Event

Object

Notes

XMLAfterInsert

Document

When any element is added to a document.

XMLBeforeDelete

Document

Triggers for every element removed from a document

XMLSelectionChange

Application

Triggers when the XML is changed

XMLValidationError

Application

On the first validation error when validating the XML in a document.

 

 

Properties and Methods

Parent Object

Feature

Property / Method

Type

Document

XML Structure

SelectNode

Method

Document

XML Structure

SelectSingleNode

Method

Document

XML Document

TransformDocument

Method

Application

XML Document

ArbitraryXMLSupportAvailable

Boolean

Range

XML Structure

InsertXML

Method

View

XML Document

ShowXMLMarkup

Toggle

 

There is also the new Document Type for XML, for example

ActiveDocument.SaveFormat = wdFormatXML

 

Reformatting Task Panes

These Task Panes help reformat document content. Both work well as docked dialogs and are begging for feature extension.

 

 

How To

 

Reveal Formatting

This displays the properties of Selection.Font and Selection.Paragraphs(1).Style objects. It allows several fancy tricks that have no VBA access at this point. Anything involving discontinuous selection is beyond our current reach.

 

Styles and Formatting

Use the standard Show filters

Call the wrapper below with the desired style Show filter. For example:

StylesAndFormattingFocus wdShowFilterFormattingAll

 

As all parameters are optional, you only need to specify those parameters whose default is unsuitable. The Show dropdown is always set to Custom, but it shows the right stuff.

Public Sub StylesAndFormattingFocus( _

 Optional ShowFont As Boolean = True, _

 Optional ShowClear As Boolean = False, _

 Optional ShowNumbering As Boolean = True, _

 Optional ShowParagraph As Boolean = True, _

 Optional FilterStyle As WdShowFilter = wdShowFilterFormattingAvailable)

 

'Ensure the S&F Task Pane is showing

 

With CommandBars("Task Pane")

   If .Controls(1).Caption <> "Styles and Formatting" _

    Then CommandBars.FindControl(ID:=5757).Execute

End With

 

With ActiveDocument

    .FormattingShowFont = ShowFont

    .FormattingShowClear = ShowClear

    .FormattingShowNumbering = ShowNumbering

    .FormattingShowParagraph = ShowParagraph

    .FormattingShowFilter = FilterStyle

End With

StylesAndFormattingRefresh

End Sub

 

Public Sub StylesAndFormattingRefresh()

SendKeys "{Enter}"

Dialogs(wdDialogFormatStylesCustom).Execute

End Sub

 


 

Show all styles

Public Sub StylesReveal()

Dim Item As Style

 

For Each Item In ActiveDocument.Styles

   Item.Visibility = True

Next

Set Item = Nothing

End Sub

 

Hide all styles

Public Sub StylesHide()

Dim Item As Style

 

For Each Item In ActiveDocument.Styles

   Item.Visibility = False

Next

Set Item = Nothing

End Sub

 

Use a custom display of selectable styles

This example solution re-uses routines from the preceding solutions.

Public Sub StylesAndFormattingCustomMine()

 

'Set the Task Pane to a custom focus

 

StylesAndFormattingFocus

 

 

'Hide all styles

 

StylesHide

 

 

'Show our styles

 

With ActiveDocument.Styles

   .Item("Body Text").Visible = True

   .Item("Heading 1").Visible = True

End With

 

'Refresh the Task Pane

 

StylesAndFormattingRefresh

 

End Sub


 

What is it?

The Styles and Formatting Task Pane is a clear winner of the move to a docked Work Pane. This is the first rudiments of a document reformatting wizard to accelerate document cleanups. Everyone who has used it loves it. 2002 has some quirky problems in the styles implementation, requiring many sets and resets of Track manual formatting to get full use out of it without ruining your document, but these have been addressed both in a Service Pack and in 2003. The one big problem is you are stick with is the large size of the styles in the list, thus showing less than a desirable number of entries at once. It would also be nice to see a Sort by frequency of appearance list. Still nicer would be to see the provided hooks for this object work without the run-around!

The Styles and Formatting Task Pane uses a hidden property of the styles to control whether they display on this pane or not. If you wanted to programmatically control which styles were shown or not, you could either show all the styles, using the sub below and then hide the ones

The Reveal Formatting Task Pane also works well as a docked dialog to let you scan around document for specific, detailed settings.

The two options of relevance are FormatScanning, labeled as Keep track of formatting in the GUI and ShowFormatError, labeled as Mark formatting inconsistencies in the GUI. Both of the GUI options are found in Tools > Options > Edit.

 

 

Developer References

 

Properties

None of the Document properties actually work.

Parent Object

Feature

Property / Method

Type

Document

Styles and Formatting

FormattingShowClear

Boolean

Document

Styles and Formatting

FormattingShowFilter

wdShowFilter

Document

Styles and Formatting

FormattingShowFont

Boolean

Document

Styles and Formatting

FormattingShowNumbering

Boolean

Document

Styles and Formatting

FormattingShowParagraph

Boolean

Options

Styles and Formatting

FormatScanning

Boolean

Options

Formatting

ShowFormatError

Boolean

 

 

Enumerations

wdShowFilter

0      wdShowFilterStylesAvailable

1      wdShowFilterStylesInUse

2      wdShowFilterStylesAll

3      wdShowFilterFormattingInUse

4      wdShowFilterFormattingAvailable

Mail Merge Task Panes

 

How To

For explanations please see What is it?.

 

Show the third step of the Mail Merge Wizard and not 5 or 6

ActiveDocument.MailMerge.ShowWizard 3,True,True,True,True,False,False

 

Determine what step the Mail Merge Wizard is up to

Dim Step as Long

Step = ActiveDocument.MailMerge.WizardState

 

Set the label on the custom destination in step 6 of the Mail Merge Wizard

ActiveDocument.MailMerge.ShowSendToCustom = "Word Heretic document solutions"

 

To get the custom destination for the Mail Merge

This function returns or sets the custom button on the Complete the merge step of the Mail Merge Wizard. The example returns the current setting.

Dim CustomSendTo as String

CustomSendTo ActiveDocument.MailMerge.ShowSendToCustom

 

 

What is it

There are several useful features available to play with this unusual set of Task Panes. It has many events, as described in Developer References, as well as some interesting properties and attributes.

The most interesting attribute is that it is not just one Task Pane, but six – one for each step of the Mail Merge Wizard. The Wizard’s state drives the contents of the Task Pane. Therefore, we have a Work Pane presenting a Task Pane presenting a Wizard!

As there are a number of panes we have a property to show us where we are up to and a method to display a new pane. The last pane also includes the capability for a custom destination for the mail merge, so there are some properties and an event for getting to that.

The old Document.MailMerge object is still around as are the Mail Merge fields and everything else that this new Task Pane uses. See the existing wealth of references on Mail Merge for more information.


 

Developer References

 

New Events

New Event

Object

Notes

MailMergeAfterMerge

Application

When all records have been merged.

MailMergeAfterRecordMerge

Application

When a record from the data source has successfully merged.

MailMergeBeforeMerge 1

Application

When a merge executes before any records merge

MailMergeBeforeRecordMerge

Application

When a merge commences for a record

MailMergeDataSourceLoad

Application

When a user opens the Recipients dialog.

MailMergeDataSourceValidate

Application

When a user selects Validate in the Mail Merge Recipients dialog.

MailMergeWizardSentToCustom

Application

When Custom destination is selected in the last step of the Mail Merge Wizard.

MailMergeWizardStateChange

Application

Whenever a user changes step in the Wizard.

 

1 The existing bug for this event still has not been fixed. The MailMergeBeforeMerge event only triggers if the mail merge is launched from the Task Pane. If it is launched from the toolbar or via automation, the event does not trigger.

 

 

Properties and Methods

Parent Object

Associated feature

Property / Method

Type

MailMerge

Mail Merge

ShowSendToCustom

String

MailMerge

Mail Merge

WizardState

Long

MailMerge

Mail Merge

ShowWizard

Method

Other Docked dialogs

These are old Word features that have found a new home as a Task Pane and some new features that needed a home.

 

 

How To

For explanations please see What is it?.

 

Clipboard

To add the selection’s range to the clipboard

Selection.Range.Copy

 

To replace the selection with the first clipboard item

Selection.Range.Paste

 

 

Fax Service

To fax a document, by way of the designated Online Fax Service Provider

This example solution does not show the fax before sending it. The recipients addresses need to be in the Recipients string and the subject for the fax in the Subject string.

ActiveDocument.SendFaxOverInternet Recipients, Subject, False

 

 

Help

To show the help Task Pane

Application.Help wdHelp

 

To show the About Word dialog

Application.Help wdHelpAbout

 

 


 

What is it?

 

The untouchables

These Task Panes cannot be interacted with: Clip Art, Research and its options, Translate and its options and Basic File Search. It is a great and glorious shame the programmers still have not provided entry points for the basic functions. The Application.FileSearch object is intact, just divorced from this Task Pane.

 

Clipboard

This still has not been meaningfully exposed to VBA. If you use system calls, you can access a fair bit of the clipboard manager’s functionality. You are still more or less stuck with Copy, Cut and Paste.

 

Fax Service

Testing this Task Pane’s interactivity with the Document.SendFaxOverInternet command is out of scope.

 

Help

The Application.Help object is supposed to allow us flexible entry points into the help system. It does not. At least you can get Help and About Word out of it, which is all we had before anyway.

 

 

Developer References

 

Clipboard

New method Document.ShowClipboard.

 

Fax Service

New method Document.SendFaxOverInternet

 

Getting Started

Application. RecentFiles is an old Word object that can be used to change the list of recently used documents. There are also the default parameters of various Document actions that add to this list.


 

Help

wdHelpType

WdHelp

Displays the Help Task Pane ready to search the last entry.

WdHelpAbout

Displays the About Microsoft Word dialog.

WdHelpActiveWindow

May display Help describing the command associated with the active view or pane given certain context.

WdHelpContents

Displays the Help Task Pane.

WdHelpHWP

No action.

WdHelpIchitaro

No action.

WdHelpIndex

Displays the Help Topics Task Pane.

wdHelpPE2

No action.

WdHelpPSSHelp

Displays the product support information page in way you cannot close the help page. Avoid this parameter.

WdHelpSearch

Displays the Help Task Pane.

WdHelpUsingHelp

Displays the Help Task Pane.

Ramifications and Ravings

This chapter is the philosophy, rants and drooling that would otherwise obfuscate the above. In isolating these idle musings, the original ideas have grown somewhat. Although prosaic, this chapter is frightfully on topic.

 

 

The sound of a dialog not opening

The new Task Pane is already replacing some built-in Dialogs. wdDialogFileNew is still unaffected – thank goodness – but wdDialogSearch has. That is, if you show the built-in file search dialog, you get the new Task Pane as it has replaced the old dialog completely. Thus, any Word 2k- VBA that uses that file search dialog will probably fail miserably for 2002+. Overall, this does not bode too well for any VBA that uses any dialog at all in a non-trivial way, although WordBasic may continue to offer some backwards compatibility as will the Dialogs object for some dialogs.

For a crazy thought experiment, let us take it to the extreme – every dialog is now a Task Pane. Wow. Our Task Panes dropdown becomes useless and most VBA code using dialogs dies drastically. If they keep full backwards compatibility with the dialogs we have an even more bloated code monster to load and control.

However, if they break out all Task Panes as editable HTML files, we can customize every aspect of our interface to suit our needs. This will tremendously enhance our capabilities, for example, we can insert a simple transform into existing dialogs to switch them into our view mode. Two dialogs for the price of one. It will also be the fastest way ever introduced to humans to completely stuff an interface up.

 

 

So take me to task over it

If Microsoft ever properly implements the notion of tasks in a workflow environment, this new device will enable awesome task-based solutions. Ideally, we use dialogs for tasks with three steps or less. We need a Task Pane for multiple steps that then invoke dialogs and functions. The Task Pane could remain as our overall task guide, as we complete the steps. For example, if the New Document Task Pane was truly to be a task, its steps could look like this:

·       Obtain page layouts

·       Obtain style set

·       Obtain initial content

·       Obtain toolbars

·       Obtain metadata.

 

Having three controls to select from is not having three steps. A single dropdown is not enough to require a task.

The Work Pane makes a great dialog that is auto-docked with the document window. Thus, some dialogs really have benefited from moving to the Work Pane even though they are not tasks. Unfortunately, this will cause vagueness about this new feature’s purpose for many years to come. What is more worrying is it will tend to hide the presence and purpose of a task sitting behind an existing dialog-on-a-Task Pane.

We have no simple way of addressing the settings and controls on these Task Panes. This has crippled them completely from the VBA coder’s perspective. It is possible the rush to market solution we have now could be upgraded in a future releases to provide us with detailed control over the existing Task Panes.


 

God helps those who help themselves

The help system is poor across the board on this topic. There are many mistakes and many omissions. Many are trivial and you can understand the poor technical writer who overlooks error handler for event handler, but they will confuse the heck out of the noobs. Then you have the whole way the new help system misbehaves to deal with. Going to the Help Task Pane > Online Content options and turning the Use Online Content off goes someway toward dealing with this.

In addition, MS really need to start providing overview topics that group many objects together by functionality and feature set. The XML topics are a laughable mess of jargon that completely fails to explain them in context and could be improved with an overview.

Then, from an API perspective, why not have a parameter to pass to Application.Help and have it execute it for us. A search term would be a nice start – Smart Documents are way too overkill for this simple function.

 

 

It is all just a variant on Word Happens anyway

Is it just me, or did you notice the disturbing trend for parameters to be Variants as well. First up, we lose enumerated types auto-popping for us in the VBE. Second, most of the time there is no need for this. I mean, if you keep wandering down this same path then why have any typed parameters at all. The whole damn lot can be Variants. Does the API suffer as a result? You bet. Does the resulting MS code base become larger and slower? You bet. At some point, the people calling the API have to ensure they have typed their variables correctly.

 

 

Smart marketing documents

The Smart Documents technology does not come with Word. Word is the engine for delivering them, but cannot use the technology. The ISmartDocument interface is clumsy at best. If they have implemented custom code to interface to a DLL, this surely would not have been too much of a stretch to allow access to a general class from VBA. Then you have to worry about Trusted sources and so on, it is a damn huge headache to say the least.

To me, this has to be just another excuse to try to force us all up to .Net.

 

 

The distant light

Go read in this reference about the exposure of the Mail Merge Task. There is our little ray of sunshine in an otherwise dark and dreary API. From the presence of the Work Pane and its children, we can infer a few things.

·       A standardized interface is an absolute requirement for many complex new features. Some of the features are now present and thus the Work Pane had to be in as well.

·       Being a half-assed slam into place, there is still some hope for its evolution as the requirements stabilize from the different feature sets that are still being designed / created.

·       MS are onto Tasks at last. Workflow management is becoming more than a buzzword. It will be slow and clumsy at first, but hopefully they will get the hang of it in a half dozen versions.

·       Wizard or Task? Wizard or Task? Will we ever know? Which came first, the Wizard or the Task?

·       Task-based solution sets fits in nicely with low TCO – all those hours spent creating then fixing Word documents must come crashing down. As they establish standard corporate workflow sub-patterns, we will find our jobs made easier and easier. XML is going to help enable this through rich document identification schemas. Less fiddling, more time to richly mark up text. Better results.

Hopefully the Work Pane will be flexible enough to allow multiple instances and the other various auto-docking display panes can become Work Panes as well. Then we can really hum along.