Manipular eventos usando delegados em C++/WinRT

Este tópico mostra como registrar e revogar delegados que manipulam eventos usando C++/WinRT. Você pode manipular um evento usando qualquer objeto de função de C++ padrão.

Usando o Visual Studio para adicionar um manipulador de eventos

Uma forma conveniente de adicionar um manipulador de eventos ao seu projeto é usar a IU (interface do usuário) do Designer XAML no Visual Studio. Com sua página XAML aberta no Designer XAML, selecione o controle cujo evento você deseja manipular. Na página de propriedades do controle, clique no ícone de raio para listar todos os eventos originados do controle. Em seguida, clique duas vezes no evento que deseja manipular; por exemplo, OnClicked.

O Designer XAML adiciona o protótipo da função do manipulador de eventos apropriado (e uma implementação de stub) aos arquivos de origem, prontos para substituição pela sua implementação.

Registrar um delegado para manipular um evento

Um exemplo simples está manipulando um evento de clique do botão. É comum usar marcação XAML para registrar uma função de membro para manipular o evento, como este.

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

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

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

O código acima foi extraído do projeto Aplicativo em Branco (C++/WinRT) no Visual Studio. O código myButton() chama uma função de acessador gerada, que retorna o Button nomeado myButton. Se você alterar o x:Name desse elemento Button, o nome da função de acessador gerada também será alterado.

Ao invés de fazer isso declarativamente na marcação, registre imperativamente uma função de membro para manipular um evento. Talvez não seja óbvio pelo exemplo de código abaixo, mas o argumento para a chamada ButtonBase::Click é uma instância do delegado RoutedEventHandler. Nesse caso, estamos usando a sobrecarga de construtor RoutedEventHandler que usa um objeto e um ponteiro para a função de membro.

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

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

Veja um exemplo que usa uma função de membro estático. Observe a sintaxe mais simples.

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

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

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

Há outras formas de criar um RoutedEventHandler. Apresentamos a seguir o bloco de sintaxe tirado do tópico da documentação de RoutedEventHandler (escolha C++/WinRT na lista suspensa Language no canto superior direito da página). Observe os vários construtores: um deles usa um lambda; outro uma função livre; e outro (aquele que usamos acima) usa um objeto e um ponteiro para função de membro.

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::Windows::UI::Xaml::RoutedEventArgs const& e) const;
};

Também é útil analisar a sintaxe do operador de chamada de função. Ela informa quais precisam ser os parâmetros do delegado. Como se pode ver, neste caso a sintaxe de operador de chamada da função combina com os parâmetros de MainPage::ClickHandler.

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

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

Se você não estiver fazendo muito trabalho no manipulador de eventos, pode usar uma função lambda em vez de uma função de membro. Talvez não seja óbvio a partir do exemplo de código abaixo, mas um delegado RoutedEventHandler está sendo construído a partir de uma função lambda que, novamente, precisa corresponder à sintaxe do operador de chamada de função.

