C++/WinRT에서 대리자를 사용하여 이벤트 처리

이 항목에서는 C++/WinRT를 사용하여 이벤트 처리 대리자를 등록하고 취소하는 방법을 보여 줍니다. 표준 C++ 함수와 유사한 개체를 사용하여 이벤트를 처리할 수 있습니다.

Visual Studio 사용하여 이벤트 처리기 추가

프로젝트에 이벤트 처리기를 추가하는 편리한 방법은 Visual Studio XAML 디자이너 UI(사용자 인터페이스)를 사용하는 것입니다. XAML 디자이너에서 XAML 페이지가 열려 있는 상태에서 처리하려는 이벤트가 있는 컨트롤을 선택합니다. 해당 컨트롤의 속성 페이지에서 번개 모양 아이콘을 클릭하여 해당 컨트롤에서 제공하는 모든 이벤트를 나열합니다. 그런 다음 처리하려는 이벤트를 두 번 클릭합니다. 예를 들어 OnClicked입니다.

XAML 디자이너는 소스 파일에 적절한 이벤트 처리기 함수 프로토타입(및 스텁 구현)을 추가하여 사용자 고유의 구현으로 바꿀 준비가 되어 있습니다.

이벤트를 처리할 대리자 등록

간단한 예는 단추의 클릭 이벤트를 처리하는 것입니다. XAML 태그를 사용하여 다음과 같이 이벤트를 처리하는 멤버 함수를 등록하는 것이 일반적입니다.

// MainPage.xaml
<Button x:Name="myButton" Click="ClickHandler">Click Me</Button>

// MainPage.h
void ClickHandler(
    winrt::Windows::Foundation::IInspectable const& sender,
    winrt::Microsoft::UI::Xaml::RoutedEventArgs const& args);

// MainPage.cpp
void MainPage::ClickHandler(
    IInspectable const& /* sender */,
    RoutedEventArgs const& /* args */)
{
    myButton().Content(box_value(L"Clicked"));
}

위 코드는 Visual Studio의 빈 앱, 패키지됨(데스크톱용 WinUI 3) 프로젝트에서 가져온 것입니다. 이 코드 myButton() 는 myButton이라는 Button을 반환하는 생성된 접근자 함수를 호출합니다. 해당 x:Name 요소의 이름을 변경 하면 생성된 접근자 함수의 이름도 변경됩니다.

태그에서 선언적으로 수행하는 대신 이벤트를 처리하기 위해 멤버 함수를 명령적으로 등록할 수 있습니다. 아래 코드 예제에서는 명확하지 않을 수 있지만 ButtonBase::Click 호출에 대한 인수는 RoutedEventHandler 대리자의 인스턴스입니다. 이 경우 개체 및 멤버에 대한 포인터 함수를 사용하는 RoutedEventHandler 생성자 오버로드를 사용합니다.

// MainPage.cpp
MainPage::MainPage()
{
    InitializeComponent();

    myButton().Click({ this, &MainPage::ClickHandler });
}

다음은 정적 멤버 함수를 사용하는 예제입니다. 더 간단한 구문을 확인합니다.

// MainPage.h
static void ClickHandler(
    winrt::Windows::Foundation::IInspectable const& sender,
    winrt::Microsoft::UI::Xaml::RoutedEventArgs const& args);

// MainPage.cpp
MainPage::MainPage()
{
    InitializeComponent();

    myButton().Click( MainPage::ClickHandler );
}
void MainPage::ClickHandler(
    IInspectable const& /* sender */,
    RoutedEventArgs const& /* args */) { ... }

RoutedEventHandler를 생성하는 다른 방법이 있습니다. 다음은 RoutedEventHandler에 대한 설명서 항목에서 가져온 구문 블록입니다(웹 페이지의 오른쪽 위 모서리에 있는 언어 드롭다운에서 C++/WinRT 선택). 다양한 생성자에 주목하세요. 하나는 람다를 받고, 다른 하나는 자유 함수를 받으며, 또 다른 하나(위에서 사용한 생성자)는 객체와 멤버 함수 포인터를 받습니다.

struct RoutedEventHandler : winrt::Windows::Foundation::IUnknown
{
    RoutedEventHandler(std::nullptr_t = nullptr) noexcept;
    template <typename L> RoutedEventHandler(L lambda);
    template <typename F> RoutedEventHandler(F* function);
    template <typename O, typename M> RoutedEventHandler(O* object, M method);
    /* ... other constructors ... */
    void operator()(winrt::Windows::Foundation::IInspectable const& sender,
        winrt::Microsoft::UI::Xaml::RoutedEventArgs const& e) const;
};

함수 호출 연산자의 구문도 확인할 수 있습니다. 대리자의 매개 변수가 무엇인지 알려줍니다. 이 경우 함수 호출 연산자 구문은 MainPage::ClickHandler의 매개 변수와 일치합니다.

// Register
event_token KeyDown(KeyEventHandler const& handler) const;

