앱 창 관리(Windows 앱 SDK)

  • 아티클

이 항목에는 코드 예제 섹션이 포함되어 있습니다.

Windows 앱 SDK는 사용하기 쉬운 Microsoft.UI.Windowing.AppWindow 클래스를 제공합니다. AppWindow 는 프레임워크에 구애받지 않으며 Win32, WPF 및 WinForms를 포함한 모든 Windows 앱에서 사용할 수 있습니다. AppWindow의 프레임워크에 구애받지 않는 특성을 Microsoft.UI.Xaml.Window과 대조할 수 있으며, 이는 WinUI3 프레임워크 전용 윈도우 클래스입니다. AppWindow는 UWP(유니버설 Windows 플랫폼)의 Windows.UI.WindowManagement.AppWindow의 진화이기도 합니다.

Microsoft.UI.Windowing.AppWindowing.의 Windows App SDK 버전은 비동기 패턴에 의존하지 않으며 API 호출 성공 여부에 대한 즉각적인 피드백을 앱에 제공합니다.

또한 Windows App SDK용 도구 설치, 첫 번째 WinUI3 프로젝트 만들기, 기존 프로젝트에 Windows App SDK 사용을 참조하십시오.

AppWindow 클래스

Microsoft.UI.Windowing.AppWindow 는 사용하기 쉬운 창 시나리오를 허용하는 상위 수준 창 API입니다. AppWindow 는 Windows UI/UX 및 다른 앱과 잘 통합됩니다.

AppWindow 는 앱 콘텐츠에 대한 시스템 관리 컨테이너의 개략적인 추상화를 나타냅니다. 콘텐츠가 호스팅되는 컨테이너입니다. 또한 사용자가 화면에서 앱의 크기를 조정하고 이동할 때 상호 작용하는 엔터티를 나타냅니다. Win32 에 익숙하다면 앱 창을 HWND 의 개략적인 추상화로 볼 수 있습니다. UWP에 익숙한 경우 앱 창 은 CoreWindow ApplicationView/Windows.UI.WindowManagement.AppWindow를/대체하는 것으로 볼 수 있습니다.

Windows App SDK 버전의 Microsoft.UI.Windowing.AppWindowing의 경우에는 최상위 수준의 HWND만 지원합니다. AppWindow와 최상위 HWND 간에는 1:1 매핑이 있습니다.

AppWindow 개체와 HWND 의 수명 은 동일하며, AppWindow 는 창이 만들어진 직후에 사용할 수 있으며 창이 닫히면 소멸됩니다.

AppWindowPresenter 클래스 및 하위 클래스

각 AppWindow에는AppWindow Present (present)가 적용되어 있습니다. Windows.UI.WindowManagement.AppWindow 를 사용한적이 있는 UWP 개발자라면 기능 및 동작의 1:1 매핑이 아니더라도 익숙할 것입니다. 또한 창 기능 마이그레이션 을 참조하세요.

Win32 응용 프로그램 모델의 새로운 개념인 프레젠터는 창 상태와 스타일의 조합과 비슷하지만 동일하지는 않습니다. 일부 발표자에는 클래식 창 상태 및 스타일 속성(예: 자동 숨기기 제목 표시줄)에서 검사할 수 없는 UI/UX 동작이 정의되어 있습니다.

기본적으로 발표자는 시스템에 의해 만들어지고 생성 시 AppWindow 에 적용됩니다. Windows 앱 SDK 1.0의 Windows 데스크톱에서 발표자 유형은 AppWindowPresenter의 하위 클래스인 OverlappedPresenter입니다. 앱에서 이를 스태시할 필요가 없으며, 다른 발표자를 적용한 후 창의 기본 발표자로 돌아가기 위해 참조를 유지할 필요도 없습니다. 이는 시스템이 이 프리젠터의 동일한 인스턴스를 생성된 AppWindow의 수명 동안 유지하고, 앱에서 AppWindowPresenterKind.Default 를 매개 변수로 사용하여 AppWindow.SetPresenter 메서드를 호출하여 다시 적용할 수 있기 때문입니다.

발표자는 한 번에 하나의 창에만 적용할 수 있습니다. 동일한 발표자를 두 번째 창에 적용하려고 하면 예외가 throw됩니다. 즉, 창이 여러 개 있고 각 창을 특정 프레젠테이션 모드로 전환하려면 같은 종류의 발표자를 여러 개 만든 다음 각 발표자를 자체 창에 적용해야 합니다.