MainPage::MainPage()
{
    InitializeComponent();

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

Você pode optar por ser um pouco mais explícito quando construir seu delegado. Por exemplo, se quiser passá-lo ou usá-lo mais de uma vez.

MainPage::MainPage()
{
    InitializeComponent();

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

Revogar um delegado registrado

Ao registrar um delegado, normalmente se recebe um token de retorno. Em seguida, é possível usar esse token para revogar seu delegado; o que significa que o delegado tem o registro do evento cancelado e não será chamado caso o evento inicie novamente.

Por questões de simplicidade, nenhum dos exemplos de código acima mostrou como fazer isso. Entretanto, este próximo exemplo de código armazena o token no membro de dados privados do struct e revoga seu manipulador no destruidor.

struct Example : ExampleT<Example>
{
    Example(winrt::Windows::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::Windows::UI::Xaml::Controls::Button m_button;
    winrt::event_token m_token;
};

Em vez de uma referência forte, como no exemplo acima, armazene uma referência fraca no botão (confira Referências fortes e fracas em C++/WinRT).

Como alternativa, ao registrar um delegado, é possível especificar winrt::auto_revoke (um valor do tipo winrt::auto_revoke_t) para solicitar um revogador de evento (do tipo winrt::event_revoker). O revogador do evento mantém uma referência fraca à origem do evento (o objeto que aciona o evento). Você pode revogar manualmente ao chamar a função de membro event_revoker::revoke; mas o revogador de evento chama essa função automaticamente quando sai do escopo. A função revoke verifica se a fonte do evento ainda existe e, em caso afirmativo, revoga o delegado. Neste exemplo, não há necessidade de armazenar a origem do evento e não há necessidade de um destruidor.

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

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

A seguir apresentamos o bloco de sintaxe do tópico de documentação para o evento ButtonBase::Click. Ele mostra os três registros diferentes e a revogação de funções. É possível ver exatamente qual tipo de revogador de evento você precisa declarar a partir da terceira sobrecarga. E você pode passar os mesmos tipos de delegados para ambas as sobrecargas registro e revogar com event_revoker.

// Register
winrt::event_token Click(winrt::Windows::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::Windows::UI::Xaml::RoutedEventHandler const& handler) const;

Considere a revogação de manipuladores em um cenário de navegação de página. Se estiver navegando repetidamente em uma página e depois retroceder, é possível revogar quaisquer manipuladores ao navegar para fora da página. Como alternativa, se estiver reutilizando a mesma instância de página, verifique o valor do token e registre somente se ele ainda não tiver sido definido (if (!m_token){ ... }). Uma terceira opção é armazenar um revogador de evento na página como um membro de dados. E uma quarta opção, conforme descrito mais adiante neste tópico, é capturar uma referência forte ou fraca para o objeto this na sua função lambda.

Se o registro de seu delegado de revogação automática falhar

Se você tentar especificar winrt::auto_revoke ao registrar um delegado e o resultado for uma exceção winrt::hresult_no_interface, normalmente isso significa que a origem do evento não dará suporte a referências fracas. Essa é uma situação comum no namespace Windows.UI.Composition, por exemplo. Nessa situação, você não pode usar o recurso de revogação automática. Você precisará fazer fallback para revogar manualmente seus manipuladores de eventos.

Tipos delegados para ações e operações assíncronas

Os exemplos acima usam o tipo delegado RoutedEventHandler, mas há muitos outros tipos de delegado, é claro. Por exemplo, ações e operações assíncronas (com e sem progresso) foram concluídas e/ou eventos de progresso que esperam delegados do tipo correspondente. Por exemplo, o evento de progresso de uma operação assíncrona com progresso (que é qualquer coisa que implementa IAsyncOperationWithProgress) requer um delegado do tipo AsyncOperationProgressHandler. Eis um exemplo de código de criação de um delegado desse tipo usando uma função lambda. O exemplo também mostra como criar um delegado 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 };
}

Como sugere o comentário da "corrotina", ao invés de usar um delegado com os eventos concluídos de ações assíncronas e operações, talvez seja mais natural usar corrotinas concomitantes. Para saber mais e obter exemplos de código, confira Simultaneidade e operações assíncronas com C++/WinRT.

Se continuar com delegados ao invés de uma corrotina, poderá optar por uma sintaxe mais simples.

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

Tipos delegados que retornam um valor

Alguns tipos delegados devem retornar um valor. Um exemplo é ListViewItemToKeyHandler, que retorna uma cadeia de caracteres. Este é um exemplo de criação de um delegado desse tipo (observe que a função lambda retorna um valor).

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

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

Acessar com segurança o ponteiro this com um delegado de manipulação de eventos

Se você manipular um evento com uma função de membro de objeto, ou de dentro de uma função lambda dentro da função de membro de um objeto, precisará pensar sobre os ciclos de vida relativos do destinatário do evento (o objeto que está manipulando o evento) e a origem do evento (o objeto que está acionando o evento). Para saber mais e obter exemplos de código, confira Referências fortes e fracas em C++/WinRT.

APIs importantes

• Struct de marcador winrt::auto_revoke_t
• Função winrt::implements::get_weak
• Função winrt::implements::get_strong

Tópicos relacionados

• Criar eventos em C++/WinRT
• Simultaneidade e operações assíncronas com C++/WinRT
• Referências fortes e fracas em C++/WinRT