Aspose::Words::Layout Namespace Reference

Detailed Description

The Aspose.Words.Layout namespace provides classes that allow to access information such as on what page and where on a page particular document elements are positioned, when the document is formatted into pages.

Classes
interface	IPageLayoutCallback
	Implement this interface if you want to have your own custom method called during build and rendering of page layout model. More...
class	LayoutCollector
	This class allows to compute page numbers of document nodes. To learn more, visit the Converting to Fixed-page Format documentation article. More...
class	LayoutEnumerator
	Enumerates page layout entities of a document. You can use this class to walk over the page layout model. Available properties are type, geometry, text and page index where entity is rendered, as well as overall structure and relationships. Use combination of GetEntity() and Current move to the entity which corresponds to a document node. To learn more, visit the Converting to Fixed-page Format documentation article. More...
class	LayoutOptions
	Holds the options that allow controlling the document layout process. To learn more, visit the Converting to Fixed-page Format documentation article. More...
class	PageLayoutCallbackArgs
	An argument passed into Notify()To learn more, visit the Converting to Fixed-page Format documentation article. More...
class	RevisionOptions
	Allows to control how document revisions are handled during layout process. To learn more, visit the Converting to Fixed-page Format documentation article. More...

Enumerations
enum class	CommentDisplayMode
	Specifies the rendering mode for document comments. More...
enum class	ContinuousSectionRestart
	Represents different behaviors when computing page numbers in a continuous section that restarts page numbering. More...
enum class	LayoutEntityType
	Types of the layout entities. More...
enum class	PageLayoutEvent
	A code of event raised during page layout model build and rendering. Page layout model is built in two steps. First, "conversion step", this is when page layout pulls document content and creates object graph. Second, "reflow step", this is when structures are split, merged and arranged into pages. Depending of the operation which triggered build, page layout model may or may not be further rendered into fixed page format. For example, computing number of pages in the document or updating fields does not require rendering, whereas export to Pdf does. More...
enum class	RevisionColor
	Allows to specify color of document revisions. More...
enum class	RevisionTextEffect
	Allows to specify decoration effect for revisions of document text. More...
enum class	ShowInBalloons
	Specifies which revisions are rendered in balloons. More...

Enumeration Type Documentation

CommentDisplayMode

enum class Aspose::Words::Layout::CommentDisplayMode

strong

Specifies the rendering mode for document comments.

Examples

Shows how to show comments when saving a document to a rendered format.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
 
builder->Write(u"Hello world!");
 
auto comment = MakeObject<Comment>(doc, u"John Doe", u"J.D.", System::DateTime::get_Now());
comment->SetText(u"My comment.");
builder->get_CurrentParagraph()->AppendChild(comment);
 
// ShowInAnnotations is only available in Pdf1.7 and Pdf1.5 formats.
// In other formats, it will work similarly to Hide.
doc->get_LayoutOptions()->set_CommentDisplayMode(CommentDisplayMode::ShowInAnnotations);
 
doc->Save(ArtifactsDir + u"Document.ShowCommentsInAnnotations.pdf");
 
// Note that it's required to rebuild the document page layout (via Document.UpdatePageLayout() method)
// after changing the Document.LayoutOptions values.
doc->get_LayoutOptions()->set_CommentDisplayMode(CommentDisplayMode::ShowInBalloons);
doc->UpdatePageLayout();
 
doc->Save(ArtifactsDir + u"Document.ShowCommentsInBalloons.pdf");

Enumerator
Hide	No document comments are rendered.
ShowInBalloons	Renders document comments in balloons in the margin. This is the default value.
ShowInAnnotations	Renders document comments in annotations. This is only available for Pdf format.

ContinuousSectionRestart

enum class Aspose::Words::Layout::ContinuousSectionRestart

strong

Represents different behaviors when computing page numbers in a continuous section that restarts page numbering.

Examples

Shows how to control page numbering in a continuous section.

auto doc = MakeObject<Document>(MyDir + u"Continuous section page numbering.docx");
 
// By default Aspose.Words behavior matches the Microsoft Word 2019.
// If you need old Aspose.Words behavior, repetitive Microsoft Word 2016, use 'ContinuousSectionRestart.FromNewPageOnly'.
// Page numbering restarts only if there is no other content before the section on the page where the section starts,
// because of that the numbering will reset to 2 from the second page.
doc->get_LayoutOptions()->set_ContinuousSectionPageNumberingRestart(ContinuousSectionRestart::FromNewPageOnly);
doc->UpdatePageLayout();
 
doc->Save(ArtifactsDir + u"Layout.RestartPageNumberingInContinuousSection.pdf");

