Maihunter789

-->

Surface Dial gives you quick and intuitive access to the brush settings you use most. Make fast and fluid color adjustments, and rotate or scale your canvas to achieve a finer level of control. Dial also works with these apps. Microsoft has all the apps you need to work and play. Watch thinking in action with Ink Replay and Surface Dial in OneNote.

Surface Dial with Surface Studio and Surface Pen (available for purchase at the Microsoft Store).

This tutorial steps through how to customize the user interaction experiences supported by wheel devices such as the Surface Dial. We use snippets from a sample app, which you can download from GitHub (see Sample code), to demonstrate the various features and associated RadialController APIs discussed in each step.

• Planning for tenant dial plans. To plan custom dial plans, follow these steps: Step 1 Decide whether a custom dial plan is needed to enhance the user dialing experience. Typically, the need for one would be to support non-E.164 dialing, such as extensions or abbreviated national d.
• Cross posted from the largely inactive onenote subreddit. While I have found developer support for the dial underwhelming across the board, particularly saddening is the lack of support for dial features within Microsoft's own apps. Specifically, this post relates to Onenote (The UWP variant).

We focus on the following:

• Specifying which built-in tools are displayed on the RadialController menu
• Adding a custom tool to the menu
• Controlling haptic feedback
• Customizing click interactions
• Customizing rotation interactions

For more about implementing these and other features, see Surface Dial interactions in Windows apps.

Introduction

The Surface Dial is a secondary input device that helps users to be more productive when used together with a primary input device such as pen, touch, or mouse. As a secondary input device, the Dial is typically used with the non-dominant hand to provide access both to system commands and to other, more contextual, tools and functionality.

Program Surface Dial

The Dial supports three basic gestures:

• Press and hold to display the built-in menu of commands.
• Rotate to highlight a menu item (if the menu is active) or to modify the current action in the app (if the menu is not active).
• Click to select the highlighted menu item (if the menu is active) or to invoke a command in the app (if the menu is not active).

Prerequisites

• A computer (or a virtual machine) running Windows 10 Creators Update, or newer
• A wheel device (only the Surface Dial at this time)
• If you're new to Windows app development with Visual Studio, have a look through these topics before you start this tutorial:

Set up your devices

1. Make sure your Windows device is on.
2. Go to Start, select Settings > Devices > Bluetooth & other devices, and then turn Bluetooth on.
3. Remove the bottom of the Surface Dial to open the battery compartment, and make sure that there are two AAA batteries inside.
4. If the battery tab is present on the underside of the Dial, remove it.
5. Press and hold the small, inset button next to the batteries until the Bluetooth light flashes.
6. Go back to your Windows device and select Add Bluetooth or other device.
7. In the Add a device dialog, select Bluetooth > Surface Dial. Your Surface Dial should now connect and be added to the list of devices under Mouse, keyboard, & pen on the Bluetooth & other devices settings page.
8. Test the Dial by pressing and holding it down for a few seconds to display the built-in menu.
9. If the menu isn't displayed on your screen (the Dial should also vibrate), go back to the Bluetooth settings, remove the device, and try connecting the device again.

Note

Wheel devices can be configured through the Wheel settings:

1. On the Start menu, select Settings.
2. Select Devices > Wheel.
   

Now you’re ready to start this tutorial.

Sample code

Throughout this tutorial, we use a sample app to demonstrate the concepts and functionality discussed.

Download this Visual Studio sample and source code from GitHub at windows-appsample-get-started-radialcontroller sample:

1. Select the green Clone or download button.
   
2. If you have a GitHub account, you can clone the repo to your local machine by choosing Open in Visual Studio.
3. If you don't have a GitHub account, or you just want a local copy of the project, choose Download ZIP (you'll have to check back regularly to download the latest updates).

Important

Most of the code in the sample is commented out. As we go through each step in this topic, you'll be asked to uncomment various sections of the code. In Visual Studio, just highlight the lines of code, and press CTRL-K and then CTRL-U.

Components that support wheel functionality

These objects provide the bulk of the wheel device experience for Windows apps.

Step 1: Run the sample

