Aspose::Words::Tables Namespace Reference

Detailed Description

The Aspose.Words.Tables namespace contains classes that represent tables, rows, cells and their formatting.

Classes
class	Cell
	Represents a table cell. To learn more, visit the Working with Tables documentation article. More...
class	CellCollection
	Provides typed access to a collection of Cell nodes. To learn more, visit the Working with Tables documentation article. More...
class	CellFormat
	Represents all formatting for a table cell. To learn more, visit the Working with Tables documentation article. More...
class	PreferredWidth
	Represents a value and its unit of measure that is used to specify the preferred width of a table or a cell. To learn more, visit the Working with Tables documentation article. More...
class	Row
	Represents a table row. To learn more, visit the Working with Tables documentation article. More...
class	RowCollection
	Provides typed access to a collection of Row nodes. To learn more, visit the Working with Tables documentation article. More...
class	RowFormat
	Represents all formatting for a table row. To learn more, visit the Working with Tables documentation article. More...
class	Table
	Represents a table in a Word document. To learn more, visit the Working with Tables documentation article. More...
class	TableCollection
	Provides typed access to a collection of Table nodes. To learn more, visit the Working with Tables documentation article. More...

Enumerations
enum class	AutoFitBehavior
	Determines how Aspose.Words resizes the table when you invoke the AutoFit() method. More...
enum class	CellMerge
	Specifies how a cell in a table is merged with other cells. More...
enum class	CellVerticalAlignment
	Specifies vertical justification of text inside a table cell. More...
enum class	PreferredWidthType
	Specifies the unit of measurement for the preferred width of a table or cell. More...
enum class	TableAlignment
	Specifies alignment for an inline table. More...
enum class	TableStyleOptions
	Specifies how table style is applied to a table. More...
enum class	TextWrapping
	Specifies how text is wrapped around the table. More...

Enumeration Type Documentation

AutoFitBehavior

enum class Aspose::Words::Tables::AutoFitBehavior

strong

Determines how Aspose.Words resizes the table when you invoke the AutoFit() method.

Examples

Shows how to build a new table while applying a style.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
SharedPtr<Table> table = builder->StartTable();
 
// We must insert at least one row before setting any table formatting.
builder->InsertCell();
 
// Set the table style used based on the style identifier.
// Note that not all table styles are available when saving to .doc format.
table->set_StyleIdentifier(StyleIdentifier::MediumShading1Accent1);
 
// Partially apply the style to features of the table based on predicates, then build the table.
table->set_StyleOptions(TableStyleOptions::FirstColumn | TableStyleOptions::RowBands | TableStyleOptions::FirstRow);
table->AutoFit(AutoFitBehavior::AutoFitToContents);
 
builder->Writeln(u"Item");
builder->get_CellFormat()->set_RightPadding(40);
builder->InsertCell();
builder->Writeln(u"Quantity (kg)");
builder->EndRow();
 
builder->InsertCell();
builder->Writeln(u"Apples");
builder->InsertCell();
builder->Writeln(u"20");
builder->EndRow();
 
builder->InsertCell();
builder->Writeln(u"Bananas");
builder->InsertCell();
builder->Writeln(u"40");
builder->EndRow();
 
builder->InsertCell();
builder->Writeln(u"Carrots");
builder->InsertCell();
builder->Writeln(u"50");
builder->EndRow();
 
doc->Save(ArtifactsDir + u"DocumentBuilder.InsertTableWithStyle.docx");

Shows how to build a formatted 2x2 table.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
 
SharedPtr<Table> table = builder->StartTable();
builder->InsertCell();
builder->get_CellFormat()->set_VerticalAlignment(CellVerticalAlignment::Center);
builder->Write(u"Row 1, cell 1.");
builder->InsertCell();
builder->Write(u"Row 1, cell 2.");
builder->EndRow();
 
// While building the table, the document builder will apply its current RowFormat/CellFormat property values
// to the current row/cell that its cursor is in and any new rows/cells as it creates them.
ASSERT_EQ(CellVerticalAlignment::Center, table->get_Rows()->idx_get(0)->get_Cells()->idx_get(0)->get_CellFormat()->get_VerticalAlignment());
ASSERT_EQ(CellVerticalAlignment::Center, table->get_Rows()->idx_get(0)->get_Cells()->idx_get(1)->get_CellFormat()->get_VerticalAlignment());
 
builder->InsertCell();
builder->get_RowFormat()->set_Height(100);
builder->get_RowFormat()->set_HeightRule(HeightRule::Exactly);
builder->get_CellFormat()->set_Orientation(TextOrientation::Upward);
builder->Write(u"Row 2, cell 1.");
builder->InsertCell();
builder->get_CellFormat()->set_Orientation(TextOrientation::Downward);
builder->Write(u"Row 2, cell 2.");
builder->EndRow();
builder->EndTable();
 
