Why winrt

This topic demonstrates how to author a Windows Runtime component containing a runtime class that raises events. It also demonstrates an app that consumes the component and handles the events. Concurrency and asynchronous operations. Advanced concurrency and asynchrony. A completion source sample. A property that can be effectively bound to a XAML control is known as an observable property. This topic shows how to implement and consume an observable property, and how to bind a XAML control to it.

A collection that can be effectively bound to a XAML items control is known as an observable collection. This topic shows how to implement and consume an observable collection, and how to bind a XAML items control to it. You can build on the info here to create your own feature-rich and customizable UI controls. Passing parameters into the ABI boundary.

You can gain porting practice and experience by following along with the walkthrough and porting the sample for yourself as you go. The Windows Runtime is a reference-counted system; and in such a system it's important for you to know about the significance of, and distinction between, strong and weak references. Agile objects. Every object in the chain holds a non-delegating IInspectable pointer to the class it composes in order to call methods on composed base class interfaces, including methods on protected interfaces.

Every object in the chain has a pointer to the controlling class for delegating lifetime and identity as well as in order to call methods on overridable interfaces.

Details on protected and overridable interfaces to follow. In that example, an instance of Button aggregates a Control instance, which in turn aggregates a UIElement instance. All three objects have a reference to the Button object for controlling lifetime and identity as well as for querying for overridable interfaces.

Each object has an IInspectable pointer to the object that it composes Button holds a pointer to Control ; Control holds a pointer to UIElement in order to be able to call methods on interfaces implemented on composed classes, including protected interfaces.

A class may not implement any interfaces defined on the class it composes, nor any class in the composition chain, unless the interface is marked as overridable in the composable class. A composable class must be marked with one or more ComposableAttributes. The ComposableAttribute carries a reference to the composition factory interface—whether the factory methods on the composition factory interface can be used for controlling object activation or not—as well as version information.

Details on composition factory interfaces and versioning to follow. A class can be marked with multiple ComposableAttributes—one for every composition factory interface implemented by the class's activation factory.

The JavaScript language projection doesn't support class composition. As such, composable classes, and classes that compose composable classes, should be marked with the WebHostHiddenAttribute indicating that JavaScript should not attempt to project these types. Third-parties can only define classes that compose other composable classes. You may not define your own composable root class. A composable class must define one or more composition factory interfaces, which in turn implement one or more composition factory methods.

Composition factory interfaces are implemented on the class's activation factory. A composition factory interface is used to create composable instances of the class.

A composable factory interface declares zero or more composable factory methods that can be used to activate instances of the class for composition purposes. Note that it is legal to have a composable factory interface with zero factory methods. This implies that the class can be used for composition, but that third-parties may not directly compose the class—the method s to create instances are internal only. A composable class declares whether the factory methods on a given composition factory interface can be used to activate the class directly as a controlling object or not.

Composable factory interfaces marked as public may be used to directly activate a class as a controlling object, as well as indirectly to activate a class as a composed object. Composable factory interfaces marked protected may only be used to indirectly activate a class as a composed object. Composable classes can always be activated as composed objects. A composition factory interface must be exclusiveto the runtime class it is implemented by.

Like an activation factory method, a composition factory method must return an instance of the composable class. A composition factory method may optionally have additional in parameters. If specified, the additional in parameters must occur at the beginning of the method signature, before the mandated parameters listed previously.

The composable factory method returns the newly activated instance as the return value. When a composable class is activated as a controlling class for example, Button in the previous example , the same composable factory methods are used as for activation for composition. This is an indicator to the composable class that it is being activated as a controlling class. The composable factory method returns the controlling class instance as the return value.

Button would in turn activate a Control instance, passing a reference to itself as the outer parameter. Control would in turn activate a UIElement instance, passing the outer reference it received as the outer parameter. The Control factory method would return to Button the newly created Control in the instance parameter as well as a reference to Control 's non-delegating IInspectable in the inner parameter.

