Tag Archives: UWP

Configure your app to start at log-in

For a long time, desktop PC users have been able to configure Win32 apps to start at startup or user log-in. This has also been possible for Desktop Bridge apps since the Windows 10 Anniversary Update (v10.0.14393.0). We’ve now extended this feature to allow regular Universal Windows Apps to take part in this also. This is available in Insider builds from Build 16226 onwards, along with the corresponding SDK. In this post, we’ll look at the code changes you need to make in your manifest and in your App class to handle the startup scenario, and how your app can work with the user to respect their choices.

Here’s a sample app, called TestStartup – the app offers a button to request enabling the startup behavior, and reports current status. Typically, you’d put this kind of option into a settings page of some kind in your app.

The first thing to note is that you must use the windows.startupTask Extension in your app manifest under the Extensions node, which is a child of the Application node. This is documented here. The same Extension declaration is used for both Desktop Bridge and regular UWP apps – but there are some differences.

  • Desktop Bridge is only available on Desktop, so it uses a Desktop-specific XML namespace. The new UWP implementation is designed for use generally on UWP, so it uses a general UAP namespace (contract version 5) – although to be clear, it is currently still only actually available on Desktop.
  • The Desktop Bridge EntryPoint must be “Windows.FullTrustApplication,” whereas for regular UWP it is the fully-qualified namespace name of your App class.
  • Desktop Bridge apps can set the Enabled attribute to true, which means that the app will start at startup without the user having to manually enable it. Conversely, for regular UWP apps this attribute is ignored, and the feature is implicitly set to “disabled.” Instead, the user must first launch the app, and the app must request to be enabled for startup activation.
  • For Desktop Bridge apps, multiple startupTask Extensions are permitted, each one can use a different Executable. Conversely, for regular UWP apps, you would have only one Executable and one startupTask Extension.
Desktop Bridge App UWP App

xmlns:desktop="http://schemas.microsoft.com/
appx/manifest/desktop/windows10"


xmlns:uap5="http://schemas.microsoft.com/
appx/manifest/uap/windows10/5"


<desktop:Extension
  Category="windows.startupTask"
  Executable="MyDesktopBridgeApp.exe"
  EntryPoint="Windows.FullTrustApplication">
  <desktop:StartupTask
    TaskId="MyStartupId"
    Enabled="false"
    DisplayName="Lorem Ipsum" />
</desktop:Extension>


<uap5:Extension
  Category="windows.startupTask"
  Executable="TestStartup.exe"
  EntryPoint="TestStartup.App">
  <uap5:StartupTask
    TaskId="MyStartupId"
    Enabled="false"
    DisplayName="Lorem Ipsum" />
</uap5:Extension>

For both Desktop Bridge apps and regular UWP apps, the user is always in control, and can change the Enabled state of your startup app at any time via the Startup tab in Task Manager:

Also for both app types, the app must be launched at least once before the user can change the Disabled/Enabled state. This is potentially slightly confusing: if the user doesn’t launch the app and then tries to change the state to Enabled in Task Manager, this will seem to be set. However, if they then close Task Manager and re-open it, they will see that the state is still Disabled. What’s happening here is that Task Manager is correctly persisting the user’s choice of the Enabled state – but this won’t actually allow the app to be activated at startup unless and until the app is launched at least once first – hence the reason it is reported as Disabled.

In your UWP code, you can request to be enabled for startup. To do this, use the StartupTask.GetAsync method to initialize a StartupTask object (documented here) – passing in the TaskId you specified in the manifest – and then call the RequestEnableAsync method. In the test app, we’re doing this in the Click handler for the button. The return value from the request is the new (possibly unchanged) StartupTaskState.


async private void requestButton_Click(object sender, RoutedEventArgs e)
{
    StartupTask startupTask = await StartupTask.GetAsync("MyStartupId");
    switch (startupTask.State)
    {
        case StartupTaskState.Disabled:
            // Task is disabled but can be enabled.
            StartupTaskState newState = await startupTask.RequestEnableAsync();
            Debug.WriteLine("Request to enable startup, result = {0}", newState);
            break;
        case StartupTaskState.DisabledByUser:
            // Task is disabled and user must enable it manually.
            MessageDialog dialog = new MessageDialog(
                "I know you don't want this app to run " +
                "as soon as you sign in, but if you change your mind, " +
                "you can enable this in the Startup tab in Task Manager.",
                "TestStartup");
            await dialog.ShowAsync();
            break;
        case StartupTaskState.DisabledByPolicy:
            Debug.WriteLine(
                "Startup disabled by group policy, or not supported on this device");
            break;
        case StartupTaskState.Enabled:
            Debug.WriteLine("Startup is enabled.");
            break;
    }
}

Because Desktop Bridge apps have a Win32 component, they run with a lot more power than regular UWP apps generally. They can set their StartupTask(s) to be Enabled in the manifest and do not need to call the API. For regular UWP apps, the behavior is more constrained, specifically:

  • The default is Disabled, so in the normal case, the user must run the app at least once explicitly – this gives the app the opportunity to request to be enabled.
  • When the app calls RequestEnableAsync, this will show a user-prompt dialog for UWP apps (or if called from a UWP component in a Desktop Bridge app from the Windows 10 Fall Creators Update onwards).
  • StartupTask includes a Disable method. If the state is Enabled, the app can use the API to set it to Disabled. If the app then subsequently requests to enable again, this will also trigger the user prompt.
  • If the user disables (either via the user prompt, or via the Task Manager Startup tab), then the prompt is not shown again, regardless of any requests from the app. The app can of course devise its own user prompts, asking the user to make manual changes in Task Manager – but if the user has explicitly disabled your startup, you should probably respect their decision and stop pestering them. In the sample code above, the app is responding to DisabledByUser by popping its own message dialog – you can obviously do this if you want, but it should be emphasized that there’s a risk you’ll just annoy the user.
  • If the feature is disabled by local admin or group policy, then the user prompt is not shown, and startup cannot be enabled. The existing StartupTaskState enum has been extended with a new value, DisabledByPolicy. When the app sees DisabledByPolicy, it should avoid re-requesting that their task be enabled, because the request will never be approved until the policy changes.
  • Platforms other than Desktop that don’t support startup tasks also report DisabledByPolicy.

Where a request triggers a user-consent prompt (UWP apps only), the message includes the DisplayName you specified in your manifest. This prompt is not shown if the state is DisabledByUser or DisabledByPolicy.

If your app is enabled for startup activation, you should handle this case in your App class by overriding the OnActivated method. Check the IActivatedEventArgs.Kind to see if it is ActivationKind.StartupTask, and if so, case the IActivatedEventArgs to a StartupTaskActivatedEventArgs. From this, you can retrieve the TaskId, should you need it. In this test app, we’re simply passing on the ActivationKind as a string to MainPage.


protected override void OnActivated(IActivatedEventArgs args)
{
    Frame rootFrame = Window.Current.Content as Frame;
    if (rootFrame == null)
    {
        rootFrame = new Frame();
        Window.Current.Content = rootFrame;
    }

    string payload = string.Empty;
    if (args.Kind == ActivationKind.StartupTask)
    { 
        var startupArgs = args as StartupTaskActivatedEventArgs;
        payload = ActivationKind.StartupTask.ToString();
    }

    rootFrame.Navigate(typeof(MainPage), payload);
    Window.Current.Activate();
}

Then, the MainPage OnNavigatedTo override tests this incoming string and uses it to report status in the UI.


protected override void OnNavigatedTo(NavigationEventArgs e)
{
    string payload = e.Parameter as string;
    if (!string.IsNullOrEmpty(payload))
    {
        activationText.Text = payload;

        if (payload == "StartupTask")
        {
            requestButton.IsEnabled = false;
            requestResult.Text = "Enabled";
            SolidColorBrush brush = new SolidColorBrush(Colors.Gray);
            requestResult.Foreground = brush;
            requestPrompt.Foreground = brush;
        }
    }
}

Note that when your app starts at startup, it will start minimized in the taskbar. In this test app, when brought to normal window mode, the app reports the ActivationKind and StartupTaskState:

Using the windows.startupTask manifest Extension and the StartupTask.RequestEnableAsync API, your app can be configured to start at user log-in. This can be useful for apps which the user expects to use heavily, and the user has control over this – but it is still a feature that you should use carefully. You should not use the feature if you don’t reasonably expect the user to want it for your app – and you should avoid repeatedly prompting them once they’ve made their choice. The inclusion of a user-prompt puts the user firmly in control, which is an improvement over the older Win32 model.

Sample Code here.

Working with Brushes and Content – XAML and Visual Layer Interop, Part One

The Composition APIs empower Universal Windows Platform (UWP) developers to do beautiful and powerful things when they access the Visual Layer. In the Windows 10 Creators Update, we made working with the Visual Layer much easier with new, powerful APIs.

In this blog series, we’ll cover some of these improvements in the Creators Update and take a look at the following APIs:

  • In Part 1, today’s post:
    • XamlCompositionBrushBase – easily paint a XAML UIElement with a CompositionBrush
    • LoadedImageSurface – load an image easily and use with Composition APIs
  • In Part 2, we’ll look at:
    • XamlLights – apply lights to your XAML UI with a single line of XAML
    • PointerPositionPropertySet – create 60 FPS animations using pointer position, off the UI thread!
    • Enabling the Translation property – animate a XAML UI Element using Composition animation

If you’d like to review the previously available ElementCompositionPreview APIs, for example working with “hand-in” and “hand-out” Visuals, you can quickly catch up here.

Using XamlCompositionBrushBase

One of the benefits of the new Composition and XAML interop APIs is the ability to use a CompositionBrush to directly paint a XAML UIElement rather than being limited to XAML brushes only. For example, you can create a CompositionEffectBrush that applies a tinted blur to the content beneath and use the brush to paint a XAML rectangle that can be included in the XAML markup

This is accomplished by using the new abstract class XamlCompositionBrushBase available in the Creators Update. To use it, you subclass XamlCompositionBrushBase to create your own XAML Brush that can be used in your markup. As seen the example code below, the XamlCompositionBrushBase exposes a CompositionBrush property that you set with your effect (or any CompositionBrush) and it will be applied to the XAML element.

This effectively replaces the need to manually create SpriteVisuals with SetElementChild for most effect scenarios. In addition to needing less code to create and add an effect to the UI, using a Brush means you get the following added benefits for free:

  • Theming and Styling
  • Binding
  • Resource and Lifetime management
  • Layout aware
  • PointerEvents
  • HitTesting and other XAML-based advantages

Microsoft, as part of the Fluent Design System, has included a few Brushes in the Creators Update that leverage the features of XamlCompositionBrushBase:

Building a Custom Composition Brush

Let’s create a XamlCompositionBrush of our own to see how simple this can be.  Here’s what we’ll create:

To start, let’s create a very simple Brush that applies an InvertEffect to content under it. First, we’ll need to make a public sealed class that inherits from XamlCompositionBrushBase and override two methods:

  • OnConnected
  • OnDisconnected

Let’s dive into the code. First, create your Brush class, which inherits from XamlCompositionBrushBase:


public class InvertBrush : XamlCompositionBrushBase
{
    protected override void OnConnected()
    {
        if (CompositionBrush == null)
        {
            // 1 - Get the BackdropBrush, this gets what is behind the UI element
            var backdrop = Window.Current.Compositor.CreateBackdropBrush();

            // CompositionCapabilities: Are effects supported? If not, return.
            if (!CompositionCapabilities.GetForCurrentView().AreEffectsSupported())
            { 
               return;
            }
                
            // 2 - Create your Effect
            // New-up a Win2D InvertEffect and use the BackdropBrush as its Source
            // Note – To use InvertEffect, you'll need to add the Win2D NuGet package to your project (search NuGet for "Win2D.uwp")
            var invertEffect = new InvertEffect
            {
                Source = new CompositionEffectSourceParameter("backdrop")
            };

            // 3 - Set up the EffectFactory
            var effectFactory = Window.Current.Compositor.CreateEffectFactory(invertEffect);

            // 4 - Finally, instantiate the CompositionEffectBrush
            var effectBrush = effectFactory.CreateBrush();

            // and set the backdrop as the original source 
            effectBrush.SetSourceParameter("backdrop", backdrop);

            // 5 - Finally, assign your CompositionEffectBrush to the XCBB's CompositionBrush property
            CompositionBrush = effectBrush;
         }
    }

    protected override void OnDisconnected()
    {
        // Clean up
        CompositionBrush?.Dispose();
        CompositionBrush = null;
    }
}

There are a few things to call out in the code above.

  • In the OnConnected method, we get a CompositionBackdropBrush. This allows you to easily get the pixels behind the UIElement.
  • We use fallback protection. If the user’s device doesn’t have support for the effect(s), then just return.
  • Next, we create the InvertEffect and use the backdropBrush for the Effect’s Source.
  • Then, we pass the finished InvertEffect to the CompositionEffectFactory.
  • Finally, we get an EffectBrush from the factory and set the XamlCompositionBrushBase.CompositionBrush property with our newly created effectBrush.

Now you can use it in your XAML. For example, let’s apply it to a Grid on top of another Grid with a background image:


<Grid>
    <Grid.Background>
        <ImageBrush ImageSource="ms-appx:///Images/Background.png"/>
    </Grid.Background>
    <Grid Width="300" Height="300" 
               HorizontalAlignment="Center"
               VerticalAlignment="Center">
        <Grid.Background>
            <brushes:InvertBrush />
        </Grid.Background>
    </Grid>
</Grid>

Now that you know the basics of creating a brush, let’s build an animated effect brush next.

Creating a Brush with Animating Effects

Now that you see how simple it is to create a CompositionBrush, let’s create a brush that applies a TemeratureAndTint effect to an image and animate the Temperature value:

We start the same way we did with the simple InvertBrush, but this time we’ll add a DependencyProperty,  ImageUriString, so that we can load an image using LoadedImageSurface in the OnConnected method.


public sealed class ImageEffectBrush : XamlCompositionBrushBase
    {
        private LoadedImageSurface _surface;
        private CompositionSurfaceBrush _surfaceBrush;
 
        public static readonly DependencyProperty ImageUriStringProperty = DependencyProperty.Register(
            "ImageUri",
            typeof(string),
            typeof(ImageEffectBrush),
            new PropertyMetadata(string.Empty, OnImageUriStringChanged)
        );
 
        public string ImageUriString
        {
            get => (String)GetValue(ImageUriStringProperty);
            set => SetValue(ImageUriStringProperty, value);
        }
 
        private static void OnImageUriStringChanged(DependencyObject d, DependencyPropertyChangedEventArgs e)
        {
            var brush = (ImageEffectBrush)d;
            // Unbox and update surface if CompositionBrush exists     
            if (brush._surfaceBrush != null)
            {
                var newSurface = LoadedImageSurface.StartLoadFromUri(new Uri((String)e.NewValue));
                brush._surface = newSurface;
                brush._surfaceBrush.Surface = newSurface;
            }
        }
 
        protected override void OnConnected()
        {
            // return if Uri String is null or empty
            if (string.IsNullOrEmpty(ImageUriString))
                return;
 
            // Get a reference to the Compositor
            Compositor compositor = Window.Current.Compositor;
 
            // Use LoadedImageSurface API to get ICompositionSurface from image uri provided
            _surface = LoadedImageSurface.StartLoadFromUri(new Uri(ImageUriString));
 
            // Load Surface onto SurfaceBrush
            _surfaceBrush = compositor.CreateSurfaceBrush(_surface);
            _surfaceBrush.Stretch = CompositionStretch.UniformToFill;
 
            // CompositionCapabilities: Are Tint+Temperature and Saturation supported?
            bool usingFallback = !CompositionCapabilities.GetForCurrentView().AreEffectsSupported();
            if (usingFallback)
            {
                // If Effects are not supported, Fallback to image without effects
                CompositionBrush = _surfaceBrush;
                return;
            }
 
            // Define Effect graph (add the Win2D.uwp NuGet package to get this effect)
            IGraphicsEffect graphicsEffect = new SaturationEffect
            {
                Name = "Saturation",
                Saturation = 0.3f,
                Source = new TemperatureAndTintEffect
                {
                    Name = "TempAndTint",
                    Temperature = 0,
                    Source = new CompositionEffectSourceParameter("Surface"),
                }
            };
 
            // Create EffectFactory and EffectBrush 
            CompositionEffectFactory effectFactory = compositor.CreateEffectFactory(graphicsEffect, new[] { "TempAndTint.Temperature" });
            CompositionEffectBrush effectBrush = effectFactory.CreateBrush();
            effectBrush.SetSourceParameter("Surface", _surfaceBrush);
 
            // Set EffectBrush to paint Xaml UIElement
            CompositionBrush = effectBrush;
 
            // Trivial looping animation to demonstrate animated effect
            ScalarKeyFrameAnimation tempAnim = compositor.CreateScalarKeyFrameAnimation();
            tempAnim.InsertKeyFrame(0, 0);
            tempAnim.InsertKeyFrame(0.5f, 1f);
            tempAnim.InsertKeyFrame(1, 0);
            tempAnim.Duration = TimeSpan.FromSeconds(5);
            tempAnim.IterationBehavior = AnimationIterationBehavior.Count;
      tempAnim.IterationCount = 10;
             effectBrush.Properties.StartAnimation("TempAndTint.Temperature", tempAnim);
        }
 
        protected override void OnDisconnected()
        {
            // Dispose Surface and CompositionBrushes if XamlCompBrushBase is removed from tree
            _surface?.Dispose();
            _surface = null;
 
            CompositionBrush?.Dispose();
            CompositionBrush = null;
        }
    }