// Previously added rows and cells are not retroactively affected by changes to the builder's formatting.
ASPOSE_ASSERT_EQ(0, table->get_Rows()->idx_get(0)->get_RowFormat()->get_Height());
ASSERT_EQ(HeightRule::Auto, table->get_Rows()->idx_get(0)->get_RowFormat()->get_HeightRule());
ASPOSE_ASSERT_EQ(100, table->get_Rows()->idx_get(1)->get_RowFormat()->get_Height());
ASSERT_EQ(HeightRule::Exactly, table->get_Rows()->idx_get(1)->get_RowFormat()->get_HeightRule());
ASSERT_EQ(TextOrientation::Upward, table->get_Rows()->idx_get(1)->get_Cells()->idx_get(0)->get_CellFormat()->get_Orientation());
ASSERT_EQ(TextOrientation::Downward, table->get_Rows()->idx_get(1)->get_Cells()->idx_get(1)->get_CellFormat()->get_Orientation());
 
doc->Save(ArtifactsDir + u"DocumentBuilder.BuildTable.docx");

Enumerator
AutoFitToContents	Aspose.Words enables the AutoFit option, removes the preferred width from the table and all cells and then updates the table layout. In the resulting table, cell widths are updated to fit the table contents. Most likely, the table will shrink.
AutoFitToWindow	When you use this value, Aspose.Words enables the AutoFit option, sets the preferred width for the table to 100%, removes preferred widths from all cells and then updates the table layout. As a result, the table occupies all available width and the cell widths are updated to fit table contents.
FixedColumnWidths	Aspose.Words disables the AutoFit option and removes the preferred with from the table. The widths of the cells remain as they are specified by their Width properties.

CellMerge

enum class Aspose::Words::Tables::CellMerge

strong

Specifies how a cell in a table is merged with other cells.

Examples

Shows how to merge table cells vertically.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
 
// Insert a cell into the first column of the first row.
// This cell will be the first in a range of vertically merged cells.
builder->InsertCell();
builder->get_CellFormat()->set_VerticalMerge(CellMerge::First);
builder->Write(u"Text in merged cells.");
 
// Insert a cell into the second column of the first row, then end the row.
// Also, configure the builder to disable vertical merging in created cells.
builder->InsertCell();
builder->get_CellFormat()->set_VerticalMerge(CellMerge::None);
builder->Write(u"Text in unmerged cell.");
builder->EndRow();
 
// Insert a cell into the first column of the second row.
// Instead of adding text contents, we will merge this cell with the first cell that we added directly above.
builder->InsertCell();
builder->get_CellFormat()->set_VerticalMerge(CellMerge::Previous);
 
// Insert another independent cell in the second column of the second row.
builder->InsertCell();
builder->get_CellFormat()->set_VerticalMerge(CellMerge::None);
builder->Write(u"Text in unmerged cell.");
builder->EndRow();
builder->EndTable();
 
doc->Save(ArtifactsDir + u"CellFormat.VerticalMerge.docx");

Shows how to merge table cells horizontally.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
 
// Insert a cell into the first column of the first row.
// This cell will be the first in a range of horizontally merged cells.
builder->InsertCell();
builder->get_CellFormat()->set_HorizontalMerge(CellMerge::First);
builder->Write(u"Text in merged cells.");
 
// Insert a cell into the second column of the first row. Instead of adding text contents,
// we will merge this cell with the first cell that we added directly to the left.
builder->InsertCell();
builder->get_CellFormat()->set_HorizontalMerge(CellMerge::Previous);
builder->EndRow();
 
// Insert two more unmerged cells to the second row.
builder->get_CellFormat()->set_HorizontalMerge(CellMerge::None);
builder->InsertCell();
builder->Write(u"Text in unmerged cell.");
builder->InsertCell();
builder->Write(u"Text in unmerged cell.");
builder->EndRow();
builder->EndTable();
 
doc->Save(ArtifactsDir + u"CellFormat.HorizontalMerge.docx");

Prints the horizontal and vertical merge type of a cell.

void CheckCellsMerged()
{
    auto doc = MakeObject<Document>(MyDir + u"Table with merged cells.docx");
    SharedPtr<Table> table = doc->get_FirstSection()->get_Body()->get_Tables()->idx_get(0);
 
    for (const auto& row : System::IterateOver(table->get_Rows()->LINQ_OfType<SharedPtr<Row>>()))
    {
        for (const auto& cell : System::IterateOver(row->get_Cells()->LINQ_OfType<SharedPtr<Cell>>()))
        {
            std::cout << PrintCellMergeType(cell) << std::endl;
        }
    }
}
 
