|
| 1 | +--- |
| 2 | +title: "Overlay Panes" |
| 3 | +page-title: "Overlay Panes - SyntaxEditor Editor View Features" |
| 4 | +order: 17 |
| 5 | +--- |
| 6 | +# Overlay Panes |
| 7 | + |
| 8 | +Overlay panes are user interface elements that are displayed in the upper-right corner of an [IEditorView](xref:@ActiproUIRoot.Controls.SyntaxEditor.IEditorView). While any content can be displayed, most content will typically be relatively small and can host interactive controls. |
| 9 | + |
| 10 | +The [Search Overlay Pane](../searching/search-overlay-pane.md) is an example of an overlay pane implementation. |
| 11 | + |
| 12 | +## Creating an Overlay Pane |
| 13 | + |
| 14 | +Any control can be an overlay pane, but it must implement the [IOverlayPane](xref:@ActiproUIRoot.Controls.SyntaxEditor.IOverlayPane) interface. |
| 15 | + |
| 16 | +@if (wpf winforms) { |
| 17 | + |
| 18 | +### Inherit OverlayPaneBase |
| 19 | + |
| 20 | +When possible, inheriting a custom pane from [OverlayPaneBase](xref:@ActiproUIRoot.Controls.SyntaxEditor.Implementation.OverlayPaneBase) will simplify the development effort. This abstract class has a default implementation for most members of the [IOverlayPane](xref:@ActiproUIRoot.Controls.SyntaxEditor.IOverlayPane) interface, and individual members can be overridden, as needed, to extend functionality for the custom pane. |
| 21 | + |
| 22 | +} |
| 23 | + |
| 24 | +@if (wpf) { |
| 25 | + |
| 26 | +### Special Consideration for Key Presses |
| 27 | + |
| 28 | +> [!WARNING] |
| 29 | +> When typing in an overlay pane, key presses are still sent to the ancestor [SyntaxEditor](xref:@ActiproUIRoot.Controls.SyntaxEditor.SyntaxEditor) control and could result in edit actions being performed. |
| 30 | +
|
| 31 | +Pressing keys like <kbd>Tab</kbd> and <kbd>Shift</kbd>+<kbd>Tab</kbd>, which normally move focus, may result in text being indented or outdented in the editor. |
| 32 | + |
| 33 | +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`. |
| 34 | + |
| 35 | +> [!TIP] |
| 36 | +> The [OverlayPaneBase](xref:@ActiproUIRoot.Controls.SyntaxEditor.Implementation.OverlayPaneBase) control has built-in support for handling key presses. By default, <kbd>Tab</kbd> and <kbd>Shift</kbd>+<kbd>Tab</kbd> will be handled and used to move keyboard focus. Override the [OnMoveFocus](xref:@ActiproUIRoot.Controls.SyntaxEditor.Implementation.OverlayPaneBase.OnMoveFocus*) method to customize which elements receive focus. Set [AllowTabKeyToMoveFocus](xref:@ActiproUIRoot.Controls.SyntaxEditor.Implementation.OverlayPaneBase.AllowTabKeyToMoveFocus) = `false` to disable the automatic handling of these keys. |
| 37 | +> |
| 38 | +>To customize the handling of additional keys, override the [ProcessKeyDown](xref:@ActiproUIRoot.Controls.SyntaxEditor.Implementation.OverlayPaneBase.ProcessKeyDown*) method and return `true` for any keys that were handled by the overlay pane. |
| 39 | +
|
| 40 | +} |
| 41 | + |
| 42 | +@if (winforms) { |
| 43 | + |
| 44 | +> [!TIP] |
| 45 | +> The [OverlayPaneBase](xref:@ActiproUIRoot.Controls.SyntaxEditor.OverlayPaneBase) control has built-in support for handling key presses. By default, <kbd>Esc</kbd> will be handled and used to close the overlay pane but can be disabled by setting [AllowEscKeyToClose](xref:@ActiproUIRoot.Controls.SyntaxEditor.OverlayPaneBase.AllowEscKeyToClose) = `false`. |
| 46 | +> |
| 47 | +>To customize the handling of additional keys, override the [ProcessKeyDown](xref:@ActiproUIRoot.Controls.SyntaxEditor.OverlayPaneBase.ProcessKeyDown) method and return `true` for any keys that were handled by the overlay pane. For example, the <kbd>Tab</kbd> and <kbd>Shift</kbd>+<kbd>Tab</kbd> keys can optionally be handled to keep keyboard focus within the pane. |
| 48 | +
|
| 49 | +} |
| 50 | + |
| 51 | +## Control Key Down Opacity |
| 52 | + |
| 53 | +Overlay panes can become semi-transparent when the <kbd>Ctrl</kbd> key is held down, thereby allowing the end user to see the text behind it. The [IOverlayPane](xref:@ActiproUIRoot.Controls.SyntaxEditor.IOverlayPane).[ControlKeyDownOpacity](xref:@ActiproUIRoot.Controls.SyntaxEditor.IOverlayPane.ControlKeyDownOpacity) property specifies the opacity when the popup is semi-transparent. |
| 54 | + |
| 55 | +The property value `0.25` is recommended for transparency. Set this property to `1.0` to prevent the pane from becoming semi-transparent. |
| 56 | + |
| 57 | +## Single or Multiple Views |
| 58 | + |
| 59 | +The [IOverlayPane](xref:@ActiproUIRoot.Controls.SyntaxEditor.IOverlayPane).[InstanceKind](xref:@ActiproUIRoot.Controls.SyntaxEditor.IOverlayPane.InstanceKind) property specifies how many instances of the overlay pane are permitted across all views of the same `SyntaxEditor` control. |
| 60 | + |
| 61 | +Set this property to [Single](xref:@ActiproUIRoot.Controls.SyntaxEditor.OverlayPaneInstanceKind.Single) to allow only one instance at a time for any view in the editor. Set this property to [SinglePerView](xref:@ActiproUIRoot.Controls.SyntaxEditor.OverlayPaneInstanceKind.SinglePerView) to allow one instance per view. |
| 62 | + |
| 63 | +## Showing and Activating an Overlay Pane |
| 64 | + |
| 65 | +The [IEditorView](xref:@ActiproUIRoot.Controls.SyntaxEditor.IEditorView).[OverlayPanes](xref:@ActiproUIRoot.Controls.SyntaxEditor.IEditorView.OverlayPanes) collection is used to manage which overlay panes are currently shown for a particular view. |
| 66 | + |
| 67 | +An overlay pane will be displayed when it is added to the [OverlayPanes](xref:@ActiproUIRoot.Controls.SyntaxEditor.IEditorView.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. |
| 68 | + |
| 69 | +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. |
| 70 | + |
| 71 | +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. |
| 72 | + |
| 73 | + |
| 74 | +```csharp |
| 75 | +/// <summary> |
| 76 | +/// Shows the overlay pane within the specified <paramref name="view"/>. |
| 77 | +/// </summary> |
| 78 | +/// <param name="view">The editor view where the overlay pane will be displayed.</param> |
| 79 | +public static void Show(IEditorView view) { |
| 80 | + if (view is null) |
| 81 | + throw new ArgumentNullException(nameof(view)); |
| 82 | + |
| 83 | + // Get or create the custom overlay pane |
| 84 | + var overlayPanes = view.OverlayPanes; |
| 85 | + var customPane = overlayPanes[Key] as CustomOverlayPane; |
| 86 | + if (customPane is null) { |
| 87 | + // Close any existing overlay panes before adding a new one |
| 88 | + overlayPanes.Clear(); |
| 89 | + |
| 90 | + // Add a new custom overlay pane |
| 91 | + customPane = new CustomOverlayPane(view); |
| 92 | + overlayPanes.Add(customPane); |
| 93 | + } |
| 94 | + |
| 95 | + // Activate the pane |
| 96 | + customPane.Activate(); |
| 97 | +} |
| 98 | +``` |
| 99 | + |
| 100 | +> [!TIP] |
| 101 | +> Use the [SyntaxEditor.ActiveView](xref:@ActiproUIRoot.Controls.SyntaxEditor.SyntaxEditor.ActiveView) property to determine which editor view is currently active. |
0 commit comments