After you've downloaded the RadialController sample app, verify that it runs:

1. Open the sample project in Visual Studio .
2. Set the Solution Platforms dropdown to a non-ARM selection.
3. Press F5 to compile, deploy, and run.

Note

Alternatively, you can select Debug > Start debugging menu item, or select the Local Machine Run button shown here:

The app window opens, and after a splash screen appears for a few seconds, you’ll see this initial screen.

Okay, we now have the basic Windows app that we’ll use throughout the rest of this tutorial. In the following steps, we add our RadialController functionality.

Step 2: Basic RadialController functionality

With the app running and in the foreground, press and hold the Surface Dial to display the RadialController menu.

We haven't done any customization for our app yet, so the menu contains a default set of contextual tools.

These images show two variations of the default menu. (There are many others, including just basic system tools when the Windows Desktop is active and no apps are in the foreground, additional inking tools when an InkToolbar is present, and mapping tools when you’re using the Maps app.

Now we'll start with some basic customization.

Step 3: Add controls for wheel input

First, let's add the UI for our app:

1. Open the MainPage_Basic.xaml file.

2. Find the code marked with the title of this step ('<!-- Step 3: Add controls for wheel input -->').

3. Uncomment the following lines.

At this point, only the Initialize sample button, slider, and toggle switch are enabled. The other buttons are used in later steps to add and remove RadialController menu items that provide access to the slider and toggle switch.

Step 4: Customize the basic RadialController menu

Now let's add the code required to enable RadialController access to our controls.

1. Open the MainPage_Basic.xaml.cs file.
2. Find the code marked with the title of this step ('// Step 4: Basic RadialController menu customization').
3. Uncomment the following lines:

   • The Windows.UI.Input and Windows.Storage.Streams type references are used for functionality in subsequent steps:

   • These global objects (RadialController, RadialControllerConfiguration, RadialControllerMenuItem) are used throughout our app.

   • Here, we specify the Click handler for the button that enables our controls and initializes our custom RadialController menu item.

   • Next, we initialize our RadialController object and set up handlers for the RotationChanged and ButtonClicked events.

   • Here, we initialize our custom RadialController menu item. We use CreateForCurrentView to get a reference to our RadialController object, we set the rotation sensitivity to '1' by using the RotationResolutionInDegrees property, we then create our RadialControllerMenuItem by using CreateFromFontGlyph, we add the menu item to the RadialController menu item collection, and finally, we use SetDefaultMenuItems to clear the default menu items and leave only our custom tool.

4. Now, run the app again.
5. Select the Initialize radial controller button.
6. With the app in the foreground, press and hold the Surface Dial to display the menu. Notice that all default tools have been removed (by using the RadialControllerConfiguration.SetDefaultMenuItems method), leaving only the custom tool. Here’s the menu with our custom tool.

7. Select the custom tool and try out the interactions now supported through the Surface Dial:
   • A rotate action moves the slider.
   • A click sets the toggle to on or off.

Ok, let's hook up those buttons.

Step 5: Configure menu at runtime

In this step, we hook up the Add/Remove item and Reset RadialController menu buttons to show how you can dynamically customize the menu.

1. Open the MainPage_Basic.xaml.cs file.

2. Find the code marked with the title of this step ('// Step 5: Configure menu at runtime').

3. Uncomment the code in the following methods and run the app again, but don't select any buttons (save that for the next step).

4. Select the Remove item button and then press and hold the Dial to display the menu again.

   Notice that the menu now contains the default collection of tools. Recall that, in Step 3, while setting up our custom menu, we removed all the default tools and added just our custom tool. We also noted that, when the menu is set to an empty collection, the default items for the current context are reinstated. (We added our custom tool before removing the default tools.)

5. Select the Add item button and then press and hold the Dial.

   Notice that the menu now contains both the default collection of tools and our custom tool.

6. Select the Reset RadialController menu button and then press and hold the Dial.

   Notice that the menu is back to its original state.

Step 6: Customize the device haptics

The Surface Dial, and other wheel devices, can provide users with haptic feedback corresponding to the current interaction (based on either click or rotation).

In this step, we show how you can customize haptic feedback by associating our slider and toggle switch controls and using them to dynamically specify haptic feedback behavior. For this example, the toggle switch must be set to on for feedback to be enabled while the slider value specifies how often the click feedback is repeated.

Note

Haptic feedback can be disabled by the user in the Settings > Devices > Wheel page.

1. Open the App.xaml.cs file.

2. Find the code marked with the title of this step ('Step 6: Customize the device haptics').

3. Comment the first and third lines ('MainPage_Basic' and 'MainPage') and uncomment the second ('MainPage_Haptics').

4. Open the MainPage_Haptics.xaml file.

5. Find the code marked with the title of this step ('<!-- Step 6: Customize the device haptics -->').

6. Uncomment the following lines. (This UI code simply indicates what haptics features are supported by the current device.)

7. Open the MainPage_Haptics.xaml.cs file

8. Find the code marked with the title of this step ('Step 6: Haptics customization')

9. Uncomment the following lines:

   • The Windows.Devices.Haptics type reference is used for functionality in subsequent steps.

   • Here, we specify the handler for the ControlAcquired event that is triggered when our custom RadialController menu item is selected.

   • Next, we define the ControlAcquired handler, where we disable default haptic feedback and initialize our haptics UI.

   • In our RotationChanged and ButtonClicked event handlers, we connect the corresponding slider and toggle button controls to our custom haptics.

   • Finally, we get the requested Waveform (if supported) for the haptic feedback.

Now run the app again to try out the custom haptics by changing the slider value and toggle-switch state.

Step 7: Define on-screen interactions for Surface Studio and similar devices

Paired with the Surface Studio, the Surface Dial can provide an even more distinctive user experience.

In addition to the default press and hold menu experience described, the Surface Dial can also be placed directly on the screen of the Surface Studio. This enables a special 'on-screen' menu.

Surface Dial Onenote App

By detecting both the contact location and bounds of the Surface Dial, the system handles occlusion by the device and displays a larger version of the menu that wraps around the outside of the Dial. This same info can also be used by your app to adapt the UI for both the presence of the device and its anticipated usage, such as the placement of the user's hand and arm.

The sample that accompanies this tutorial includes a slightly more complex example that demonstrates some of these capabilities.

To see this in action (you'll need a Surface Studio):

Surface Dial Onenote Download

1. Download the sample on a Surface Studio device (with Visual Studio installed)

2. Open the sample in Visual Studio

3. Open the App.xaml.cs file

4. Find the code marked with the title of this step ('Step 7: Define on-screen interactions for Surface Studio and similar devices')

5. Comment the first and second lines ('MainPage_Basic' and 'MainPage_Haptics') and uncomment the third ('MainPage')

6. Run the app and place the Surface Dial in each of the two control regions, alternating between them.
   

   Here's a video of this sample in action:

Summary

Congratulations, you've completed the Get Started Tutorial: Support the Surface Dial (and other wheel devices) in your Windows app! We showed you the basic code required for supporting a wheel device in your Windows apps, and how to provide some of the richer user experiences supported by the RadialController APIs.

Surface Dial On Screen Compatibility

Related articles

API reference

Samples

Topic samples

Other samples

Microsoft introduced the Surface Dial along with the Surface Studio. The accessory works really well in Windows 10 as it’s integrated into some of the stock Windows 10 apps. But what makes it even better is the fact that third-party developers can add support for the Surface Dial to their apps, too.

For months, finding apps that are compatible with Surface Dial has been quite difficult. Microsoft listed the apps that support Surface Dial on its official product listing, but there never was a way of telling whether an app supports the Surface Dial on the Windows Store. To address this issue, Microsoft is releasing a new app collection that’ll help users find all the apps that work with the Surface Dial.

You can find the app collection here, and it includes some pretty major apps including things like Spotify, djay Pro, StaffPad, and Microsoft’s own OneNote. The majority of the Windows Store apps, as you will notice, still don’t support Microsoft’s Surface Dial. While most of the Windows Store don’t really need to work with the Surface Dial, it’d be nice to see more apps getting support for Microsoft’s $99 Surface Dial.