일부 발표자에는 사용자가 앱의 자체 제어 범위를 벗어나 변경할 수 있는 기능이 있습니다. 이러한 변경이 발생하면 AppWindowChangedEventArgs.DidPresenterChange 속성이 설정된 영향을 받는 AppWindow 의 AppWindow.Changed 이벤트에 의해 앱에 알림이 표시됩니다 true. 그런 다음 앱은 적용된 발표자의 속성을 검사하여 변경된 내용을 확인해야 합니다.

적용된 Presenter는 라이브 개체입니다. AppWindow.Presenter 개체의 속성 에 대한 변경 내용은 즉시 적용됩니다.

발표자는 창에 적용되는 동안 소멸될 수 없습니다. 프리젠터 개체를 삭제하려면 먼저 창에 다른 프리젠터 개체를 적용합니다. 이렇게 하면 제거하려는 발표자가 창에서 제거됩니다. 창에 다른 특정 발표자를 적용하거나 AppWindowPresenterKind.Default 를 인수로 사용하여 AppWindow.SetPresenter 메서드를 호출하여 시스템에서 만든 기본 발표자를 창에 다시 적용하여 이 작업을 수행할 수 있습니다. 창에 대해 시스템에서 만든 발표자에 대한 참조를 유지한 경우 이 시점에서 유효합니다(즉, 창에 대해 처음 만든 인스턴스가 다시 적용됨).

사용 가능한 Presenter

이러한 AppWindowPresenter 파생 발표자가 제공되며 지원되는 모든 OS 버전에서 사용할 수 있습니다.

  • CompactOverlayPresenter. 16:9 가로 세로 비율로 고정된 크기의 항상 맨 위에 있는 창을 만들어 PIP(Picture-in-Picture )와 같은 경험을 제공합니다.
  • FullScreenPresenter. 창이 전체 화면 환경으로 전환되도록 허용합니다.
  • OverlappedPresenter. 시스템에서 만든 기본 발표자 - 작업 및 상태 변경을 최소화/최대화/복원하도록 요청하고 대응할 수 있습니다.

UI 프레임워크 및 HWND 상호 운용성

이 앱 윈도우 클래스는 앱에서 아무 최상위 레벨 HWND에 사용할 수 있습니다. 즉, 데스크톱 UI 프레임워크(WinUI 3 포함)로 작업할 때 해당 프레임워크의 진입점을 계속 사용하여 창을 만들고 콘텐츠를 연결할 수 있습니다. 해당 UI 프레임워크를 사용하여 창을 만든 후에는 Windows 앱 SDK 제공된 창 interop 함수(아래 참조)를 사용하여 해당 AppWindow 및 해당 메서드, 속성 및 이벤트에 액세스할 수 있습니다.

AppWindow 를 사용하면 UI 프레임워크로 작업하는 경우에도 다음과 같은 몇 가지 이점이 있습니다.

  • 쉬운 제목 표시줄 사용자 정의; 기본적으로 Windows 11 UI(둥근 모서리, 스냅 그룹 플라이아웃)를 유지합니다.
  • 시스템에서 제공하는 전체 화면 및 컴팩트 오버레이(PIP(Picture-in-Picture) 환경).
  • 핵심 Win32 창 개념 중 일부에 대한 WinRT(Windows 런타임) API 표면입니다.

코드 예

이 코드 예제에서는 Microsoft.UI.Xaml.Window.AppWindow 속성을 사용하여 WinUI 3 창에서 Microsoft.UI.Windowing.AppWindow를 검색하는 방법을 보여 줍니다. 이 예제를 사용하려면 새 빈 앱인 Packaged(데스크톱의 WinUI 3) 프로젝트를 만들고 코드를 붙여넣습니다.

AppWindow 를 사용하는방법에 대한 자세한 내용은 창 갤러리 샘플을 참조하세요.

// MainWindow.xaml.cs
private void myButton_Click(object sender, RoutedEventArgs e)
{
    // Retrieve the AppWindow for the current (XAML) WinUI 3 window.
    Microsoft.UI.Windowing.AppWindow appWindow = this.AppWindow;

    if (appWindow != null)
    {
        // With a non-null AppWindow object, you can call its methods
        // to manipulate the window. As an example, let's change the title
        // text of the window.
        appWindow.Title = "Title text updated via AppWindow!";
    }
}

// pch.h
#include <winrt/Microsoft.UI.Windowing.h> // For the AppWindow class.

// mainwindow.xaml.cpp
void MainWindow::myButton_Click(IInspectable const&, RoutedEventArgs const&)
{
    // Retrieve the AppWindow for the current (XAML) WinUI 3 window.
    Microsoft::UI::Windowing::AppWindow appWindow = this->AppWindow();

    if (appWindow)
    {
        // With a non-null AppWindow object, you can call its methods
        // to manipulate the window. As an example, let's change the title
        // text of the window.
        appWindow.Title(L"Title text updated via AppWindow!");
    }
}