Enumerator
Always	Page numbering always restarts regardless of content flow.
FromNewPageOnly	Page numbering restarts only if there is no other content before the section on the page where the section starts.

LayoutEntityType

enum class Aspose::Words::Layout::LayoutEntityType

strong

Types of the layout entities.

Examples

Shows ways of traversing a document's layout entities.

void LayoutEnumerator_()
{
    // Open a document that contains a variety of layout entities.
    // Layout entities are pages, cells, rows, lines, and other objects included in the LayoutEntityType enum.
    // Each layout entity has a rectangular space that it occupies in the document body.
    auto doc = MakeObject<Document>(MyDir + u"Layout entities.docx");
 
    // Create an enumerator that can traverse these entities like a tree.
    auto layoutEnumerator = MakeObject<LayoutEnumerator>(doc);
 
    ASPOSE_ASSERT_EQ(doc, layoutEnumerator->get_Document());
 
    layoutEnumerator->MoveParent(LayoutEntityType::Page);
 
    ASSERT_EQ(LayoutEntityType::Page, layoutEnumerator->get_Type());
    ASSERT_THROW(layoutEnumerator->get_Text(), System::InvalidOperationException);
 
    // We can call this method to make sure that the enumerator will be at the first layout entity.
    layoutEnumerator->Reset();
 
    // There are two orders that determine how the layout enumerator continues traversing layout entities
    // when it encounters entities that span across multiple pages.
    // 1 -  In visual order:
    // When moving through an entity's children that span multiple pages,
    // page layout takes precedence, and we move to other child elements on this page and avoid the ones on the next.
    std::cout << "Traversing from first to last, elements between pages separated:" << std::endl;
    TraverseLayoutForward(layoutEnumerator, 1);
 
    // Our enumerator is now at the end of the collection. We can traverse the layout entities backwards to go back to the beginning.
    std::cout << "Traversing from last to first, elements between pages separated:" << std::endl;
    TraverseLayoutBackward(layoutEnumerator, 1);
 
    // 2 -  In logical order:
    // When moving through an entity's children that span multiple pages,
    // the enumerator will move between pages to traverse all the child entities.
    std::cout << "Traversing from first to last, elements between pages mixed:" << std::endl;
    TraverseLayoutForwardLogical(layoutEnumerator, 1);
 
    std::cout << "Traversing from last to first, elements between pages mixed:" << std::endl;
    TraverseLayoutBackwardLogical(layoutEnumerator, 1);
}
 
static void TraverseLayoutForward(SharedPtr<LayoutEnumerator> layoutEnumerator, int depth)
{
    do
    {
        PrintCurrentEntity(layoutEnumerator, depth);
 
        if (layoutEnumerator->MoveFirstChild())
        {
            TraverseLayoutForward(layoutEnumerator, depth + 1);
            layoutEnumerator->MoveParent();
        }
    } while (layoutEnumerator->MoveNext());
}
 
static void TraverseLayoutBackward(SharedPtr<LayoutEnumerator> layoutEnumerator, int depth)
{
    do
    {
        PrintCurrentEntity(layoutEnumerator, depth);
 
        if (layoutEnumerator->MoveLastChild())
        {
            TraverseLayoutBackward(layoutEnumerator, depth + 1);
            layoutEnumerator->MoveParent();
        }
    } while (layoutEnumerator->MovePrevious());
}
 
static void TraverseLayoutForwardLogical(SharedPtr<LayoutEnumerator> layoutEnumerator, int depth)
{
    do
    {
        PrintCurrentEntity(layoutEnumerator, depth);
 
        if (layoutEnumerator->MoveFirstChild())
        {
            TraverseLayoutForwardLogical(layoutEnumerator, depth + 1);
            layoutEnumerator->MoveParent();
        }
    } while (layoutEnumerator->MoveNextLogical());
}
 
static void TraverseLayoutBackwardLogical(SharedPtr<LayoutEnumerator> layoutEnumerator, int depth)
{
    do
    {
        PrintCurrentEntity(layoutEnumerator, depth);
 
        if (layoutEnumerator->MoveLastChild())
        {
            TraverseLayoutBackwardLogical(layoutEnumerator, depth + 1);
            layoutEnumerator->MoveParent();
        }
    } while (layoutEnumerator->MovePreviousLogical());
}
 