void operator()(
  winrt::Windows::Foundation::IInspectable const& sender,
  winrt::Microsoft::UI::Xaml::Input::KeyRoutedEventArgs const& e) const;

이벤트 처리기에서 많은 작업을 수행하지 않는 경우 멤버 함수 대신 람다 함수를 사용할 수 있습니다. 다시 말하지만, 아래 코드 예제에서는 명확하지 않을 수 있지만 RoutedEventHandler 대리자는 위에서 설명한 함수 호출 연산자의 구문과 일치해야 하는 람다 함수에서 생성됩니다.

MainPage::MainPage()
{
    InitializeComponent();

    myButton().Click([this](IInspectable const& /* sender */, RoutedEventArgs const& /* args */)
    {
        myButton().Content(box_value(L"Clicked"));
    });
}

대리자를 생성할 때 좀 더 명시적으로 선택할 수 있습니다. 예를 들어 전달하거나 두 번 이상 사용하려는 경우입니다.

MainPage::MainPage()
{
    InitializeComponent();

    auto click_handler = [](IInspectable const& sender, RoutedEventArgs const& /* args */)
    {
        sender.as<winrt::Microsoft::UI::Xaml::Controls::Button>().Content(box_value(L"Clicked"));
    };
    myButton().Click(click_handler);
    AnotherButton().Click(click_handler);
}

등록된 대리자 해지

대리자를 등록하면 일반적으로 토큰이 반환됩니다. 이후에 해당 토큰을 사용하여 대리자를 해지할 수 있습니다. 즉, 대리자가 이벤트에서 등록 취소되고 이벤트가 다시 발생하면 호출되지 않습니다.

간단히 하기 위해 위의 코드 예제 중 어느 것도 그렇게 하는 방법을 보여주지 않았습니다. 그러나 다음 코드 예제에서는 구조체의 프라이빗 데이터 멤버에 토큰을 저장하고 소멸자에서 해당 처리기를 해지합니다.

struct Example : ExampleT<Example>
{
    Example(winrt::Microsoft::UI::Xaml::Controls::Button const& button) : m_button(button)
    {
        m_token = m_button.Click([this](IInspectable const&, RoutedEventArgs const&)
        {
            // ...
        });
    }
    ~Example()
    {
        m_button.Click(m_token);
    }

private:
    winrt::Microsoft::UI::Xaml::Controls::Button m_button;
    winrt::event_token m_token;
};

위의 예제와 같이 강력한 참조 대신 단추에 대한 약한 참조를 저장할 수 있습니다( C++/WinRT의 강력한 참조 및 약한 참조 참조).

또는 대리자를 등록할 때 winrt::auto_revoke ( winrt::auto_revoke_t 형식의 값)를 지정하여 이벤트 해지자( winrt::event_revoker 형식)를 요청할 수 있습니다. 이벤트 취소자는 사용자를 대신해 이벤트 소스(이벤트를 발생시키는 개체)에 대한 약한 참조를 유지합니다. event_revoker::revoke 멤버 함수를 호출하여 수동으로 해지할 수 있습니다. 그러나 이벤트 해지자는 범위를 벗어나면 해당 함수 자체를 자동으로 호출합니다. revoke 함수는 이벤트 원본이 여전히 존재하는지 확인하고, 있는 경우 대리자를 해지합니다. 이 예제에서는 이벤트 원본을 저장할 필요가 없으며 소멸자가 필요하지 않습니다.

struct Example : ExampleT<Example>
{
    Example(winrt::Microsoft::UI::Xaml::Controls::Button button)
    {
        m_event_revoker = button.Click(
            winrt::auto_revoke,
            [this](IInspectable const& /* sender */,
            RoutedEventArgs const& /* args */)
        {
            // ...
        });
    }

private:
    winrt::Microsoft::UI::Xaml::Controls::Button::Click_revoker m_event_revoker;
};

다음은 ButtonBase::Click 이벤트에 대한 설명서 항목에서 가져온 구문 블록입니다. 세 가지 다른 등록 및 해지 함수를 보여 줍니다. 세 번째 오버로드에서 선언해야 하는 이벤트 해지자의 유형을 정확히 확인할 수 있습니다. 또한 register 및 revoke with event_revoker 오버로드 모두에 동일한 종류의 대리자를 전달할 수 있습니다.

// Register
winrt::event_token Click(winrt::Microsoft::UI::Xaml::RoutedEventHandler const& handler) const;

// Revoke with event_token
void Click(winrt::event_token const& token) const;

// Revoke with event_revoker
Button::Click_revoker Click(winrt::auto_revoke_t,
    winrt::Microsoft::UI::Xaml::RoutedEventHandler const& handler) const;

페이지 탐색 시나리오에서 처리기를 해지하는 것이 좋습니다. 페이지로 반복적으로 이동한 다음 다시 나가는 경우 페이지에서 벗어날 때 처리기를 취소할 수 있습니다. 또는 동일한 페이지 인스턴스를 다시 사용하는 경우 토큰 값을 확인하고 아직 설정되지 않은 경우에만 등록합니다(if (!m_token){ ... }). 세 번째 옵션은 페이지에 이벤트 해지자를 데이터 멤버로 저장하는 것입니다. 이 항목의 뒷부분에서 설명한 대로 네 번째 옵션은 람다 함수에서 이 개체에 대한 강력한 참조 또는 약한 참조를 캡처하는 것입니다.