String PrintCellMergeType(SharedPtr<Cell> cell)
{
    bool isHorizontallyMerged = cell->get_CellFormat()->get_HorizontalMerge() != CellMerge::None;
    bool isVerticallyMerged = cell->get_CellFormat()->get_VerticalMerge() != CellMerge::None;
    String cellLocation = String::Format(u"R{0}, C{1}", cell->get_ParentRow()->get_ParentTable()->IndexOf(cell->get_ParentRow()) + 1,
                                         cell->get_ParentRow()->IndexOf(cell) + 1);
 
    if (isHorizontallyMerged && isVerticallyMerged)
    {
        return String::Format(u"The cell at {0} is both horizontally and vertically merged", cellLocation);
    }
    if (isHorizontallyMerged)
    {
        return String::Format(u"The cell at {0} is horizontally merged.", cellLocation);
    }
 
    return isVerticallyMerged ? String::Format(u"The cell at {0} is vertically merged", cellLocation)
                              : String::Format(u"The cell at {0} is not merged", cellLocation);
}

Enumerator
None	The cell is not merged.
First	The cell is the first cell in a range of merged cells.
Previous	The cell is merged to the previous cell horizontally or vertically.

CellVerticalAlignment

enum class Aspose::Words::Tables::CellVerticalAlignment

strong

Specifies vertical justification of text inside a table cell.

Examples

Shows how to build a formatted 2x2 table.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
 
SharedPtr<Table> table = builder->StartTable();
builder->InsertCell();
builder->get_CellFormat()->set_VerticalAlignment(CellVerticalAlignment::Center);
builder->Write(u"Row 1, cell 1.");
builder->InsertCell();
builder->Write(u"Row 1, cell 2.");
builder->EndRow();
 
// While building the table, the document builder will apply its current RowFormat/CellFormat property values
// to the current row/cell that its cursor is in and any new rows/cells as it creates them.
ASSERT_EQ(CellVerticalAlignment::Center, table->get_Rows()->idx_get(0)->get_Cells()->idx_get(0)->get_CellFormat()->get_VerticalAlignment());
ASSERT_EQ(CellVerticalAlignment::Center, table->get_Rows()->idx_get(0)->get_Cells()->idx_get(1)->get_CellFormat()->get_VerticalAlignment());
 
builder->InsertCell();
builder->get_RowFormat()->set_Height(100);
builder->get_RowFormat()->set_HeightRule(HeightRule::Exactly);
builder->get_CellFormat()->set_Orientation(TextOrientation::Upward);
builder->Write(u"Row 2, cell 1.");
builder->InsertCell();
builder->get_CellFormat()->set_Orientation(TextOrientation::Downward);
builder->Write(u"Row 2, cell 2.");
builder->EndRow();
builder->EndTable();
 
// Previously added rows and cells are not retroactively affected by changes to the builder's formatting.
ASPOSE_ASSERT_EQ(0, table->get_Rows()->idx_get(0)->get_RowFormat()->get_Height());
ASSERT_EQ(HeightRule::Auto, table->get_Rows()->idx_get(0)->get_RowFormat()->get_HeightRule());
ASPOSE_ASSERT_EQ(100, table->get_Rows()->idx_get(1)->get_RowFormat()->get_Height());
ASSERT_EQ(HeightRule::Exactly, table->get_Rows()->idx_get(1)->get_RowFormat()->get_HeightRule());
ASSERT_EQ(TextOrientation::Upward, table->get_Rows()->idx_get(1)->get_Cells()->idx_get(0)->get_CellFormat()->get_Orientation());
ASSERT_EQ(TextOrientation::Downward, table->get_Rows()->idx_get(1)->get_Cells()->idx_get(1)->get_CellFormat()->get_Orientation());
 
doc->Save(ArtifactsDir + u"DocumentBuilder.BuildTable.docx");

Enumerator
Top	Text is aligned at the top of a cell.
Center	Text is aligned in the middle of a cell.
Bottom	Text is aligned at the bottom of the cell.

PreferredWidthType

enum class Aspose::Words::Tables::PreferredWidthType

strong

Specifies the unit of measurement for the preferred width of a table or cell.

See also

Aspose::Words::Tables::PreferredWidth

Examples

Shows how to verify the preferred width type and value of a table cell.

auto doc = MakeObject<Document>(MyDir + u"Tables.docx");
 
SharedPtr<Table> table = doc->get_FirstSection()->get_Body()->get_Tables()->idx_get(0);
SharedPtr<Cell> firstCell = table->get_FirstRow()->get_FirstCell();
 
ASSERT_EQ(PreferredWidthType::Percent, firstCell->get_CellFormat()->get_PreferredWidth()->get_Type());
ASPOSE_ASSERT_EQ(11.16, firstCell->get_CellFormat()->get_PreferredWidth()->get_Value());

