Skip to main content

Top level

The TopLevel acts as the visual root, and is the base class for all top level controls, for example Window. It handles scheduling layout, styling and rendering as well as keeping track of the client size. Most services are accessed through the TopLevel.

Getting the TopLevel​

Here are two common ways to access a TopLevel instance.

Using TopLevel.GetTopLevel​

You can use the static GetTopLevel method of the TopLevel class to get the top-level control that contains the current control.

var topLevel = TopLevel.GetTopLevel(control);
// Here you can reference various services like Clipboard or StorageProvider from topLevel instance.

This method can be helpful if you're working within a user control or a lower-level component and need access to the TopLevel services.

note

If TopLevel.GetTopLevel returns null, likely control is not yet attached to the root. To ensure control is attached, you should handle Control.Loaded and Control.Unloaded events and keep track of current top level from these events.

Using the Window class​

Since the Window class inherits from TopLevel, you can directly access services from an instance of Window:

var topLevel = window;

This method is typically used when you're already working within the context of a window, such as in a ViewModel or an event handler within the Window class.

Common properties​

ActualTransparencyLevel​

Gets the achieved WindowTransparencyLevel that the platform was able to provide.

WindowTransparencyLevel ActualTransparencyLevel { get; }

ClientSize​

Gets the client size of the window.

Size ClientSize { get; }

Clipboard​

Gets the platform's Clipboard implementation.

IClipboard? Clipboard { get; }

FocusManager​

Gets focus manager of the root.

IFocusManager? FocusManager { get; }

FrameSize​

Gets the total size of the top level including system frame if presented.

Size? FrameSize { get; }

InsetsManager​

Gets the platform's InsetsManager implementation.

IInsetsManager? InsetsManager { get; }

PlatformSettings​

Represents a contract for accessing top-level platform-specific settings.

IPlatformSettings? PlatformSettings { get; }

RendererDiagnostics​

Gets a value indicating whether the renderer should draw specific diagnostics.

RendererDiagnostics RendererDiagnostics { get; }

RenderScaling​

Gets the scaling factor to use in rendering.

double RenderScaling { get; }

Screens​

Gets the Screens instance that provides information about connected monitors, including resolution, working area, scaling, and orientation.

Screens Screens { get; }

Use Screens to query the primary display, enumerate all displays, or find the screen containing a specific window or point. See Working with screens for usage examples.

RequestedThemeVariant​

Gets or sets the UI theme variant that is used by the control (and its child elements) for resource determination. The UI theme you specify with ThemeVariant can override the app-level ThemeVariant.

ThemeVariant? RequestedThemeVariant { get; set; }

StorageProvider​

File System storage service used for file pickers and bookmarks.

IStorageProvider StorageProvider { get; }

TransparencyBackgroundFallback​

Gets or sets the IBrush that transparency will blend with when transparency is not supported. By default this is a solid white brush.

IBrush TransparencyBackgroundFallback { get; set; }

TransparencyLevelHint​

Gets or sets the WindowTransparencyLevel that the TopLevel should use when possible. Accepts multiple values which are applied in a fallback order. For instance, with "Mica, Blur" Mica will be applied only on platforms where it is possible, and Blur will be used on the rest of them. Default value is an empty array or "None".

IReadOnlyList<WindowTransparencyLevel> TransparencyLevelHint { get; set; }

Common events​

BackRequested​

Occurs when physical Back Button is pressed or a back navigation has been requested.

event EventHandler<RoutedEventArgs> BackRequested { add; remove; }

Closed​

Fired when the window is closed.

event EventHandler Closed;

Opened​

Fired when the window is opened.

event EventHandler Opened;

ScalingChanged​

Occurs when the TopLevel's scaling changes.

event EventHandler ScalingChanged;

Common methods​

GetTopLevel​

Gets the TopLevel for which the given Visual is hosted in.

Parameters​

control The visual to query its TopLevel

static TopLevel? GetTopLevel(Visual? visual)

RequestAnimationFrame​

Enqueues a callback to be called on the next animation tick. The callback runs on the UI thread, synchronized with Avalonia's rendering cycle. Each call schedules a single invocation. To create a continuous animation loop, call RequestAnimationFrame again from within the callback.

void RequestAnimationFrame(Action<TimeSpan> action)

Parameters​

action A callback that receives a TimeSpan representing the elapsed time since the animation system started. Use this value to calculate frame-independent animation progress.

Example: continuous animation loop​

var topLevel = TopLevel.GetTopLevel(this);

topLevel.RequestAnimationFrame(OnAnimationFrame);

private void OnAnimationFrame(TimeSpan elapsed)
{
    // Update your visual state based on elapsed time
    _angle = elapsed.TotalSeconds * 90; // 90 degrees per second
    InvalidateVisual();

    // Schedule the next frame to keep the loop running
    TopLevel.GetTopLevel(this)?.RequestAnimationFrame(OnAnimationFrame);
}

This is the Avalonia equivalent of WPF's CompositionTarget.Rendering. For render-thread callbacks that do not block the UI thread, see CompositionCustomVisualHandler.

RequestPlatformInhibition​

Requests a PlatformInhibitionType to be inhibited. The behavior remains inhibited until the return value is disposed. The available set of PlatformInhibitionTypes depends on the platform. If a behavior is inhibited on a platform where this type is not supported the request will have no effect.

async Task<IDisposable> RequestPlatformInhibition(PlatformInhibitionType type, string reason)

TryGetPlatformHandle​

Tries to get the platform handle for the TopLevel-derived control.

IPlatformHandle? TryGetPlatformHandle()

See also​

On this page