If you use Visual Studio and happen to own a Surface Dial, you might be glad to know that there’s a new extension that lets you add Surface Dial integration to Visual Studio. With this extension enabled, you can scroll in the editor in Visual Studio, browse through your bookmarks or interact with the editor itself. For instance, you can use the Surface Dial to play around with hex color or you can use it to change integer values which is pretty neat. Here’s a GIF showing off the Dial menu on Visual Studio action:
Here’s a full list of features:
- Status bar indicator
- Editor shifters
If you want to give the extension a try, you can download it from the Visual Studio marketplace here.-->
Surface Dial is a new tool for the creative process that keeps you in the flow. If you have one (or another wheel device), here’s how to set it up and customize what it does. Surface Dial is compatible with any PC, laptop, or tablet that has the.
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.
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.
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.
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).
- 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
- Make sure your Windows device is on.
- Go to Start, select Settings > Devices > Bluetooth & other devices, and then turn Bluetooth on.
- Remove the bottom of the Surface Dial to open the battery compartment, and make sure that there are two AAA batteries inside.
- If the battery tab is present on the underside of the Dial, remove it.
- Press and hold the small, inset button next to the batteries until the Bluetooth light flashes.
- Go back to your Windows device and select Add Bluetooth or other device.
- 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.
- Test the Dial by pressing and holding it down for a few seconds to display the built-in menu.
- 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.
Wheel devices can be configured through the Wheel settings:
- On the Start menu, select Settings.
- Select Devices > Wheel.
Now you’re ready to start this tutorial.
Surface Dial On Screen Compatibility
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:
- Select the green Clone or download button.
- If you have a GitHub account, you can clone the repo to your local machine by choosing Open in Visual Studio.
- 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).
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.
|RadialController class and related||Represents a wheel input device or accessory such as the Surface Dial.|
|IRadialControllerConfigurationInterop / IRadialControllerInterop|
We do not cover this functionality here, for more information, see the Windows classic desktop sample.
|Enables interoperability with a Windows app.|
Step 1: Run the sample
After you've downloaded the RadialController sample app, verify that it runs:
- Open the sample project in Visual Studio .
- Set the Solution Platforms dropdown to a non-ARM selection.
- Press F5 to compile, deploy, and run.
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.
|RadialController menu (default)||RadialController menu (default with media playing)|
Now we'll start with some basic customization.
Step 3: Add controls for wheel input
First, let's add the UI for our app:
Open the MainPage_Basic.xaml file.
Find the code marked with the title of this step ('<!-- Step 3: Add controls for wheel input -->').
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.
- Open the MainPage_Basic.xaml.cs file.
- Find the code marked with the title of this step ('// Step 4: Basic RadialController menu customization').
- 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.
- Now, run the app again.
- Select the Initialize radial controller button.
- 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.
|RadialController menu (custom)|
- 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.
Open the MainPage_Basic.xaml.cs file.
Find the code marked with the title of this step ('// Step 5: Configure menu at runtime').
Uncomment the code in the following methods and run the app again, but don't select any buttons (save that for the next step).
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.)
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.
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.
Surface Dial Onenote Manual
Haptic feedback can be disabled by the user in the Settings > Devices > Wheel page.
Open the App.xaml.cs file.
Find the code marked with the title of this step ('Step 6: Customize the device haptics').
Comment the first and third lines ('MainPage_Basic' and 'MainPage') and uncomment the second ('MainPage_Haptics').
Open the MainPage_Haptics.xaml file.
Find the code marked with the title of this step ('<!-- Step 6: Customize the device haptics -->').
Uncomment the following lines. (This UI code simply indicates what haptics features are supported by the current device.)
Open the MainPage_Haptics.xaml.cs file
Find the code marked with the title of this step ('Step 6: Haptics customization')
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.
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):
Download the sample on a Surface Studio device (with Visual Studio installed)
Open the sample in Visual Studio
Open the App.xaml.cs file
Find the code marked with the title of this step ('Step 7: Define on-screen interactions for Surface Studio and similar devices')
Comment the first and second lines ('MainPage_Basic' and 'MainPage_Haptics') and uncomment the third ('MainPage')
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:
Using Surface Dial With Onenote
Surface Dial Onenote 2
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.