RadialController class
Collapse the table of content
Expand the table of content

RadialController class

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.

Syntax


var radialController = Windows.UI.Input.RadialController;

Members

The RadialController class has these types of members:

Events

The RadialController class has these events.

EventDescription
ButtonClicked Occurs when the wheel device is pressed and then released while a customRadialController tool is active.
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.
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.
RotationChanged Occurs when the wheel device is rotated while a custom RadialController tool is active.
ScreenContactContinued Occurs only when the wheel device is moved while in contact with the digitizer surface, and a custom RadialController tool is active.
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.
ScreenContactStarted Occurs when initial contact is detected between a wheel device and the digitizer surface, and a custom RadialController tool is active.

 

Methods

The RadialController class has these methods. With C#, Visual Basic, and C++, it also inherits methods from the Object class.

MethodDescription
CreateForCurrentView Instantiates a RadialController object for the wheel device and binds it to the active application.
IsSupported Retrieves a value that indicates whether wheel devices are supported by the system.

 

Properties

The RadialController class has these properties.

PropertyAccess typeDescription

Menu

Read-only

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

RotationResolutionInDegrees

Read/write

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

UseAutomaticHapticFeedback

Read/write

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

 

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;
     }
 }

Requirements (Windows 10 device family)

Device family

Universal, introduced version 10.0.14393.0

API contract

Windows.Foundation.UniversalApiContract, introduced version 3.0

Namespace

Windows.UI.Input
Windows::UI::Input [C++]

Metadata

Windows.Foundation.UniversalApiContract.winmd

Attributes

[DualApiPartition()]
[MarshalingBehavior(Agile)]
[Version]

See also

Windows.UI.Input Classes
Object
RadialController APIs
RadialController class
RadialControllerButtonClickedEventArgs class
RadialControllerConfiguration class
RadialControllerControlAcquiredEventArgs class
RadialControllerMenu class
RadialControllerMenuItem class
RadialControllerRotationChangedEventArgs class
RadialControllerScreenContact class
RadialControllerScreenContactContinuedEventArgs class
RadialControllerScreenContactStartedEventArgs class
RadialControllerMenuKnownIcon enum
RadialControllerSystemMenuItemKind enum
Developer and UX guidance
Surface Dial interactions
Samples
Universal Windows Platform samples (C# and C++)
Windows classic desktop sample

 

 

Show:
© 2017 Microsoft