# Architecture and Control Lifecycle

> Text parts of a Windows Forms TextControl, where code goes from InitializeComponent and OnLoad to FormClosing, and a control that grows with AutoControlSize.

- **Product:** TX Text Control .NET for Windows Forms
- **Section:** Documentation
- **Kind:** Topic
- **Path:** TX Text Control .NET for Windows Forms > Document Editor > Architecture and Control Lifecycle
- **3918 words**
- **Web URL:** https://docs.textcontrol.com/tx-text-control-dotnet-winforms/document-editor/architecture/
- **LLMs URL:** https://docs.textcontrol.com/tx-text-control-dotnet-winforms/document-editor/architecture/llms.txt
- **LLMs-Full URL:** https://docs.textcontrol.com/tx-text-control-dotnet-winforms/document-editor/architecture/llms-full.txt

---

Code that runs at the wrong moment is a common source of trouble in an editor application: a document loaded before the form is shown, a selection changed in the wrong text part, a document lost when the form closes. Knowing what a `TextControl` holds, which part of the document your code works on, and when the control is created, ready and gone tells you where each piece of your code belongs.

The overview of the product's parts is in [Product Architecture](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/overview/architecture/llms-full.txt), and the control itself is introduced in [TextControl](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/overview/components/textcontrol/llms-full.txt). Read on for how the control and its document are organized and how a form goes through its life with an editor on it.

### What a TextControl Holds

[TextControl](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/textcontrol/llms-full.txt) is a Windows Forms control derived from `System.Windows.Forms.Control`. The document it shows is not one block of text but several *text parts*: the main text, the text frames, the headers and footers, and the footnote sections. Each text part has its own lines, paragraphs, characters, tables, images and fields.

```text
TextControl
+-- Main text           the body of the document
+-- Text frames         text in positioned frames
+-- Headers and footers the headers and footers of the sections
+-- Footnote sections   the text of the footnotes

Document-wide: Sections, ParagraphStyles, InlineStyles, DocumentSettings, FormFields, TrackedChanges
```

All text parts implement the [IFormattedText](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/iformattedtext/llms-full.txt) interface, and so do `TextControl` and [ServerTextControl](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/servertextcontrol/llms-full.txt). That is why the same members, such as `Selection`, `Paragraphs` and `Tables`, appear on the control, on a [TextFrame](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/textframe/llms-full.txt) and on a [HeaderFooter](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/headerfooter/llms-full.txt), and why code written for the editor also works with `ServerTextControl`.

#### The Text Part With the Input Focus

When you use [Selection](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/textcontrol/selection-property/llms-full.txt), [Paragraphs](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/textcontrol/paragraphs-property/llms-full.txt) or [InputPosition](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/textcontrol/inputposition-property/llms-full.txt) of the `TextControl`, they refer to the text part that has the input focus. That is the main text, unless the user has clicked into a header, a footer or a text frame. Code that formats "the selection" therefore formats text in the header if the user is editing the header.

[TextParts](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/textcontrol/textparts-property/llms-full.txt) returns all text parts in a [TextPartCollection](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/textpartcollection/llms-full.txt): first the main text, then the text frames and then the headers and footers, each group in the order of their position in the document. The following method lists them and gives the main text the input focus again:

```csharp
private void ListTextParts()
{
    foreach (IFormattedText textPart in textControl1.TextParts)
    {
        Debug.WriteLine(textPart.GetType().Name + ": " + textPart.Paragraphs.Count + " paragraphs");
    }

    // Give the main text the input focus again
    textControl1.TextParts.Activate(textControl1.TextParts.GetMainText());
}
```

- Each element of the collection is a [MainText](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/maintext/llms-full.txt), `TextFrame`, `HeaderFooter` or [FootnoteSection](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/footnotesection/llms-full.txt) object, and each can be used through `IFormattedText`.
- [Activate](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/textpartcollection/activate-method/llms-full.txt) moves the input focus to a main text, text frame or header or footer and scrolls it into view. [GetMainText](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/textpartcollection/getmaintext-method/llms-full.txt) returns the main text.
- The method needs `using System.Diagnostics;` for `Debug`.

[Headers and Footers](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/document-editor/headers-footers/llms-full.txt), [Text Frames and Shapes](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/document-editor/text-frames-shapes/llms-full.txt) and [Footnotes](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/document-editor/footnotes/llms-full.txt) show how to work with each kind of text part.

