Hantera händelser med hjälp av ombud i C++/WinRT

Det här avsnittet visar hur du registrerar och återkallar ombud för händelsehantering med hjälp av C++/WinRT. Du kan hantera en händelse med valfritt C++-standardfunktionsliknande objekt.

Använda Visual Studio för att lägga till en händelsehanterare

Ett praktiskt sätt att lägga till en händelsehanterare i projektet är att använda användargränssnittet för XAML Designer i Visual Studio. När XAML-sidan är öppen i XAML Designer väljer du den kontroll vars händelse du vill hantera. På egenskapssidan för kontrollen klickar du på blixtikonen för att visa en lista över alla händelser som kommer från kontrollen. Dubbelklicka sedan på den händelse som du vill hantera. till exempel OnClicked.

XAML Designer lägger till lämplig prototyp av händelsehanterarens funktion (och en stub-implementering) till dina källfiler, som är redo att ersättas med din egen implementering.

Registrera ett ombud för att hantera en händelse

Ett enkelt exempel är att hantera en knapps klickhändelse. Det är vanligt att använda XAML-markering för att registrera en medlemsfunktion för att hantera händelsen, så här.

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

Koden ovan hämtas från projektet Blank App, Packaged (WinUI 3 in Desktop) i Visual Studio. Koden myButton() anropar en genererad accessor-funktion som returnerar knappen som vi gav myButton namnet. Om du ändrar x:Nameknappelementets namn ändras även namnet på den genererade accessorfunktionen.

I stället för att göra det deklarativt i markup-kod kan du registrera en medlemsfunktion imperativt som hanterar en händelse. Det kanske inte är uppenbart i kodexemplet nedan, men argumentet till ButtonBase::Click-anropet är en instans av RoutedEventHandler-ombudet . I det här fallet använder vi den överlagrade konstruktorn RoutedEventHandler som tar emot ett objekt och en pekare till en medlemsfunktion.

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

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

Här är ett exempel som använder en statisk medlemsfunktion. observera den enklare syntaxen.

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

Det finns andra sätt att skapa en RoutedEventHandler. Nedan visas syntaxblocket från dokumentationsavsnittet för RoutedEventHandler (välj C++/WinRT i listrutan Språk i det övre högra hörnet på webbsidan). Observera de olika konstruktorerna: en tar emot en lambda, en annan en frifunktion, och ytterligare en (den vi använde ovan) tar emot ett objekt och en pekare till en medlemsfunktion.

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

Syntaxen för funktionsanropsoperatorn är också användbar att se. Den visar vad ombudets parametrar måste vara. Som du ser matchar syntaxen för funktionsanropsoperatorn i det här fallet parametrarna för vår 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;

Om du inte utför mycket arbete i händelsehanteraren kan du använda en lambda-funktion i stället för en medlemsfunktion. Återigen kanske det inte är uppenbart från kodexemplet nedan, men ett RoutedEventHandler-ombud skapas från en lambda-funktion som återigen måste matcha syntaxen för funktionsanropsoperatorn som vi diskuterade ovan.

