XAML egyéni (sablonos) vezérlők C++/WinRT használatával

A Windows App SDK egyik leghatékonyabb funkciója a felhasználói felületi (UI) verem által biztosított rugalmasság, amellyel egyéni vezérlőket hozhat létre az XAML-vezérlő típusa alapján. Az XAML felhasználói felület keretrendszer olyan funkciókat biztosít, mint az egyéni függőségi tulajdonságok , a csatolt tulajdonságok és a vezérlősablonok, amelyek megkönnyítik a funkciókban gazdag és testreszabható vezérlők létrehozását. Ez a témakör végigvezeti egy egyéni (sablonalapú) vezérlő C++/WinRT használatával történő létrehozásának lépésein.

Üres alkalmazás létrehozása (BgLabelControlApp)

Először hozzon létre egy új projektet a Microsoft Visual Studióban. Hozzon létre egy Blank App, Packaged (WinUI 3 in Desktop) C++-projektet, állítsa a nevét erre: BgLabelControlApp, és (hogy a mappaszerkezet megfeleljen az útmutatónak) győződjön meg arról, hogy az A megoldás és a projekt elhelyezése ugyanabban a könyvtárban jelölőnégyzet nincs bejelölve. A Windows SDK legújabb általánosan elérhető (azaz nem előzetes verziójú) verzióját célozza meg.

A témakör egy későbbi szakaszában a rendszer a projekt összeállítására fogja irányítani (de addig ne építsen).

Létrehozunk egy új osztályt, amely egy egyéni (sablonalapú) vezérlőt jelöl. Az osztályt ugyanabban a fordítási egységben hozzuk létre és használjuk. De szeretnénk ezt az osztályt XAML-jelölőnyelvből példányosítani, ezért runtime osztály lesz. És a C++/WinRT-t fogjuk használni mind a létrehozására, mind a használatára.

Az új futtatókörnyezeti osztály elkészítésének első lépése egy új Midl-fájl (.idl) elem hozzáadása a projekthez. Nevezze el a következőképpen: BgLabelControl.idl. Törölje a modul alapértelmezett tartalmát BgLabelControl.idl, és illessze be ezt a futtatókörnyezeti osztály deklarációját.

// BgLabelControl.idl
namespace BgLabelControlApp
{
    runtimeclass BgLabelControl : Microsoft.UI.Xaml.Controls.Control
    {
        BgLabelControl();
        static Microsoft.UI.Xaml.DependencyProperty LabelProperty{ get; };
        String Label;
    }
}

A fenti lista a függőségi tulajdonság (DP) deklarálásakor követendő mintát mutatja. Minden DP két részből áll. Először egy DependencyProperty típusú írásvédett statikus tulajdonságot deklarálsz. A neve az Ön DP-jének neve, valamint a Property. Ezt a statikus tulajdonságot fogja használni a megvalósításban. Másodszor deklarál egy olvasásra és írásra alkalmas példánytulajdonságot a DP típusával és nevével. Ha csatolt tulajdonságot (DP helyett) szeretne létrehozni, tekintse meg a kódpéldákat az Egyéni csatolt tulajdonságokban.

Mentse a fájlt. A projekt jelenleg nem készül el a befejezésig, de az összeállítás most hasznos dolog, mert létrehozza a forráskódfájlokat, amelyekben implementálni fogja a BgLabelControl futtatókörnyezeti osztályt. Tehát most nyugodtan indítsa el a fordítást (az ebben a szakaszban várható fordítási hibák egy „unresolved external symbol” hibához kapcsolódnak).

A buildelési folyamat során az midl.exe eszköz egy Windows-futtatókörnyezet metaadatfájl (\BgLabelControlApp\Debug\BgLabelControlApp\Unmerged\BgLabelControl.winmd) létrehozásához fut, amely leírja a futtatókörnyezeti osztályt. Ezután az cppwinrt.exe eszköz futtatásával forráskódfájlokat hozhat létre a futtatókörnyezeti osztály létrehozásához és használatához. Ezek a fájlok csonkokat tartalmaznak az IDL-ben deklarált BgLabelControl futtatókörnyezeti osztály implementálásának megkezdéséhez. Azok a csonkok: \BgLabelControlApp\BgLabelControlApp\Generated Files\sources\BgLabelControl.h és BgLabelControl.cpp.