The Button composition factory would return to the calling code the newly created Button in the instance parameter, and null for the inner parameter. It's possible for a class to be sometimes activated for composition, and other times activated as the controlling class. For example, if RadioButton composed Button , then Button would be activated for composition when a RadioButton was activated; but activated as the controlling class when Button was activated directly.

In either case, the Control class that Button composes would be activated for composition. A composable class may declare zero or more of its member interfaces to be protected. A non-composable class may not declare member interfaces to be protected. Only code in a class that composes a composable class directly or indirectly may query for and use interfaces that the composable class declares as protected. Code from outside the composition chain may not query for, nor use, interfaces that the composable class declares as protected.

A composable class may declare zero or more of its member interfaces to be overridable. An overridable interface may only be queried for, and used within, a composition chain—similar to the rules about accessing protected interfaces detailed previously. However, where a protected interface may only be implemented by the class that originally declared it, overridable interfaces may be re-implemented by classes that compose the class that implemented the overridable interface.

This pointer returns the implementation of the overridable interface earliest in the composition chain that is, closest to the controlling class instance. A class that wishes to access the overridable interfaces of the class it composes may do so via the non-delegating reference that a composable class holds to its composed class. In that case, classes that derive from UIElement , including both direct Control and indirect Button derivation, would be allowed to implement it.

If Button wants to access its composed class functionality, it can use the non-delegating IInspectable that was returned from the composition factory method to query the base class for that interface. A runtime class optionally has an activation factory. A runtime class must have an activation factory if the class is activatable, composable, or has static interfaces.

The activation factory for a class can be retrieved from the system at runtime via the RoGetActivationFactory Win32 function. Activation Factories must implement the IActivationFactory interface.

However, only classes that support direct activation provide an implementation of IActivationFactory 's single method ActivateInstance. The activation factory must implement all activation factory interfaces, composition factory interfaces, and static interfaces defined on the runtime class. There is no guarantee that language projections maintain a single activation factory instance for the lifetime of the factory.

WinRT class authors who need to save long-lived information for static member access need to store it somewhere outside of the activation factory. While WinRT is primarily an interface-based programming model under the hood, runtime classes provide a class-based programming model that is better aligned to modern, mainstream, object-oriented OO programming languages.

Language projections are expected to project a runtime class as a single entity, rather than as a bag of interfaces that the developer has to deal with separately. To achieve this class-based model, language projections are expected to project type members from a class's member interfaces as direct class members. Language projections are expected to project type members from a class's static interfaces as static class members.

Finally, language projections are expected to project activation methods direct activation as well as interfaces from factory and composable factory interfaces as class constructors. To assist in this class-based projection, metadata for runtime classes specify a class member for all the methods, properties, and events from every interface they implement. Every class member is explicitly tied back to the interface member where it was originally defined.

This allows language projections to expose the class as a single entity, handling all the interface querying and reference counting under the covers on behalf of the developer. By default, every implemented interface member is projected as a class member. However, because runtime classes can implement multiple independent interfaces and version over time versioning details to follow , it is possible for there to be name collisions for members defined on different interfaces implemented by a single runtime class.

When collisions occur, default class member projection is impossible. If collisions occur across interfaces added in separate versions, the colliding member from the earliest version is projected as a class member. When collisions occur across interfaces added in the same version, none of the colliding members are projected as class members. Note, methods with colliding names are permitted so long as all the versions are of different arity as described in Method overloading.

Interface members that are not projected as class members must be made available to developers. Typically, this is a done by a casting or dynamic lookup operator, allowing the developer to specify the specific interface and method they want to invoke. In order to resolve method name collisions, runtime classes may specify alternative names for methods on the member and static interfaces they implement. This alternative name is used by the language projection to provide disambiguated access to colliding method names from a class instance.

