Paragraphs
- 4 minutes to read
Overview
Paragraphs are the most basic units of block-level content within a document. A paragraph defines a distinct division of content that begins on a new line. As text content, paragraphs are stored within a sub-document’s text buffer. The end of paragraphs is marked with a specific paragraph end symbol (¶).
Definition
A paragraph is a logical unit that contains paragraph-specific settings and that defines to which text buffer interval these settings should be applied. Programmatically, a paragraph is implemented as the Paragraph client object. A list of paragraph objects in the active sub-document can be accessed through the paragraphsInfo client property (SubDocument.paragraphsInfo) in the following notation.
clientRichEditName.document.activeSubDocument.paragraphsInfo
You also can use the SubDocument.findParagraphs method to get portion of paragraphs that intersect the specified position or intervals.
A paragraph can be fully defined using the following characteristics (some of them are optional).
Start position (Paragraph.start)
A position in a sub-document text buffer where the paragraph’s first text run starts.
Length (Paragraph.length)
The number of characters in a paragraph within the text buffer.
Index (Paragraph.index)
The index of the paragraph in the sub-document.
Paragraph properties (ParagraphFormattingSettings)
Paragraph-specific formatting settings.
Paragraph style name (Paragraph.styleName)
The name of a separate style object containing uniform paragraph formatting settings.
List-related information, if any (Paragraph.listIndex, Paragraph.listLevelIndex)
The indexes of a parent list and its child list item represented by a paragraph.
Paragraph Properties
Paragraphs expose their own paragraph-specific formatting settings. Some examples of paragraph properties are alignment, spacing and indentation. Information about paragraph formatting is exposed by client API - through the properties of the ParagraphFormattingSettings client object. This object is used in the changeParagraphFormatting client command (RichEditCommands.changeParagraphFormatting): in its execute method’s parameter and in the getState method’s return value.
Client API
The following client commands are available for applying paragraph formatting directly to the text. Call the commands in the notation given below:
clientRichEditName.commands.commandName.execute(parameter_if_any)
| Command Name | Link | Description |
|---|---|---|
| addSpacingAfterParagraph | RichEditCommands.addSpacingAfterParagraph | Gets a command to add spacing after a paragraph. |
| addSpacingBeforeParagraph | RichEditCommands.addSpacingBeforeParagraph | Gets a command to add spacing before a paragraph. |
| changeParagraphBackColor | RichEditCommands.changeParagraphBackColor | Gets a command to change the background color of paragraphs in a selected range. |
| changeParagraphFormatting | RichEditCommands.changeParagraphFormatting | Gets a command to apply formatting settings to paragraphs within a selected range. |
| changeTabs | RichEditCommands.changeTabs | Gets a command to change the default tab stop value of a document and apply custom tab settings to the selected paragraphs. |
| decreaseIndent | RichEditCommands.decreaseIndent | Gets a command to decrease the indent level of paragraphs in a selected range. |
| decrementParagraphLeftIndent | RichEditCommands.decrementParagraphLeftIndent | Gets a command to decrement the paragraph’s left indent position. |
| increaseIndent | RichEditCommands.increaseIndent | Gets a command to increment the indent level of paragraphs in a selected range. |
| incrementParagraphLeftIndent | RichEditCommands.incrementParagraphLeftIndent | Gets a command to increment the left indent of paragraphs in a selected range. |
| openParagraphFormattingDialog | RichEditCommands.openParagraphFormattingDialog | Gets a command to invoke the Indents And Spacing tab of the Paragraph dialog window. |
| openTabsDialog | RichEditCommands.openTabsDialog | Gets a command to invoke the Tabs dialog window. |
| removeSpacingAfterParagraph | RichEditCommands.removeSpacingAfterParagraph | Gets a command to remove spacing after the selected paragraph. |
| removeSpacingBeforeParagraph | RichEditCommands.removeSpacingBeforeParagraph | Gets a command to remove spacing before the selected paragraph. |
| setDoubleParagraphSpacing | RichEditCommands.setDoubleParagraphSpacing | Gets a command to format a selected paragraph with double line spacing. |
| setSesquialteralParagraphSpacing | RichEditCommands.setSesquialteralParagraphSpacing | Gets a command to format a current paragraph with one and a half line spacing. |
| setSingleParagraphSpacing | RichEditCommands.setSingleParagraphSpacing | Gets a command to format a current paragraph with single line spacing. |
| toggleParagraphAlignmentCenter | RichEditCommands.toggleParagraphAlignmentCenter | Gets a command to toggle centered paragraph alignment on and off. |
| toggleParagraphAlignmentJustify | RichEditCommands.toggleParagraphAlignmentJustify | Gets a command to toggle justified paragraph alignment on and off. |
| toggleParagraphAlignmentLeft | RichEditCommands.toggleParagraphAlignmentLeft | Gets a command to toggle left paragraph alignment on and off. |
| toggleParagraphAlignmentRight | RichEditCommands.toggleParagraphAlignmentRight | Gets a command to toggle right paragraph alignment on and off. |
Paragraph Styles
To uniformly format multiple paragraphs, a paragraph style can be used. A paragraph style is a detached container of specific character and paragraph formatting settings. It allows you to apply a similar format to all required characters and paragraphs at once.
Note
If a certain text formatting property (for example, bold or indent) is set directly within the text as a character or paragraph property, style formatting is not applied to this setting (the style property setting does not override the explicitly defined character or paragraph property setting). To reset character or paragraph formatting, use the RichEditCommands.clearFormatting client command.
Client API
A list of paragraph styles can be accessed using the following paragraphStylesInfo property in the notation given below.
clientRichEditName.document.paragraphStylesInfo
| Property Name | Link | Description |
|---|---|---|
| paragraphStylesInfo | RichEditDocument.paragraphStylesInfo | Returns information about paragraph styles in the document. |
To apply a paragraph style to the text, use the following changeStyle client command in the notation given below.
clientRichEditName.commands.changeStyle(parameter_if_any)
| Command Name | Link | Description |
|---|---|---|
| changeStyle | RichEditCommands.changeStyle | Gets a command to apply a character or paragraph style settings to text in a selected range. |
Paragraph formatting can be modified using a number of ribbon commands and a specific dialog. See the Formatting Paragraphs topic for more information.