Másolja a csonkfájlokat, BgLabelControl.h és BgLabelControl.cpp, a \BgLabelControlApp\BgLabelControlApp\Generated Files\sources\ könyvtárból a projektmappába, azaz a \BgLabelControlApp\BgLabelControlApp\ mappába. A Megoldáskezelő ablakban győződjön meg arról, hogy az Összes fájl megjelenítése be van kapcsolva. Kattintson az egér jobb gombjával a másolt csonkfájlokra, majd válassza a Projektbe foglalás parancsot.

A(z) BgLabelControl.h és BgLabelControl.cpp tetején megjelenik egy static_assert, amelyet el kell távolítania. Most a projekt létrejön.

A BgLabelControl egyéni vezérlőosztály implementálása

Most pedig nyissuk meg a \BgLabelControlApp\BgLabelControlApp\BgLabelControl.h és BgLabelControl.cpp elemeket, és valósítsuk meg a futásidejű osztályunkat. Ebben BgLabelControl.ha mezőben módosítsa a konstruktort az alapértelmezett stíluskulcs beállítására, implementálja a Label and LabelProperty elemet, adjon hozzá egy OnLabelChanged nevű statikus eseménykezelőt a függőségi tulajdonság értékének módosításához, és adjon hozzá egy privát tagot a LabelProperty háttérmezőjének tárolásához.

Miután hozzáadta őket, a BgLabelControl.h így néz ki. A kódlista másolásával és beillesztésével lecserélheti a fájl tartalmát BgLabelControl.h.

// BgLabelControl.h
#pragma once
#include "BgLabelControl.g.h"

namespace winrt::BgLabelControlApp::implementation
{
    struct BgLabelControl : BgLabelControlT<BgLabelControl>
    {
        BgLabelControl() { DefaultStyleKey(winrt::box_value(L"BgLabelControlApp.BgLabelControl")); }

        winrt::hstring Label()
        {
            return winrt::unbox_value<winrt::hstring>(GetValue(m_labelProperty));
        }

        void Label(winrt::hstring const& value)
        {
            SetValue(m_labelProperty, winrt::box_value(value));
        }

        static Microsoft::UI::Xaml::DependencyProperty LabelProperty() { return m_labelProperty; }

        static void OnLabelChanged(Microsoft::UI::Xaml::DependencyObject const&, Microsoft::UI::Xaml::DependencyPropertyChangedEventArgs const&);

    private:
        static Microsoft::UI::Xaml::DependencyProperty m_labelProperty;
    };
}
namespace winrt::BgLabelControlApp::factory_implementation
{
    struct BgLabelControl : BgLabelControlT<BgLabelControl, implementation::BgLabelControl>
    {
    };
}

Ebben BgLabelControl.cppa szakaszban definiálja az ehhez hasonló statikus tagokat. A kódlista másolásával és beillesztésével lecserélheti a fájl tartalmát BgLabelControl.cpp.

// BgLabelControl.cpp
#include "pch.h"
#include "BgLabelControl.h"
#include "BgLabelControl.g.cpp"

namespace winrt::BgLabelControlApp::implementation
{
    Microsoft::UI::Xaml::DependencyProperty BgLabelControl::m_labelProperty =
        Microsoft::UI::Xaml::DependencyProperty::Register(
            L"Label",
            winrt::xaml_typename<winrt::hstring>(),
            winrt::xaml_typename<BgLabelControlApp::BgLabelControl>(),
            Microsoft::UI::Xaml::PropertyMetadata{ winrt::box_value(L"default label"), Microsoft::UI::Xaml::PropertyChangedCallback{ &BgLabelControl::OnLabelChanged } }
    );

    void BgLabelControl::OnLabelChanged(Microsoft::UI::Xaml::DependencyObject const& d, Microsoft::UI::Xaml::DependencyPropertyChangedEventArgs const& /* e */)
    {
        if (BgLabelControlApp::BgLabelControl theControl{ d.try_as<BgLabelControlApp::BgLabelControl>() })
        {
            // Call members of the projected type via theControl.

            BgLabelControlApp::implementation::BgLabelControl* ptr{ winrt::get_self<BgLabelControlApp::implementation::BgLabelControl>(theControl) };
            // Call members of the implementation type via ptr.
        }
    }
}

Ebben az útmutatóban nem fogjuk használni az OnLabelChanged parancsot. Azért van ott, hogy láthassa, hogyan kell egy függőségi tulajdonságot tulajdonságváltozási visszahívással regisztrálni. Az OnLabelChanged implementációja azt is bemutatja, hogyan lehet származtatott előrejelzett típust lekérni egy alapvetített típusból (ebben az esetben a tervezett alaptípus a DependencyObject). Bemutatja, hogyan szerezhet be mutatót arra a típusra, amely megvalósítja a tervezett típust. Ez a második művelet természetesen csak abban a projektben lesz lehetséges, amely megvalósítja a tervezett típust (vagyis a futtatókörnyezeti osztályt megvalósító projektet).

