Collapsing Outline levels in the Word 2013 object model
In my last blog post I described the new functionality in the Word 2013 UI for collapsing and expanding Headings and Outline levels. Today, I’ll cover the corresponding additions to the Word object model.
In the object model, this functionality is comprised in the following methods and properties:pan>
View.CollapseAllHeadings
,View.ExpandAllHeadings
: These two methods expand/collapse all headings in the document. They take no parameters and return no values.
Paragraph.CollapsedState
is a property that returnsTrue
if collapsed,False
if not. Setting the property totrue
/false
collapses/expands the paragraph. The property takes effect if the paragraph is formatted with an outline level, regardless whether it’s formatted with a heading style. If no outline level formatting has been applied nothing happens and no error is triggered.CollapsedState
is equivalent to the user clicking on the symbol next to the paragraph, as described in the blog post about the feature in the UI.Paragraph.CollapseByDefault
is also a property returning/acceptingtrue
/false
. It corresponds to the new checkbox „Collapse by default“ in the Paragraph dialog box.ParagraphFormat.CollapseHeadingsByDefault
is another new property. It is designed to work with theFind
object and enables code to find paragraphs that are formatted withParagraph.CollapseByDefault
(More below)Options.ExpandHeadingsOnOpen
is a property at the application level. It’s specific to the individual user and forces all documents to open with headings expanded. It is the equivalent to File/Options/Advanced/Show Document Content/Expand all headings.
Using Find
on the Selection
object with ParagraphFormat.CollapseHeadingsByDefault
as part of the search criteria will expand any collapsed headings if the search term is found in the selection. Using Find
on a Range object will not expand the heading.
In some cases it is advisable to expand all headings when automating Word as text in a collapsed range will not necessarily return the expected result. For example, if you search a term using Range.Find
then want to use Word’s Information
function to determine its vertical position on the page (wdVerticalPositionRelativeToPage
) the result will be the position of the outline level paragraph under which the Range is collapsed, not the found Range.
Sub UsingFindWithCollapsedHeadings() Dim rng As Word.Range Dim findText As String 'Uncomment the following line in order to get 'the expected result every time 'ActiveDocument.ActiveWindow.View.ExpandAllHeadings 'Assume the current selection is an outline level paragraph 'with the text below it collapsed. 'The collapsed text contains the search term. Debug.Print Selection.Information( _ wdVerticalPositionRelativeToPage) Set rng = ActiveDocument.Content findText = "comprised" rng.Find.Execute findText:=findText 'The result will be the same as for the first Debug.Print line Debug.Print rng.Information( _ wdVerticalPositionRelativeToPage) 'Now the heading will be expanded and the found text selected Selection.Find.Execute findText:=findText 'Correspondingly, the value now changes Debug.Print Selection.Information( _ wdVerticalPositionRelativeToPage) End Sub