There are some new things here to call out that are different from the InvertBrush:

  • We use the new LoadedImageSurface API to easily load an image in the OnConnected method, but also when the ImageUriString value changes. Prior to Creators Update, this required a hand-in Visual (a SpriteVisual, painted with an EffectBrush, which was handed back into the XAML Visual Tree). See the LoadedImageSurface section later in this article for more details.
  • Notice that we gave the effects a Name value. In particular, TemperatureAndTintEffect, uses the name “TempAndTint.” This is required to animate properties as it is used for the reference to the effect in the AnimatableProperties array that is passed to the effect factory. Otherwise, you’ll encounter a “Malformed animated property name” error.
  • After we assign the CompositionBrush property, we created a simple looping animation to oscillate the value of the TempAndTint from 0 to 1 and back every 5 seconds.

Let’s take a look at an instance of this Brush in markup:


<Grid>
            <Grid.Background>
                <brushes:ImageEffectBrush ImageUriString="ms-appx:///Images/Background.png"/>
            </Grid.Background>
</Grid>

For more information on using XamlCompositionBrushBase, see here. Now, let’s take a closer look at how easy it is now to bring in images to the Visual layer using LoadedImageSurface

Loading images with LoadedImageSurface

With the new LoadedImageSurface class, it’s never been easier to load an image and work with it in the visual layer. The class has the same codec support that Windows 10 has via the Windows Imaging Component (see full list here), thus it supports the following image file types:

  • Joint Photographic Experts Group (JPEG)
  • Portable Network Graphics (PNG)
  • Bitmap (BMP)
  • Graphics Interchange Format (GIF)
  • Tagged Image File Format (TIFF)
  • JPEG XR
  • Icons (ICO)

NOTE: When using an animated GIF, only the first frame will be used for the Visual, as animation is not supported in this scenario.

To load in an image, you can use one of the four factory methods:

As you can see there are two ways to load an image: with a Uri or a Stream. Additionally, you have an option to use an overload to set the size of the image (if you don’t pass in a Size, it will decode to the natural size).


CompositionSurfaceBrush imageBrush = compositor.CreateSurfaceBrush();
LoadedImageSurface loadedSurface = LoadedImageSurface.StartLoadFromUri(new Uri("ms-appx:///Images/Photo.jpg"), new Size(200.0, 200.0));
imageBrush.Surface = loadedSurface;

This is very helpful when you need to load an image that will be used for your CompositionBrush (e.g. CompositionEffectBrush) or SceneLightingEffect (e.g. NormalMap for textures) as you no longer need to manually create a hand-in Visual (a SpriteVisual painted with an EffectBrush). In an upcoming post in this series, we will explore this further using NormalMap images with to create advanced lighting to create unique and compelling materials.

Using LoadedImageSurface with a Composition Island

LoadedImageSurface is also useful when loading an image onto a SpriteVisual inserted in XAML UI using ElementCompositionPreview. For this scenario, you can use the Loaded event to adjust the visual’s properties after the image has finished loading.

Here is an example of using LoadedImageSurface for a CompositionSurfaceBrush, then updating the SpriteVisual’s size with the image’s DecodedSize when the image is loaded:


private SpriteVisual spriteVisual;
private void LoadImage(Uri imageUri)
{
    CompositionSurfaceBrush surfaceBrush = Window.Current.Compositor.CreateSurfaceBrush();

    // You can load an image directly and set a SurfaceBrush's Surface property with it
    var loadedImageSurface = LoadedImageSurface.StartLoadFromUri(imageUri);
    loadedImageSurface.LoadCompleted += Load_Completed;
    surfaceBrush.Surface = loadedImageSurface;

    // We'll use a SpriteVisual for the hand-in visual
    spriteVisual = Window.Current.Compositor.CreateSpriteVisual();
    spriteVisual.Brush = surfaceBrush;

    ElementCompositionPreview.SetElementChildVisual(MyCanvas, spriteVisual);
}

private void Load_Completed(LoadedImageSurface sender, LoadedImageSourceLoadCompletedEventArgs args)
{
    if (args.Status == LoadedImageSourceLoadStatus.Success)
    {
        Size decodedSize = sender.DecodedSize;
        spriteVisual.Size = new Vector2((float)decodedSize.Width, (float)decodedSize.Height);
    }
}

There are some things you should be aware before getting started with LoadedImageSurface. This class makes working with images a lot easier, however you should understand the lifecycle and when images get decoded/sized. We recommend that you take a couple minutes and read the documentation before getting started.

Wrapping up

Using Composition features in your XAML markup is easier than ever. From painting your UIElements with CompositionBrushes and applying lighting, to smooth off-UIThread animations, the power of the Composition API is more accessible than ever.

In the next post, we’ll explore more new APIs like the new Translation property, using XamlLights in your XAML markup and how to create a custom light using the new PointerPositionPropertySet.

Resources

Calling all game devs: The Dream.Build.Play 2017 Challenge is Here!

Dream.Build.Play is back! The long-running indie game development contest was on hiatus for a few years, so it’s high time for it to make a resounding return.

The Dream.Build.Play 2017 Challenge is the new contest: It just launched on June 27, and it challenges you to build a game and submit it by December 31 in one of four categories. We’re not super-picky — you can choose the technology to use just so long as it falls into one of the challenges and that you publish it as a Universal Windows Platform (UWP) game. It’s up to you to build a quality game that people will line up to play.

The four categories are:

Cloud-powered game – Grand Prize: $100,000 USD

Azure Cloud Services hands you a huge amount of back-end power and flexibility, and we think it’s cool (yes, we’re biased). So, here’s your shot of trying Azure out and maybe even win big. Build a game that uses Azure Cloud Services on the backend, like Service Fabric, CosmosDB, containers, VMs, storage and Analytics. Judges will give higher scores to games that use multiple services in creative ways — and will award bonus points for Mixer integration.

PC game – Grand Prize: $50,000 USD

Building on Windows 10, for Windows 10? This is the category for you. Create your best UWP game that lives and breathes on Windows 10 and is available to the more than 450 million users through the Windows Store. It’s simple: Create a game with whatever technology you want and publish it in the Windows Store. We’ll look favorably on games that add Windows 10 features such as Cortana or Inking because we really want to challenge you.

Mixed Reality game – Grand Prize: $50,000

Oh, so you want to enhance this world you live in with something a little…augmented? Virtual? Join us in the Mixed Reality challenge and build a volumetric experience that takes advantage of 3D content in a virtual space. You’ll need to create your game for Windows Mixed Reality, but you can use technology like Unity to get you kickstarted. Oh, and don’t forget the audio to really immerse us in your world.

Console game – Grand Prize: $25,000

Console gamers unite! Want to try your hand at building a game for Xbox? This category is your jam. Your UWP game will be built for the Xbox One console family and must incorporate Xbox Live Creators Program with at least Xbox Live presence. Consideration will be given for games that incorporate more Xbox Live services such as leaderboards and statistics.