1.3 이전 버전의 Windows 앱 SDK 코드 예제(또는 다른 데스크톱 앱 프레임워크)

위의 코드 예제에서 사용되는 Microsoft.UI.Xaml.Window.AppWindow 속성은 Windows 앱 SDK 버전 1.3 이상에서 사용할 수 있습니다. 이전 버전의 경우 이 섹션에서 기능적으로 동등한 코드 예제를 사용할 수 있습니다.

C#. 창 interop 함수에 대한 .NET 래퍼는 Microsoft.UI.Win32Interop 클래스의 메서드로 구현됩니다. 또한 .NET 앱에서 interop API 호출 을 참조하세요.

C++. Interop 함수는 winrt/Microsoft.ui.interop.h 헤더 파일에 정의 되어 있습니다.

아래 코드 예제 섹션은 실제 소스 코드를 보여 주지만, 기존 창이 지정된 경우 AppWindow 개체를 검색하는 방법은 다음과 같습니다.

  1. 아직 없는 경우 기존 창 개체(UI 프레임워크용)에 대한 HWND를 검색합니다.
  2. 해당 HWND를GetWindowIdFromWindow interop 함수에 전달하여 WindowId 를 검색합니다.
  3. 해당 WindowId를 정적 AppWindow.GetFromWindowId 메서드에 전달하여 AppWindow를 검색합니다.
// MainWindow.xaml.cs
private void myButton_Click(object sender, RoutedEventArgs e)
{
    // Retrieve the window handle (HWND) of the current (XAML) WinUI 3 window.
    var hWnd =
        WinRT.Interop.WindowNative.GetWindowHandle(this);

    // Retrieve the WindowId that corresponds to hWnd.
    Microsoft.UI.WindowId windowId =
        Microsoft.UI.Win32Interop.GetWindowIdFromWindow(hWnd);

    // Lastly, retrieve the AppWindow for the current (XAML) WinUI 3 window.
    Microsoft.UI.Windowing.AppWindow appWindow =
        Microsoft.UI.Windowing.AppWindow.GetFromWindowId(windowId);

    if (appWindow != null)
    {
        // You now have an AppWindow object, and you can call its methods to manipulate the window.
        // As an example, let's change the title text of the window.
        appWindow.Title = "Title text updated via AppWindow!";
    }
}

// pch.h
#include "microsoft.ui.xaml.window.h" // For the IWindowNative interface.
#include <winrt/Microsoft.UI.Interop.h> // For the WindowId struct and the GetWindowIdFromWindow function.
#include <winrt/Microsoft.UI.Windowing.h> // For the AppWindow class.

// mainwindow.xaml.cpp
void MainWindow::myButton_Click(IInspectable const&, RoutedEventArgs const&)
{
    // Retrieve the window handle (HWND) of the current (XAML) WinUI 3 window.
    auto windowNative{ this->m_inner.as<::IWindowNative>() };
    HWND hWnd{ 0 };
    windowNative->get_WindowHandle(&hWnd);

    // Retrieve the WindowId that corresponds to hWnd.
    Microsoft::UI::WindowId windowId = 
        Microsoft::UI::GetWindowIdFromWindow(hWnd);

    // Lastly, retrieve the AppWindow for the current (XAML) WinUI 3 window.
    Microsoft::UI::Windowing::AppWindow appWindow = 
        Microsoft::UI::Windowing::AppWindow::GetFromWindowId(windowId);

    if (appWindow)
    {
        // You now have an AppWindow object, and you can call its methods to manipulate the window.
        // As an example, let's change the title text of the window.
        appWindow.Title(L"Title text updated via AppWindow!");
    }
}

제한 사항

  • AppWindow 는 WinUI 3 API입니다. 즉, 데스크톱 앱(패키지 및 패키지되지 않음)에서만 사용할 수 있습니다. UWP 앱에서 사용할 수 없습니다.
  • Windows 앱 SDK는 현재 UI 프레임워크 콘텐츠를 AppWindow에 연결하는 메서드를 제공하지 않습니다. 그러나 코드 예제 섹션을 참조하세요.
  • 제목 표시줄 사용자 지정은 Windows 11 이상에서 지원됩니다. 버전 1.2 이상용 Windows 10에서 Windows 앱 SDK. 자세한 내용은, 제목 표시줄 사용자 지정을 참조하세요.