앱 창 관리(Windows 앱 SDK)

아티클
03/03/2023
읽는 데 12분 걸림

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

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

microsoft.UI.Windowing.AppWindow의 Windows 앱 SDK 버전은 비동기 패턴을 사용하지 않으며 API 호출이 성공했는지 여부에 대한 즉각적인 피드백을 앱에 제공합니다. 앞으로 새로운 기능을 도입하고, Windows UI/UX와 통합하고, 새로운 창 시나리오를 사용하도록 설정하는 데 있어 Windows 앱 SDK 창 API가 집중될 것입니다. 창 작업에 대해 이러한 API를 활용하는 것이 좋습니다.

또한 Windows 앱 SDK 대한 도구 설치, 첫 번째 WinUI 3 프로젝트 만들기 및 기존 프로젝트에서 Windows 앱 SDK 사용을 참조하세요.

AppWindow 클래스

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

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

Microsoft.UI.Windowing.AppWindow의 Windows 앱 SDK 버전에서는 최상위 HWND만 지원합니다. AppWindow와 최상위 HWND 간에는 1:1 매핑이 있습니다.

AppWindow 개체와 HWND의 수명은 동일합니다. 창을 만든 직후 AppWindow를 사용할 수 있습니다. 창이 닫혀 있으면 삭제됩니다.

AppWindowPresenter 클래스 및 하위 클래스

각 AppWindow 에는 AppWindowPresenter (발표자)가 적용됩니다. Windows.UI.WindowManagement.AppWindow로 작업한 UWP 개발자인 경우 익숙할 것입니다. 기능 및 동작의 1:1 매핑이 아니더라도 입니다. 창 기능 마이그레이션도 참조하세요.

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

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

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

일부 발표자에는 사용자가 앱의 컨트롤 외부에서 변경할 수 있는 기능이 있습니다. 이러한 변경이 발생하면 AppWindowChangedEventArgs.DidPresenterChange 속성이 로 설정된 영향을 받는 AppWindow의 AppWindow.Changed 이벤트로 true앱에 알림이 표시됩니다. 그러면 앱이 적용된 발표자의 속성을 검사하여 변경된 내용을 확인해야 합니다.

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

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

사용 가능한 Presenter

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

CompactOverlayPresenter. 그림과 유사한 환경을 사용할 수 있도록 가로 세로 비율이 16:9인 고정 크기의 상시 위쪽 창을 만듭니다.
FullScreenPresenter. 창이 전체 화면 환경으로 전환되도록 허용합니다.
OverlappedPresenter. 시스템에서 만든 기본 발표자로, 작업 최소화/최대화/복원 및 상태 변경을 요청하고 대응할 수 있습니다.

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

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

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

C++. interop 함수는 winrt/Microsoft.ui.interop.h 헤더 파일에 정의됩니다.

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

아직 없는 경우 기존 창 개체(UI 프레임워크용)에 대한 HWND 를 검색합니다.
해당 HWND 를 GetWindowIdFromWindow interop 함수에 전달하여 WindowId를 검색합니다.
해당 WindowId 를 정적 AppWindow.GetFromWindowId 메서드에 전달하여 AppWindow를 검색합니다.

AppWindow를 사용할 때의 이점 중 일부는 UI 프레임워크를 사용하는 경우에도 다음과 같습니다.

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

코드 예제

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

C#의 검사 샘플을 참조하세요. 코드 예제에서는 WinRT.Interop.WindowNative 및 Microsoft.UI.Win32Interop 클래스를 사용합니다( .NET 앱에서 interop API 호출 참조). 또한 HWND(창 핸들 검색)를 참조하세요.

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 AppWindow::GetFromWindowId

// 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->try_as<::IWindowNative>() };
    winrt::check_bool(windowNative);
    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 는 데스크톱 앱(패키지 및 패키지되지 않음)에서만 사용할 수 있습니다. UWP 앱에서 사용할 수 없습니다.
Windows 앱 SDK 현재 AppWindow에 UI 프레임워크 콘텐츠를 연결하는 메서드를 제공하지 않습니다. 코드 예제 섹션에 설명된 HWND interop 액세스 메서드를 사용하도록 제한됩니다.
TitleBar 사용자 지정은 현재 Windows 11 이상 버전에서만 지원됩니다. 자세한 내용은 제목 표시줄 사용자 지정 을 참조하세요.

앱 창 관리(Windows 앱 SDK)

AppWindow 클래스

AppWindowPresenter 클래스 및 하위 클래스

사용 가능한 Presenter

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

코드 예제

제한 사항

추가 리소스

추가 리소스

앱 창 관리(Windows 앱 SDK)

AppWindow 클래스

AppWindowPresenter 클래스 및 하위 클래스

사용 가능한 Presenter

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

코드 예제

제한 사항

관련 항목

추가 리소스

추가 리소스