Text

Text and associated leaders can be accessed from the TextNote class.

TextNote

A TextNote can have plain text or formatted text. The overloaded TextNote.Create() method provides options for creating unwrapped and line-wrapping text note elements. The width for the area of the text content can be specified on creation, but is restricted by a minimum and maximum width that is based on properties of the text and its type. The overloaded methods GetMinimumAllowedWidth() and GetMaximumAllowedWidth(), inherited from TextElement, return the constraints for either a specific TextNote or for a given document and text type id.

The following example creates a new TextNote at a user specified point and with a given width and TextNoteOptions.

Code Region: Create a TextNote 

public TextNote AddNewTextNote(UIDocument uiDoc)
{
    Document doc = uiDoc.Document;
    XYZ textLoc = uiDoc.Selection.PickPoint("Pick a point for sample text.");
    ElementId defaultTextTypeId = doc.GetDefaultElementTypeId(ElementTypeGroup.TextNoteType);
    double noteWidth = .2;

    // make sure note width works for the text type
    double minWidth = TextNote.GetMinimumAllowedWidth(doc, defaultTextTypeId);
    double maxWidth = TextNote.GetMaximumAllowedWidth(doc, defaultTextTypeId);
    if (noteWidth < minWidth)
    {
        noteWidth = minWidth;
    }
    else if (noteWidth > maxWidth)
    {
        noteWidth = maxWidth;
    }

    TextNoteOptions opts = new TextNoteOptions(defaultTextTypeId);
    opts.HorizontalAlignment = HorizontalTextAlignment.Left;
    opts.Rotation = Math.PI / 4;
           
    TextNote textNote = TextNote.Create(doc, doc.ActiveView.Id, textLoc, noteWidth, "New sample text", opts);

    return textNote;
}

Whether a TextNote has plain or formatted text, the unformatted text can always be retrieved from the TextNote.Text property.

FormattedText

When first created, the TextNote will have plain text. Use the TextNote.GetFormattedText() method to get a FormattedText object for the TextNote. The FormattedText class can be used to apply various formatting to the text such as bold, underline, superscript or all caps. The TextNote is not updated until SetFormattedText() is called with the modified FormattedText.

The text in the FormattedText can be formatted in whole or in part using a TextRange. A TextRange specifies a start index and length based on the text in the FormattedText object. When the overload of a formatting method (such as SetItalicStatus() or SetAllCapsStatus()) uses a TextRange, only the characters within the range will be modified. A TextRange can be defined explicitly using its constructor, or can be retrieved using the FormattedText.Find() method to get the range for a given search string. The Find() method specifies a start index for the search, as well as whether to match the case of the search string or whether to do a whole word search. If the text in the search string is not found or if the given start index is beyond the end of the length of the entire text, an empty TextRange will be returned. Before using the returned range to set formatting on the text, ensure that it is not empty to avoid an exception.

The following example demonstrates how to format text from a TextNote and set it back to the TextNote. It uses the Find() method to bold and underline specific words in the text.

Code Region: Format text in a TextNote 

public void FormatText(TextNote textNote)
{
    // TextNote created with "New sample text"
    FormattedText formatText = textNote.GetFormattedText();

    // italicize "New"
    TextRange range = new TextRange(0, 3);
    formatText.SetItalicStatus(range, true);

    // make "sample" bold
    range = formatText.Find("sample", 0, false, true);
    if (range.Length > 0)
        formatText.SetBoldStatus(range, true);

    // make "text" underlined
    range = formatText.Find("text", 0, false, true);
    if (range.Length > 0)
        formatText.SetUnderlineStatus(range, true);

    // make all text uppercase
    formatText.SetAllCapsStatus(true);

    textNote.SetFormattedText(formatText);
}

New text can be added to existing text in a FormattedText object. The SetPlainText() method will either replace some existing text if the overload that has a TextRange parameter is used, or will replace the entire text if not. To insert text without replacing existing text, use a TextRange with a Length of 0. The new text will be inserted at the index specified by the TextRange.Start property. Note that when inserting text, it may pick up the formatting of the adjacent text, similar to how pasting unformatted text into a Word document will result in text with the current formatting for the insertion point. If formatting has been applied to the entire FormattedText as in the case of the SetAllCapsStatus(true) call in the example above, that formatting will be applied to any new text that is inserted.

In the following example, new text is appended to the end of existing text by first finding the end of the current text and setting that as the Start of the range to be added. It also demonstrates how to create a list (which can be bulleted, numbered or lettered). Note that it also calls GetAllCapsStatus() for the range of the new text and turns off caps if the status is not FormatStatus.None (other options are All and Mixed).

Code Region: Inserting new text 

public void AppendText(TextNote textNote)
{
    FormattedText formatText = textNote.GetFormattedText();

    TextRange range = formatText.AsTextRange();
                
    range.Start = range.End - 1;
    // set Length to 0 to insert
    range.Length = 0;
    string someNewText = "\rThis is a new paragraph\vThis is a new line without a paragraph break\r";
    formatText.SetPlainText(range, someNewText);

    // get range for entire text
    range = formatText.AsTextRange();
    range.Start = range.End - 1;
    range.Length = 0;
    string someListText = "\rBulleted List item 1\rItem 2\vSecond line for Item 2\rThird bullet point";
    formatText.SetPlainText(range, someListText);
    range.Start++;
    range.Length = someListText.Length;
    formatText.SetListType(range, ListType.Bullet);

    if (formatText.GetAllCapsStatus(range) != FormatStatus.None)
    {
        formatText.SetAllCapsStatus(range, false);
    }

    textNote.SetFormattedText(formatText);
}

The code above shows how to use \r to create a line break, and \v for a vertical tab that does not break the paragraph. In the text for the bulleted list, a "\v" is used to create a two line bullet point. A new bullet is only inserted when using "\r".

Text Editor

The TextEditorOptions class can be used to control the appearance and functionality of the text editor in Revit. These settings are saved in the Revit.ini file and are not tied to the document.

Code Region: Setting text editor options 

public void SetEditorOptions()
{
    TextEditorOptions editorOptions = TextEditorOptions.GetTextEditorOptions();
    editorOptions.ShowBorder = false;
    editorOptions.ShowOpaqueBackground = true;
}

Leaders

Revit supports two kinds of Leaders: straight leaders and arc leaders. Leaders can be added to a TextNote using the AddLeader() method, specifying the leader type using the TextNoteLeaderType enumerated type:

Table 39: Leader Types

Function

Member Name

-Add a right arc leader

TNLT_ARC_R

-Add a left arc leader

TNLT_ARC_L

-Add a right leader.

TNLT_STRAIGHT_R

-Add a left leader.

TNLT_STRAIGHT_L

Note: Straight leaders and arc leaders cannot be added to a Text type at the same time.

The TextNote.LeaderCount property returns the number of leaders and the GetLeaders() method returns all leaders currently attached to the text component. LeaderLeftAttachment and LeaderRightAttachment indicate the attachment position of the leaders on the corresponding side of the TextNote. Options for the LeaderAttachment are TopLine, MidPoint, and BottomLine. Use the RemoveLeaders() method to remove all leaders from the TextNote.

Parent topic: Annotation Elements