Behandeln von Ereignissen mithilfe von Delegaten in C++/WinRT

In diesem Thema wird gezeigt, wie Sie Ereignisbehandlungsdelegaten mit C++/WinRT registrieren und aufheben. Sie können ein Ereignis mithilfe eines beliebigen standardmäßigen C++-Funktionsobjekts behandeln.

Verwenden von Visual Studio zum Hinzufügen eines Ereignishandlers

Eine bequeme Möglichkeit zum Hinzufügen eines Ereignishandlers zu Ihrem Projekt ist die Verwendung der XAML-Designer-Benutzeroberfläche (UI) in Visual Studio. Wählen Sie bei geöffneter XAML-Seite im XAML-Designer das Steuerelement aus, dessen Ereignis Sie behandeln möchten. Klicken Sie auf der Eigenschaftenseite für dieses Steuerelement auf das Blitzsymbol, um alle Ereignisse auflisten zu können, die von diesem Steuerelement stammen. Doppelklicken Sie dann auf das Ereignis, das Sie behandeln möchten. Beispiel: OnClicked.

Der XAML-Designer fügt ihren Quelldateien den entsprechenden Prototyp der Ereignishandlerfunktion (und eine Stubimplementierung) hinzu, die Sie durch Ihre eigene Implementierung ersetzen können.

Einen Delegaten zur Behandlung eines Ereignisses registrieren

Ein einfaches Beispiel ist die Behandlung des Klickereignisses einer Schaltfläche. In der Regel wird XAML-Markup verwendet, um eine Memberfunktion für die Behandlung des Ereignisses zu registrieren:

// 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"));
}

Der obige Code stammt aus dem Projekt "Leere App, Verpackt" (WinUI 3 in Desktop) in Visual Studio. Der Code myButton() ruft eine generierte Accessorfunktion auf, die die Schaltfläche zurückgibt, die wir myButton genannt haben. Wenn Sie das x:Name Element " Button" ändern, ändert sich auch der Name der generierten Accessorfunktion.

Alternativ kannst du auch imperativ eine Memberfunktion für die Behandlung eines Ereignisses registrieren, anstatt eine Deklaration im Markup zu verwenden. Es ist möglicherweise nicht offensichtlich aus dem folgenden Codebeispiel, aber das Argument für den ButtonBase::Click-Aufruf ist eine Instanz des RoutedEventHandler-Delegaten . In diesem Fall verwenden wir die Konstruktorüberladung RoutedEventHandler, die ein Objekt und eine Pointer-to-Member-Funktion akzeptiert.

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

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

Hier ist ein Beispiel, das eine statische Memberfunktion verwendet. Beachten Sie die einfachere Syntax.

// 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 */) { ... }

Es gibt andere Möglichkeiten zum Erstellen eines RoutedEventHandlers. Unten sehen Sie den Syntaxblock aus dem Dokumentationsthema für RoutedEventHandler (wählen Sie C++/WinRT aus der Dropdownliste "Sprache " in der oberen rechten Ecke der Webseite aus). Beachte die verschiedenen Konstruktoren: Einer akzeptiert eine Lambda-Funktion, ein anderer eine freie Funktion und ein weiterer (der oben verwendete) ein Objekt sowie eine Pointer-to-Member-Funktion.

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;
};

Es ist auch hilfreich, sich die Syntax des Funktionsaufrufoperators anzusehen. Sie erfahren, was die Parameter Ihrer Stellvertretung sein müssen. Wie Sie sehen können, entspricht die Syntax des Funktionsaufrufoperators den Parametern unserer 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;

Wenn Sie nicht viel Arbeit in Ihrem Ereignishandler ausführen, können Sie anstelle einer Memberfunktion eine Lambda-Funktion verwenden. Auch hier ist es möglicherweise nicht offensichtlich aus dem folgenden Codebeispiel, aber ein RoutedEventHandler-Delegat wird aus einer Lambda-Funktion erstellt, die wiederum mit der Syntax des oben beschriebenen Funktionsaufrufoperators übereinstimmen muss.

MainPage::MainPage()
{
    InitializeComponent();

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

Sie können beim Konstruieren Ihres Delegaten etwas expliziter vorgehen. Wenn Sie es beispielsweise mehrmals übergeben oder verwenden möchten.

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);
}

Widerrufen eines registrierten Delegaten

Wenn Sie eine Stellvertretung registrieren, wird normalerweise ein Token an Sie zurückgegeben. Anschließend können Sie dieses Token verwenden, um die Registrierung Ihres Delegaten aufzuheben; das bedeutet, dass der Delegat vom Ereignis abgemeldet wird und nicht aufgerufen wird, sollte das Ereignis erneut ausgelöst werden.

Aus Gründen der Einfachheit zeigte keiner der obigen Codebeispiele, wie dies zu tun ist. Im nächsten Codebeispiel wird das Token allerdings im privaten Datenmember der Struktur gespeichert und der zugehörige Handler im Destruktor widerrufen.

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;
};

Anstelle eines starken Verweises können Sie wie im obigen Beispiel einen schwachen Verweis auf die Schaltfläche speichern (siehe Starke und schwache Verweise in C++/WinRT).