MainPage::MainPage()
{
    InitializeComponent();

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

Du kan välja att vara lite mer explicit när du skapar ditt ombud. Om du till exempel vill skicka runt den eller använda den mer än en gång.

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

Återkalla ett registrerat ombud

När du registrerar ett ombud returneras vanligtvis en token till dig. Därefter kan du använda den token för att återkalla ditt ombud. vilket innebär att ombudet avregistreras från händelsen och inte anropas om händelsen aktiveras igen.

För enkelhetens skull visade inget av kodexemplen ovan hur du gör det. Men i nästa kodexempel lagrar strukturen token i sin privata datamedlem och avregistrerar sin hanterare i destruktorn.

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

I stället för en stark referens, som i exemplet ovan, kan du lagra en svag referens till knappen (se Starka och svaga referenser i C++/WinRT).

När du registrerar ett ombud kan du också ange winrt::auto_revoke (vilket är ett värde av typen winrt::auto_revoke_t) för att begära en händelse-återkallare (av typen winrt::event_revoker). Återkallaren för händelsen har en svag referens till händelsekällan (objektet som utlöser händelsen) åt dig. Du kan återkalla den manuellt genom att anropa medlemsfunktionen event_revoker::revoke; men event revokern anropar den funktionen automatiskt när den går ur scope. Funktionen återkalla kontrollerar om händelsekällan fortfarande finns och återkallar i så fall ombudet. I det här exemplet behöver du inte lagra händelsekällan och inget behov av en destructor.

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

Nedan visas syntaxblocket från dokumentationsavsnittet för händelsen ButtonBase::Click . Den visar de tre olika funktionerna för registrering och återkallande. Du kan se exakt vilken typ av händelse-återkallare du behöver deklarera från den tredje överlagringen. Du kan också skicka samma typer av delegater till både register- och revoke med event_revoker-överlagringarna.

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

Du kan överväga att återkalla hanterare i ett sidnavigeringsscenario. Om du flera gånger navigerar till en sida och sedan backar ur kan du återkalla alla hanterare när du navigerar bort från sidan. Om du använder samma sidinstans igen kan du också kontrollera värdet för din token och bara registrera om den ännu inte har angetts (if (!m_token){ ... }). Ett tredje alternativ är att lagra en händelseåterkallare i sidan som en medlemsvariabel. Och ett fjärde alternativ, som beskrivs senare i det här ämnet, är att fånga en stark eller svag referens till det här objektet i din lambda-funktion.

Om ombudet för automatisk återkallande inte kan registrera sig

Om du försöker ange winrt::auto_revoke när du registrerar en delegat, och du får ett winrt::hresult_no_interface-undantag, innebär det vanligtvis att händelsekällan inte stöder svaga referenser. Det är en vanlig situation i namnområdet Microsoft.UI.Composition, till exempel. I det här fallet kan du inte använda funktionen för automatisk återkallande. Du måste återgå till att manuellt återkalla dina händelsehanterare.

Delegattyper för asynkrona åtgärder och operationer

Exemplen ovan använder ombudstypen RoutedEventHandler , men det finns naturligtvis många andra ombudstyper. Till exempel har asynkrona åtgärder och operationer (med och utan förloppsindikering) slutförandehändelser och/eller förloppshändelser som förväntar sig delegater av motsvarande typ. Förloppshändelsen för en asynkron åtgärd med förlopp (vilket är allt som implementerar IAsyncOperationWithProgress) kräver till exempel ett ombud av typen AsyncOperationProgressHandler. Här är ett kodexempel på hur du skriver en delegat av den här typen med hjälp av en lambda-funktion. Exemplet visar också hur du definierar en AsyncOperationWithProgressCompletedHandler-delegat.

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

Som kommentaren om "coroutine" ovan antyder kommer du förmodligen att tycka att det känns mer naturligt att använda korutiner i stället för att använda en delegat med slutförandehändelserna för asynkrona åtgärder och operationer. Mer information och kodexempel finns i Samtidighet och asynkrona åtgärder med C++/WinRT.

Om du använder delegater i stället för en korutin, kan du välja en enklare syntax.

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

Delegattyper som returnerar ett värde

Vissa delegattyper måste själva returnera ett värde. Ett exempel är ListViewItemToKeyHandler, som returnerar en sträng. Här är ett exempel på hur du redigerar ett ombud av den typen (observera att lambda-funktionen returnerar ett värde).

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

Åtkomst till den här pekaren på ett säkert sätt med ett ombud för händelsehantering

Om du hanterar en händelse med ett objekts medlemsfunktion, eller inifrån en lambda-funktion inuti ett objekts medlemsfunktion, måste du tänka på händelsemottagarens relativa livslängd (objektet som hanterar händelsen) och händelsekällan (objektet som lyfter händelsen). Mer information och kodexempel finns i Starka och svaga referenser i C++/WinRT.

Viktiga API:er

• winrt::auto_revoke_t marker struct
• winrt::implements::get_weak function
• winrt::implements::get_strong funktion

Relaterade ämnen

• Skapa händelser i C++/WinRT
• Samtidighet och asynkrona åtgärder med C++/WinRT
• Starka och svaga referenser i C++/WinRT