Text and Paragraph Formatting

Users format text in a TX Text Control editor the way they do in a word processor: they select it and click Bold, pick a font, center a paragraph or open the Paragraph dialog box. Your code has the same tools. It formats the selected text through Selection, sets paragraph attributes through ParagraphFormat, opens the built-in formatting dialog boxes and keeps your own toolbar in step with the text. Formatting through named styles has a page of its own, Stylesheets, and bulleted and numbered lists are covered in Bullets and Numbered Lists.

How Formatting Works

Formatting has two levels. Character formatting, such as the font, the size, bold or the text color, applies to single characters. Paragraph formatting, such as the alignment, the indents, the line spacing or tab stops, applies to whole paragraphs.

Both are set through Selection, which refers to the selected text of the text part with the input focus:

• Text is selected. A property such as Bold formats the selected characters. Paragraph attributes apply to every paragraph the selection touches.
• Nothing is selected. Character attributes apply at the input position, so the text the user types next gets them. Paragraph attributes apply to the paragraph of the input position.

Sizes and distances are measured in twips, a twentieth of a point: 20 twips are 1 point, 1,440 twips are 1 inch, and about 567 twips are 1 centimeter.

Users reach the same attributes through the Font and Paragraph groups of the ribbon's formatting tab, a RibbonFormattingTab:

A ButtonBar and the mini toolbar that ShowMiniToolbar turns on offer the common attributes too; Toolbars and Mini Toolbars describes them. The text mini toolbar appears next to the selected text:

Format Characters

The following Click handlers of two buttons on Form1 toggle bold and format the selection as a heading. They need using System.Drawing; and using TXTextControl;:

private void boldButton_Click(object sender, EventArgs e)
{
    // Toggle bold for the selected text or the input position
    textControl1.Selection.Bold = !textControl1.Selection.Bold;
}

private void headingButton_Click(object sender, EventArgs e)
{
    textControl1.Selection.FontName = "Arial";
    textControl1.Selection.FontSize = 320;   // 16 points, in twips
    textControl1.Selection.ForeColor = Color.DarkBlue;
    textControl1.Selection.Underline = FontUnderlineStyle.Single;
}

The character attributes of a Selection:

AutoBaseline, Capitals, CharacterSpacing and CharacterScaling were introduced in version 30.0.

Format Text That Code Inserts

To format a range that your code has just inserted without selecting it on the screen, prepare a Selection object with a start position and a length, set its attributes and assign it to textControl1.Selection. Select and Replace Text in Code shows the code and why the change then counts as one undo step.

Format Paragraphs

Paragraph attributes are grouped in a ParagraphFormat object. Create one, set the attributes you want to change and assign it to Selection.ParagraphFormat:

private void paragraphButton_Click(object sender, EventArgs e)
{
    ParagraphFormat format = new ParagraphFormat();
    format.Alignment = TXTextControl.HorizontalAlignment.Justify;
    format.LeftIndent = 567;       // 1 cm, in twips
    format.TopDistance = 120;      // 6 points before the paragraph
    format.BottomDistance = 120;   // 6 points after the paragraph
    format.LineSpacing = 150;      // 150 percent
    format.Frame = Frame.BottomLine;
    format.FrameLineWidth = 20;
    format.FrameStyle = TXTextControl.FrameStyle.Single;

    textControl1.Selection.ParagraphFormat = format;
}

HorizontalAlignment and FrameStyle also exist in System.Windows.Forms, which a Windows Forms file imports. Write them with the TXTextControl namespace, as above, or the compiler reports an ambiguous reference.

Tables of Contents explains structure levels, and Right-to-Left UI the writing direction.

Set Tab Stops

Tab stops are three arrays of ParagraphFormat with one entry per tab: TabPositions in twips, TabTypes and TabLeaders. A paragraph has at most 14 tabs, the value of MaxTabs.

private void tabsButton_Click(object sender, EventArgs e)
{
    ParagraphFormat format = new ParagraphFormat();
    format.TabPositions = new int[] { 2835, 5670 };                 // 5 cm and 10 cm
    format.TabTypes = new TabType[] { TabType.LeftTab, TabType.DecimalTab };
    format.TabLeaders = new TabLeader[] { TabLeader.None, TabLeader.Dot };

    textControl1.Selection.ParagraphFormat = format;
    textControl1.Selection.Text = "Item\t\t12.50";
}

A TabType is LeftTab, RightTab, CenterTab, DecimalTab or RightBorderTab; a decimal tab aligns the decimal sign at the position. A TabLeader fills the gap with Period, Dot, Dash or Underline, or leaves it empty with None.

Users set the same values in the Tabs dialog box, which TabDialog opens: a list of the tab stop positions of the paragraph, the alignment and the leader of the selected tab stop, and Set, Clear and Clear All buttons:

Use the One-Click Commands

Selection has methods for the commands of the ribbon buttons. Each works on the selection, or at the input position when nothing is selected:

• GrowFont and ShrinkFont step the font size up and down through the sizes that the button bar and the font dialog box offer.
• IncreaseIndent and DecreaseIndent change the left indent of the paragraphs, to positions taken from their tab positions and the indents of the surrounding paragraphs.
• RemoveFormatting resets the character attributes of the selection to their defaults, and the paragraph attributes too when nothing or more than one paragraph is selected.

Open the Built-In Dialog Boxes

TextControl opens its formatting dialog boxes with one call each. Each method returns a DialogResult, which is Cancel when the user canceled the dialog box.

For example, a menu item that opens the paragraph settings calls textControl1.ParagraphFormatDialog(); in its Click handler. Built-in Dialog Boxes lists all dialog boxes of the editor.

Keep Your Own Controls in Step

A toolbar of your own has to show the attributes at the input position, such as whether the Bold button is pressed. CharFormatChanged occurs when the character attributes of the selection or the input position have changed, and ParagraphFormatChanged when the paragraph attributes have. Integrating Existing Menus and Toolbars builds a ToolStrip whose buttons follow these events.

When the selection contains different values of an attribute, the Selection property returns its default value. IsCommonValueSelected with a Selection.Attribute value, such as Selection.Attribute.FontName, tells you whether the whole selection has one value, so that a font box can stay empty for a selection in several fonts. InputFormat gives all attributes at the input position in one InputFormat object, whose properties are nullable, such as bool? for Bold.

Next Steps

• Stylesheets: name a set of attributes once and apply it everywhere.
• Bullets and Numbered Lists: format paragraphs as lists.
• Toolbars and Mini Toolbars: the formatting controls that come with the editor.
• Text, Paragraphs, and Stylesheets: format documents without an editor.