static void PrintCurrentEntity(SharedPtr<LayoutEnumerator> layoutEnumerator, int indent)
{
    String tabs(u'\t', indent);
 
    std::cout << (layoutEnumerator->get_Kind() == String::Empty
                      ? String::Format(u"{0}-> Entity type: {1}", tabs, layoutEnumerator->get_Type())
                      : String::Format(u"{0}-> Entity type & kind: {1}, {2}", tabs, layoutEnumerator->get_Type(), layoutEnumerator->get_Kind()))
              << std::endl;
 
    // Only spans can contain text.
    if (layoutEnumerator->get_Type() == LayoutEntityType::Span)
    {
        std::cout << tabs << "   Span contents: \"" << layoutEnumerator->get_Text() << "\"" << std::endl;
    }
 
    System::Drawing::RectangleF leRect = layoutEnumerator->get_Rectangle();
    std::cout << tabs << "   Rectangle dimensions " << leRect.get_Width() << "x" << leRect.get_Height() << ", X=" << leRect.get_X()
              << " Y=" << leRect.get_Y() << std::endl;
    std::cout << tabs << "   Page " << layoutEnumerator->get_PageIndex() << std::endl;
}

Enumerator
None	Default value.
Page	Represents page of a document. Page may have Column, HeaderFooter and Comment child entities.
Column	Represents a column of text on a page. Column may have the same child entities as Cell, plus Footnote, Endnote and NoteSeparator entities.
Row	Represents a table row. Row may have Cell as child entities.
Cell	Represents a table cell. Cell may have Line and Row child entities.
Line	Represents line of characters of text and inline objects. Line may have Span child entities.
Span	Represents one or more characters in a line. This include special characters like field start/end markers, bookmarks and comments. Span may not have child entities.
Footnote	Represents placeholder for footnote content. Footnote may have Note child entities.
Endnote	Represents placeholder for endnote content. Endnote may have Note child entities.
Note	Represents placeholder for note content. Note may have Line and Row child entities.
HeaderFooter	Represents placeholder for header/footer content on a page. HeaderFooter may have Line and Row child entities.
TextBox	Represents text area inside of a shape. Textbox may have Line and Row child entities.
Comment	Represents placeholder for comment content. Comment may have Line and Row child entities.
NoteSeparator	Represents footnote/endnote separator. NoteSeparator may have Line and Row child entities.

PageLayoutEvent

enum class Aspose::Words::Layout::PageLayoutEvent

strong

A code of event raised during page layout model build and rendering. Page layout model is built in two steps. First, "conversion step", this is when page layout pulls document content and creates object graph. Second, "reflow step", this is when structures are split, merged and arranged into pages. Depending of the operation which triggered build, page layout model may or may not be further rendered into fixed page format. For example, computing number of pages in the document or updating fields does not require rendering, whereas export to Pdf does.

Examples

Shows how to track layout changes with a layout callback.

void PageLayoutCallback()
{
    auto doc = MakeObject<Document>();
    doc->get_BuiltInDocumentProperties()->set_Title(u"My Document");
 
    auto builder = MakeObject<DocumentBuilder>(doc);
    builder->Writeln(u"Hello world!");
 
    doc->get_LayoutOptions()->set_Callback(MakeObject<ExLayout::RenderPageLayoutCallback>());
    doc->UpdatePageLayout();
 
    doc->Save(ArtifactsDir + u"Layout.PageLayoutCallback.pdf");
}
 
class RenderPageLayoutCallback : public IPageLayoutCallback
{
public:
    void Notify(SharedPtr<PageLayoutCallbackArgs> a) override
    {
        switch (a->get_Event())
        {
        case PageLayoutEvent::PartReflowFinished:
            NotifyPartFinished(a);
            break;
 
        case PageLayoutEvent::ConversionFinished:
            NotifyConversionFinished(a);
            break;
 
        default:
            break;
        }
    }
 
    RenderPageLayoutCallback() : mNum(0)
    {
    }
 
private:
    int mNum;
 
    void NotifyPartFinished(SharedPtr<PageLayoutCallbackArgs> a)
    {
        std::cout << "Part at page " << (a->get_PageIndex() + 1) << " reflow." << std::endl;
        RenderPage(a, a->get_PageIndex());
    }
 
    void NotifyConversionFinished(SharedPtr<PageLayoutCallbackArgs> a)
    {
        std::cout << "Document \"" << a->get_Document()->get_BuiltInDocumentProperties()->get_Title() << "\" converted to page format." << std::endl;
    }
 
    void RenderPage(SharedPtr<PageLayoutCallbackArgs> a, int pageIndex)
    {
        auto saveOptions = MakeObject<ImageSaveOptions>(SaveFormat::Png);
        saveOptions->set_PageSet(MakeObject<PageSet>(pageIndex));
 
        {
            auto stream = MakeObject<System::IO::FileStream>(ArtifactsDir + String::Format(u"PageLayoutCallback.page-{0} {1}.png", pageIndex + 1, ++mNum),
                                                             System::IO::FileMode::Create);
            a->get_Document()->Save(stream, saveOptions);
        }
    }
};