While the runtime class may provide an alternative method name, the method signature, parameters, and any attributes attached to the method or its attributes must still match the original interface definition exactly. Since direct activation, factory methods, and composition factory methods are projected as class constructors, they are all projected on the runtime class as if they have the same name. All methods across all factory interfaces must have unique signatures, should favor arity -based overloading over type-based overloading, and must use the DefaultOverloadAttribute to disambiguate factory methods of the same arity.

Runtime classes are additively versionable. Subsequent versions of a given runtime class may specify additional interfaces of all types, with further details on individual interface types below. Pre-existing interfaces specified by a class may never be removed or changed without breaking backwards compatibility. Member interfaces on runtime classes are additively versionable. Subsequent versions of a given runtime class may implement additional member interfaces, even if the class had never implemented member interfaces previously.

Subsequent versions of a given composable runtime class may implement additional protected and overridable interfaces. Interfaces implemented by a runtime class optionally carry the VersionAttribute to distinguish when specific interfaces were added to the runtime class type. Interface implementation values without a VersionAttribute are considered to have the same version value as the enclosing runtime class type.

Static interfaces on runtime classes are additively versionable. Subsequent versions of a given runtime class may implement additional static interfaces, even if the class had never implemented static interfaces previously. The StaticAttribute includes a UInt32 parameter for version number, which defines the version of Windows that added that activation support. Activation support for runtime classes is additively versionable.

Subsequent versions of a given runtime class may implement additional activation mechanisms, even if the class had never implemented an activation mechanism.

Note, composable classes are not activatable, and thus may not add activation support. Note that a class that supports direct activation may only add new factory activation interfaces. A class that previously only supported factory activation may add direct activation support as well as new factory activation interfaces. The ActivatableAttribute includes a UInt32 parameter for version number.

The version number for the ActivatableAttribute defines the version of Windows that added that activation support. Composition support for runtime classes is additively versionable. Subsequent versions of a given composable runtime class may implement additional composition mechanisms, provided the class was defined as composable when it was created. Composable classes may not add activation support.

The ComposableAttribute includes a UInt32 parameter for version number. The version number for the ComposableAttribute defines the version of Windows that added that composition support. WinRT supports the definition of custom metadata attributes. All constructs in the WinRT type system can carry custom metadata attributes. This includes all named types enums, structs, delegates, interfaces, classes, etc. Custom attributes are named like other WinRT types. However, they are not activatable.

They are purely a data construct. Custom attributes define a data schema of either positional parameters or named fields. A custom attribute may not use both positional parameters and named fields—it must choose one or the other. The types of a custom attribute's parameters and fields are limited to the WinRT fundamental types, enums, and references to other WinRT types. No other parameter or field type is allowed. Custom attributes that use positional parameters must define one or more valid sets of positional parameters.

Each set must specify zero or more positional parameters. An instance of the custom attribute must specify a single set of positional parameters as well as data for each positional parameter in the selected set. A custom attribute that uses named fields specifies zero fields with names and types. An attribute may specify the types of WinRT type constructs that it may be associated with via the AttributeUsageAttribute. You can point the cppwinrt. Windows Runtime metadata.

By pointing cppwinrt. For a runtime class, you just describe your types in an IDL file, and midl. For a list of customization options for the cppwinrt. Then use those stub type definitions for reference to implement your local runtime classes.

See Factoring runtime classes into Midl files. Core namespace. After building and running, click on an empty space to add a colored square; then click on a colored square to drag it. Uri inside a Win32 MessageBox.

This template demonstrates the midl. In an IDL file, define the runtime classes in your component, their default interface, and any other interfaces they implement. Build the project once to generate module.

Then use those the stub type definitions for reference to implement the runtime classes in your component. Bundle the built Windows Runtime component binary and its. We recommend that you install or update to the latest version of the VSIX extension. It is configured to update itself by default. If you do that, and you have projects that were created with a version of the VSIX extension earlier than 1.

If you don't update, then you'll still find the info in this section useful. The info below describes important differences regarding the behavior and configuration of projects created with or upgraded to work with earlier versions. If your project was created with a version of the VSIX extension earlier than 1.