Events

Your application learns what happens in the editor through events: the user types, moves the caret, loads a file, clicks an image, adds a comment. The Windows Forms TextControl raises more than 140 events of its own, next to the usual events of a Windows Forms control such as KeyDown or MouseWheel. Find out how to connect handlers, which events belong to which subject and which events two common tasks, an unsaved-changes flag and a position display, are built from.

The examples use Form1.cs with a TextControl named textControl1, as created in Create Your First Windows Forms Application.

How the Events Work

The events of the TextControl are ordinary .NET events. A handler receives two parameters: sender, the TextControl that raised the event, and an event argument with the details:

• Events such as Changed, InputPositionChanged or PageChanged pass a plain EventArgs. The handler reads what it needs from the control, for example the new InputPosition.
• Events about an object pass an argument class with that object, for example TrackedChangeEventArgs with the tracked change, or ImageEventArgs with the image.
• Some argument classes let the handler change what the editor does next, such as CannotTrackChangeEventArgs with Cancel and Handled, or HyphenateWordEventArgs with the position at which a word is divided.

The reference page of each event names its argument class and describes when the event occurs.

Connect an Event Handler

In the designer, select textControl1 and click the Events button, the lightning bolt, in the Properties window. Double-click an event, and Visual Studio creates a handler such as textControl1_Changed in Form1.cs and connects it in Form1.Designer.cs.

In code, connect the handler with +=, for example in the constructor after InitializeComponent, and disconnect it with -= when it is no longer needed:

public Form1()
{
    InitializeComponent();

    textControl1.Changed += textControl1_Changed;
    textControl1.DocumentLoaded += textControl1_DocumentLoaded;
}

Track Unsaved Changes

A word processor asks before it closes a document with unsaved changes. Changed occurs when the contents of the document have changed, DocumentLoaded when a new document has been loaded, and ContentsReset when all contents have been deleted and reset. A handler of Changed sets a modified flag, and the handlers of the other two, like your save code, clear it again. Architecture and Control Lifecycle shows where these events occur in the life of a form, and Load and Save Documents builds the complete save-changes prompt.

Show the Position of the Caret

InputPositionChanged occurs whenever the input position changes, by typing, clicking or code; Selections and Caret Position shows a handler that displays the page, line and column. For buttons of your own, CharFormatChanged and ParagraphFormatChanged tell when the formatting at the input position or of the selection has changed, for example to check a bold button when Selection.Bold is true. The status bar of TX Text Control shows such information without code; see Rulers and Status Bar.

Events by Subject

Many events come in families: an object is created, deleted, selected, clicked, moved or sized. The table lists the events by subject, with the page that describes them:

Handle Events in a Derived Control

For every event, the TextControl has a protected method that raises it, named On and the event name, such as OnChanged. A control derived from TextControl overrides the method to react before or after the handlers of the form. Call the base method, or the event is not raised:

using System;
using TXTextControl;

public class AuditTextControl : TXTextControl.TextControl
{
    public DateTime LastChange { get; private set; }

    protected override void OnChanged(EventArgs e)
    {
        LastChange = DateTime.Now;

        // Raise the Changed event for the connected handlers
        base.OnChanged(e);
    }
}

Next Steps

• Architecture and Control Lifecycle: when the control is ready and in which order it is set up.
• Selections and Caret Position: the input position that many events report.
• Track Changes and Comments: events of a review workflow in use.
• TextControl: the properties, methods and events of the editor at a glance.