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. More...
 
class  CellCollection
 Provides typed access to a collection of Cell nodes. More...
 
class  CellFormat
 Represents all formatting for a table cell. 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. More...
 
class  Row
 Represents a table row. More...
 
class  RowCollection
 Provides typed access to a collection of Row nodes. More...
 
class  RowFormat
 Represents all formatting for a table row. More...
 
class  Table
 Represents a table in a Word document. More...
 
class  TableCollection
 Provides typed access to a collection of Table nodes. 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

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.
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

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 (auto row : System::IterateOver(table->get_Rows()->LINQ_OfType<SharedPtr<Row>>()))
{
for (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

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

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

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.
// Fill the cells with a light green solid color.
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

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.
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

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.