#### Runtime-Only Members

The reference marks many members of `TextControl` as "Runtime only", among them `Selection`, `InputPosition` and `TextParts`. They are not available in the **Properties** window: you use them in code while the application runs. Properties without this limitation, such as [ViewMode](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/textcontrol/viewmode-property/llms-full.txt) or [FormattingPrinter](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/textcontrol/formattingprinter-property/llms-full.txt), can also be set in the designer.

### The Life of the Control

A `TextControl` on a form goes through the same stages as the form. Unlike a `ServerTextControl`, it needs no call to `Create`: the form creates and releases it.

| Stage | What happens | Where your code goes |
|---|---|---|
| Created | `InitializeComponent` in the constructor of the form creates the control and applies the values of the **Properties** window. | The constructor, after `InitializeComponent`: connect event handlers and set properties. |
| Ready | The form is loaded and about to be shown. | The `Load` event of the form, or an override of `OnLoad`: load the first document, set the focus. |
| Working | Users and your code load, edit and save documents. | Event handlers such as `Changed` and `DocumentLoaded`. |
| Closing | The user closes the form. | The `FormClosing` event: ask whether to save changes, and cancel closing if needed. |

The TX Words sample that the setup installs follows this pattern: its main form connects its features to the `TextControl` in an override of `OnLoad`. For more control over the moment the window handle exists, `TextControl` also overrides [OnHandleCreated](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/textcontrol/onhandlecreated-method/llms-full.txt) of `Control`, which a class derived from `TextControl` can override in turn.

The following form puts the stages together. It assumes a `TextControl` named `textControl1` on `Form1` and a file *report.docx* in the folder of the application:

```csharp
using System;
using System.Diagnostics;
using System.Windows.Forms;
using TXTextControl;

public partial class Form1 : Form
{
    public Form1()
    {
        // Creates textControl1 with the settings of the Properties window
        InitializeComponent();

        textControl1.DocumentLoaded += textControl1_DocumentLoaded;
        textControl1.ContentsReset += textControl1_ContentsReset;
        textControl1.Changed += textControl1_Changed;
        FormClosing += Form1_FormClosing;
    }

    protected override void OnLoad(EventArgs e)
    {
        base.OnLoad(e);

        // The form is about to be shown for the first time
        textControl1.Load("report.docx", StreamType.WordprocessingML);
        textControl1.Focus();
    }

    private void textControl1_DocumentLoaded(object sender, EventArgs e)
    {
        Debug.WriteLine("A document has been loaded.");
    }

    private void textControl1_ContentsReset(object sender, EventArgs e)
    {
        Debug.WriteLine("The contents have been reset.");
    }

    private void textControl1_Changed(object sender, EventArgs e)
    {
        Debug.WriteLine("The contents have changed.");
    }

    private void Form1_FormClosing(object sender, FormClosingEventArgs e)
    {
        // Ask the user to save changes here, and set e.Cancel to keep the form open
    }
}
```

The code works as follows:

- **Loading.** [Load](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/textcontrol/load-method/llms-full.txt) replaces the complete contents of the control. [DocumentLoaded](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/textcontrol/documentloaded-event/llms-full.txt) occurs when a new document has been loaded, which is the moment to read its properties or update your user interface.
- **Resetting.** [ResetContents](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/textcontrol/resetcontents-method/llms-full.txt) deletes the entire contents, for example for a **New** command. [ContentsReset](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/textcontrol/contentsreset-event/llms-full.txt) occurs when all text has been deleted and all attributes have been reset to the state after initialization.
- **Editing.** [Changed](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/textcontrol/changed-event/llms-full.txt) indicates that the contents of the document have changed. Use it to mark the document as modified.
- **Closing.** The document exists only in the memory of the control until your code saves it. The `FormClosing` handler is the last place to save it. [Load and Save Documents](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/getting-started/document-editor/load-save/llms-full.txt) in Getting Started shows a complete save-changes prompt.

[Events](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/document-editor/events/llms-full.txt) lists the other events of the control.

### One Engine for Display and Printing

