RadialController RadialController RadialController Class

Definition

Represents a wheel input device or accessory such as the Surface Dial.

Note

Wheel devices are a new category of input device (supported in Windows 10, version 1607 and newer).

Surface Dial with Surface Studio and Pen

With a form factor based on a rotate action (or gesture), the Surface Dial is intended as a secondary, multi-modal input device that complements input from a primary device. In most cases, the device is manipulated by a user's non-dominant hand while performing a task with their dominant hand (such as inking with a pen). It is not designed for precision pointer input (like touch, pen, or mouse).

The Surface Dial also supports both a press and hold action and a click action. Press and hold has a single function: display a menu of commands. If the menu is active, the rotate and click input is processed by the menu. Otherwise, the input is passed to your app for processing.

The RadialController and related APIs (see end of topic) enable you to customize both the integrated command menu and the interaction experience supported by your app.

public sealed class RadialController : IRadialController, IRadialController2public sealed class RadialController : IRadialController, IRadialController2Public NotInheritable Class RadialController Implements IRadialController, IRadialController2
Attributes
Windows 10 requirements
Device family
Windows 10 Anniversary Edition (introduced v10.0.14393.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v3)

Remarks

Examples

In this example, we add a custom tool to the Surface Dial menu and declare the RadialController input handlers.

  1. First, we create a reference to the RadialController object for the Surface Dial (myController) by calling CreateForCurrentView.
  2. We then create an instance of a RadialControllerMenuItem (myItem) by calling RadialControllerMenuItem.CreateFromIcon.
  3. Next, we append that item to the collection of menu items.
  4. We declare the input event handlers (ButtonClicked and RotationChanged ) for the RadialController object.
  5. Finally, we define the event handlers.
public sealed partial class MainPage : Page
 {
     RadialController myController;

     public MainPage()
     {
         this.InitializeComponent();
         // Create a reference to the RadialController.
         myController = RadialController.CreateForCurrentView();

         // Create an icon for the custom tool.
         RandomAccessStreamReference icon =
           RandomAccessStreamReference.CreateFromUri(
             new Uri("ms-appx:///Assets/StoreLogo.png"));

         // Create a menu item for the custom tool.
         RadialControllerMenuItem myItem =
           RadialControllerMenuItem.CreateFromIcon("Sample", icon);

         // Add the custom tool to the RadialController menu.
         myController.Menu.Items.Add(myItem);

         // Declare input handlers for the RadialController.
         myController.ButtonClicked += MyController_ButtonClicked;
         myController.RotationChanged += MyController_RotationChanged;
     }

     // Handler for rotation input from the RadialController.
     private void MyController_RotationChanged(RadialController sender,
       RadialControllerRotationChangedEventArgs args)
     {
         if (RotationSlider.Value + args.RotationDeltaInDegrees > 100)
         {
             RotationSlider.Value = 100;
             return;
         }
         else if (RotationSlider.Value + args.RotationDeltaInDegrees < 0)
         {
             RotationSlider.Value = 0;
             return;
         }
         RotationSlider.Value += args.RotationDeltaInDegrees;
     }

     // Handler for click input from the RadialController.
     private void MyController_ButtonClicked(RadialController sender,
       RadialControllerButtonClickedEventArgs args)
     {
         ButtonToggle.IsOn = !ButtonToggle.IsOn;
     }
 }

In the initialization function shown here, we declare the various input event handlers for the RadialController object.

[TODO:AUTO_SNIPPET (SAMPLE_ID:RadialController)(SNIPPET_ID:InitializeController)]Finally, we define the event handlers for our app.

In the ButtonClicked handler, the interaction sets the state of a toggle button to checked or unchecked.

[TODO:AUTO_SNIPPET (SAMPLE_ID:RadialController)(SNIPPET_ID:ButtonClickedHandler)]In the RotationChanged handler, the interaction modifies the value of a slider.

[TODO:AUTO_SNIPPET (SAMPLE_ID:RadialController)(SNIPPET_ID:RotationChangedHandler)]

Properties

Menu Menu Menu

Gets a reference to the menu associated with the RadialController object.

public RadialControllerMenu Menu { get; }public RadialControllerMenu Menu { get; }Public ReadOnly Property Menu As RadialControllerMenu
Value
RadialControllerMenu RadialControllerMenu RadialControllerMenu

The integrated menu of contextual app commands associated with the RadialController object.

Attributes
See Also

RotationResolutionInDegrees RotationResolutionInDegrees RotationResolutionInDegrees

Gets or sets the minimum rotational value required for the RadialController object to fire a RotationChanged event.

public double RotationResolutionInDegrees { get; set; }public double RotationResolutionInDegrees { get; set; }Public ReadWrite Property RotationResolutionInDegrees As double
Value
double double double

The minimum rotational value required to fire a RotationChanged event.

Attributes
See Also

