com.aspose.words

Class OutlineOptions

  • java.lang.Object
    • com.aspose.words.OutlineOptions
public class OutlineOptions 
extends java.lang.Object

Allows to specify outline options.

Example:

Shows to process bookmarks in headers/footers in a document that we are rendering to PDF.
Document doc = new Document(getMyDir() + "Bookmarks in headers and footers.docx");

// Create a "PdfSaveOptions" object that we can pass to the document's "Save" method
// to modify how that method converts the document to .PDF.
PdfSaveOptions saveOptions = new PdfSaveOptions();

// Set the "PageMode" property to "PdfPageMode.UseOutlines" to display the outline navigation pane in the output PDF.
saveOptions.setPageMode(PdfPageMode.USE_OUTLINES);

// Set the "DefaultBookmarksOutlineLevel" property to "1" to display all
// bookmarks at the first level of the outline in the output PDF.
saveOptions.getOutlineOptions().setDefaultBookmarksOutlineLevel(1);

// Set the "HeaderFooterBookmarksExportMode" property to "HeaderFooterBookmarksExportMode.None" to
// not export any bookmarks that are inside headers/footers.
// Set the "HeaderFooterBookmarksExportMode" property to "HeaderFooterBookmarksExportMode.First" to
// only export bookmarks in the first section's header/footers.
// Set the "HeaderFooterBookmarksExportMode" property to "HeaderFooterBookmarksExportMode.All" to
// export bookmarks that are in all headers/footers.
saveOptions.setHeaderFooterBookmarksExportMode(headerFooterBookmarksExportMode);

doc.save(getArtifactsDir() + "PdfSaveOptions.HeaderFooterBookmarksExportMode.pdf", saveOptions);

Constructor Summary
 
Property Getters/Setters Summary
BookmarksOutlineLevelCollectiongetBookmarksOutlineLevels()
Allows to specify individual bookmarks outline level.
booleangetCreateMissingOutlineLevels()
void
          

Gets or sets a value determining whether or not to create missing outline levels when the document is exported.

Default value for this property is false.

booleangetCreateOutlinesForHeadingsInTables()
void
           Specifies whether or not to create outlines for headings (paragraphs formatted with the Heading styles) inside tables.
intgetDefaultBookmarksOutlineLevel()
void
           Specifies the default level in the document outline at which to display Word bookmarks.
intgetExpandedOutlineLevels()
void
           Specifies how many levels in the document outline to show expanded when the file is viewed.