자동 해지 대리자가 등록에 실패하는 경우

대리자를 등록할 때 winrt::auto_revoke 지정하려고 하고 결과가 winrt::hresult_no_interface 예외인 경우 일반적으로 이벤트 원본이 약한 참조를 지원하지 않음을 의미합니다. 예를 들어, Microsoft.UI.Composition 네임스페이스에서는 흔히 있는 상황입니다. 이 경우 자동 해지 기능을 사용할 수 없습니다. 이벤트 핸들러를 수동으로 제거하는 수밖에 없습니다.

비동기 작업 및 작업에 대한 대리자 형식

위의 예제에서는 RoutedEventHandler 대리자 형식을 사용하지만 다른 대리자 형식도 많이 있습니다. 예를 들어, 비동기 동작과 작업은 진행률 보고 유무와 관계없이 해당 형식의 대리자를 필요로 하는 완료 이벤트 및/또는 진행률 이벤트를 갖습니다. 예를 들어 진행률이 있는 비동기 작업의 진행률 이벤트( IAsyncOperationWithProgress를 구현하는 모든 항목)에는 AsyncOperationProgressHandler 형식의 대리자가 필요합니다. 다음은 람다 함수를 사용하여 해당 형식의 대리자를 작성하는 코드 예제입니다. 또한 이 예제에서는 AsyncOperationWithProgressCompletedHandler 대리자를 작성하는 방법도 보여줍니다.

#include <winrt/Windows.Foundation.h>
#include <winrt/Windows.Web.Syndication.h>

using namespace winrt;
using namespace Windows::Foundation;
using namespace Windows::Web::Syndication;

void ProcessFeedAsync()
{
    Uri rssFeedUri{ L"https://blogs.windows.com/feed" };
    SyndicationClient syndicationClient;

    auto async_op_with_progress = syndicationClient.RetrieveFeedAsync(rssFeedUri);

    async_op_with_progress.Progress(
        [](
            IAsyncOperationWithProgress<SyndicationFeed,
            RetrievalProgress> const& /* sender */,
            RetrievalProgress const& args)
        {
            uint32_t bytes_retrieved = args.BytesRetrieved;
            // use bytes_retrieved;
        });

    async_op_with_progress.Completed(
        [](
            IAsyncOperationWithProgress<SyndicationFeed,
            RetrievalProgress> const& sender,
            AsyncStatus const /* asyncStatus */)
        {
            SyndicationFeed syndicationFeed = sender.GetResults();
            // use syndicationFeed;
        });

    // or (but this function must then be a coroutine, and return IAsyncAction)
    // SyndicationFeed syndicationFeed{ co_await async_op_with_progress };
}

위의 'coroutine' 주석이 시사하듯이, 비동기 동작 및 작업의 완료 이벤트에서 델리게이트를 사용하는 대신 코루틴을 사용하는 편이 아마 더 자연스럽게 느껴질 것입니다. 자세한 내용 및 코드 예제는 C++/WinRT를 사용한 동시성 및 비동기 작업을 참조하세요.

코루틴 대신 대리자를 사용하는 경우 더 간단한 구문을 선택할 수 있습니다.

async_op_with_progress.Completed(
    [](auto&& /*sender*/, AsyncStatus const /* args */)
{
    // ...
});

값을 반환하는 대리자 형식

일부 대리자 형식은 스스로 값을 반환해야 합니다. 예를 들어 문자열을 반환하는 ListViewItemToKeyHandler가 있습니다. 다음은 해당 형식의 대리자를 작성하는 예제입니다(람다 함수는 값을 반환합니다).

using namespace winrt::Microsoft::UI::Xaml::Controls;

winrt::hstring f(ListView listview)
{
    return ListViewPersistenceHelper::GetRelativeScrollPosition(listview, [](IInspectable const& item)
    {
        return L"key for item goes here";
    });
}

이벤트 처리 델리게이트를 사용하여 this 포인터에 안전하게 접근하기

개체의 멤버 함수 또는 개체의 멤버 함수 내의 람다 함수 내에서 이벤트를 처리하는 경우 이벤트 수신자(이벤트를 처리하는 개체) 및 이벤트 원본(이벤트를 발생시키는 개체)의 상대 수명에 대해 고려해야 합니다. 자세한 정보 및 코드 예제는 C++/WinRT의 강력한 참조 및 약한 참조를 참조하세요.

중요 API

• winrt::auto_revoke_t 표식 구조체
• winrt::implements::get_weak 함수
• winrt::implements::get_strong 함수

관련 항목

• C++/WinRT에서 이벤트 작성
• C++/WinRT를 사용하는 동시성 및 비동기 작업
• C++/WinRT의 강력한 참조 및 약한 참조