C++/WinRT ile XAML özel (şablonlu) denetimler

Önemli

C++/WinRT ile çalışma zamanı sınıflarını kullanma ve yazma hakkında bilginizi destekleyen temel kavramlar ve terimler için bkz. C++/WinRT ile API'leri kullanma ve C++/WinRT ile API'leri yazma.

Windows Uygulama SDK'sı en güçlü özelliklerinden biri, kullanıcı arabirimi (UI) yığınının XAML Denetim türüne göre özel denetimler oluşturmak için sağladığı esnekliktir. XAML UI çerçevesi, özellik açısından zengin ve özelleştirilebilir denetimler oluşturmayı kolaylaştıran özel bağımlılık özellikleri ve ekli özellikler ve denetim şablonları gibi özellikler sağlar. Bu konu, C++/WinRT ile özel (şablonlu) denetim oluşturma adımlarını gösterir.

Boş Uygulama Oluşturma (BgLabelControlApp)

Microsoft Visual Studio'da yeni bir proje oluşturarak başlayın. C++ projesi için Paketlenmiş (Masaüstünde WinUI 3) adlı boş bir uygulama oluşturun, adını BgLabelControlApp olarak ayarlayın ve (klasör yapınızın izlenecek yol ile eşleşmesi için) Çözümü ve projeyi aynı dizine yerleştir seçeneğinin işaretlenmediğinden emin olun. Windows SDK'sının genel kullanıma sunulan (önizleme değil) en son sürümünü hedefleyin.

Bu konunun ilerleyen bölümlerinden birinde projenizi derlemeniz istenecek (ancak o zamana kadar derlemeyin).

Note

C++/WinRT geliştirmesi için C++/WinRT Visual Studio Uzantısını (VSIX) ve NuGet paketini (birlikte proje şablonu ve derleme desteği sağlayan) yükleme ve kullanma dahil olmak üzere Visual Studio ayarlama hakkında bilgi için bkz. C++/WinRT için Visual Studio desteği.

Özel (şablonlu) denetimi temsil eden yeni bir sınıf yazacağız. Sınıfı aynı derleme birimi içinde hem tanımlıyor hem de kullanıyoruz. Ancak XAML işaretlemesinden bu sınıfın örneğini oluşturabilmek istiyoruz ve bu nedenle bir çalışma zamanı sınıfı olacak. Hem yazmak hem de kullanmak için C++/WinRT kullanacağız.

Yeni bir çalışma zamanı sınıfı yazmanın ilk adımı, projeye yeni bir Midl Dosyası (.idl) öğesi eklemektir. BgLabelControl.idl olarak adlandırın. BgLabelControl.idl öğesinin varsayılan içeriğini silin ve bunun yerine bu çalışma zamanı sınıf bildirimini yapıştırın.

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

Yukarıdaki liste, bağımlılık özelliğini (DP) bildirirken izlediğiniz deseni gösterir. Her bir DP'nin iki parçası vardır. İlk olarak , DependencyProperty türünde salt okunur bir statik özellik bildirirsiniz. Adı, DP'nizin adı ile Özellik sözcüğünün birleşiminden oluşur. Bu statik özelliği uygulamanızda kullanacaksınız. İkincisi, DP'nizin türü ve adıyla bir okuma-yazma örnek özelliği bildirirsiniz. Ekli bir özellik (DP yerine) yazmak istiyorsanız Özel ekli özellikler'deki kod örneklerine bakın.

Note

Kayan nokta türüne sahip bir DP istiyorsanız, bunu double yapın (DoubleMIDL 3.0'da). float türünde bir DP’nin bildirilip uygulanması (Single MIDL’de) ve ardından XAML işaretlemesinde bu DP için bir değer ayarlanması, '<NUMBER>' metninden 'Windows.Foundation.Single' oluşturulamadı hatasına neden olur.

Dosyayı kaydedin. Proje şu anda tamamlanmaya kadar derlenmez, ancak bgLabelControl çalışma zamanı sınıfını uygulayabileceğiniz kaynak kod dosyalarını oluşturduğundan şimdi derlemek yararlı bir işlemdir. Bu nedenle şimdi derleyin (bu aşamada görmeyi bekleyebileceğiniz derleme hataları "çözülmemiş dış simge" ile ilgilidir).

Derleme işlemi sırasında, çalışma zamanı sınıfını midl.exe açıklayan bir Windows Çalışma Zamanı meta veri dosyası (\BgLabelControlApp\Debug\BgLabelControlApp\Unmerged\BgLabelControl.winmd) oluşturmak için araç çalıştırılır. Ardından, cppwinrt.exe çalışma zamanı sınıfınızı yazma ve kullanma konusunda sizi desteklemek üzere kaynak kod dosyaları oluşturmak için araç çalıştırılır. Bu dosyalar, IDL'nizde bildirdiğiniz BgLabelControl çalışma zamanı sınıfını uygulamaya başlamanızı sağlayan saplamalar içerir. Bu saplamalar \BgLabelControlApp\BgLabelControlApp\Generated Files\sources\BgLabelControl.h ve BgLabelControl.cpp'dir.

\BgLabelControlApp\BgLabelControlApp\Generated Files\sources\ konumundan BgLabelControl.h ve BgLabelControl.cpp taslak dosyalarını, yani \BgLabelControlApp\BgLabelControlApp\ olan proje klasörüne kopyalayın. Çözüm Gezgini'daTüm Dosyaları Göster seçeneğinin açık olduğundan emin olun. Kopyaladığınız taslak dosyalarına sağ tıklayın ve Projeye Dahil Et'e tıklayın.

BgLabelControl.h ve BgLabelControl.cpp öğelerinin üst kısmında bir static_assert görürsünüz; bunu kaldırmanız gerekir. Şimdi proje derlenecek.

BgLabelControl özel denetim sınıfını uygulama

Şimdi çalışma zamanı sınıfımızı açıp \BgLabelControlApp\BgLabelControlApp\BgLabelControl.hBgLabelControl.cpp uygulayalım. içinde BgLabelControl.h, oluşturucuyu değiştirerek varsayılan stil anahtarını ayarlayın, Label ve LabelProperty uygulayın, bağımlılık özelliğinin değerindeki değişiklikleri işlemek için OnLabelChanged adlı bir statik olay işleyicisi ekleyin ve LabelProperty için yedekleme alanını depolamak için özel bir üye ekleyin.

Bunları ekledikten sonra, BgLabelControl.h öğeniz şöyle görünür. içeriğini BgLabelControl.hdeğiştirmek için bu kod listesini kopyalayıp yapıştırabilirsiniz.

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

içinde BgLabelControl.cpp, statik üyeleri bu şekilde tanımlayın. içeriğini BgLabelControl.cppdeğiştirmek için bu kod listesini kopyalayıp yapıştırabilirsiniz.

// 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.
        }
    }
}

