Other Useful Events

This page documents the events on the WpfHtmlEditor control that are less commonly subscribed than the five covered on the Useful Events page. They are still important when an application needs to respond to clicks on specific HTML elements, react to file load / save, surface status or error notifications, or react to the completion of a spell-check pass.

Namespace: SpiceLogic.HtmlEditor.WPF
Assembly: SpiceLogic.HtmlEditor.WPF.dll

HtmlElementClicked

Occurs when the user clicks an HTML element of a registered type inside the editor in design mode. To get this event for a given element type, list that type in Options.FireHtmlElementClickEventFor before the editor is initialized; the editor then attaches the MSHTML hooks for you. The handler is told which element was clicked and the categorical element type.

Syntax

public event HtmlElementClickedEventHandler HtmlElementClicked;
public delegate void HtmlElementClickedEventHandler(object sender, HtmlElementClickedEventArgs e);

Public Event HtmlElementClicked As HtmlElementClickedEventHandler
Public Delegate Sub HtmlElementClickedEventHandler(sender As Object, e As HtmlElementClickedEventArgs)

Event Data (HtmlElementClickedEventArgs)

Remarks

This is a plain CLR event (not a RoutedEvent). The editor uses a CLR event here on purpose: a routed event raised on every click adds noticeable per-fire cost, and a CLR event lets the editor cheaply skip work when no handler is attached.

Example

using SpiceLogic.HtmlEditor.Abstractions;

MyEditor.Options.FireHtmlElementClickEventFor = HtmlElementTypes.Hyperlink;
MyEditor.HtmlElementClicked += (s, e) =>
{
    if (e.ElementType == HtmlElementTypes.Hyperlink)
    {
        string href = e.ClickedElement.getAttribute("href") as string;
        MessageBox.Show("Hyperlink clicked: " + href);
    }
};

Imports SpiceLogic.HtmlEditor.Abstractions

MyEditor.Options.FireHtmlElementClickEventFor = HtmlElementTypes.Hyperlink
MyEditor.HtmlElementClicked += Sub(s, e)
                                   If e.ElementType Is HtmlElementTypes.Hyperlink Then
                                       Dim href As String = TryCast(e.ClickedElement.getAttribute("href"), String)
                                       MessageBox.Show("Hyperlink clicked: " & href)
                                   End If

HtmlElementMouseDown

Occurs when the mouse button goes down on an HTML element of a registered type. Fires earlier than HtmlElementClicked and is useful for click-vs-drag distinction. List the element types in Options.FireHtmlElementMouseDownEventFor.

Syntax

public event HtmlElementClickedEventHandler HtmlElementMouseDown;

Public Event HtmlElementMouseDown As HtmlElementClickedEventHandler

Event Data

Same HtmlElementClickedEventArgs type used by HtmlElementClicked (ClickedElement, EventData, ElementType).

Remarks

This is a plain CLR event for the same reasons as HtmlElementClicked.

Example

using SpiceLogic.HtmlEditor.Abstractions;

MyEditor.Options.FireHtmlElementMouseDownEventFor = HtmlElementTypes.Image;
MyEditor.HtmlElementMouseDown += (s, e) =>
{
    if (e.ElementType == HtmlElementTypes.Image)
        _dragSrc = e.ClickedElement.getAttribute("src") as string;
};

Imports SpiceLogic.HtmlEditor.Abstractions

MyEditor.Options.FireHtmlElementMouseDownEventFor = HtmlElementTypes.Image
MyEditor.HtmlElementMouseDown += Sub(s, e)
                                     If e.ElementType Is HtmlElementTypes.Image Then _dragSrc = TryCast(e.ClickedElement.getAttribute("src"), String)

FileOpened

Raised after the editor successfully loads a file via Content.LoadBodyHtmlFromFile, LoadDocumentHtmlFromFile, or OpenFile. The event args carry the full path of the file that was loaded.

Syntax

public event FileEventHandler FileOpened;
public delegate void FileEventHandler(object sender, FileRoutedEventArgs e);