Alternativ können Sie beim Registrieren einer Stellvertretung winrt::auto_revoke (ein Wert vom Typ winrt::auto_revoke_t) angeben, um einen Ereignis-Revoker (vom Typ winrt::event_revoker) anzufordern. Der Ereignis-Revoker enthält einen schwachen Verweis auf die Ereignisquelle (das Objekt, das das Ereignis auslöst). Zum manuellen Widerrufen kannst du die Memberfunktion event_revoker::revoke aufrufen. Der Ereignis-Revoker ruft diese Funktion bei Verlassen des Gültigkeitsbereichs aber automatisch selbst auf. Die Funktion revoke überprüft, ob die Ereignisquelle noch existiert, und hebt gegebenenfalls Ihre Delegierung auf. In diesem Beispiel ist es nicht erforderlich, die Ereignisquelle zu speichern und keinen Destruktor zu benötigen.

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;
};

Nachfolgend finden Sie den Syntaxblock aus dem Dokumentationsabschnitt für das ButtonBase::Click-Ereignis. Es zeigt die drei verschiedenen Registrierungs- und Widerrufsfunktionen. Anhand der dritten Überladung siehst du ganz genau, welche Art von Ereignis-Revoker du deklarieren musst. Und Sie können die gleichen Arten von Delegaten sowohl an die Registrieren- als auch an die Widerrufen mit event_revoker-Überladungen übergeben.

// 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;

Sie könnten in Betracht ziehen, Handler im Fall einer Seitennavigation zu deaktivieren. Wenn du wiederholt zu einer Seite navigierst und sie wieder verlässt, kannst du beim Verlassen der Seite alle Handler widerrufen. Alternativ: Wenn Sie dieselbe Seiteninstanz wiederverwenden, prüfen Sie den Wert Ihres Tokens und registrieren Sie es nur, wenn es noch nicht gesetzt ist (if (!m_token){ ... }). Eine dritte Möglichkeit besteht darin, einen Ereignis-Revoker auf der Seite als Datenmember zu speichern. Und eine vierte Option, wie weiter unten in diesem Thema beschrieben, besteht darin, einen starken oder schwachen Verweis auf dieses Objekt in Ihrer Lambda-Funktion zu erfassen.

Wenn Ihr Delegierter für automatischen Widerruf nicht registriert werden kann

Wenn Sie beim Registrieren eines Delegaten winrt::auto_revoke angeben und das Ergebnis eine winrt::hresult_no_interface-Ausnahme ist, bedeutet dies in der Regel, dass die Ereignisquelle schwache Verweise nicht unterstützt. Das ist beispielsweise eine häufige Situation im Microsoft.UI.Composition-Namensraum. In diesem Fall können Sie das Feature zum automatischen Widerrufen nicht verwenden. Sie müssen die Ereignishandler manuell widerrufen.

Delegattypen für asynchrone Aktionen und Vorgänge

In den obigen Beispielen wird der RoutedEventHandler-Delegattyp verwendet, aber natürlich gibt es viele andere Delegattypen. Asynchrone Aktionen und Vorgänge (mit und ohne Fortschritt) verfügen beispielsweise über Abschluss- und/oder Fortschrittsereignisse, die Delegaten des entsprechenden Typs erwarten. Beispielsweise erfordert das Statusereignis eines asynchronen Vorgangs mit Fortschritt (d. h. alles, was IAsyncOperationWithProgress implementiert) einen Delegaten vom Typ "AsyncOperationProgressHandler". Hier ist ein Codebeispiel für die Definition eines Delegaten dieses Typs mit einer Lambda-Funktion. Das Beispiel zeigt auch, wie ein AsyncOperationWithProgressCompletedHandler-Delegat erstellt wird.

#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 };
}

Wie im obigen Kommentar zu Coroutinen bereits angedeutet, ist die Verwendung von Coroutinen für dich wahrscheinlich naheliegender als die Verwendung eines Delegaten mit den Abschlussereignissen asynchroner Aktionen und Vorgänge. Ausführliche Informationen und Codebeispiele finden Sie unter Parallelität und asynchrone Vorgänge mit C++/WinRT.

Wenn du dich für Delegaten und gegen eine Coroutine entscheidest, kannst du eine einfachere Syntax verwenden.

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

Delegattypen, die einen Wert zurückgeben

Einige Delegattypen müssen selbst einen Wert zurückgeben. Ein Beispiel ist ListViewItemToKeyHandler, der eine Zeichenfolge zurückgibt. Hier ist ein Beispiel für die Erstellung eines Delegaten dieses Typs (beachten Sie, dass die Lambda-Funktion einen Wert zurückgibt).

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";
    });
}

Sicherer Zugriff auf diesen Zeiger mit einem Ereignisbehandlungsdelegat

Wenn Sie ein Ereignis mit der Memberfunktion eines Objekts oder innerhalb einer Lambda-Funktion innerhalb der Memberfunktion eines Objekts behandeln, müssen Sie über die relative Lebensdauer des Ereignisempfängers (das Objekt, das das Ereignis verarbeitet) und die Ereignisquelle (das Objekt, das das Ereignis auslöst) nachdenken. Weitere Informationen und Codebeispiele finden Sie unter Starke und schwache Verweise in C++/WinRT.

Wichtige APIs

• winrt::auto_revoke_t-Markierungsstruktur
• winrt::implements::get_weak-Funktion
• winrt::implements::get_strong-Funktion

Zugehörige Themen

• Ereignisse in C++/WinRT erstellen
• Nebenläufigkeit und asynchrone Operationen mit C++/WinRT
• Starke und schwache Verweise in C++/WinRT