Enumerator
None	Default value.
WatchDog	Corresponds to a checkpoint in code which is often visited and which is suitable to abort process. While inside Notify() throw custom exception to abort process. You can throw when handling any callback event to abort process. Note that if process is aborted the page layout model remains in undefined state. If process is aborted upon reflow of a complete page, however, it should be possible to use layout model up to the end of that page.
BuildStarted	Build of the page layout has started. Fired once. This is the first event which occurs when UpdatePageLayout is called.
BuildFinished	Build of the page layout has finished. Fired once. This is the last event which occurs when UpdatePageLayout is called.
ConversionStarted	Conversion of document model to page layout has started. Fired once. This occurs when layout model starts pulling document content.
ConversionFinished	Conversion of document model to page layout has finished. Fired once. This occurs when layout model stops pulling document content.
ReflowStarted	Reflow of the page layout has started. Fired once. This occurs when layout model starts reflowing document content.
ReflowFinished	Reflow of the page layout has finished. Fired once. This occurs when layout model stops reflowing document content.
PartReflowStarted	Reflow of the page has started. Note that page may reflow multiple times and that reflow may restart before it is finished. See also Aspose::Words::Layout::PageLayoutCallbackArgs::get_PageIndex
PartReflowFinished	Reflow of the page has finished. Note that page may reflow multiple times and that reflow may restart before it is finished. See also Aspose::Words::Layout::PageLayoutCallbackArgs::get_PageIndex
PartRenderingStarted	Rendering of page has started. This is fired once per page.
PartRenderingFinished	Rendering of page has finished. This is fired once per page.

RevisionColor

enum class Aspose::Words::Layout::RevisionColor

strong

Allows to specify color of document revisions.

Examples

Shows how to alter the appearance of revisions in a rendered output document.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
 
// Insert a revision, then change the color of all revisions to green.
builder->Writeln(u"This is not a revision.");
doc->StartTrackRevisions(u"John Doe", System::DateTime::get_Now());
builder->Writeln(u"This is a revision.");
doc->StopTrackRevisions();
builder->Writeln(u"This is not a revision.");
 
// Remove the bar that appears to the left of every revised line.
doc->get_LayoutOptions()->get_RevisionOptions()->set_InsertedTextColor(RevisionColor::BrightGreen);
doc->get_LayoutOptions()->get_RevisionOptions()->set_ShowRevisionBars(false);
 
doc->Save(ArtifactsDir + u"Document.LayoutOptionsRevisions.pdf");

Enumerator
Auto	Default.
Black	Represents 000000 color.
Blue	Represents 2e97d3 color.
BrightGreen	Represents 84a35b color.
ClassicBlue	Represents 0000ff color.
ClassicRed	Represents ff0000 color.
DarkBlue	Represents 376e96 color.
DarkRed	Represents 881824 color.
DarkYellow	Represents e09a2b color.
Gray25	Represents a0a3a9 color.
Gray50	Represents 50565e color.
Green	Represents 2c6234 color.
Pink	Represents ce338f color.
Red	Represents b5082e color.
Teal	Represents 1b9cab color.
Turquoise	Represents 3eafc2 color.
Violet	Represents 633277 color.
White	Represents ffffff color.
Yellow	Represents fad272 color.
NoHighlight	No color is used to highlight revision changes.
ByAuthor	Revisions of each author receive their own color for highlighting from a predfined set of hi-contrast colors.

RevisionTextEffect

enum class Aspose::Words::Layout::RevisionTextEffect

strong

Allows to specify decoration effect for revisions of document text.

Examples

Shows how to modify the appearance of revisions.

auto doc = MakeObject<Document>(MyDir + u"Revisions.docx");
 
// Get the RevisionOptions object that controls the appearance of revisions.
SharedPtr<RevisionOptions> revisionOptions = doc->get_LayoutOptions()->get_RevisionOptions();
 
// Render insertion revisions in green and italic.
revisionOptions->set_InsertedTextColor(RevisionColor::Green);
revisionOptions->set_InsertedTextEffect(RevisionTextEffect::Italic);
 
// Render deletion revisions in red and bold.
revisionOptions->set_DeletedTextColor(RevisionColor::Red);
revisionOptions->set_DeletedTextEffect(RevisionTextEffect::Bold);
 