Enumerator
Auto	The preferred width is not specified. The actual width of the table or cell is either specified using the explicit width or will be determined automatically by the table layout algorithm when the table is displayed, depending on the table auto fit setting.
Percent	Measure the current item width using a specified percentage.
Points	Measure the current item width using a specified number of points (1/72 inch).

TableAlignment

enum class Aspose::Words::Tables::TableAlignment

strong

Specifies alignment for an inline table.

Examples

Shows how to apply an outline border to a table.

auto doc = MakeObject<Document>(MyDir + u"Tables.docx");
SharedPtr<Table> table = doc->get_FirstSection()->get_Body()->get_Tables()->idx_get(0);
 
// Align the table to the center of the page.
table->set_Alignment(TableAlignment::Center);
 
// Clear any existing borders and shading from the table.
table->ClearBorders();
table->ClearShading();
 
// Add green borders to the outline of the table.
table->SetBorder(BorderType::Left, LineStyle::Single, 1.5, System::Drawing::Color::get_Green(), true);
table->SetBorder(BorderType::Right, LineStyle::Single, 1.5, System::Drawing::Color::get_Green(), true);
table->SetBorder(BorderType::Top, LineStyle::Single, 1.5, System::Drawing::Color::get_Green(), true);
table->SetBorder(BorderType::Bottom, LineStyle::Single, 1.5, System::Drawing::Color::get_Green(), true);
 
// Fill the cells with a light green solid color.
table->SetShading(TextureIndex::TextureSolid, System::Drawing::Color::get_LightGreen(), System::Drawing::Color::Empty);
 
doc->Save(ArtifactsDir + u"Table.SetOutlineBorders.docx");

Enumerator
Left	The table is aligned to the left.
Center	The table is centered.
Right	The table is aligned to the right.

TableStyleOptions

enum class Aspose::Words::Tables::TableStyleOptions

strong

Specifies how table style is applied to a table.

See also

Aspose::Words::Tables::Table::get_StyleOptions

Examples

Shows how to build a new table while applying a style.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
SharedPtr<Table> table = builder->StartTable();
 
// We must insert at least one row before setting any table formatting.
builder->InsertCell();
 
// Set the table style used based on the style identifier.
// Note that not all table styles are available when saving to .doc format.
table->set_StyleIdentifier(StyleIdentifier::MediumShading1Accent1);
 
// Partially apply the style to features of the table based on predicates, then build the table.
table->set_StyleOptions(TableStyleOptions::FirstColumn | TableStyleOptions::RowBands | TableStyleOptions::FirstRow);
table->AutoFit(AutoFitBehavior::AutoFitToContents);
 
builder->Writeln(u"Item");
builder->get_CellFormat()->set_RightPadding(40);
builder->InsertCell();
builder->Writeln(u"Quantity (kg)");
builder->EndRow();
 
builder->InsertCell();
builder->Writeln(u"Apples");
builder->InsertCell();
builder->Writeln(u"20");
builder->EndRow();
 
builder->InsertCell();
builder->Writeln(u"Bananas");
builder->InsertCell();
builder->Writeln(u"40");
builder->EndRow();
 
builder->InsertCell();
builder->Writeln(u"Carrots");
builder->InsertCell();
builder->Writeln(u"50");
builder->EndRow();
 
doc->Save(ArtifactsDir + u"DocumentBuilder.InsertTableWithStyle.docx");

Enumerator
None	No table style formatting is applied.
FirstRow	Apply first row conditional formatting.
LastRow	Apply last row conditional formatting.
FirstColumn	Apply 1 first column conditional formatting.
LastColumn	Apply last column conditional formatting.
RowBands	Apply row banding conditional formatting.
ColumnBands	Apply column banding conditional formatting.
Default2003	Row and column banding is applied. This is Microsoft Word default for old formats such as DOC, WML and RTF.
Default	This is Microsoft Word defaults.

TextWrapping

enum class Aspose::Words::Tables::TextWrapping

strong

Specifies how text is wrapped around the table.

Examples

Shows how to work with table text wrapping.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
 
SharedPtr<Table> table = builder->StartTable();
builder->InsertCell();
builder->Write(u"Cell 1");
builder->InsertCell();
builder->Write(u"Cell 2");
builder->EndTable();
table->set_PreferredWidth(PreferredWidth::FromPoints(300));
 
builder->get_Font()->set_Size(16);
builder->Writeln(u"Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.");
 
// Set the "TextWrapping" property to "TextWrapping.Around" to get the table to wrap text around it,
// and push it down into the paragraph below by setting the position.
table->set_TextWrapping(TextWrapping::Around);
table->set_AbsoluteHorizontalDistance(100);
table->set_AbsoluteVerticalDistance(20);
 
doc->Save(ArtifactsDir + u"Table.WrapText.docx");

Enumerator
None	Text and table is displayed in the order of their appearance in the document.
Around	Text is wrapped around the table occupying available side space.
Default	Default value.