There are some important dates to be aware of:

  • June 27: Competition opens for registration
  • August 2: Team formation and game submission period opens
  • December 31: Game submission period closes
  • January 2018: Finalists announced
  • March 2018: Winners awarded

We have big things planned for you. Maybe some additional contests and challenges, maybe some extra-cool prizes for the finalists, maybe some extra-cool interviews and educational materials. Once you register, we’ll keep you updated via email, but also keep an eye on our Windows Developer social media accounts.

As I mentioned earlier, you can pretty much use whatever technology you want. Create something from the ground up in JavaScript or XAML or C++ and DirectX. Leverage one of our great middleware partners like Unity, GameMaker, Cocos2D or Monogame. Or do a bit of both – do your own thing and incorporate Mixer APIs into it, Vungle or any one (or more) of our other partners. The biggest thing we want from you is a fun game that’s so enjoyable for us to play that we forget we’re judging it!

Speaking of that, you might be wondering how we judge the games. We have four “big bucket” criteria for you to aim for:

  • Fun Factor – 40%: Bottom line – your game needs to be fun. That doesn’t mean it has to be cutesy or simple. Fun comes in many forms, but we can’t forget what we’re aiming for here – a great game. Take us for a ride!
  • Innovation – 30%: And while you’re taking us on that ride, surprise us! We’re not looking for a clone of an existing game or a tired theme that has been done a bazillion times before. Mash-up two genres. Take a theme and turn it on its head. Don’t restrict your innovation to the game, but also the technology you’re using and how you’re using it. Think outside the box when you incorporate Windows features, or how you can creatively use a service like Mixer.
  • Production Quality – 20%: Games have to be fun and we want them to be innovative, but if they don’t run, then they’re just not ready to be called a game. This scoring criterion is all about making sure your framerate is right, you have audio where you should, you’ve catered for network instability and more. Give us every opportunity to get to your game and enjoy it the way you intended.
  • Business Viability/Feasibility – 10%: And of course, what’s your plan to engage your gaming customers? Do you have a good revenue-generating plan (e.g., in-app purchases, premium charges, marketing, rollouts, etc.)? That’s stuff you might not normally think about, but we’re gonna make you. Because we care.

If you want to get started with UWP game development, you can try our Game Development Guide.

Want more? Check out the introductory .GAME episode here:

So, what are you waiting for? Get in there and register!

Announcing UWP Community Toolkit 1.5

Today marks the sixth release of the UWP Community Toolkit – all packages are updated to version 1.5. Thanks to the UWP developer community, the UWP Community Toolkit has seen great improvements and stability to the existing controls and services. The community partnership has led to several new additions to this release.

To highlight a few of the new additions, the UWP Community Toolkit now includes:

  1. Menu: A classic control used by traditional desktop applications, adapted for the Universal Windows Platform. As requested by the community on UserVoice, the Menu allows the developer to provide a hierarchical list of menus and submenus that support any input modality and can adapt to the screen size to provide a natural and fluid interaction.
  2. OrbitView: A new ItemsControl that arranges elements around a center element and provides flexibility for size and distance for each element, as well as the ability to show orbits or anchors for each item.
  3. RadialProgressBar: A XAML Control that displays a value within a range using a circular sector that grows clockwise until it becomes a full ring. A fantastic variation of the ProgressBar.
  4. RoundImageEx: Similar to the ImageEx control, the RoundImageEx control downloads and locally caches images asynchronously while showing loading indicators. In addition, the RoundImageEx allows images to be clipped as circles.
  5. ExpressionBuilder: A type-safe way to build powerful composition ExpressionAnimation.
  6. BluetoothLEHelper: The BluetoothLEHelper class provides functionality to easily enumerate, connect to and interact with Bluetooth LE Peripherals.

For a complete overview of what’s new in version 1.5, please read our release notes on GitHub.

The release of Windows 10 Creators Update (build 10.0.15063) has enabled several new APIs that make it possible to improve several controls used in apps targeting the latest update. Therefore, several packages are now targeting the Windows 10 Creators Update and can take advantage of these new APIs. We encourage all developers using the toolkit to update their apps to the latest version of the UWP Community Toolkit.

As a reminder, the UWP Community Toolkit can be used in any UWP app across PC, Xbox One, mobile, HoloLens and Surface Hub devices. You can get started by following this tutorial, or preview the latest features by installing the UWP Community Toolkit Sample App from the Windows Store.

If you would like to contribute, please join us on GitHub!

UWP App Diagnostics

At Build this year, we gave a sneak preview of a set of new APIs designed to provide diagnostic information about running apps. You can see the videos here and here – but note that these were based on a pre-release implementation. So, while the Build videos are still correct on broad functionality, the final API names are almost all slightly different. Plus, we added a couple of extra features after Build.

The final versions for the upcoming release are available in the Insider builds from Build 16226, along with the corresponding SDK.

At a high level, these APIs allow an app to:

  • Enumerate a list of running apps, including UWP apps, Win32 apps, system services and so on.
  • For each app, get process-specific metrics on:
    • Memory usage (private commit and working set).
    • CPU usage.
    • Disk reads and writes.
  • For each UWP app, get additional metrics on:
    • Memory usage (including shared commit) equivalent to the Windows.System.MemoryManager report previously available to an app for its own usage.
    • State info: running, suspending, suspended, not running.
    • Energy quota info: under or over.
    • Enumerate a list of any background tasks that are active for the app, including name, trigger type and entry point.
    • Enumerate all the processes for the app (using an enhancement to the existing Windows.System.Diagnostics.ProcessDiagnosticInfo class that was previously restricted to an app for its own usage).

The API has a simple hierarchical structure:

  • The AppDiagnosticInfo type represents a single app. Callers would normally request either a single AppDiagnosticInfo for the app you’re interested in or a list of AppDiagnosticInfos if you’re interested in multiple apps.

  • Once you’ve gotten hold of an AppDiagnosticInfo for an app you’re interested in, you’d call GetResourceGroups to get a list of AppResourceGroupInfo objects. Each AppResourceGroupInfo corresponds to a resource group. An app can define resource groups in its manifest as a way to organize its components (foreground app, background tasks) into groups for resource management purposes. If you don’t define any explicit resource groups, the system will provide at least one (for the foreground app) plus potentially more (if you have out-of-proc background tasks, for example).

  • From there, you’d call any of the AppResourceGroupInfo methods to get snapshot reports of memory usage, execution and energy quota state, and the app’s running background tasks (if any) via the AppResourceGroupMemoryReport, AppResourceGroupStateReport and AppResourceGroupBackgroundTaskReport classes.

  • And finally, each group exposes a list of ProcessDiagnosticInfo objects.

As you can see from the class diagrams, the AppDiagnosticInfo and ProcessDiagnosticInfo each have a link to the other. This means you can get all the rich process-specific info for any running process and get the UWP-specific info for any process related to a UWP app (including Desktop Bridge apps).

These APIs are intended to support app developers who either need more diagnostic support during their own app development and testing, or who want to build a general-purpose diagnostic app and publish it in the Windows Store. Exposing information about other apps raises potential privacy concerns, so if your app uses these APIs, you’ll need to declare the appDiagnostics capability in your manifest, along with the corresponding namespace declaration:


<Package
  xmlns:rescap="http://schemas.microsoft.com/appx/manifest/foundation/ windows10/restrictedcapabilities"
  IgnorableNamespaces="uap mp rescap">
  ...

  <Capabilities>
    <rescap:Capability Name="appDiagnostics" />
  </Capabilities>
</Package>

This is a restricted capability: If you submit an app with this capability to the Windows Store, this will trigger closer scrutiny. The app must be in the Developer Tools category, and we will examine your app to make sure that it is indeed a developer tool before approving the submission.

At run time, the capability also triggers a user-consent prompt the first time any of the diagnostic APIs are called:

The user is always in control: If permission is denied, then the APIs will only return information about the current app. The prompt is only shown on first use, but the user can change his or her mind any time via the privacy pages in Settings. All apps that use the APIs will be listed here, and the user can toggle permission either globally or on a per-app basis:

Given the richness of the APIs, it’s not too much of a stretch to envisage creating a UWP version of Task Manager. There are a few features that we can’t implement just yet (terminating apps and controlling system services, for example), but certainly most of the data reporting is perfectly possible with the new APIs:

The first thing to do is to request permission to access diagnostics for other apps using AppDiagnosticInfo.RequestAccessAsync. The result could be Denied, Limited (which means you can only get information for the current app package) or Allowed.


DiagnosticAccessStatus diagnosticAccessStatus = 
    await AppDiagnosticInfo.RequestAccessAsync();
switch (diagnosticAccessStatus)
{
    case DiagnosticAccessStatus.Allowed:
        Debug.WriteLine("We can get diagnostics for all apps.");
        break;
    case DiagnosticAccessStatus.Limited:
        Debug.WriteLine("We can only get diagnostics for this app package.");
        break;
}

Then, to emulate Task Manager, you’d start with a list of the ProcessDiagnosticInfo objects for all running processes.


IReadOnlyList<ProcessDiagnosticInfo> processes = ProcessDiagnosticInfo.GetForProcesses();

For each running process, you can extract the top-level process-specific information such as the ExecutableFileName and the ProcessId. You can also get the more detailed process information from each of the three reports for CpuUsage, MemoryUsage and DiskUsage.


if (processes != null)
{
    foreach (ProcessDiagnosticInfo process in processes)
    {
        string exeName = process.ExecutableFileName;
        string pid = process.ProcessId.ToString();

        ProcessCpuUsageReport cpuReport = process.CpuUsage.GetReport();
        TimeSpan userCpu = cpuReport.UserTime;
        TimeSpan kernelCpu = cpuReport.KernelTime;

        ProcessMemoryUsageReport memReport = process.MemoryUsage.GetReport();
        ulong npp = memReport.NonPagedPoolSizeInBytes;
        ulong pp = memReport.PagedPoolSizeInBytes;
        ulong peakNpp = memReport.PeakNonPagedPoolSizeInBytes;
        //...etc

        ProcessDiskUsageReport diskReport = process.DiskUsage.GetReport();
        long bytesRead = diskReport.BytesReadCount;
        long bytesWritten = diskReport.BytesWrittenCount;
        //...etc
    }
}

For any process associated with a UWP app, the IsPackaged property is true. So, for each of these, you can get from the ProcessDiagnosticInfo to the AppDiagnosticInfo. It might seem strange that we can get AppDiagnosticInfos (plural) from a process – but this is to allow for the possibility that a single process is associated with more than one app. That’s an extremely uncommon scenario, but it is possible in the case of VoIP apps where two or more apps in the same package can share a component running in a separate process at run time. In almost all cases, though, there will only be one AppDiagnosticInfo per process.


if (process.IsPackaged)
{
    IList<AppDiagnosticInfo> diagnosticInfos = process.GetAppDiagnosticInfos();
    if (diagnosticInfos != null && diagnosticInfos.Count > 0)
    {
        AppDiagnosticInfo diagnosticInfo = diagnosticInfos.FirstOrDefault();
        if (diagnosticInfo != null)
        {
            IList<AppResourceGroupInfo> groups = diagnosticInfo.GetResourceGroups();
            if (groups != null && groups.Count > 0)
            {

From the AppDiagnosticInfo, you can walk down the hierarchy and get a collection of AppResourceGroupInfos. Then, for each AppResourceGroupInfo, you can get the UWP-specific state and memory information:


AppResourceGroupInfo group = groups.FirstOrDefault();
if (group != null)
{
    string name = diagnosticInfo.AppInfo.DisplayInfo.DisplayName;
    string description = diagnosticInfo.AppInfo.DisplayInfo.Description;
    BitmapImage bitmapImage = await GetLogoAsync(diagnosticInfo);

    AppResourceGroupStateReport stateReport= group.GetStateReport();
    if (stateReport != null)
    {
        string executionStatus = stateReport.ExecutionState.ToString();
        string energyStatus = stateReport.EnergyQuotaState.ToString();
    }

    AppResourceGroupMemoryReport memoryReport = group.GetMemoryReport();
    if (memoryReport != null)
    {
        AppMemoryUsageLevel level = memoryReport.CommitUsageLevel;
        ulong limit = memoryReport.CommitUsageLimit;
        ulong totalCommit = memoryReport.TotalCommitUsage;
        ulong privateCommit = memoryReport.PrivateCommitUsage;
        ulong sharedCommit = totalCommit - privateCommit;
    }
}

Note: to get the packaged logo from the app, there’s a little extra work. You call GetLogo from the AppDisplayInfo to return the data as a stream; if there are multiple logos available, this will return the largest one that is within the specified size.


private async Task<BitmapImage> GetLogoAsync(AppDiagnosticInfo app)
{
    RandomAccessStreamReference stream = 
        app.AppInfo.DisplayInfo.GetLogo(new Size(64, 64));
    IRandomAccessStreamWithContentType content = await stream.OpenReadAsync();
    BitmapImage bitmapImage = new BitmapImage();
    await bitmapImage.SetSourceAsync(content);
    return bitmapImage;
}

Once you’ve collected all the various detailed metrics you’re interested in, it’s a simple matter to populate your viewmodel for data-binding purposes, to perform data analytics or to do whatever other processing you might want.

In a later post, we’ll look at how you can integrate the diagnostic APIs with existing developer tools such as Visual Studio and Appium.

Smooth Interaction and Motion with the Visual Layer in Windows 10 Creators Update

The Composition APIs come with a robust animation engine that provides quick and fluid motion running in a separate process from your Universal Windows Platform (UWP) app. This ensures a consistent 60 frames per second when running your app on an IoT device as well as on a screaming gaming machine. It is, quite simply, fast. This is an essential capability for implementing the Fluent Design System which calls on us to create a sense of cinematic motion in our UWP apps.

The Composition APIs also provide something you probably have never had access to before: the ability to create high-performing, low-level manipulation-driven custom animations like the one shown above.  In the same way that we that want our visuals to be fast and smooth, we want our touch interactions to be sticky and responsive. Moving a visual with a finger or a digital pen should result in the visual element clinging to us no matter how fast we push and pull it across the display.

Even if a motion looks good, it also needs to feel good under the finger. It needs to maintain the illusion that we are interacting with a real object. It ought to possess the proper physics so that when we drag a visual across the screen and let go, it continues with the proper inertial movement. Similarly, user controls should provide the right amount of resistance when we pull and release them.

A fast and fluid animation system

The Visual Layer supports both keyframe animations as well as expression animations. If you have worked with XAML animations before, then you are probably already familiar with how keyframes work. In a keyframe animation, you set values for some property you want to change over time and also assign the duration for the change: in the example below, a start value, a middle value and then an ending value. The animation system will take care of tweening your animation – in other words, generating all the values between the ones you have explicitly specified based on the easing function you select. Whether Linear, or a Cubic Bezier, the animation system will use that to determine the values when interpolating.


CubicBezierEasingFunction cubicBezier = _compositor.CreateCubicBezierEasingFunction(new Vector2(.17f, .67f), new Vector2(1f, 1f));
ScalarKeyFrameAnimation blurAnimation = _compositor.CreateScalarKeyFrameAnimation();
blurAnimation.InsertKeyFrame(0.0f, 0.0f);
blurAnimation.InsertKeyFrame(0.5f, 100.0f);
blurAnimation.InsertKeyFrame(1.0f, 0.0f);
blurAnimation.Duration = TimeSpan.FromSeconds(4);
blurAnimation.IterationBehavior = AnimationIterationBehavior.Forever;
_brush.StartAnimation("Blur.BlurAmount", blurAnimation);

A keyframe animation is a fire-and-forget mechanism that is time based. There are situations, however, when you need your animations to be coordinated and driving each other instead of simply moving in synchronized fashion.

In the animation above (source code), each gray gear is animated based on the animation of the gear preceding it. If the preceding gear suddenly goes faster or reverses direction, it forces the following gear to do the same. Keyframe animations can’t create motion effects that work in this way, but expression animations can. They are able to do so because, while keyframe animations are time based, expression animations are reference based.

The critical code that hooks up the gears for animation is found in the following code sample, which uses the new Expression Builder Library—an open source component released alongside of the Creators Update to construct expression animations. The expression below says that the animation should reference and be driven by the RotationAngleInDegrees property of the Visual that is indicated by the parameter “previousGear”. In the next line, the current Visual’s RotationAngleInDegrees property is finally animated based on the value referred to in an expression.


private void ConfigureGearAnimation(Visual currentGear, Visual previousGear)
{
    // If rotation expression is null then create an expression of a gear rotating the opposite direction

    var _rotateExpression = previousGear.GetReference().RotationAngleInDegrees;

    // Start the animation based on the Rotation Angle in Degrees.
    currentGear.StartAnimation("RotationAngleInDegrees", _rotateExpression);
}

But if an animation can be driven by another animation, you may be wondering, couldn’t we also drive an animation with something more concrete like user input? Why, yes. Yes, we can.

The beauty of the ScrollViewer ManipulationPropertySet

Driving an animation from a ScrollViewer using XAML-Composition interop is fairly easy. With just a few lines of code, you can enhance the visuals of a pre-existing ScrollViewer control with a CompositionAnimation by taking advantage of the GetScrollViewerManipulationPropertySet method on the ElementCompositionPreview class. Using an animation expression, you can tie your animation to the Position of your ScrollViewer component.

You would use this technique if you wanted to add a parallax effect to your XAML or to create a sticky header that stays in place as content scrolls beneath it. In the demo illustrated below (source code), a ScrollViewer is even used to drive a parallax effect on a ListView.

Adding parallax behavior to a XAML page can be accomplished in just a few lines.


// Note: We're not using the ScrollViewer's offset values directly. Instead, we use this PropertySet which holds the position values of the ScrollViewer in real-time.
var scrollPropSet = _scrollProperties.GetSpecializedReference<ManipulationPropertySetReferenceNode>();
var startOffset = ExpressionValues.Constant.CreateConstantScalar("startOffset", 0.0f);
var parallaxValue = 0.5f;
var itemHeight = 0.0f;
var parallax = (scrollPropSet.Translation.Y + startOffset - (0.5f * itemHeight));
_parallaxExpression = parallax * parallaxValue - parallax;
_parallaxExpression.SetScalarParameter("StartOffset", (float)args.ItemIndex * visual.Size.Y / 4.0f);
visual.StartAnimation("Offset.Y", _parallaxExpression);

The even more beautiful InteractionTracker

Driving expression animations with a ScrollViewer is extremely powerful, but what if you want to drive animations using touch gestures that aren’t limited to a pan/zoom gesture? Additionally, when using the ScrollViewer’s manipulations, your animations are linked to the UI thread responsiveness and can lose that buttery-smooth feel when the UI thread gets bogged down.

What if you want to pull items toward you with your finger, as in the demo below (source code), or animate multiple flying images across and into the screen as happens in the demo at the top of this post (source code)?

In order to achieve these effects, you would use the new InteractionTracker and VisualInteractionSource classes. InteractionTracker is a state machine that can be driven by active input. InteractionTracker also maintains a series of properties like Position and ScalePosition as part of maintaining the state. This is what you hook up to your animations. The VisualInteractionSource class, on the other hand, determines what kind of input you will use to drive your InteractionTracker and also when to start handling input (touch in particular).

The following sample code demonstrates a basic implementation of an InteractionTracker. The viewportVisual is simply the backing Visual for the root element on the page. You use this as the VisualInteractionSource for the tracker. In doing so, you specify that you are tracking X and Y manipulations. You also indicate that you want to track inertial movement.


_tracker = InteractionTracker.Create(_compositor);

var interactionSource = VisualInteractionSource.Create(viewportVisual);

interactionSource.PositionXSourceMode = InteractionSourceMode.EnabledWithInertia;
interactionSource.PositionYSourceMode = InteractionSourceMode.EnabledWithInertia;

_tracker.InteractionSources.Add(interactionSource);

Hooking the tracker up to an expression animation works basically the same way as hooking up a gear Visual to another gear Visual, as you did earlier. You call the CreateExpressionAnimation factory method on the current Compositor and reference the Position property of the tracker.


ar positionExpression = _compositor.CreateExpressionAnimation("-tracker.Position");
positionExpression.SetReferenceParameter("tracker", _tracker);

contentVisual.StartAnimation("Offset", positionExpression);

This code uses the InteractionTracker’s position to produce a smooth animation for the Offset of the Visual. You can also power your Blur and Opacity animations for your other Visuals as well. This will have a result where all three animations work together, with values based on how far the user dragged their finger, to result in an amazingly fluid visual experience. Run the demo and try it for yourself (source code).

Those are the basics of driving any animation from any input. What you do with this amazing new power is entirely up to you.

Wrapping up

Expression animations and Visual Layer Interactions are both topics that can become very deep very fast. To help you through these deeper waters, we highly recommend the following videos and articles:

Smooth as Butter Animations in the Visual Layer with the Windows 10 Creators Update

The Windows 10 Creators Update marks the third major release of the Windows UI platform APIs. With each release, an attempt is frequently made to simplify features introduced in prior releases. This encourages Universal Windows Platform (UWP) developers to standardize on these features. The new hide and show implicit animations are an example of this.

At the same time, too much standardization can potentially lead to conformity, so with each new release more powerful visual features like the new custom animations are also added, which allow developers who are willing and able to dive into them to customize their user interfaces and stand out from the crowd. This inherent tension between ease of use and the power to customize rewards developers for their efforts while also making sure that no one gets left behind.

Hide and show animations for page transitions

Page transitions, often accompanied by state transitions as visual elements, are added to the visual tree of the new page. In fact, a lot of interactivity in UWP simply involves deciding which content to show and which content to hide as the state of the app changes. More often than not, this is tied to changing the value of the Visibility properties of the elements on the screen.

In the Creators Update, two new implicit animation techniques have been added to help you make these transitions more fluid: ElementCompositionPreview.SetImplicitShowAnimation and ElementCompositionPreview.SetImplicitHideAnimation. Whenever a UIElement is loaded or when that element’s Visibility property is set to Visible, the implicit animation associated with it using SetImplicitShowAnimation will play. Similarly, whenever the user navigates away from a page or when a UIElement is hidden, an animation associated with it using the SetImplicitHideAnimation method will be invoked. These two mechanisms make it easier for you to include motion as an inherent aspect of all your visual elements, while providing a seamless experience for your users.

Connected animations

Implicit animations are great for animating controls inside a page. For navigation transitions between pages, however, the Visual Layer provides a different mechanism known as connected animations to help you make your UI even sweeter. Connected animations help the user stay oriented when she is performing common tasks such as context switching from a list of items to a details page.

The Windows UI platform APIs provide a class named the ConnectedAnimationService to coordinate animations between the source page and the destination page during navigation. You access the service by calling the static GetForCurrentView method. Then in the source page, you invoke PrepareToAnimate, passing in a unique key and the image that should be used for the transition animation.


ConnectedAnimationService.GetForCurrentView().PrepareToAnimate("MyUniqueId", image);

In the destination page, you retrieve the image from your ConnectedAnimationService service and invoke TryStart on the ConnectedAnimation while passing in the destination UIElement.


var animation = ConnectedAnimationService.GetForCurrentView().GetAnimation("MyUniqueId");
if (animation != null)
{
    animation.TryStart(DestinationImage);
};

In the Anniversary Update you did not have much control over this animation technique. Everyone got pretty much the same standard one. With the Creators Update, on the other hand, you have lots of new superpowers to personalize your transitions with:

  • Coordinated animations
  • Custom animations
  • Better image animations

Just to reiterate the point made in the introduction, the goal in designing the Windows UI platform APIs is to provide an awesome experience out of the box so you can copy the standard samples and get beautiful, fast and visually appealing visuals. At the same time, this shouldn’t ever take away from your ability to personalize the user experience to create something truly unique and wonderful with powerful new tools, like coordinated animations and custom animations.

Coordinated animations

A coordinated animation is a type of animation that appears alongside your connected animation and which works in coordination with your connected animation target. A coordinated animation gives extra visual flair to your page transition.

In the coordinated animation sample above, caption text that is not present in the source page is added to the destination page. The caption text is animated in tandem with the connected animation. We are doing two things here (in designer terms): providing context between the source and the destination using our connected animation while also adding visual interest with a coordinated animation at the destination. In user experience terms, though, all we’re doing is making the app’s transition animations look really cool.

Coordinated animations are fortunately also easy to implement. The TryStart method of the ConnectedAnimation class provides an override that allows you to pop in an array of visual elements you want to animate in a coordinated fashion. Let’s say that your caption text is in a visual element that you’ve named “DescriptionRoot.” You can add this as a coordinated animation by tweaking the previous code like so:


var animation = ConnectedAnimationService.GetForCurrentView().GetAnimation("MyUniqueId");
if (animation != null)
{
    animation.TryStart(DestinationImage, new UIElement[] { DescriptionRoot });
};

That’s a lot of power packed into a little argument.

Custom animations

By default, the connected animations in the navigation sample move in a straight line from the origin position in the source page to the target position in the destination page. If you select a box in the far-left column, it will move more or less straight up, while if you select a box in the top row, it will more or less move directly left to get to that target position. But what if you could put some English on this?

You can with custom animations, introduced in the Creators Update. The custom animations feature lets you modulate your transitions in four ways:

  • Crossfade – Lets you customize how elements crossfade as source element reaches destination
  • OffsetX – Lets you customize the X channel of Offset
  • OffsetY – Lets you customize the Y channel of Offset
  • Scale – Lets you customize scale of the element as it animates

In order to customize a particular part of a connected animation, you will need to create a keyframe animation and add it to your page transition using the SetAnimationComponent call like so:


var animation = ConnectedAnimationService.GetForCurrentView().GetAnimation("MyUniqueId");

var customXAnimation = Window.Compositor.CreateScalarKeyFrameAnimation();
customXAnimation.Duration = ConnectedAnimationService.GetForCurrentView().DefaultDuration;
customXAnimation.InsertExpressionKeyFrame(0.0f, "StartingValue");
customXAnimation.InsertExpressionKeyFrame(0.5f, "FinalValue + 25");
customXAnimation.InsertExpressionKeyFrame(1.0f, "FinalValue");

animation.SetAnimationComponent(ConnectedAnimationComponent.OffsetX, customXAnimation);

Note that you use expressions to get the starting and ending values of the connected animation.

Awesome image animations

The Creators Update also introduces improved image interpolation for connected animations where the image size and even the relative dimensions are changing between the source and the destination—for instance transitioning from a square to a rectangular image.

This interpolation happens automagically so you have less to worry about.

Implicit animation support for property sets and shadows

Finally, animation capabilities are also extended in the Creators Update by allowing you to apply implicit animations to property sets and shadows.

This change provides developers with even more creative flexibility and the ability to modify shadows in interesting new ways, as shown in the code sample below.


var shadowBlurAnimation = compositor.CreateScalarKeyFrameAnimation();
shadowBlurAnimation.InsertExpressionKeyFrame(1.0f, "this.FinalValue");
shadowBlurAnimation.Duration = TimeSpan.FromSeconds(1);
shadowBlurAnimation.Target = "BlurRadius";

//Associating animations with triggers 
implicitAnimationShadow["BlurRadius"] = shadowBlurAnimation;
implicitAnimationShadow["Opacity"] = shadowOpacityAnimation;
implicitAnimationShadow["Scale"] = shadowScaleAnimation;

implicitAnimationVisual["Translation"] = translationAnimation;
            

//Applying Implicit Animations to objects 
content.Properties.ImplicitAnimations = implicitAnimationVisual;
shadow.DropShadow.ImplicitAnimations = implicitAnimationShadow;

Wrapping up

The visual power being made available to developers through the Windows UI platform APIs have basically always been a part of the UI Framework. They just haven’t always been accessible until now. Think of this as a UI nuclear reactor being handed over to you to play with. With this awesome power, however, also comes the responsibility to create sweet UI and beautiful interactions. Go forth and be amazing.

To learn more about the topics covered in this post, you are encouraged to voraciously consume the following articles and videos:

Sweet UI made possible and easy with Windows.UI and the Windows 10 Creators Update

Since its original debut with the Windows 10 November 2015 update, Windows.UI.Composition has been empowering developers to build fast, beautiful, sweet user interfaces in UWP and has been providing enhancements with every subsequent Windows release. At Build 2017, we revealed what all of this continuous work has been leading up to: The Fluent Design System (aka ‘Project Neon’).

Moving from classic ‘Flat Design’ to Fluent Design requires the visual and performance capabilities that the Composition APIs offers along with the interop features that let you draw on this power from your XAML layer. In case you are not yet familiar with the concepts behind the Composition APIs, here’s a quick refresher on what the Composition APIs are all about.

The Windows.UI.Composition namespace allows Universal Windows Platform (UWP) developers to use a new Visual Layer that will get them closer to the metal, graphically speaking, while still using familiar technologies like XAML and C#. By getting closer to the metal, actually down to the system compositor level, developers are able to get great visual performance and custom UI experiences. By working through the XAML layer, developers get the ease of use they have come to expect out of UWP. This is basically a best of both worlds scenario that puts great responsibility in the developer’s hands. And with great responsibility, as we all know, comes great power.

So why do you need all these graphical and UX superpowers? In addition to giving pizazz to your UWP apps, access to the system compositor level also helps your users to accomplish their tasks faster and more fluidly. For instance, when you use Composition effects to blur a background in response to a click, you are focusing the user’s attention on her current task and removing distractions. This is the sort of subtle UI implementation that actually makes your user’s life easier – and it works best when your user doesn’t even know that you did anything for them. They are just left with the impression that your app is easy to use and feels fast, even if they can’t exactly put their finger on the reason.

The Visual family

To better understand the basic principles of Windows.UI.Composition, it’s important that we also introduce you to the visual family. In order to get fast and fluid effects, you need direct access to something called the system compositor (sometimes also referred to as the DWM). The system compositor is agnostic to the UI thread and doesn’t really care about being on the UI thread or blocking threads. Things happen very quickly at the system compositor level, where everything that is about to be sent to the display screen gets put together. This is also where you get to add additional effects if you want to just before shipping all your visuals to the display.

The visual family lives down at that compositor level where things happen rapidly. The visual family is made up of Visuals, ContainerVisuals and SpriteVisuals. The SpriteVisual class inherits from container visual, and the ContainerVisual class inherits from the base Visual class. There is also a Compositor class which acts as the senior member of the visual family. It quite literally creates visual objects if you need them and also manages the relationship between an application and the system compositor process.

The visual family is a lot of fun. Let’s say your XAML, many levels above, has a Grid object. That Grid will have a member of the visual family assigned to it. In technical parlance, we say that the Grid is backed by a visual. Once you grab hold of this backing visual, you can start to animate it using the composition animation system. If it is a ContainerVisual, then you can add additional visuals to it. Finally, you can also create sprite visuals, using the compositor factory class, in order to add brush effects to your visual using the Windows.UI.Composition effects system.

What’s new for sweet UI in the Windows 10 Creators Update

Several highly requested UI.Composition features have been added in the Creators Update to support fast and fluid UI as well as the Fluent Design System, for instance:

  • SVG support
  • Normal and Virtual Surfaces
  • Hover Interactions
  • Implicit Show and Hide
  • Expression Helpers
  • Offset stomping fix

At first these can seem like small disconnected improvements. Brought together, however, they will make creating beautiful UI both faster and easier.

XAML support for static SVG files

Vector images are often better for icons and logos because they can be resized without losing image quality. Before the Windows 10 Creators Update, however, vector graphics were not supported in XAML and working with iconography in UWP typically involved multiple versions of every image to adapt for multiple DPIs.  Now that that problem is solved, not only does XAML support static SVG files, but they also work with the Composition APIs.

Normal and virtual surfaces

The CompositionDrawingSurface has been a core component of the Composition APIs since the beginning, facilitating interop between XAML and Direct2D or Direct3D. The Creators Update is introducing the CompositionVirtualDrawingSurface for situations where only a portion of the content needs to be shown to the user at any given time. It basically bridges the concepts of graphics culling in video games and the development of infinite lists in desktop enterprise apps.

Independent hover interactions off the UI thread

One of the most powerful things about the Composition APIs is that they allow effects and animations to run independently of your main UI thread at 60 frames per second. With the Creators Update, this feature will also apply to hover animations in order to light up the many pointer activated effects that are a major part of fluent design.

There is also a subtle computer etiquette benefit to this new feature. Have you ever watched a busy animation play while your app’s UI was hanging and tried to move your mouse around in circles to try to make the animation go faster, but it has no effect? That is now a thing of the past.

Implicit show and hide

If you look at the code behind any UWP app, you will likely find that a large portion of UI code is devoted to setting visibility properties on UIElements in order to alternatively hide and show content. With this understanding, the Composition APIs now allow you to associate animations with your visual elements that are implicitly triggered when you hide or show them.


    ElementCompositionPreview.SetImplicitShowAnimation(MainContent, mainContentShowAnimations);
    ElementCompositionPreview.SetImplicitHideAnimation(MainContent, mainContentExitAnimation);

Implicit hide and show animations allow you to continue using this basic UI metaphor while also making it easier to create elegant visuals around them.

Expression helpers

Expression animations provide a way to create mathematical relationships between composition objects that can then be used to drive animations. The results of applying expression animations can often be breathtaking.

One piece of feedback we received about how we implemented expression animations is that it depends heavily on long strings of text like the following:


  rotationAnimation.Expression = "ACos( ( (A.Offset.X * B.Offset.X) + (A.Offset.Y*B.Offset.Y) + (A.Offset.Z * B.Offset.Z) ) / ( Length(A.Offset) *  Length(B.Offset) ) )";
  lineVisual.StartAnimation("RotationAngle", rotationAnimation);

The phrase “magic number” may even have been raised with respect to this. Just in time for the Creators Update, the Expression Builder Library is being introduced to provide you with type safety, IntelliSense and autocompletion as you create your own amazing expression animations.

Translation property

In earlier versions of the Composition APIs, there was a complication in the way UIElement properties were shared between the XAML layer and the Visual Layer that could cause the actual position of the visual to be overwritten or “stomped” in response to layout changes. While there was a workaround previously, there is now an actual fix with the new translation property. To prevent offset stomping, you now just need to enable the new Translation property through the ElementCompositionPreview class.


ElementCompositionPreview.SetIsTranslationEnabled(Rectangle1, true);

This is one of those issues that, if you’ve run into it before, you will feel a slight sense of relief. Just add a mental bookmark for yourself about the Translation property until you need to use it.

The sample gallery

The best way to deep dive into Windows.UI.Composition is by pulling down the sample code that the Composition team created and published to Github. The Windows UI Dev Labs samples, as they’re called, are extensive and visually rich. The samples extend from simple photo effects to complex parallax animations on XAML controls.

Don’t hesitate. It’s hard to really grasp the magnitude of the visual capabilities you are getting with Windows.UI.Composition until you see for yourself all that it empowers you to do.

Wrapping up

In addition to diving into the sample gallery on Github, which is highly recommended, you can also learn more about Windows Composition through the following articles, videos and blog posts.

How to distribute your existing Desktop Applications via Windows Store to Windows 10 PCs – including the new Windows 10 S configuration

Overview

Windows 10 S is a specific configuration of Windows 10 Pro that offers a familiar, productive Windows experience that’s streamlined for security and performance. By exclusively using apps in the Windows Store and ensuring that you browse safely with Microsoft Edge, Windows 10 S keeps you running fast and secure day in and day out. Windows 10 S was inspired by students and teachers and it’s the best Windows ever for schools. It’s also a great choice for any Windows customer looking for consistent performance and advanced security. By limiting apps to those in the Windows Store, Windows 10 S is ideal for people who have everything they need in the Windows Store and prefer the peace of mind that comes with removing the risk of downloading apps from other places.

What do I do with my existing non-Store app? Desktop Bridge is the answer

With the Desktop Bridge you can easily package your current desktop application or game as an .appx, distribute through the Windows Store and target all Windows Desktop devices including Windows 10 S to increase your user reach and easier monetization.

You can package any desktop application such as: WPF, WinForms, MFC, VB6, etc.

Once completed, your users will enjoy from smooth installation and update experiences: Clean, simple and fast install/uninstall updates via differential packages, streaming and many more.

Now you can also modernize your app with the Universal Windows Platform (UWP) to increase user engagement and reach all Windows devices.

We have a lot of customers that already went through the process such as: Kodi, Slack, Evernote, Adobe Photoshop Elements 15 and many others.

Here are few customers that shared their stories:

  1. MusiXmatch is the world’s largest lyrics platform with millions of lyrics available online and more than 50 million users on various platforms
  2. Tale of Wuxia (侠客风云传) is a traditional desktop Win32 role-playing game (RPG) that was created by Heluo Studio
  3. CLIP STUDIO PAINT is the leading paint tool software that supports creation of animation and manga

A quote from Evernote:

“The Desktop Bridge vastly simplifies our [Evernote] installer and uninstaller. It also opens up UWP APIs including Live Tiles and notifications. And having the full-featured Evernote app in the Windows Store means future improvements will reach users faster.”

—Seth Hitchings, VP Engineering, Evernote

What should I do next?

  1. Register as an app developer in the Windows Dev Center
  2. Prepare to package your application
  3. Sign up and get started using the Desktop Bridge
  4. Package your current desktop application as an .appx
  5. Test your Windows app for Windows 10 S, you can also check out this blog post for more details
  6. Submit your app to the Windows Store

Resources

Did you find this post helpful? Please let us know in the comments below—and also let us know if there’s anything else you’d like us to dig into for you about this topic.

Enjoy!

Toolkits, Toolkits, Toolkits!

As a UWP developer, you have many options to help build your application quickly and reliably. In fact, there are so many options that you may feel like you can choose only one. Luckily, that’s not the case, and many toolkits complement each other in various ways.

Today, we’ll talk about two open source toolkits:

Both are open source, but each has different strengths. These two particular toolkits can bring tools and controls for a variety of application scenarios. Let’s start by introducing the toolkits and how they can help.

UWP Community Toolkit

The UWP Community Toolkit is the ultimate collaboration between Microsoft and the UWP developer community. With dozens of features such as helper functions, custom UI components, animations and app services, the UWP Community toolkit is a great time saver and can bring your application to the next level.

The toolkit has had 12 releases so far and is currently on v 1.4 (released on April 3, 2017). It has more than 80 contributors, with thousands of commits, and the community is constantly working on improvements. Conveniently, it’s broken up into several nuget packages so you can pick and choose exactly what you need.

Examples of this toolkit’s power can be found in the Services namespace, where you can easily interact with social media services with as little as two lines of code.

Here’s an example of getting a Twitter user’s timeline:


TwitterService.Instance.Initialize("consumer-key", "consumer-secret", "callback-uri");
ListView.ItemsSource = await TwitterService.Instance.GetUserTimeLineAsync("user-screenname", 50);

You can find a full demo application here in the source code or here in the Windows Store. Go here to see a full list of the available features (controls, helpers, etc.) and go here to find the documentation.

Telerik UI for UWP

Telerik UI for UWP, from Progress Software, is a recently open sourced toolkit that contains an amazing set of Line of Business (LOB) controls with which you can create native, business-focused, UWP applications. With controls such as DataGrid and RadListView, the Telerik UI provides the powerful sorting, grouping and editing experiences you might expect from a desktop application, as well as rich data visualization experiences with controls such as Charts, Gauges and BulletGraphs.

We recommend you check out the Customer Database Example application here on GitHub to see the DataGrid in action, as well as the SDK Examples app here. You can see a full list of available controls here and find the documentation here (if you’re looking for a little extra help, Progress Software also offers professional support in the premium package).

An example of this toolkit’s power is the RadDataGrid. With one line of code you get a bunch of out-of-the-box features like grouping, sorting and filtering.

You can install UI for UWP in your application using the nuget package or build from the source directly. If you would like to read more about why Progress Software open sourced Telerik UI for UWP, we recommend you check out this great article.

Contributing

If you’re a developer who likes contributing to GitHub repos and giving back to the community, or if you have ideas to make things better for other developers, both toolkits accept pull requests and each has its own contribution guidelines (here for UWP community toolkit and here for Telerik UI for UWP).

Wrapping up

Both toolkits complement each other. You can use them side by side in your application to bring the user a delightful, yet powerful, experience in your UWP application. With dozens of UI controls, helpers, services and more, you can get your UWP app to market faster and with more confidence than ever. We look forward to seeing your UWP Community Toolkit and UI for UWP powered applications in the Windows Store!

Resources