intgetHeadingsOutlineLevels()
void
           Specifies how many levels of headings (paragraphs formatted with the Heading styles) to include in the document outline.
 

    • Constructor Detail

      • OutlineOptions

        public OutlineOptions()
    • Property Getters/Setters Detail

      • getBookmarksOutlineLevels

        public BookmarksOutlineLevelCollection getBookmarksOutlineLevels()
        
        Allows to specify individual bookmarks outline level.

        If bookmark level is not specified in this collection then DefaultBookmarksOutlineLevel value is used.

        Example:

        Shows how to set outline levels for bookmarks.
        Document doc = new Document();
        DocumentBuilder builder = new DocumentBuilder(doc);
        
        // Insert a bookmark with another bookmark nested inside it.
        builder.startBookmark("Bookmark 1");
        builder.writeln("Text inside Bookmark 1.");
        
        builder.startBookmark("Bookmark 2");
        builder.writeln("Text inside Bookmark 1 and 2.");
        builder.endBookmark("Bookmark 2");
        
        builder.writeln("Text inside Bookmark 1.");
        builder.endBookmark("Bookmark 1");
        
        // Insert another bookmark.
        builder.startBookmark("Bookmark 3");
        builder.writeln("Text inside Bookmark 3.");
        builder.endBookmark("Bookmark 3");
        
        // When saving to .pdf, bookmarks can be accessed via a drop-down menu and used as anchors by most readers.
        // Bookmarks can also have numeric values for outline levels,
        // enabling lower level outline entries to hide higher-level child entries when collapsed in the reader.
        PdfSaveOptions pdfSaveOptions = new PdfSaveOptions();
        BookmarksOutlineLevelCollection outlineLevels = pdfSaveOptions.getOutlineOptions().getBookmarksOutlineLevels();
        
        outlineLevels.add("Bookmark 1", 1);
        outlineLevels.add("Bookmark 2", 2);
        outlineLevels.add("Bookmark 3", 3);
        
        Assert.assertEquals(outlineLevels.getCount(), 3);
        Assert.assertTrue(outlineLevels.contains("Bookmark 1"));
        Assert.assertEquals(outlineLevels.get(0), 1);
        Assert.assertEquals(outlineLevels.get("Bookmark 2"), 2);
        Assert.assertEquals(outlineLevels.indexOfKey("Bookmark 3"), 2);
        
        // We can remove two elements so that only the outline level designation for "Bookmark 1" is left.
        outlineLevels.removeAt(2);
        outlineLevels.remove("Bookmark 2");
        
        // There are nine outline levels. Their numbering will be optimized during the save operation.
        // In this case, levels "5" and "9" will become "2" and "3".
        outlineLevels.add("Bookmark 2", 5);
        outlineLevels.add("Bookmark 3", 9);
        
        doc.save(getArtifactsDir() + "BookmarksOutlineLevelCollection.BookmarkLevels.pdf", pdfSaveOptions);
        
        // Emptying this collection will preserve the bookmarks and put them all on the same outline level.
        outlineLevels.clear();
      • getCreateMissingOutlineLevels/setCreateMissingOutlineLevels

        public boolean getCreateMissingOutlineLevels() / public void setCreateMissingOutlineLevels(boolean value)
        

        Gets or sets a value determining whether or not to create missing outline levels when the document is exported.

        Default value for this property is false.

        Example:

        Shows how to work with outline levels that do not contain any corresponding headings when saving a PDF document.
        Document doc = new Document();
        DocumentBuilder builder = new DocumentBuilder(doc);
        
        // Insert headings that can serve as TOC entries of levels 1 and 5.
        builder.getParagraphFormat().setStyleIdentifier(StyleIdentifier.HEADING_1);
        
        Assert.assertTrue(builder.getParagraphFormat().isHeading());
        
        builder.writeln("Heading 1");
        
        builder.getParagraphFormat().setStyleIdentifier(StyleIdentifier.HEADING_5);
        
        builder.writeln("Heading 1.1.1.1.1");
        builder.writeln("Heading 1.1.1.1.2");
        
        // Create a "PdfSaveOptions" object that we can pass to the document's "Save" method
        // to modify how that method converts the document to .PDF.
        PdfSaveOptions saveOptions = new PdfSaveOptions();
        
        // The output PDF document will contain an outline, which is a table of contents that lists headings in the document body.
        // Clicking on an entry in this outline will take us to the location of its respective heading.
        // Set the "HeadingsOutlineLevels" property to "5" to include all headings of levels 5 and below in the outline.
        saveOptions.getOutlineOptions().setHeadingsOutlineLevels(5);
        
        // This document contains headings of levels 1 and 5, and no headings with levels of 2, 3, and 4. 
        // The output PDF document will treat outline levels 2, 3, and 4 as "missing".
        // Set the "CreateMissingOutlineLevels" property to "true" to include all missing levels in the outline,
        // leaving blank outline entries since there are no usable headings.
        // Set the "CreateMissingOutlineLevels" property to "false" to ignore missing outline levels,
        // and treat the outline level 5 headings as level 2.
        saveOptions.getOutlineOptions().setCreateMissingOutlineLevels(createMissingOutlineLevels);
        
        doc.save(getArtifactsDir() + "PdfSaveOptions.CreateMissingOutlineLevels.pdf", saveOptions);
      • getCreateOutlinesForHeadingsInTables/setCreateOutlinesForHeadingsInTables

        public boolean getCreateOutlinesForHeadingsInTables() / public void setCreateOutlinesForHeadingsInTables(boolean value)
        
        Specifies whether or not to create outlines for headings (paragraphs formatted with the Heading styles) inside tables.

        Default value is false.

        Example:

        Shows how to create PDF document outline entries for headings inside tables.
        Document doc = new Document();
        DocumentBuilder builder = new DocumentBuilder(doc);
        
        // Create a table with three rows. The first row,
        // whose text we will format in a heading-type style, will serve as the column header.
        builder.startTable();
        builder.insertCell();
        builder.getParagraphFormat().setStyleIdentifier(StyleIdentifier.HEADING_1);
        builder.write("Customers");
        builder.endRow();
        builder.insertCell();
        builder.getParagraphFormat().setStyleIdentifier(StyleIdentifier.NORMAL);
        builder.write("John Doe");
        builder.endRow();
        builder.insertCell();
        builder.write("Jane Doe");
        builder.endTable();
        
        // Create a "PdfSaveOptions" object that we can pass to the document's "Save" method
        // to modify how that method converts the document to .PDF.
        PdfSaveOptions pdfSaveOptions = new PdfSaveOptions();
        
        // The output PDF document will contain an outline, which is a table of contents that lists headings in the document body.
        // Clicking on an entry in this outline will take us to the location of its respective heading.
        // Set the "HeadingsOutlineLevels" property to "1" to get the outline
        // to only register headings with heading levels that are no larger than 1.
        pdfSaveOptions.getOutlineOptions().setHeadingsOutlineLevels(1);
        
        // Set the "CreateOutlinesForHeadingsInTables" property to "false" to exclude all headings within tables,
        // such as the one we have created above from the outline.
        // Set the "CreateOutlinesForHeadingsInTables" property to "true" to include all headings within tables
        // in the outline, provided that they have a heading level that is no larger than the value of the "HeadingsOutlineLevels" property.
        pdfSaveOptions.getOutlineOptions().setCreateOutlinesForHeadingsInTables(createOutlinesForHeadingsInTables);
        
        doc.save(getArtifactsDir() + "PdfSaveOptions.TableHeadingOutlines.pdf", pdfSaveOptions);
      • getDefaultBookmarksOutlineLevel/setDefaultBookmarksOutlineLevel

        public int getDefaultBookmarksOutlineLevel() / public void setDefaultBookmarksOutlineLevel(int value)
        
        Specifies the default level in the document outline at which to display Word bookmarks.

        Individual bookmarks level could be specified using BookmarksOutlineLevels property.

        Specify 0 and Word bookmarks will not be displayed in the document outline. Specify 1 and Word bookmarks will be displayed in the document outline at level 1; 2 for level 2 and so on.

        Default is 0. Valid range is 0 to 9.

        Example:

        Shows to process bookmarks in headers/footers in a document that we are rendering to PDF.
        Document doc = new Document(getMyDir() + "Bookmarks in headers and footers.docx");
        
        // Create a "PdfSaveOptions" object that we can pass to the document's "Save" method
        // to modify how that method converts the document to .PDF.
        PdfSaveOptions saveOptions = new PdfSaveOptions();
        
        // Set the "PageMode" property to "PdfPageMode.UseOutlines" to display the outline navigation pane in the output PDF.
        saveOptions.setPageMode(PdfPageMode.USE_OUTLINES);
        
        // Set the "DefaultBookmarksOutlineLevel" property to "1" to display all
        // bookmarks at the first level of the outline in the output PDF.
        saveOptions.getOutlineOptions().setDefaultBookmarksOutlineLevel(1);
        
        // Set the "HeaderFooterBookmarksExportMode" property to "HeaderFooterBookmarksExportMode.None" to
        // not export any bookmarks that are inside headers/footers.
        // Set the "HeaderFooterBookmarksExportMode" property to "HeaderFooterBookmarksExportMode.First" to
        // only export bookmarks in the first section's header/footers.
        // Set the "HeaderFooterBookmarksExportMode" property to "HeaderFooterBookmarksExportMode.All" to
        // export bookmarks that are in all headers/footers.
        saveOptions.setHeaderFooterBookmarksExportMode(headerFooterBookmarksExportMode);
        
        doc.save(getArtifactsDir() + "PdfSaveOptions.HeaderFooterBookmarksExportMode.pdf", saveOptions);
      • getExpandedOutlineLevels/setExpandedOutlineLevels

        public int getExpandedOutlineLevels() / public void setExpandedOutlineLevels(int value)
        
        Specifies how many levels in the document outline to show expanded when the file is viewed.

        Note that this options will not work when saving to XPS.

        Specify 0 and the document outline will be collapsed; specify 1 and the first level items in the outline will be expanded and so on.

        Default is 0. Valid range is 0 to 9.

        Example:

        Shows how to convert a whole document to PDF with three levels in the document outline.
        Document doc = new Document();
        DocumentBuilder builder = new DocumentBuilder(doc);
        
        // Insert headings of levels 1 to 5.
        builder.getParagraphFormat().setStyleIdentifier(StyleIdentifier.HEADING_1);
        
        Assert.assertTrue(builder.getParagraphFormat().isHeading());
        
        builder.writeln("Heading 1");
        
        builder.getParagraphFormat().setStyleIdentifier(StyleIdentifier.HEADING_2);
        
        builder.writeln("Heading 1.1");
        builder.writeln("Heading 1.2");
        
        builder.getParagraphFormat().setStyleIdentifier(StyleIdentifier.HEADING_3);
        
        builder.writeln("Heading 1.2.1");
        builder.writeln("Heading 1.2.2");
        
        builder.getParagraphFormat().setStyleIdentifier(StyleIdentifier.HEADING_4);
        
        builder.writeln("Heading 1.2.2.1");
        builder.writeln("Heading 1.2.2.2");
        
        builder.getParagraphFormat().setStyleIdentifier(StyleIdentifier.HEADING_5);
        
        builder.writeln("Heading 1.2.2.2.1");
        builder.writeln("Heading 1.2.2.2.2");
        
        // Create a "PdfSaveOptions" object that we can pass to the document's "Save" method
        // to modify how that method converts the document to .PDF.
        PdfSaveOptions options = new PdfSaveOptions();
        
        // The output PDF document will contain an outline, which is a table of contents that lists headings in the document body.
        // Clicking on an entry in this outline will take us to the location of its respective heading.
        // Set the "HeadingsOutlineLevels" property to "4" to exclude all headings whose levels are above 4 from the outline.
        options.getOutlineOptions().setHeadingsOutlineLevels(4);
        
        // If an outline entry has subsequent entries of a higher level inbetween itself and the next entry of the same or lower level,
        // an arrow will appear to the left of the entry. This entry is the "owner" of several such "sub-entries".
        // In our document, the outline entries from the 5th heading level are sub-entries of the second 4th level outline entry,
        // the 4th and 5th heading level entries are sub-entries of the second 3rd level entry, and so on. 
        // In the outline, we can click on the arrow of the "owner" entry to collapse/expand all its sub-entries.
        // Set the "ExpandedOutlineLevels" property to "2" to automatically expand all heading level 2 and lower outline entries
        // and collapse all level and 3 and higher entries when we open the document. 
        options.getOutlineOptions().setExpandedOutlineLevels(2);
        
        doc.save(getArtifactsDir() + "PdfSaveOptions.ExpandedOutlineLevels.pdf", options);
      • getHeadingsOutlineLevels/setHeadingsOutlineLevels

        public int getHeadingsOutlineLevels() / public void setHeadingsOutlineLevels(int value)
        
        Specifies how many levels of headings (paragraphs formatted with the Heading styles) to include in the document outline.

        Specify 0 for no headings in the outline; specify 1 for one level of headings in the outline and so on.

        Default is 0. Valid range is 0 to 9.

        Example:

        Shows how to convert a whole document to PDF with three levels in the document outline.
        Document doc = new Document();
        DocumentBuilder builder = new DocumentBuilder(doc);
        
        // Insert headings of levels 1 to 5.
        builder.getParagraphFormat().setStyleIdentifier(StyleIdentifier.HEADING_1);
        
        Assert.assertTrue(builder.getParagraphFormat().isHeading());
        
        builder.writeln("Heading 1");
        
        builder.getParagraphFormat().setStyleIdentifier(StyleIdentifier.HEADING_2);
        
        builder.writeln("Heading 1.1");
        builder.writeln("Heading 1.2");
        
        builder.getParagraphFormat().setStyleIdentifier(StyleIdentifier.HEADING_3);
        
        builder.writeln("Heading 1.2.1");
        builder.writeln("Heading 1.2.2");
        
        builder.getParagraphFormat().setStyleIdentifier(StyleIdentifier.HEADING_4);
        
        builder.writeln("Heading 1.2.2.1");
        builder.writeln("Heading 1.2.2.2");
        
        builder.getParagraphFormat().setStyleIdentifier(StyleIdentifier.HEADING_5);
        
        builder.writeln("Heading 1.2.2.2.1");
        builder.writeln("Heading 1.2.2.2.2");
        
        // Create a "PdfSaveOptions" object that we can pass to the document's "Save" method
        // to modify how that method converts the document to .PDF.
        PdfSaveOptions options = new PdfSaveOptions();
        
        // The output PDF document will contain an outline, which is a table of contents that lists headings in the document body.
        // Clicking on an entry in this outline will take us to the location of its respective heading.
        // Set the "HeadingsOutlineLevels" property to "4" to exclude all headings whose levels are above 4 from the outline.
        options.getOutlineOptions().setHeadingsOutlineLevels(4);
        
        // If an outline entry has subsequent entries of a higher level inbetween itself and the next entry of the same or lower level,
        // an arrow will appear to the left of the entry. This entry is the "owner" of several such "sub-entries".
        // In our document, the outline entries from the 5th heading level are sub-entries of the second 4th level outline entry,
        // the 4th and 5th heading level entries are sub-entries of the second 3rd level entry, and so on. 
        // In the outline, we can click on the arrow of the "owner" entry to collapse/expand all its sub-entries.
        // Set the "ExpandedOutlineLevels" property to "2" to automatically expand all heading level 2 and lower outline entries
        // and collapse all level and 3 and higher entries when we open the document. 
        options.getOutlineOptions().setExpandedOutlineLevels(2);
        
        doc.save(getArtifactsDir() + "PdfSaveOptions.ExpandedOutlineLevels.pdf", options);