UseAutomaticHapticFeedback UseAutomaticHapticFeedback UseAutomaticHapticFeedback

Gets or sets whether haptic feedback is enabled on the wheel device for each RotationChanged event fired by the RadialController.

public bool UseAutomaticHapticFeedback { get; set; }public bool UseAutomaticHapticFeedback { get; set; }Public ReadWrite Property UseAutomaticHapticFeedback As bool
Value
bool bool bool

true if haptic feedback is enabled; otherwise false.

Attributes
See Also

Methods

CreateForCurrentView() CreateForCurrentView() CreateForCurrentView()

Instantiates a RadialController object for the wheel device and binds it to the active application.

public static RadialController CreateForCurrentView()public static RadialController CreateForCurrentView()Public Static Function CreateForCurrentView() As RadialController
Returns

The RadialController object to bind to the active application.

Attributes
See Also

IsSupported() IsSupported() IsSupported()

Retrieves a value that indicates whether wheel devices are supported by the system.

public static bool IsSupported()public static bool IsSupported()Public Static Function IsSupported() As bool
Returns
bool bool bool

true if wheel devices are supported by the system; otherwise false.

Attributes
See Also

Events

ButtonClicked ButtonClicked ButtonClicked

Occurs when the wheel device is pressed and then released while a custom RadialController tool is active.

Your app does not receive this event when:

Note

When a time threshold is crossed, click becomes a press and hold action. In this case, the integrated menu of contextual app commands associated with the RadialController object is displayed, and subsequent rotate and click events are processed by the menu.

public event TypedEventHandler ButtonClickedpublic event TypedEventHandler ButtonClickedPublic Event ButtonClicked
Attributes
See Also

ButtonHolding ButtonHolding ButtonHolding

Occurs when the user presses and holds down the wheel device.

public event TypedEventHandler ButtonHoldingpublic event TypedEventHandler ButtonHoldingPublic Event ButtonHolding
Attributes

Remarks

Your app does not receive this event when:

ButtonPressed ButtonPressed ButtonPressed

Occurs when the wheel device is pressed.

public event TypedEventHandler ButtonPressedpublic event TypedEventHandler ButtonPressedPublic Event ButtonPressed
Attributes

ButtonReleased ButtonReleased ButtonReleased

Occurs when the wheel device is pressed and then released.

public event TypedEventHandler ButtonReleasedpublic event TypedEventHandler ButtonReleasedPublic Event ButtonReleased
Attributes

ControlAcquired ControlAcquired ControlAcquired

Occurs when a custom RadialController tool (defined by an app) is selected from the menu, or when an app associated with the RadialController object is brought to the foreground while a custom RadialController tool is active.

public event TypedEventHandler ControlAcquiredpublic event TypedEventHandler ControlAcquiredPublic Event ControlAcquired
Attributes
See Also

ControlLost ControlLost ControlLost

Occurs while a custom RadialController tool (defined by an app) is active, and either the app associated with the RadialController object is sent to the background, or the user activates the RadialController menu.

public event TypedEventHandler ControlLostpublic event TypedEventHandler ControlLostPublic Event ControlLost
Attributes
See Also

RotationChanged RotationChanged RotationChanged

Occurs when the wheel device is rotated while a custom RadialController tool is active.

Your app does not receive this event when:

public event TypedEventHandler RotationChangedpublic event TypedEventHandler RotationChangedPublic Event RotationChanged
Attributes
See Also

ScreenContactContinued ScreenContactContinued ScreenContactContinued

Occurs only when the wheel device is moved while in contact with the digitizer surface, and a custom RadialController tool is active.

Your app does not receive this event when:

Tip

In addition to the default press and hold menu experience, 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 can handle occlusion by the device and display 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.

This event occurs after ScreenContactStarted and stops on ScreenContactEnded.

public event TypedEventHandler ScreenContactContinuedpublic event TypedEventHandler ScreenContactContinuedPublic Event ScreenContactContinued
Attributes
See Also

ScreenContactEnded ScreenContactEnded ScreenContactEnded

Occurs when a wheel device that is in contact with the digitizer surface is removed (or is no longer detected), and a custom RadialController tool is active.

Your app does not receive this event when:

Tip

In addition to the default press and hold menu experience, 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 can handle occlusion by the device and display 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.

This event occurs after ScreenContactStarted.

public event TypedEventHandler ScreenContactEndedpublic event TypedEventHandler ScreenContactEndedPublic Event ScreenContactEnded
Attributes
See Also

ScreenContactStarted ScreenContactStarted ScreenContactStarted

Occurs when initial contact is detected between a wheel device and the digitizer surface, and a custom RadialController tool is active.

Your app does not receive this event when:

Tip

In addition to the default press and hold menu experience, 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 can handle occlusion by the device and display 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.

public event TypedEventHandler ScreenContactStartedpublic event TypedEventHandler ScreenContactStartedPublic Event ScreenContactStarted
Attributes
See Also

See Also