A BgLabelControl alapértelmezett stílusának megtervezése

Konstruktorában BgLabelControl beállítja magának az alapértelmezett stíluskulcsot. De mi az alapértelmezett stílus? Az egyéni (sablonalapú) vezérlőknek alapértelmezett stílussal kell rendelkezniük – amely egy alapértelmezett vezérlősablont tartalmaz –, amelyet arra az esetre használhat, ha a vezérlő fogyasztója nem állít be stílust és/vagy sablont. Ebben a szakaszban hozzáadunk egy jelölőfájlt a projektünkhöz, amely tartalmazza az alapértelmezett stílusunkat.

Győződjön meg arról, hogy Az összes fájl megjelenítése továbbra is be van kapcsolva (Megoldáskezelő). A projektcsomópont alatt hozzon létre egy új mappát (nem szűrőt, hanem egy mappát), és nevezze el "Témák" néven. Themes alatt adjon hozzá egy új, Visual C++>XAML>XAML View típusú elemet, és nevezze el „Generic.xaml”-nek. A mappa- és fájlneveknek így kell lenniük ahhoz, hogy az XAML-keretrendszer megtalálja az egyéni vezérlő alapértelmezett stílusát. Törölje a fájl alapértelmezett tartalmát Generic.xaml, és illessze be az alábbi korrektúrát.

<!-- \Themes\Generic.xaml -->
<ResourceDictionary
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:local="using:BgLabelControlApp">

    <Style TargetType="local:BgLabelControl" >
        <Setter Property="Template">
            <Setter.Value>
                <ControlTemplate TargetType="local:BgLabelControl">
                    <Grid Width="100" Height="100" Background="{TemplateBinding Background}">
                        <TextBlock HorizontalAlignment="Center" VerticalAlignment="Center" Text="{TemplateBinding Label}"/>
                    </Grid>
                </ControlTemplate>
            </Setter.Value>
        </Setter>
    </Style>
</ResourceDictionary>

Ebben az esetben az alapértelmezett stíluskészletek egyetlen tulajdonsága a vezérlősablon. A sablon egy négyzetből (amelynek háttere az XAML-vezérlőtípus összes példányához tartozó Háttér tulajdonsághoz van kötve) és egy szövegelemből (amelynek szövege a BgLabelControl::Label dependency tulajdonsághoz van kötve).

Adja hozzá a(z) BgLabelControl példányát a fő felhasználói felület oldalához

Nyissa meg a MainPage.xamlfájlt, amely tartalmazza a fő felhasználói felület oldalának XAML jelölését. Közvetlenül a Gomb elem (a StackPanel) után adja hozzá a következő jelölést.

<local:BgLabelControl Background="Red" Label="Hello, World!"/>

Adja hozzá a következő include-direktívát az MainPage.h elemhez is, hogy a MainPage típus (a XAML-jelölőnyelv és az imperatív kód fordításának kombinációja) ismerje a BgLabelControl egyéni vezérlőtípust. Ha BgLabelControl szeretne használni egy másik XAML-oldalról, akkor a lap fejlécfájljának is adja hozzá ugyanezt a belefoglalási direktívát. Vagy másik lehetőségként egyszerűen helyezzen el egyetlen belefoglalási irányelvet az előre összeállított fejlécfájlba.

// MainPage.h
...
#include "BgLabelControl.h"
...

Most építse fel és futtassa a projektet. Láthatja, hogy az alapértelmezett vezérlősablon a háttérkeféhez és a címkéhez van kötve a BgLabelControl példányban a jelölésben.

Ez az útmutató egy egyszerű példát mutatott be egy egyéni (sablonos) vezérlőre a C++/WinRT alkalmazásban. Saját egyéni vezérlőit tetszőlegesen gazdagsá és teljes funkcionalitásúvá teheti. Az egyéni vezérlők például olyan bonyolultak lehetnek, mint egy szerkeszthető adatrács, egy videolejátszó vagy a 3D geometria vizualizációja.

Felülírható módszerek implementálása, például MeasureOverride és OnApplyTemplate

Tekintse meg a C++/WinRT használatával történő alaptípus meghívása és felülírása című szakaszt.

Fontos API-k

• Vezérlőosztály
• DependencyProperty osztály
• FrameworkElement osztály
• UIElement osztály

Kapcsolódó témakörök

• Vezérlősablonok
• Egyéni függőségi tulajdonságok