IElementHandler<TVirtualView,TPlatformView> Interface
Definition
Important
Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
Defines a strongly typed, platform-neutral element handler contract.
generic <typename TVirtualView, typename TPlatformView>
where TVirtualView : IElement where TPlatformView : classpublic interface class IElementHandler : Microsoft::Maui::IElementHandler
public interface IElementHandler<out TVirtualView,out TPlatformView> : Microsoft.Maui.IElementHandler where TVirtualView : IElement where TPlatformView : class
type IElementHandler<'VirtualView, 'PlatformView (requires 'VirtualView :> IElement and 'PlatformView : null)> = interface
interface IElementHandler
Public Interface IElementHandler(Of Out TVirtualView, Out TPlatformView)
Implements IElementHandler
Type Parameters
- TVirtualView
The cross-platform (virtual view) type this handler manages.
This type parameter is covariant. That is, you can use either the type you specified or any type that is more derived. For more information about covariance and contravariance, see Covariance and Contravariance in Generics.- TPlatformView
The native type this handler creates.
This type parameter is covariant. That is, you can use either the type you specified or any type that is more derived. For more information about covariance and contravariance, see Covariance and Contravariance in Generics.- Derived
- Implements
Examples
// In an external platform backend, with a native type MAUI knows nothing about:
public class MyWindowHandler : ElementHandler<IWindow, MyNativeWindow>
{
public MyWindowHandler() : base(WindowHandler.Mapper) { }
protected override MyNativeWindow CreatePlatformElement() => new MyNativeWindow();
}
// Consumers match it platform-neutrally. The typed members below throw once the handler is
// disconnected, so guard on the nullable IElementHandler.PlatformView first.
if (window.Handler is { PlatformView: not null } handler &&
handler is IElementHandler<IWindow, object> windowHandler)
{
IWindow virtualView = windowHandler.VirtualView;
object nativeWindow = windowHandler.PlatformView;
}
Remarks
The per-control handler interfaces such as IWindowHandler declare PlatformView using a using PlatformView = ... alias that resolves to a different native type for every target framework. That makes them impossible to implement from an external platform backend whose native types are not the ones .NET MAUI ships in the box: the compiler reports CS0738 (or CS9333 on the platform-neutral target framework) because the implementing member's return type does not match the alias exactly.
This interface has no such alias. Both type parameters are covariant, so a handler can be matched platform-neutrally by testing for IElementHandler<IWindow, object> regardless of which native type it actually creates.
ElementHandler<TVirtualView,TPlatformView> implements this interface, so any handler derived from it — in the box or in an external backend — satisfies the contract without writing any additional members.
Lifecycle. VirtualView and PlatformView are non-nullable here, matching the non-nullable properties on ElementHandler<TVirtualView,TPlatformView> that satisfy them — and those properties throw InvalidOperationException rather than returning null once the handler is disconnected. DisconnectHandler() clears the platform view before invoking the disconnect callback, so a handler is only guaranteed to have one between SetVirtualView(IElement) and DisconnectHandler(). The inherited VirtualView and PlatformView return null in exactly that state and never throw, so code that can run outside a connected window — teardown paths, weak-reference caches, diagnostics — should read those instead. Property and command mappers always run while the handler is connected and can use the typed members freely.
Properties
| Name | Description |
|---|---|
| MauiContext |
Gets the .NET MAUI context associated with the element. (Inherited from IElementHandler) |
| PlatformView |
Gets the native view associated with the handler. |
| VirtualView |
Gets the cross-platform virtual view associated with the handler. |
Methods
| Name | Description |
|---|---|
| DisconnectHandler() |
Disconnects the element handler from the element for clean up. (Inherited from IElementHandler) |
| Invoke(String, Object) |
Invokes the specified command on the element with the given arguments. (Inherited from IElementHandler) |
| SetMauiContext(IMauiContext) |
Sets the .NET MAUI context for the element handler. (Inherited from IElementHandler) |
| SetVirtualView(IElement) |
Sets the cross-platform virtual view associated with the handler. (Inherited from IElementHandler) |
| UpdateValue(String) |
Updates the value of the specified property on the handler. (Inherited from IElementHandler) |