Class OutlineOptions
Class OutlineOptions
Namespace: Aspose.Words.Saving
Assembly: Aspose.Words.dll (25.12.0)
Allows to specify outline options.
To learn more, visit the Save a Document documentation article.
public class OutlineOptionsInheritance
Inherited Members
object.GetType() , object.MemberwiseClone() , object.ToString() , object.Equals(object?) , object.Equals(object?, object?) , object.ReferenceEquals(object?, object?) , object.GetHashCode()
Examples
Shows to process bookmarks in headers/footers in a document that we are rendering to PDF.
Document doc = new Document(MyDir + "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.PageMode = PdfPageMode.UseOutlines;
// Set the "DefaultBookmarksOutlineLevel" property to "1" to display all
// bookmarks at the first level of the outline in the output PDF.
saveOptions.OutlineOptions.DefaultBookmarksOutlineLevel = 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.HeaderFooterBookmarksExportMode = headerFooterBookmarksExportMode;
doc.Save(ArtifactsDir + "PdfSaveOptions.HeaderFooterBookmarksExportMode.pdf", saveOptions);Constructors
OutlineOptions()
public OutlineOptions()Properties
BookmarksOutlineLevels
Allows to specify individual bookmarks outline level.
public BookmarksOutlineLevelCollection BookmarksOutlineLevels { get; }Property Value
BookmarksOutlineLevelCollection
Examples
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.OutlineOptions.BookmarksOutlineLevels;
outlineLevels.Add("Bookmark 1", 1);
outlineLevels.Add("Bookmark 2", 2);
outlineLevels.Add("Bookmark 3", 3);
Assert.That(outlineLevels.Count, Is.EqualTo(3));
Assert.That(outlineLevels.Contains("Bookmark 1"), Is.True);
Assert.That(outlineLevels[0], Is.EqualTo(1));
Assert.That(outlineLevels["Bookmark 2"], Is.EqualTo(2));
Assert.That(outlineLevels.IndexOfKey("Bookmark 3"), Is.EqualTo(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(ArtifactsDir + "BookmarksOutlineLevelCollection.BookmarkLevels.pdf", pdfSaveOptions);
// Emptying this collection will preserve the bookmarks and put them all on the same outline level.
outlineLevels.Clear();Remarks
If bookmark level is not specified in this collection then Aspose.Words.Saving.OutlineOptions.DefaultBookmarksOutlineLevel value is used.
CreateMissingOutlineLevels
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.
public bool CreateMissingOutlineLevels { get; set; }Property Value
Examples
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.ParagraphFormat.StyleIdentifier = StyleIdentifier.Heading1;
Assert.That(builder.ParagraphFormat.IsHeading, Is.True);
builder.Writeln("Heading 1");
builder.ParagraphFormat.StyleIdentifier = StyleIdentifier.Heading5;
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.OutlineOptions.HeadingsOutlineLevels = 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.OutlineOptions.CreateMissingOutlineLevels = createMissingOutlineLevels;
doc.Save(ArtifactsDir + "PdfSaveOptions.CreateMissingOutlineLevels.pdf", saveOptions);CreateOutlinesForHeadingsInTables
Specifies whether or not to create outlines for headings (paragraphs formatted with the Heading styles) inside tables.
public bool CreateOutlinesForHeadingsInTables { get; set; }Property Value
Examples
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.ParagraphFormat.StyleIdentifier = StyleIdentifier.Heading1;
builder.Write("Customers");
builder.EndRow();
builder.InsertCell();
builder.ParagraphFormat.StyleIdentifier = 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.OutlineOptions.HeadingsOutlineLevels = 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.OutlineOptions.CreateOutlinesForHeadingsInTables = createOutlinesForHeadingsInTables;
doc.Save(ArtifactsDir + "PdfSaveOptions.TableHeadingOutlines.pdf", pdfSaveOptions);Remarks
Default value is false.
DefaultBookmarksOutlineLevel
Specifies the default level in the document outline at which to display Word bookmarks.
public int DefaultBookmarksOutlineLevel { get; set; }Property Value
Examples
Shows to process bookmarks in headers/footers in a document that we are rendering to PDF.
Document doc = new Document(MyDir + "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.PageMode = PdfPageMode.UseOutlines;
// Set the "DefaultBookmarksOutlineLevel" property to "1" to display all
// bookmarks at the first level of the outline in the output PDF.
saveOptions.OutlineOptions.DefaultBookmarksOutlineLevel = 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.HeaderFooterBookmarksExportMode = headerFooterBookmarksExportMode;
doc.Save(ArtifactsDir + "PdfSaveOptions.HeaderFooterBookmarksExportMode.pdf", saveOptions);Remarks
Individual bookmarks level could be specified using Aspose.Words.Saving.OutlineOptions.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.
ExpandedOutlineLevels
Specifies how many levels in the document outline to show expanded when the file is viewed.
public int ExpandedOutlineLevels { get; set; }Property Value
Examples
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.ParagraphFormat.StyleIdentifier = StyleIdentifier.Heading1;
Assert.That(builder.ParagraphFormat.IsHeading, Is.True);
builder.Writeln("Heading 1");
builder.ParagraphFormat.StyleIdentifier = StyleIdentifier.Heading2;
builder.Writeln("Heading 1.1");
builder.Writeln("Heading 1.2");
builder.ParagraphFormat.StyleIdentifier = StyleIdentifier.Heading3;
builder.Writeln("Heading 1.2.1");
builder.Writeln("Heading 1.2.2");
builder.ParagraphFormat.StyleIdentifier = StyleIdentifier.Heading4;
builder.Writeln("Heading 1.2.2.1");
builder.Writeln("Heading 1.2.2.2");
builder.ParagraphFormat.StyleIdentifier = StyleIdentifier.Heading5;
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.OutlineOptions.HeadingsOutlineLevels = 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.OutlineOptions.ExpandedOutlineLevels = 2;
doc.Save(ArtifactsDir + "PdfSaveOptions.ExpandedOutlineLevels.pdf", options);Remarks
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.
HeadingsOutlineLevels
Specifies how many levels of headings (paragraphs formatted with the Heading styles) to include in the document outline.
public int HeadingsOutlineLevels { get; set; }Property Value
Examples
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.ParagraphFormat.StyleIdentifier = StyleIdentifier.Heading1;
Assert.That(builder.ParagraphFormat.IsHeading, Is.True);
builder.Writeln("Heading 1");
builder.ParagraphFormat.StyleIdentifier = StyleIdentifier.Heading2;
builder.Writeln("Heading 1.1");
builder.Writeln("Heading 1.2");
builder.ParagraphFormat.StyleIdentifier = StyleIdentifier.Heading3;
builder.Writeln("Heading 1.2.1");
builder.Writeln("Heading 1.2.2");
builder.ParagraphFormat.StyleIdentifier = StyleIdentifier.Heading4;
builder.Writeln("Heading 1.2.2.1");
builder.Writeln("Heading 1.2.2.2");
builder.ParagraphFormat.StyleIdentifier = StyleIdentifier.Heading5;
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.OutlineOptions.HeadingsOutlineLevels = 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.OutlineOptions.ExpandedOutlineLevels = 2;
doc.Save(ArtifactsDir + "PdfSaveOptions.ExpandedOutlineLevels.pdf", options);Remarks
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.