Public Event FileOpened As FileEventHandler
Public Delegate Sub FileEventHandler(sender As Object, e As FileRoutedEventArgs)

Event Data (FileRoutedEventArgs)

Remarks

This is a WPF RoutedEvent (Bubble strategy). Use it to update window titles, recent-files lists, or breadcrumb UI when a document is loaded.

Example

MyEditor.FileOpened += (s, e) =>
{
    this.Title = "Editing -- " + System.IO.Path.GetFileName(e.FilePath);
};

MyEditor.FileOpened += Sub(s, e) Me.Title = "Editing -- " & System.IO.Path.GetFileName(e.FilePath).ToString()

FileSaved

Raised after the editor successfully writes a file via Content.SaveBodyHtmlToFile, SaveDocumentHtmlToFile, or SaveEditorContentAsXml.

Syntax

public event FileEventHandler FileSaved;

Public Event FileSaved As FileEventHandler

Event Data (FileRoutedEventArgs)

Remarks

This is a WPF RoutedEvent (Bubble strategy). Pair it with FileOpened for a complete record of round-trip file activity.

Example

MyEditor.FileSaved += (s, e) =>
{
    statusBar.Text = "Saved to " + e.FilePath;
};

ErrorOccurred

Raised when the editor catches an exception in a non-fatal code path (for example a failure inside a deferred behavior repair, or a clipboard read that fails). Subscribe to surface internal errors in the host application's diagnostics or telemetry.

Syntax

public event ErrorOccurredEventHandler ErrorOccurred;
public delegate void ErrorOccurredEventHandler(object sender, ErrorEventArgs e);

Public Event ErrorOccurred As ErrorOccurredEventHandler
Public Delegate Sub ErrorOccurredEventHandler(sender As Object, e As ErrorEventArgs)

Event Data (ErrorEventArgs)

Remarks

This is a WPF RoutedEvent (Bubble strategy). The editor never bubbles fatal exceptions through this event -- those still propagate to the host. Use this event purely for observability.

Example

MyEditor.ErrorOccurred += (s, e) =>
{
    System.Diagnostics.Trace.TraceWarning(
        "Editor warning: " + e.Message + " " + (e.Exception?.ToString() ?? ""));
};

StatusChanged

Raised when the editor reports a status-bar-style message (for example progress strings during a long spell-check or a long paste-from-Word operation).

Syntax

public event StatusChangedEventHandler StatusChanged;
public delegate void StatusChangedEventHandler(object sender, StatusChangedEventArgs e);

Public Event StatusChanged As StatusChangedEventHandler
Public Delegate Sub StatusChangedEventHandler(sender As Object, e As StatusChangedEventArgs)

Event Data (StatusChangedEventArgs)

Remarks

This is a WPF RoutedEvent (Bubble strategy). Wire this into a status bar at the bottom of the host window for a built-in progress feel.

Example

MyEditor.StatusChanged += (s, e) =>
{
    statusBar.Text = e.StatusMessage;
};

SpellCheckCompleted

Raised after a full-document spell-check pass finishes (either because the user reached the end of the document or because they cancelled the dialog).

Syntax

public event SpellCheckCompletedEventHandler SpellCheckCompleted;
public delegate void SpellCheckCompletedEventHandler(object sender, SpellCheckCompletedEventArgs e);

Public Event SpellCheckCompleted As SpellCheckCompletedEventHandler
Public Delegate Sub SpellCheckCompletedEventHandler(sender As Object, e As SpellCheckCompletedEventArgs)

Event Data (SpellCheckCompletedEventArgs)

Remarks

This is a WPF RoutedEvent (Bubble strategy). The event fires only for the dialog-driven spell-check pass; the lightweight inline (red-underline) checker does not raise it.

Example

MyEditor.SpellCheckCompleted += (s, e) =>
{
    statusBar.Text = e.Canceled
        ? "Spell check cancelled"
        : "Spell check finished";
};

See also

For the five most-used events (HtmlChanged, Pasting, SelectionChanged, EditorModeChanged, ContextMenuShowing) see the Useful Events page in this section.