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 returns True if collapsed, False if not. Setting the property to true/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/accepting true/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 the Find object and enables code to find paragraphs that are formatted with Paragraph.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

This entry was posted on September 6, 2012 at 19:17 and is filed under Word 2013, Word object model. Tagged: , , , . You can follow any responses to this entry through the RSS 2.0 feed. You can leave a response, or trackback from your own site.



Leave a Reply