`TextControl` formats the document with the text dimensions of a printer, which [FormattingPrinter](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/textcontrol/formattingprinter-property/llms-full.txt) names, so that the document on the screen has the same layout as the printed one. The printer is contacted while the control initializes, so a slow printer can delay the start of the control. [Printing](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/document-processing/printing/#choose-the-formatting-printer) lists the values of `FormattingPrinter`, and [Performance Best Practices](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/performance/best-practices/#start-without-waiting-for-a-printer) shows how to start without waiting for a printer.

### Several Editors and Background Work

Each `TextControl` has its own document. A form with two editors, such as a document and a template side by side, keeps two independent documents, and nothing is shared unless your code copies it, for example by saving one document to a byte array and loading it into the other.

Work that the user doesn't watch, such as creating many documents or preparing a document before it is shown, belongs in a [ServerTextControl](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/servertextcontrol/llms-full.txt). It has the same programming interface but no window. You create it in code, call [Create](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/servertextcontrol/create-method/llms-full.txt) before any other member, and dispose of it when the work is done. [Using ServerTextControl in Desktop Applications](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/document-processing/servertextcontrol/llms-full.txt) and [UI Threading and Background Operations](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/performance/threading/llms-full.txt) go further.

### Let the Control Grow With Its Content

A `TextControl` doesn't have to be a full editor. Used as a formatted input field on a form, it can change its own width or height as the user types, like a text box that grows with its text. [AutoControlSize](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/textcontrol/autocontrolsize-property/llms-full.txt) turns this on with an [AutoSize](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/autosize/llms-full.txt) object. It works only when [ViewMode](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/textcontrol/viewmode-property/llms-full.txt) is `ViewMode.SimpleControl`, where the text is formatted to the extent of the control instead of to a page.

```csharp
// The control grows and shrinks horizontally, up to 600 pixels
textControl1.ViewMode = ViewMode.SimpleControl;
textControl1.AutoControlSize.AutoExpand = AutoSizeDirection.Horizontal;
textControl1.AutoControlSize.AutoShrink = AutoSizeDirection.Horizontal;
textControl1.AutoControlSize.MaxSize = new Size(600, 600);

textControl1.HExpanded += (sender, e) => Debug.WriteLine("Wider: " + textControl1.Width);
textControl1.HShrunk += (sender, e) => Debug.WriteLine("Narrower: " + textControl1.Width);
```

The code works as follows:

- [AutoExpand](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/autosize/autoexpand-property/llms-full.txt) and [AutoShrink](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/autosize/autoshrink-property/llms-full.txt) take an [AutoSizeDirection](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/autosizedirection/enumeration/llms-full.txt) value: `None`, `Vertical`, `Horizontal` or `Both`.
- [MaxSize](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/autosize/maxsize-property/llms-full.txt) limits the growth and [MinSize](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/autosize/minsize-property/llms-full.txt) the shrinking, in pixels. The control never shrinks below the space of one character, and its width and height can't exceed `short.MaxValue`.
- [HExpanded](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/textcontrol/hexpanded-event/llms-full.txt) and [HShrunk](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/textcontrol/hshrunk-event/llms-full.txt) occur after the control has changed its width, [VExpanded](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/textcontrol/vexpanded-event/llms-full.txt) and [VShrunk](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/textcontrol/vshrunk-event/llms-full.txt) after it has changed its height. Use them to move the controls below or beside it. `Size` needs `using System.Drawing;`.

The [AutoSize constructor](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/autosize/constructor/llms-full.txt) sets all four values at once for an assignment to `AutoControlSize`, and [ResetAutoControlSize](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/textcontrol/resetautocontrolsize-method/llms-full.txt) goes back to the default, a control that keeps its size.

### Next Steps

- [Loading and Saving Documents](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/document-editor/load-save/llms-full.txt): all ways to get a document into the editor and out again.
- [Selections and Caret Position](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/document-editor/editing-text/selections/llms-full.txt): work with the selection and the input position.
- [Events](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/document-editor/events/llms-full.txt): react to what happens in the editor.
- [Creating and Configuring Controls in Code](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/integration/controls-in-code/llms-full.txt): create a `TextControl` without the designer.

---

## Nearby

- **Previous:** [Document Editor](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/document-editor/llms-full.txt)
- **Next:** [Loading and Saving Documents](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/document-editor/load-save/llms-full.txt)