Encapsulage et désencapsulage de valeurs en IInspectable avec C++/WinRT

L’interface IInspectable est l’interface racine de toute classe d’exécution dans Windows Runtime (WinRT). Il s’agit d’une idée analogue à IUnknown se trouvant à la racine de chaque interface et classe COM, et à System.Object se trouvant à la racine de chaque classe du Common Type System.

En d’autres termes, une fonction qui s’attend à ce que IInspectable puisse être passée à une instance de n’importe quelle classe runtime. Mais vous ne pouvez pas passer directement à une telle fonction une valeur scalaire (telle qu’une valeur numérique ou de texte), ni un tableau. Au lieu de cela, une valeur scalaire ou de tableau doit être encapsulée à l’intérieur d’un objet de classe de référence. Cette opération d’encapsulation de la valeur est appelée boxing.

C++/WinRT fournit la fonction winrt::box_value, qui prend une valeur scalaire ou un tableau, et renvoie la valeur encapsulée dans un IInspectable. Pour extraire un IInspectable en une valeur scalaire ou un tableau, il existe la fonction winrt::unbox_value. Pour extraire un IInspectable en valeur scalaire, il existe également la fonction winrt::unbox_value_or.

Exemples d’encapsulage d’une valeur

La fonction d’accesseur LaunchActivatedEventArgs ::Arguments retourne une valeur winrt ::hstring, qui est une valeur scalaire. Nous pouvons boxer cette valeur de type hstring et la passer à une fonction qui attend IInspectable comme suit.

void App::OnLaunched(LaunchActivatedEventArgs const& e)
{
    ...
    rootFrame.Navigate(winrt::xaml_typename<BlankApp1::MainPage>(), winrt::box_value(e.Arguments()));
    ...
}

Pour définir la propriété de contenu d’un bouton XAML, vous appelez la fonction button ::Content mutator. Pour définir la propriété de contenu sur une valeur de chaîne, vous pouvez utiliser ce code.

Button().Content(winrt::box_value(L"Clicked"));

Tout d’abord, le constructeur de conversion hstring convertit le littéral de chaîne en hstring. Ensuite, la surcharge de winrt::box_value qui prend une valeur de type hstring est appelée.

Exemples de désencapsulation d’un IInspectable

Dans vos propres fonctions qui attendent IInspectable, vous pouvez utiliser winrt::unbox_value pour extraire la valeur, et vous pouvez utiliser winrt::unbox_value_or pour extraire la valeur avec une valeur par défaut. Vous pouvez également utiliser try_as pour extraire la valeur dans un std::optional.

void Unbox(winrt::Windows::Foundation::IInspectable const& object)
{
    hstring hstringValue = unbox_value<hstring>(object); // Throws if object is not a boxed string.
    hstringValue = unbox_value_or<hstring>(object, L"Default"); // Returns L"Default" if object is not a boxed string.
    float floatValue = unbox_value_or<float>(object, 0.f); // Returns 0.0 if object is not a boxed float.
    std::optional<int> optionalInt = object.try_as<int>(); // Returns std::nullopt if object is not a boxed int.
}

Déterminer le type d’une valeur encapsulée

Si vous recevez une valeur boxée et que vous ne savez pas quel type elle contient (vous devez connaître son type pour la déballer), vous pouvez interroger la valeur boxée sur son interface IPropertyValue, puis appeler Type dessus. Voici un exemple de code.

WINRT_ASSERT est une définition de macro, et elle s’étend à _ASSERTE.

float pi = 3.14f;
auto piInspectable = winrt::box_value(pi);
auto piPropertyValue = piInspectable.as<winrt::Windows::Foundation::IPropertyValue>();
WINRT_ASSERT(piPropertyValue.Type() == winrt::Windows::Foundation::PropertyType::Single);

API importantes

• Interface IInspectable
• modèle de fonction winrt ::box_value
• struct winrt::hstring
• modèle de fonction winrt ::unbox_value
• modèle de fonction winrt ::unbox_value_or