A document consists of several parts, including the main text, headers, footers, and text frames, which are accessible through the TextPartCollection in form of IFormattedText objects. In addition, you can use the SubTextPart class to define your own custom parts.

These SubTextParts are areas of text with a specific name and ID that persist when the document is saved. They automatically expand as users type more text. Internally, TX Text Control uses this element for various features such as editable regions (for the exceptions), track changes, and repeating merge blocks.

These regions can be nested so that existing SubTexParts can have nested child parts embedded. In addition, it is possible to define a highlight color and a highlight mode to specify whether or not these areas should be highlighted.

The following code shows how to convert the currently selected text into a SubTexParts that is highlighted with a transparent red color.

// create a new SubTextPart with the name "part1" and id 1
 TXTextControl.SubTextPart subTextPart = new TXTextControl.SubTextPart("part1", 1);

 // set the highlight color to red
 subTextPart.HighlightColor = Color.FromArgb(60, Color.Red);
 subTextPart.HighlightMode = TXTextControl.HighlightMode.Always;

 // add the subtext part to the SubTextParts collection
 textControl1.SubTextParts.Add(subTextPart);

The following screenshot shows the result of the code shown above:

Typical Use Cases

Prior to the introduction of SubTextParts in TX Text Control, text boxes or bookmark markers were used to mark a specific block of text in a document. An advantage of using SubTextParts is that they can consist of any other document element, including other SubTextParts, text fields, bookmarks, or document targets. If you use text fields to mark a particular section, you cannot add other text fields to those sections.

Saving SubTextParts

For example, if a document is divided into several sections and the content needs to be tracked or stored in a database as it is changed. In this case, this section can be easily found in the document by iterating through the collection of SubTextParts or by finding the SubTextPart by name. Without explicit selection, any SubTextPart can be saved directly.

byte[] textBlock;

textControl1.SubTextParts.GetItem("part1").Save(out textBlock, 
    TXTextControl.BinaryStreamType.InternalUnicodeFormat);

Storing Additional Data

SubTextParts can be used to store additional data in a document. This data can be used to store additional information such as comments, meta data, or other information that is not visible in the document.

Consider a scenario in which you want to store some additional information that is not visible to the reader. The following class holds user information that should be stored with the SubTextParts.

public class UserInfo
{
    public string Name { get; set; }
    public string Address { get; set; }
    public string City { get; set; }
    public string State { get; set; }
    public string Zip { get; set; }
    public string Phone { get; set; }
    public string Email { get; set; }
}

The following code shows how to store this information with a SubTextPart:

// create a new SubTextPart with the name "part1" and id 1
TXTextControl.SubTextPart subTextPart = new TXTextControl.SubTextPart("part1", 1);

// create a new UserInfo object
UserInfo userInfo = new UserInfo()
{
    Name = "John Doe",
    Address = "123 Main Street",
    City = "Dallas",
    State = "TX",
    Zip = "75201",
    Phone = "214-555-1212"
};

// serialize the UserInfo object to a JSON string
subTextPart.Data = JsonSerializer.Serialize(userInfo);

// add the subtext part to the SubTextParts collection
textControl1.SubTextParts.Add(subTextPart);

When the document is loaded, the SubTextPart can be accessed and the additional data can be retrieved:

UserInfo userInfo;

 // deserialize the JSON string to a UserInfo object if data is available
 if (textControl1.SubTextParts.GetItem("part1").Data != null)
 {
     userInfo = JsonSerializer.Deserialize<UserInfo>(textControl1.SubTextParts.GetItem("part1").Data);
 }

Warning

SubTextParts themselves are maintained, but the stored data is not when saving in formats other than the internal TX Text Control format. To load SubTextParts, the LoadSettings must be used.

TXTextControl.LoadSettings loadSettings = new TXTextControl.LoadSettings()
{
    LoadSubTextParts = true,
;

textControl1.Load("document1.docx",
  TXTextControl.StreamType.WordprocessingML,
  loadSettings);

SubTextPart Events

SubTextParts provide a variety of events to keep track of the interactions of the user. The event handler returns the associated SubTextPart.

The following code shows how to handle the SubTextPartEntered event:

private void textControl1_SubTextPartEntered(object sender, SubTextPartEventArgs e)
{
    UserInfo userInfo;

    // deserialize the JSON string to a UserInfo object if data is available
    if (e.SubTextPart.Data != null)
    {
        userInfo = JsonSerializer.Deserialize<UserInfo>(e.SubTextPart.Data);

        MessageBox.Show(userInfo.Name);
    }
}

The data is read from the SubTextPart when the user enters the SubTextPart.

Conclusion

SubTextParts are a powerful feature of TX Text Control that can be used to create reusable document parts. This article showed typical use cases for SubTextParts and how to use them.