Word’s Task Panes VBA Reference
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
The sound of a dialog not opening
God helps those who help themselves
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 https://wordmvp.com/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
https://wordmvp.com/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: To show / hide the help link:
To disable the feature
entirely for the GUI user, use
|
|
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 |
|
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.
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.