// The same text will appear twice in a movement revision:
// once at the departure point and once at the arrival destination.
// Render the text at the moved-from revision yellow with a double strike through
// and double-underlined blue at the moved-to revision.
revisionOptions->set_MovedFromTextColor(RevisionColor::Yellow);
revisionOptions->set_MovedFromTextEffect(RevisionTextEffect::DoubleStrikeThrough);
revisionOptions->set_MovedToTextColor(RevisionColor::Blue);
revisionOptions->set_MovedFromTextEffect(RevisionTextEffect::DoubleUnderline);
 
// Render format revisions in dark red and bold.
revisionOptions->set_RevisedPropertiesColor(RevisionColor::DarkRed);
revisionOptions->set_RevisedPropertiesEffect(RevisionTextEffect::Bold);
 
// Place a thick dark blue bar on the left side of the page next to lines affected by revisions.
revisionOptions->set_RevisionBarsColor(RevisionColor::DarkBlue);
revisionOptions->set_RevisionBarsWidth(15.0f);
 
// Show revision marks and original text.
revisionOptions->set_ShowOriginalRevision(true);
revisionOptions->set_ShowRevisionMarks(true);
 
// Get movement, deletion, formatting revisions, and comments to show up in green balloons
// on the right side of the page.
revisionOptions->set_ShowInBalloons(ShowInBalloons::Format);
revisionOptions->set_CommentColor(RevisionColor::BrightGreen);
 
// These features are only applicable to formats such as .pdf or .jpg.
doc->Save(ArtifactsDir + u"Revision.RevisionOptions.pdf");

Enumerator
None	Revised content has no special effects applied. This corresponds to NoHighlight.
Color	Revised content is highlighted with color only.
Bold	Revised content is made bold and colored.
Italic	Revised content is made italic and colored.
Underline	Revised content is underlined and colored.
DoubleUnderline	Revised content is double underlined and colored.
StrikeThrough	Revised content is stroked through and colored.
DoubleStrikeThrough	Revised content is double stroked through and colored.
Hidden	Revised content is hidden.

ShowInBalloons

enum class Aspose::Words::Layout::ShowInBalloons

strong

Specifies which revisions are rendered in balloons.

Examples

Shows how to modify the appearance of revisions.

auto doc = MakeObject<Document>(MyDir + u"Revisions.docx");
 
// Get the RevisionOptions object that controls the appearance of revisions.
SharedPtr<RevisionOptions> revisionOptions = doc->get_LayoutOptions()->get_RevisionOptions();
 
// Render insertion revisions in green and italic.
revisionOptions->set_InsertedTextColor(RevisionColor::Green);
revisionOptions->set_InsertedTextEffect(RevisionTextEffect::Italic);
 
// Render deletion revisions in red and bold.
revisionOptions->set_DeletedTextColor(RevisionColor::Red);
revisionOptions->set_DeletedTextEffect(RevisionTextEffect::Bold);
 
// The same text will appear twice in a movement revision:
// once at the departure point and once at the arrival destination.
// Render the text at the moved-from revision yellow with a double strike through
// and double-underlined blue at the moved-to revision.
revisionOptions->set_MovedFromTextColor(RevisionColor::Yellow);
revisionOptions->set_MovedFromTextEffect(RevisionTextEffect::DoubleStrikeThrough);
revisionOptions->set_MovedToTextColor(RevisionColor::Blue);
revisionOptions->set_MovedFromTextEffect(RevisionTextEffect::DoubleUnderline);
 
// Render format revisions in dark red and bold.
revisionOptions->set_RevisedPropertiesColor(RevisionColor::DarkRed);
revisionOptions->set_RevisedPropertiesEffect(RevisionTextEffect::Bold);
 
// Place a thick dark blue bar on the left side of the page next to lines affected by revisions.
revisionOptions->set_RevisionBarsColor(RevisionColor::DarkBlue);
revisionOptions->set_RevisionBarsWidth(15.0f);
 
// Show revision marks and original text.
revisionOptions->set_ShowOriginalRevision(true);
revisionOptions->set_ShowRevisionMarks(true);
 
// Get movement, deletion, formatting revisions, and comments to show up in green balloons
// on the right side of the page.
revisionOptions->set_ShowInBalloons(ShowInBalloons::Format);
revisionOptions->set_CommentColor(RevisionColor::BrightGreen);
 
// These features are only applicable to formats such as .pdf or .jpg.
doc->Save(ArtifactsDir + u"Revision.RevisionOptions.pdf");

Enumerator
None	Renders insert, delete and format revisions inline.
Format	Renders insert and delete revisions inline, format revisions in balloons.
FormatAndDelete	Renders insert revisions inline, delete and format revisions in balloons.