Bu kılavuzda OnLabelChanged kullanmayacağız. Ama orada bulunmasının nedeni, özellik değiştiğinde tetiklenen bir geri çağırma ile bir bağımlılık özelliğinin nasıl kaydedileceğini görebilmenizdir. OnLabelChanged uygulamasının uygulanması, temel yansıtılan türden türetilmiş bir tür elde etme işlemini de gösterir (temel öngörülen tür, bu örnekte DependencyObject'tir). Daha sonra, yansıtılan türü uygulayan türe ilişkin bir işaretçinin nasıl elde edilebileceğini gösterir. Bu ikinci işlem doğal olarak yalnızca öngörülen türü (çalışma zamanı sınıfını uygulayan proje) uygulayan projede mümkün olacaktır.

Note

Windows SDK sürüm 10.0.17763.0'ı (Windows 10, sürüm 1809) veya daha sonraki bir sürümü yüklemediyseniz, yukarıdaki bağımlılık özelliği değiştirme olayı işleyicisinde winrt::get_self yerine winrt::from_abi çağırmanız gerekir.

BgLabelControl için varsayılan stili tasarlama

Oluşturucusunda BgLabelControl kendisi için varsayılan bir stil anahtarı ayarlar. Peki varsayılan stil nedir ? Özel (şablonlu) denetimin varsayılan bir stile (varsayılan denetim şablonu içeren) sahip olması gerekir. Bu stil, denetimin tüketicisinin stil ve/veya şablon ayarlamaması durumunda kendisini işlemek için kullanılabilir. Bu bölümde projeye varsayılan stilimizi içeren bir işaretleme dosyası ekleyeceğiz.

Tüm Dosyaları Göster seçeneğinin hala açık olduğundan emin olun (Çözüm Gezgini). Proje düğümünüzün altında yeni bir klasör (filtre değil, klasör) oluşturun ve bunu "Temalar" olarak adlandırabilirsiniz. Themes altında, Visual C++>XAML>XAML Görünümü türünde yeni bir öğe ekleyin ve adını "Generic.xaml" olarak belirleyin. XAML çerçevesinin özel denetim için varsayılan stili bulabilmesi için klasör ve dosya adlarının bu şekilde olması gerekir. Generic.xaml öğesinin varsayılan içeriğini silin ve aşağıdaki işaretlemeyi yapıştırın.

<!-- \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>

Bu durumda, varsayılan stilin ayar yaptığı tek özellik denetim şablonudur. Şablon bir kareden (arka planı XAML Denetimi türünün tüm örneklerinin sahip olduğu Background özelliğine bağlı olan) ve bir metin öğesinden (metni BgLabelControl::Label bağımlılık özelliğine bağlı) oluşur.

Ana kullanıcı arabirimi sayfasına BgLabelControl örneği ekleme

ana kullanıcı arabirimi sayfamız için XAML işaretlemesini içeren MainPage.xamlaçın. Düğmesi öğesinin hemen arkasına (StackPanel) aşağıdaki işaretlemeyi ekleyin.

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

Ayrıca, MainPage.h öğesine aşağıdaki include yönergesini ekleyin; böylece MainPage türü (XAML işaretlemesi ile buyruksal kodun derlenmesinin bir birleşimi) BgLabelControl özel denetim türünü tanır. Başka bir XAML sayfasından bgLabelControl kullanmak istiyorsanız, bu sayfanın üst bilgi dosyasına da bu ekleme yönergesini ekleyin. Alternatif olarak, önceden derlenmiş üst bilgi dosyanıza tek bir ekleme yönergesi koymanız da önerilir.

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

Şimdi projeyi oluşturun ve çalıştırın. Varsayılan denetim şablonunun, işaretlemedeki BgLabelControl örneğinin arka plan fırçasına ve etiketine bağlandığını göreceksiniz.

Bu kılavuzda, C++/WinRT'de özel (şablonlu) denetimin basit bir örneği gösterildi. Kendi özel denetimlerinizi rastgele zengin ve tam özellikli yapabilirsiniz. Örneğin, özel denetim düzenlenebilir bir veri kılavuzu, video oynatıcı veya 3B geometri görselleştiricisi gibi karmaşık bir şey biçimini alabilir.

MeasureOverride ve OnApplyTemplate gibi geçersiz kılınabilir yöntemler uygulama

C++/WinRT ile temel türünüzü çağırma ve geçersiz kılma bölümündeki bölüme bakın.

Önemli API'ler

• Denetim sınıfı
• DependencyProperty sınıfı
• FrameworkElement sınıfı
• UIElement sınıfı

İlgili konular

• Denetim şablonları
• Özel bağımlılık özellikleri