Overlay Panes

Overlay panes are user interface elements that are displayed in the upper-right corner of an IEditorView. While any content can be displayed, most content will typically be relatively small and can host interactive controls.

The Search Overlay Pane is an example of an overlay pane implementation.

Creating an Overlay Pane

Any control can be an overlay pane, but it must implement the IOverlayPane interface.

Inherit OverlayPaneBase

When possible, inheriting a custom pane from OverlayPaneBase will simplify the development effort. This abstract class has a default implementation for most members of the IOverlayPane interface, and individual members can be overridden, as needed, to extend functionality for the custom pane.

Special Consideration for Key Presses

Pressing keys like Tab and Shift+Tab, which normally move focus, may result in text being indented or outdented in the editor.

To prevent these keys (or any other key combination) from reaching the SyntaxEditor control, override the overlay pane control's OnKeyDown method and set KeyEventArgs.Handled = true.

Control Key Down Opacity

Overlay panes can become semi-transparent when the Ctrl key is held down, thereby allowing the end user to see the text behind it. The IOverlayPane.ControlKeyDownOpacity property specifies the opacity when the popup is semi-transparent.

The property value 0.25 is recommended for transparency. Set this property to 1.0 to prevent the pane from becoming semi-transparent.

Single or Multiple Views

The IOverlayPane.InstanceKind property specifies how many instances of the overlay pane are permitted across all views of the same SyntaxEditor control.

Set this property to Single to allow only one instance at a time for any view in the editor. Set this property to SinglePerView to allow one instance per view.

Showing and Activating an Overlay Pane

The IEditorView.OverlayPanes collection is used to manage which overlay panes are currently shown for a particular view.

An overlay pane will be displayed when it is added to the OverlayPanes collection. If an overlay pane of the same key is already displayed, the existing pane can typically be reused instead of creating a new one.

Most overlay panes are interactive and should be activated when they are shown. Each overlay pane can provide its own implementation for what it means to be activated, but this will typically involve setting keyboard focus to a specific element on the pane.

A good practice is to define a static Show method on the class that defines an overlay pane. The following code example demonstrates how a Show method could be defined on a CustomOverlayPane class.

/// <summary>
/// Shows the overlay pane within the specified <paramref name="view"/>.
/// </summary>
/// <param name="view">The editor view where the overlay pane will be displayed.</param>
public static void Show(IEditorView view) {
	if (view is null)
		throw new ArgumentNullException(nameof(view));

	// Get or create the custom overlay pane
	var overlayPanes = view.OverlayPanes;
	var customPane = overlayPanes[Key] as CustomOverlayPane;
	if (customPane is null) {
		// Close any existing overlay panes before adding a new one
		overlayPanes.Clear();

		// Add a new custom overlay pane
		customPane = new CustomOverlayPane(view);
		overlayPanes.Add(customPane);
	}

	// Activate the pane
	customPane.Activate();
}