ToastOcclusionManagerPreview.SetToastWindowMargin(WindowId, Double) Method
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.
Requests that the OS display app notifications with the specified vertical offset, in view pixels, in order to avoid the notification occluding content in the specified window.
Important
The ToastOcclusionManagerPreview.SetToastWindowMargin API is part of a Limited Access Feature (see LimitedAccessFeatures class). For more information or to request an unlock token, please use the LAF Access Token Request Form.
public:
static void SetToastWindowMargin(WindowId appWindowId, double margin); static void SetToastWindowMargin(WindowId const& appWindowId, double const& margin);public static void SetToastWindowMargin(WindowId appWindowId, double margin);function setToastWindowMargin(appWindowId, margin)Public Shared Sub SetToastWindowMargin (appWindowId As WindowId, margin As Double)Parameters
- appWindowId
- WindowId
The WindowId of the window for associated with the notification offset request. For the offset to be applied, the specified window must be maximized, in focus, on the primary screen, and the onscreen keyboard must not be visible.
- margin
-
Double
double
The vertical offset with which app notifications are displayed, in view pixels. The current maximum value for the margin is 180 pixels. Requests for margins greater than 180 pixels will succeed, but will be clamped to 180 pixels. If a negative value is specified, it is clamped to 0.
Remarks
This API is being released as a preview to enable testing of the feature by enterprise customers. This API is likely to be removed and/or modified in a future release. Before using the API, apps should call LimitedAccessFeatures.TryUnlockFeature, passing in the feature ID and app token provided by Microsoft, to verify that the app is authorized to use the API. Calls by unauthorized apps will have no effect.
The following example code demonstrates how to check for the availability of SetToastWindowMargin for the calling app and, if it is available, call the API to request that app notifications be shifted up by 90 pixels. These calls should be made during app launch.
// App.xaml.cpp
static Platform::String^ FeatureName = L"com.microsoft.windows.ui.notifications.preview.toastOcclusionManagerPreview";
static Platform::String^ ApiToken = L"[API token]";
static Platform::String^ ApiAttestation = L"[Package family name] has registered their use of com.microsoft.windows.ui.notifications.preview.toastOcclusionManagerPreview with Microsoft and agrees to the terms of use.";
App::App()
{
InitializeComponent();
Suspending += ref new SuspendingEventHandler(this, &App::OnSuspending);
m_isToastOcclusionManagerPreviewAvailable = DetectToastOcclusionManagerPreview();
}
bool App::DetectToastOcclusionManagerPreview()
{
LimitedAccessFeatureRequestResult^ result = LimitedAccessFeatures::TryUnlockFeature(FeatureName, ApiToken, ApiAttestation);
switch (result->Status)
{
case LimitedAccessFeatureStatus::Available:
case LimitedAccessFeatureStatus::AvailableWithoutToken:
return true;
}
return false;
}
void App::OnLaunched(Windows::ApplicationModel::Activation::LaunchActivatedEventArgs^ e)
{
...
// Request for toast window to be shifted up 90 pixels
// Toasts will only be shifted up if the window is maximized,
// on the primary screen and the software keyboard isn't present.
if (!m_isRegistered && m_isToastOcclusionManagerPreviewAvailable)
{
HWND window;
IInspectable* inspectable = reinterpret_cast<IInspectable*>(CoreWindow::GetForCurrentThread());
winrt::com_ptr<ICoreWindowInterop> interop;
if (SUCCEEDED(inspectable->QueryInterface(IID_PPV_ARGS(&interop))) && SUCCEEDED(interop->get_WindowHandle(&window)))
{
// Get the windowId
winrt::Windows::UI::WindowId windowId{ reinterpret_cast<uint64_t>(window) };
ToastOcclusionManagerPreview::SetToastWindowMargin(windowId, 90);
}
m_isRegistered = true;
}
}