Properties
The WpfHtmlEditor control exposes its host-app API primarily as properties on the control instance. These properties fall into a handful of buckets: content properties (such as DocumentHtml, BodyHtml, DocumentTitle) that round-trip the editor's HTML; appearance properties (font defaults, body colour, border) that style the document and the chrome; behavior properties (such as EditorMode, Language, ScrollBarSetting) that switch the control between modes or locales; options aggregates (Options and SpellCheckOptions) that hold the rest of the configurable knobs; and service properties (Content, Caret, Selection, etc.) that expose the underlying engines for programmatic editing.
Most properties shown here are CLR properties backed by either a WPF DependencyProperty (so they participate in XAML data-binding) or a plain backing field. Where a property is a dependency property, the Remarks section says so explicitly. Properties that read or write the live HTML document (for example BodyHtml or BodyStyle) round-trip through the underlying MSHTML document and require the editor to be in WysiwygDesign mode for the write to take effect on the design surface.
Throughout this reference, the variable MyEditor refers to a WpfHtmlEditor instance, either created in code-behind or declared in XAML and resolved through x:Name="MyEditor". Properties marked [Browsable(false)] are still public and fully usable from code; they are merely hidden from the WPF designer property grid.
BackgroundImagePath
Sets or returns the URL of the image painted as the document body background. The value is persisted into the body element's style attribute as the standard CSS background-image rule, so it survives a round-trip through DocumentHtml. Pass an empty string to remove the background image.
Syntax
public string BackgroundImagePath { get; set; }Property value
string — absolute URL or file path of the background image; an empty string means no background image.
Example
MyEditor.BackgroundImagePath = "file:///C:/skins/paper.jpg";BaseUrl
Sets or returns the base URL the document uses to resolve relative resource paths (images, stylesheets, hyperlinks). Setting this property before assigning HTML lets relative paths in that HTML resolve correctly even when the editor is hosted in a tool where the document's natural location is unknown.
Syntax
public string BaseUrl { get; set; }Property value
string — a file-system path or HTTP URL used as the base for relative resource references inside the document.
Remarks
When EditorMode is EditorModes.HtmlEdit the getter returns an empty string — the source-view text area has no notion of a base URL.
Example
// In a Window.Loaded handler:
MyEditor.BaseUrl = System.IO.Path.Combine(
AppDomain.CurrentDomain.BaseDirectory, "images");
MyEditor.BodyHtml = "<img src='banner.png' />"; // resolves to images\banner.pngBodyColor
Sets or returns the document body background colour. The value is persisted into the body element's bgcolor attribute and round-trips through DocumentHtml.
Syntax
public System.Windows.Media.Color BodyColor { get; set; }Property value
System.Windows.Media.Color — the colour used to fill the body background.
Example
MyEditor.BodyColor = System.Windows.Media.Colors.LightYellow;BodyCSSClassName
Sets or returns the value of the class attribute on the document's <body> tag. Combined with a stylesheet (DocumentCSSFilePath or HeaderStyleContent) this lets the host application skin the editor's document from CSS.
Syntax
public string BodyCSSClassName { get; set; }Property value
string — the CSS class name placed on the document body, or null to clear the attribute.
Example
MyEditor.DocumentCSSFilePath = "skins/site.css";
MyEditor.BodyCSSClassName = "article-body";BodyHtml
Sets or returns the HTML that lives between the <body> and </body> tags. This is the property to bind for the typical case where the host application stores user content but the HTML <head> is owned by the editor (or by the host's own CSS/JS).
Syntax
public string BodyHtml { get; set; }Property value
string — the inner HTML of the document body. Defaults to an empty string.
Remarks
Backed by the dependency property BodyHtmlProperty; binds two-way by default, with UpdateSourceTrigger.LostFocus as the default trigger.
Example
// Set from code-behind:
MyEditor.BodyHtml = "<p>Welcome</p>";
// Or bind in XAML:
// <wpf:WpfHtmlEditor x:Name="MyEditor" BodyHtml="{Binding Letter.Body, Mode=TwoWay}" />BodyStyle
Sets or returns the value of the style attribute on the document's <body> tag, allowing inline CSS to be applied or harvested as a single string.
Syntax
public string BodyStyle { get; set; }Property value
string — the CSS rules placed on the style attribute of the body element.
Example
MyEditor.BodyStyle = "margin:8px; background-color:#fefefe; font-family:Calibri";BodyStyleAsDOM
Returns the body element's style object as an MSHTML IHTMLStyle COM pointer, allowing the host app to read or set individual CSS properties without parsing the BodyStyle string.
Syntax
public IHTMLStyle BodyStyleAsDOM { get; }Property value
mshtml.IHTMLStyle — the live style DOM object for the body.
Example
var style = MyEditor.BodyStyleAsDOM;
if (style != null)
{
style.marginLeft = "12px";
style.marginRight = "12px";
}Caret
Returns the caret-manipulation service for the editor. Use this to query or move the caret programmatically (for example, after a custom toolbar action).
Syntax
public ICaretService Caret { get; set; }Property value
ICaretService — the caret service instance.
Example
// Move the caret to the end of the body, then insert a paragraph:
MyEditor.Caret.MoveCaretToEnd();
MyEditor.Content.InsertHtml("<p>Appended paragraph</p>");Charset
Sets or returns the document's charset (encoding) as declared in the document's <meta> tag.
Syntax
public string Charset { get; set; }Property value
string — for example "unicode", "utf-8", or "iso-8859-1". Defaults to "unicode".
Example
MyEditor.Charset = "utf-8";Content
Returns the content-manipulation service. This is the primary entry point for inserting HTML, loading and saving files, and walking the document's element tree.
Syntax
public IContentService Content { get; set; }Property value
IContentService — the content service. See the Content Service page for the full member list.
Example
// Insert a hyperlink at the caret position:
MyEditor.Content.InsertHtml("<a href='https://spicelogic.com'>SpiceLogic</a>");DefaultFontFamily
Sets or returns the default font family for the document body. The value is persisted into the body element's style attribute as the font-family rule, so it round-trips through DocumentHtml. The toolbar's font-name combo is kept in sync.
Syntax
public string DefaultFontFamily { get; set; }Property value
string — a font family name, e.g. "Calibri" or "Arial".
Example
MyEditor.DefaultFontFamily = "Calibri";DefaultFontSizeInPt
Sets or returns the default font size for the document body in points. Numeric values without a unit are interpreted as pixels and converted to points (15 → 11pt). Pass values with the explicit pt suffix to set the size in points directly.
Syntax
public string DefaultFontSizeInPt { get; set; }Property value
string — the body font size in points, e.g. "11pt".
Example
MyEditor.DefaultFontSizeInPt = "14pt";DefaultForeColor
Sets or returns the default foreground (text) colour for the document body. The value is persisted into the body style attribute as color and round-trips through DocumentHtml.
Syntax
public System.Windows.Media.Color DefaultForeColor { get; set; }Property value
System.Windows.Media.Color — defaults to Colors.Black.
Example
MyEditor.DefaultForeColor = System.Windows.Media.Color.FromRgb(0x22, 0x22, 0x22);Dialog
Returns the dialog service used by the built-in toolbar to show the editor's modal dialogs (Insert Image, Find & Replace, etc.). Useful for invoking the editor's native dialogs from custom toolbar items.
Syntax
public IDialogService Dialog { get; set; }Property value
IDialogService — the dialog service.
Example
// Open the built-in Insert Image dialog from a custom button:
BtnInsertImage.Click += (s, e) => MyEditor.Dialog.ShowInsertImageDialog();DocumentCSSFilePath
Sets or returns the URL of an external CSS file linked from the document head. Setting this property writes (or updates) a <link rel="stylesheet"> element identified by Options.DefaultCssFileLinkNameAttribute.
Syntax
public string DocumentCSSFilePath { get; set; }Property value
string — absolute or relative URL of the stylesheet; an empty string removes the link.
Example
MyEditor.DocumentCSSFilePath = "file:///C:/skins/article.css";DocumentHtml
Sets or returns the entire HTML document including the <html>, <head>, and <body> markup. Use this in preference to BodyHtml when the host application owns the full document (custom doctype, charset, header style block).
Syntax
public string DocumentHtml { get; set; }Property value
string — the full HTML document as a single string.
Remarks
Backed by the dependency property DocumentHtmlProperty; binds two-way by default, with UpdateSourceTrigger.LostFocus as the default trigger.
Example
// Save the full document to disk:
System.IO.File.WriteAllText("page.html", MyEditor.DocumentHtml);
// Load a document from disk back into the editor:
MyEditor.DocumentHtml = System.IO.File.ReadAllText("page.html");DocumentTitle
Sets or returns the value of the <title> element in the document head.
Syntax
public string DocumentTitle { get; set; }Property value
string — the document title; defaults to empty.
Remarks
Backed by the dependency property DocumentTitleProperty; binds two-way by default.
Example
MyEditor.DocumentTitle = "Customer Welcome Letter";
this.Title = MyEditor.DocumentTitle; // mirror to the Window captionEditor
Returns the lower-level editor service that owns scrolling, focus, and design-mode toggling.
Syntax
public IEditorServiceBase Editor { get; set; }Property value
IEditorServiceBase — the editor service.
Example
// Wire a host-app Undo button to the editor:
BtnUndo.Click += (s, e) => MyEditor.Editor.Undo();EditorBorderColor
Sets or returns the colour of the border drawn around the editor surface. Set the value to default(Color) to fall back to the theme default at design time.
Syntax
public System.Windows.Media.Color EditorBorderColor { get; set; }Property value
System.Windows.Media.Color — editor border colour.
Example
MyEditor.EditorBorderColor = System.Windows.Media.Colors.SteelBlue;EditorBorderWidth
Sets or returns the thickness of the editor border. Set the value to new Thickness(0) to hide the border entirely.
Syntax
public System.Windows.Thickness EditorBorderWidth { get; set; }Property value
System.Windows.Thickness — editor border thickness.
Example
// Hide the border entirely for an embedded edit-in-place look:
MyEditor.EditorBorderWidth = new System.Windows.Thickness(0);EditorContextMenuStrip
Sets or returns the WPF ContextMenu used when the user right-clicks inside the editing surface. Replaces the built-in context menu.
Syntax
public System.Windows.Controls.ContextMenu EditorContextMenuStrip { get; set; }Property value
ContextMenu — the custom context menu, or null to keep the default.
Example
var menu = new System.Windows.Controls.ContextMenu();
var item = new System.Windows.Controls.MenuItem { Header = "Insert Customer Name" };
item.Click += (s, e) => MyEditor.Content.InsertHtml("{{customer}}");
menu.Items.Add(item);
MyEditor.EditorContextMenuStrip = menu;EditorMode
Sets or returns the editor's current view: design (WYSIWYG), HTML source, or preview. Changing the mode at runtime triggers a synchronous re-layout of the editor chrome.
Syntax
public EditorModes EditorMode { get; set; }Property value
EditorModes — one of WysiwygDesign (default), HtmlEdit, or Preview.
Remarks
Backed by the dependency property EditorModeProperty.
Example
// Toggle to source mode so the user can hand-edit the HTML:
MyEditor.EditorMode = EditorModes.HtmlEdit;Focused
Returns whether the editor (or any of its inner controls) currently has the keyboard focus.
Syntax
public bool Focused { get; }Property value
bool — true if the editor has input focus; otherwise false.
Example
// Only auto-save while the user is typing into the editor:
if (MyEditor.Focused) AutoSave(MyEditor.DocumentHtml);Formatting
Returns the formatting service used to apply bold, italic, lists, alignment, and similar text formatting to the current selection.
Syntax
public IFormattingService Formatting { get; set; }Property value
IFormattingService — the formatting service.
Example
// Bold the current selection from a custom toolbar button:
BtnBold.Click += (s, e) => MyEditor.Formatting.ToggleBold();HeaderStyleContent
Sets or returns the CSS rules inside the <style> block identified by HeaderStyleContentElementID in the document head. Use this to inject document-scoped CSS without rewriting the whole document head.
Syntax
public string HeaderStyleContent { get; set; }Property value
string — the CSS rules to place inside the named <style> element.
Example
MyEditor.HeaderStyleContentElementID = "page_style";
MyEditor.HeaderStyleContent = "p { line-height: 1.5; } a { color: #06c; }";HeaderStyleContentElementID
Sets or returns the id attribute of the head <style> element controlled by HeaderStyleContent. Changing this id at runtime removes the previous <style id="..."> element from the document, so the document never accumulates stale style blocks.
Syntax
public string HeaderStyleContentElementID { get; set; }Property value
string — defaults to "page_style".
Example
MyEditor.HeaderStyleContentElementID = "reader-theme";HorizontalScrollPosition
Returns the editor's current horizontal scroll position in pixels. Always returns 0 when the editor is in HTML-source mode.
Syntax
public int HorizontalScrollPosition { get; }Property value
int — horizontal scroll offset in pixels.
Example
int x = MyEditor.HorizontalScrollPosition;
if (x > 0) System.Diagnostics.Debug.WriteLine("Document is wider than the viewport.");KeyBindings
Returns the manager used to bind, rebind, override, or disable keyboard shortcuts on the editor. Parallel to ToolbarItemOverrider — where the overrider intercepts toolbar clicks, this manager intercepts keystrokes.
Syntax
public KeyBindingsManager KeyBindings { get; }Property value
KeyBindingsManager — the customer-facing key bindings manager.
Example
// Redirect Ctrl+S to a host-app save handler:
MyEditor.KeyBindings.Override(EditorActionId.Save, () => SaveDocument());
// Disable the built-in Ctrl+P print shortcut:
MyEditor.KeyBindings.Disable(EditorActionId.Print);Language
Sets or returns the UI language of the editor control. Changing this property re-localises toolbar tooltips, dialog labels, context-menu items, and message strings. When SpellCheckOptions.SpellCheckLanguage is set to SameAsEditorLanguage (the default) the spell-checker language follows this property automatically.
Syntax
public EditorLanguage Language { get; set; }Property value
EditorLanguage — defaults to EditorLanguage.EnglishUs.
Remarks
Backed by the dependency property LanguageProperty.
Example
MyEditor.Language = EditorLanguage.German;LicenseKey
Sets or returns the license key applied to all instances of WpfHtmlEditor created by the host application. Assign this once at application startup (typically in App.xaml.cs) before any editor instance is constructed.
Syntax
public static string LicenseKey { get; set; }Property value
string — the license-key string.
Example
// In App.xaml.cs OnStartup, before any Window is shown:
WpfHtmlEditor.LicenseKey = "your-license-key-here";Options
Returns (or replaces) the aggregate option object holding behavior flags such as EnterKeyResponse, AutoDetectWordPaste, AutoResizeLargeImages, MaxPastedImageWidth, EnableTableCellMerge, ConvertAbsoluteUrlsToRelativeUrls, UrlEncodeHyperlinkHRefs, DefaultHtmlType, ShowZeroBorderGuideline, FooterTagNavigatorTextColor, and FooterTagNavigatorFontInfo.
Syntax
public UserOption Options { get; set; }Property value
UserOption — the editor's user-options bag. See the UserOption reference for the full list of sub-properties.
Example
MyEditor.Options.AutoDetectWordPaste = true;
MyEditor.Options.MaxPastedImageWidth = 720;
MyEditor.Options.EnterKeyResponse = EnterKeyResponses.NewParagraph;ProductVersion
Returns the assembly version of the control. Useful for logging, telemetry, or showing a version banner in the host application's About dialog.
Syntax
public string ProductVersion { get; }Property value
string — the product version string, e.g. "9.0.14.0".
Example
LblAbout.Content = $"SpiceLogic HTML Editor v{MyEditor.ProductVersion}";ScrollBarSetting
Sets or returns the visibility of the editor's scroll bars. In EditorModes.HtmlEdit the property is fixed at ScrollBarVisibility.Auto and writes are ignored.
Syntax
public ScrollBarVisibility ScrollBarSetting { get; set; }Property value
SpiceLogic.HtmlEditor.Abstractions.ScrollBarVisibility — one of Default, Visible, Hidden, or Auto.
Example
MyEditor.ScrollBarSetting = ScrollBarVisibility.Auto;ScrollRectangle
Returns the rectangle representing the editor's scrollable region in pixels. Useful when implementing custom scroll-driven behaviors such as floating UI on top of the editor.
Syntax
public System.Drawing.Rectangle ScrollRectangle { get; }Property value
System.Drawing.Rectangle — the scrollable region.
Example
var rect = MyEditor.ScrollRectangle;
System.Diagnostics.Debug.WriteLine($"Document body is {rect.Width} x {rect.Height} pixels");Selection
Returns the selection service used to read, set, and manipulate the current text selection inside the editor.
Syntax
public ISelectionService Selection { get; set; }Property value
ISelectionService — the selection service.
Example
string selected = MyEditor.Selection.GetSelectedHtml();
if (!string.IsNullOrEmpty(selected)) System.Windows.MessageBox.Show(selected);SpellCheckOptions
Returns (or replaces) the spell-checker option object. The object holds the dictionary language, the dictionary-location strategy, and toggle flags such as inline-on-type and ignore-uppercase.
Syntax
public SpellCheckerOption SpellCheckOptions { get; set; }Property value
SpellCheckerOption — the spell-checker options.
Example
MyEditor.SpellCheckOptions.SpellCheckLanguage = SpellCheckLanguages.SameAsEditorLanguage;
MyEditor.SpellCheckOptions.IgnoreDigits = true;StateQuery
Returns the state-query service used to ask the editor questions about the current selection (is bold on? is the caret in a list?). Toolbar synchronisation and custom UI overlays use this service.
Syntax
public IStateQueryService StateQuery { get; set; }Property value
IStateQueryService — the state-query service.
Example
// Sync a host toolbar button's IsChecked state with the editor:
BtnBold.IsChecked = MyEditor.StateQuery.IsBold();Toolbar1
Returns the first (upper) factory toolbar instance. Use this to add, remove, or reorder toolbar buttons programmatically.
Syntax
public FirstToolbar Toolbar1 { get; }Property value
FirstToolbar — the first toolbar.
Example
// Hide the entire top toolbar for a chrome-less embedded view:
MyEditor.Toolbar1.Visibility = System.Windows.Visibility.Collapsed;Toolbar2
Returns the second (lower) factory toolbar instance.
Syntax
public SecondToolbar Toolbar2 { get; }Property value
SecondToolbar — the second toolbar.
Example
MyEditor.Toolbar2.Visibility = System.Windows.Visibility.Collapsed;ToolbarFooter
Returns the footer toolbar (tag navigator and mode-switch buttons).
Syntax
public FooterToolbar ToolbarFooter { get; }Property value
FooterToolbar — the footer toolbar.
Example
// Force-hide the footer for a kiosk-mode window:
MyEditor.ToolbarFooter.Visibility = System.Windows.Visibility.Collapsed;Toolbar1Items
Returns the live ItemCollection of additional items shown on Toolbar1. Add WPF controls (Button, Separator, custom UserControl) to this collection in XAML or code to extend the toolbar.
Syntax
public ItemCollection Toolbar1Items { get; }Property value
ItemCollection — additional Toolbar1 items.
Example
var btn = new System.Windows.Controls.Button { Content = "Insert Date" };
btn.Click += (s, e) => MyEditor.Content.InsertHtml(DateTime.Today.ToShortDateString());
MyEditor.Toolbar1Items.Add(btn);Toolbar1ItemsSource
Sets or returns an enumerable bound as ItemsSource for the Toolbar1 extension area. Use this when you want to drive the toolbar from a view-model.
Syntax
public IEnumerable Toolbar1ItemsSource { get; set; }Property value
IEnumerable — the items source.
Remarks
Backed by the dependency property Toolbar1ItemsSourceProperty.
Example
// In XAML:
// <wpf:WpfHtmlEditor Toolbar1ItemsSource="{Binding ExtraToolbarItems}" />
// Or in code:
MyEditor.Toolbar1ItemsSource = ViewModel.ExtraToolbarItems;Toolbar2Items
Returns the live ItemCollection of additional items shown on Toolbar2.
Syntax
public ItemCollection Toolbar2Items { get; }Property value
ItemCollection — additional Toolbar2 items.
Example
MyEditor.Toolbar2Items.Add(new System.Windows.Controls.Separator());
MyEditor.Toolbar2Items.Add(new System.Windows.Controls.Button { Content = "Custom" });Toolbar2ItemsSource
Sets or returns an enumerable bound as ItemsSource for the Toolbar2 extension area.
Syntax
public IEnumerable Toolbar2ItemsSource { get; set; }Property value
IEnumerable — the items source.
Remarks
Backed by the dependency property Toolbar2ItemsSourceProperty.
Example
MyEditor.Toolbar2ItemsSource = ViewModel.SecondaryToolbarItems;ToolbarContextMenuStrip
Sets or returns the WPF ContextMenu used when the user right-clicks on the toolbar strips. To set a context menu for the editing surface, use EditorContextMenuStrip instead.
Syntax
public System.Windows.Controls.ContextMenu ToolbarContextMenuStrip { get; set; }Property value
ContextMenu — toolbar context menu, or null to clear.
Example
var menu = new System.Windows.Controls.ContextMenu();
var item = new System.Windows.Controls.MenuItem { Header = "Hide Toolbar" };
item.Click += (s, e) => MyEditor.Toolbar1.Visibility = System.Windows.Visibility.Collapsed;
menu.Items.Add(item);
MyEditor.ToolbarContextMenuStrip = menu;ToolbarItemOverrider
Returns the helper used to override the click behavior of any built-in factory toolbar button (Save, Open, Bold, Insert Image, etc.). Each built-in button exposes a corresponding override method; subscribe to redirect clicks to a host-app handler.
Syntax
public ToolbarItemOverrideHelper ToolbarItemOverrider { get; }Property value
ToolbarItemOverrideHelper — the override helper.
Example
// Replace the built-in Save handler with a host-app implementation:
MyEditor.ToolbarItemOverrider.OnSaveButtonClick += (s, e) =>
{
e.Handled = true;
MyDocumentRepository.Save(MyEditor.DocumentHtml);
};VerticalScrollPosition
Returns the editor's current vertical scroll position in pixels. Always returns 0 when the editor is in HTML-source mode.
Syntax
public int VerticalScrollPosition { get; }Property value
int — vertical scroll offset in pixels.
Example
int y = MyEditor.VerticalScrollPosition;
LblStatus.Content = $"Scrolled {y}px from the top";WordWrap
Sets or returns whether long lines automatically wrap at the editor's right margin. When false, whitespace collapses as for white-space: nowrap and lines extend horizontally until a manual line break.
Syntax
public bool WordWrap { get; set; }Property value
bool — true (the default) to word-wrap lines; false to suppress wrapping.
Example
// Long lines should scroll horizontally instead of wrapping:
MyEditor.WordWrap = false;