Working with Paragraphs

A paragraph is a set of characters combined into a logical block and ending with a special character – a paragraph break. In Aspose.Words, a paragraph is represented by the Paragraph class.

Insert a Paragraph

To insert a new paragraph into the document, in fact, you need to insert a paragraph break character into it. DocumentBuilder.Writeln inserts not only a string of text into the document, but also adds a paragraph break.

The current font formatting is also specified by the Font property, and the current paragraph formatting is determined by the ParagraphFormat property. In the next section, we will go into more detail about paragraph formatting.

The following code example shows how to insert a paragraph into a document:

Format Paragraph

Current paragraph formatting is represented by the ParagraphFormat object that is returned by the ParagraphFormat property. This object encapsulates various paragraph formatting properties available in Microsoft Word. You can easily reset a paragraph’s formatting to its default – Normal style, left-aligned, no indentation, no spacing, no borders, no shading – by calling ClearFormatting.

The following code example shows how to set paragraph formatting:

Apply Paragraph Style

Some formatting objects, such as Font or ParagraphFormat, support styles. One built-in or user-defined style is represented by a Style object, which contains the appropriate style properties like name, base style, font, style paragraph formatting, and so on.

In addition, the Style object exposes the StyleIdentifier property, which returns the locale-independent style identifier represented by the StyleIdentifier enumeration value. The fact is that the names of the built-in styles in Microsoft Word are localized for different languages. Using the style identifier, you can find the correct style regardless of the document language. The enumeration values correspond to the built-in Microsoft Word styles such as Normal, Heading 1, Heading 2 and so on. All user-defined styles are set to the StyleIdentifier.User enumeration value.

The following code example shows how to apply a paragraph style:

Insert Style Separator to Put Different Paragraph Styles

A style separator can be added to the end of a paragraph using the keyboard shortcut Ctrl+Alt+Enter in Microsoft Word. This feature allows you to use two different paragraph styles in the same logical printed paragraph. If you want some text from the beginning of a particular heading to appear in the table of contents, but do not want the entire heading to show in the table of contents, you can use this function.

The following code example shows how to insert a style separator to accommodate different paragraph styles:

Identify Paragraph Style Separator

Aspose.Words exposes the BreakIsStyleSeparator public property on the Paragraph class to identify a paragraph with a style separator, as shown in the example below:

Apply Borders and Shading to a Paragraph

Borders in Aspose.Words are represented by the BorderCollection class – this is a collection of Border objects that are accessed by index or by border type. The border type is in turn represented by the BorderType enumeration. Some enumeration values apply to multiple or only one document element. For example, BorderType.Bottom applies to a paragraph or table cell, while BorderType.DiagonalDown specifies a diagonal border in a table cell only.

Both the border collection and each separate border have similar attributes such as color, line style, line width, distance from text, and optional shadow. They are represented by properties of the same name. You can get different border types by combining property values. In addition, the BorderCollection and Border objects allow you to reset these values to their default values by calling the ClearFormatting method.

Aspose.Words also has the Shading class that contains shading attributes for document elements. You can set the desired shading texture and colors that are applied to the background and foreground of an element using the TextureIndex enumeration value. TextureIndex also allows you to apply different patterns to the Shading object. For example, to set the background color for a document element, use the TextureIndex.TextureSolid value and set the foreground shading color as appropriate.

The following code example shows how to apply borders and shading to a paragraph:

Count Paragraph Lines

If you want to count the number of lines in a paragraph for any Word document, the following code sample can be used: