RadialController 类

定义

命名空间:

Windows.UI.Input

表示滚轮输入设备或附件，例如 Surface Dial。

借助基于旋转操作（或手势）的外形规格，Surface Dial 旨在成为对主设备输入进行补充的多模态辅助输入设备。 在大多数情况下，用户使用其惯用手执行某个任务（如使用笔进行墨迹书写）期间，该设备由其非惯用手操控。 它不是专为精确指针输入（如触摸、笔或鼠标）而设计。

此外，Surface Dial 同时支持长按操作和单击操作。 长按只有一个功能：显示命令的菜单。 如果菜单处于活动状态，则由该菜单处理旋转和单击输入。 否则，该输入会传递给你的应用进行处理。

RadialController 和相关 API (查看主题结尾) 使你能够自定义集成命令菜单和应用支持的交互体验。

public ref class RadialController sealed

/// [Windows.Foundation.Metadata.ContractVersion(Windows.Foundation.UniversalApiContract, 196608)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
class RadialController final

[Windows.Foundation.Metadata.ContractVersion(typeof(Windows.Foundation.UniversalApiContract), 196608)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
public sealed class RadialController

Public NotInheritable Class RadialController

继承

Object Platform::Object IInspectable RadialController

属性

ContractVersionAttribute MarshalingBehaviorAttribute

Windows 要求

设备系列	Windows 10 Anniversary Edition (在 10.0.14393.0 中引入)
API contract	Windows.Foundation.UniversalApiContract (在 v3.0 中引入)

示例

在此示例中，我们将自定义工具添加到 Surface Dial 菜单，并声明 RadialController 输入处理程序。

1. 首先，通过调用 CreateForCurrentView 创建对 Surface Dial (myController) 的 RadialController 对象的引用。
2. 然后，通过调用 RadialControllerMenuItem.CreateFromIcon 创建 RadialControllerMenuItem (myItem) 的实例。
3. 接下来，我们将该项附加到菜单项的集合。
4. 我们为 RadialController 对象声明输入事件处理程序（ButtonClicked 和 RotationChanged）。
5. 最后，我们定义事件处理程序。

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

在此处显示的初始化函数中，我们声明 RadialController 对象的各种输入事件处理程序。

// Create and configure our radial controller.
private void InitializeController() 
{
    // Create a reference to the RadialController.
    radialController = RadialController.CreateForCurrentView();
    // Set rotation resolution to 1 degree of sensitivity.
    radialController.RotationResolutionInDegrees = 1;

    // Declare input handlers for the RadialController.
    radialController.ButtonClicked += (sender, args) =>
    { RadialController_ButtonClicked(sender, args); };
    radialController.RotationChanged += (sender, args) =>
    { RadialController_RotationChanged(sender, args); };

    radialController.ControlAcquired += (sender, args) =>
    { RadialController_ControlAcquired(sender, args); };
    radialController.ControlLost += (sender, args) =>
    { RadialController_ControlLost(sender, args); };
    radialController.ScreenContactStarted += (sender, args) =>
    { RadialController_ScreenContactStarted(sender, args); };
    radialController.ScreenContactContinued += (sender, args) =>
    { RadialController_ScreenContactContinued(sender, args); };
    radialController.ScreenContactEnded += (sender, args) =>
    { RadialController_ScreenContactEnded(sender, args); };
    AddToLog("Input handlers created");

    // Create the custom menu items.
    CreateMenuItems();
    // Specify the menu items.
    ConfigureMenu();
}

在 ButtonClicked 处理程序中，交互将切换按钮的状态设置为选中或未选中。

// Occurs when the wheel device is pressed and then released 
// while a customRadialController tool is active.
// NOTE: Your app does not receive this event when the RadialController 
// menu is active or a built-in tool is active
// Send click input to toggle button of active region.
private void RadialController_ButtonClicked(RadialController sender,
  RadialControllerButtonClickedEventArgs args)
{
    toggles[activeMenuItemIndex].IsOn = !toggles[activeMenuItemIndex].IsOn;
}

在 RotationChanged 处理程序中，交互修改滑块的值。

// Occurs when the wheel device is rotated while a custom 
// RadialController tool is active.
// NOTE: Your app does not receive this event when the RadialController 
// menu is active or a built-in tool is active
// Send rotation input to slider of active region.
private void RadialController_RotationChanged(RadialController sender,
  RadialControllerRotationChangedEventArgs args)
{
    Slider slider = sliders[activeMenuItemIndex];
    if (slider.Value + args.RotationDeltaInDegrees > 100)
    {
        slider.Value = 100;
        return;
    }
    else if (slider.Value + args.RotationDeltaInDegrees < 0)
    {
        slider.Value = 0;
        return;
    }
    slider.Value += args.RotationDeltaInDegrees;
    AddToLog("\nRotation: " + sliders[activeMenuItemIndex].Name + " value changed to " + slider.Value);
}

注解

版本历史记录

Windows 版本	SDK 版本	已添加值
1703	15063	ButtonHolding
1703	15063	ButtonPressed
1703	15063	ButtonReleased

属性

Menu	获取对与 RadialController 对象关联的菜单的引用。
RotationResolutionInDegrees	获取或设置 RadialController 对象触发 RotationChanged 事件所需的最小旋转值。
UseAutomaticHapticFeedback	获取或设置是否为 RadialController 触发的每个 RotationChanged 事件在滚轮设备上启用触觉反馈。

方法

CreateForCurrentView()	实例化 wheel 设备的 RadialController 对象，并将其绑定到活动应用程序。
IsSupported()	检索一个值，该值指示系统是否支持滚轮设备。

事件

ButtonClicked	在自定义 RadialController 工具处于活动状态时按下然后松开滚轮设备时发生。 应用在以下情况下不会收到此事件： RadialController 菜单处于活动状态 内置工具处于活动状态 注意 超过时间阈值时，单击将变为长按操作。 在这种情况下，将显示与 RadialController 对象关联的上下文应用命令的集成菜单，随后的旋转和单击事件由菜单处理。
ButtonHolding	当用户按下并按住滚轮设备时发生。
ButtonPressed	按下滚轮设备时发生。
ButtonReleased	在按下滚轮设备然后松开时发生。
ControlAcquired	当从菜单中选择由应用定义的自定义 RadialController 工具 () ，或者在自定义 RadialController 工具处于活动状态时将与 RadialController 对象关联的应用带到前台时发生。
ControlLost	当由应用) 定义的自定义 RadialController 工具 (处于活动状态，并且与 RadialController 对象关联的应用发送到后台，或者用户激活 RadialController 菜单时发生。
RotationChanged	在自定义 RadialController 工具处于活动状态时旋转滚轮设备时发生。 应用在以下情况下不会收到此事件： RadialController 菜单处于活动状态 内置工具处于活动状态
ScreenContactContinued	仅当滚轮设备在与数字化器表面接触时移动，并且自定义 RadialController 工具处于活动状态时发生。 应用在以下情况下不会收到此事件： RadialController 菜单处于活动状态 内置工具处于活动状态 提示 除了默认的长按菜单体验外，Surface Dial 还可以直接放置在Surface Studio屏幕上。 这会启用一个特殊的“屏幕”菜单。 通过检测 Surface Dial 的接触位置和边界，系统可以处理设备的遮挡，并显示环绕拨号外部的更大版本的菜单。 应用还可以使用这一相同信息针对设备的存在及其预期用途（例如用户的手和臂的放置）排布 UI。 此事件在 ScreenContactStarted 之后发生，并在 ScreenContactEnded 上停止。
ScreenContactEnded	当与数字化器表面接触的滚轮设备 (移除或不再) 检测到，并且自定义 RadialController 工具处于活动状态时发生。 应用在以下情况下不会收到此事件： RadialController 菜单处于活动状态 内置工具处于活动状态 提示 除了默认的长按菜单体验外，Surface Dial 还可以直接放置在Surface Studio屏幕上。 这会启用一个特殊的“屏幕”菜单。 通过检测 Surface Dial 的接触位置和边界，系统可以处理设备的遮挡，并显示环绕拨号外部的更大版本的菜单。 应用还可以使用这一相同信息针对设备的存在及其预期用途（例如用户的手和臂的放置）排布 UI。 此事件在 ScreenContactStarted 之后发生。
ScreenContactStarted	在轮设备和数字化器表面之间检测到初始接触并且自定义 RadialController 工具处于活动状态时发生。 应用在以下情况下不会收到此事件： RadialController 菜单处于活动状态 内置工具处于活动状态 提示 除了默认的长按菜单体验外，Surface Dial 还可以直接放置在Surface Studio屏幕上。 这会启用一个特殊的“屏幕”菜单。 通过检测 Surface Dial 的接触位置和边界，系统可以处理设备的遮挡，并显示环绕拨号外部的更大版本的菜单。 应用还可以使用这一相同信息针对设备的存在及其预期用途（例如用户的手和臂的放置）排布 UI。

另请参阅

• Windows.UI.Input
• RadialControllerButtonClickedEventArgs
• RadialControllerConfiguration
• RadialControllerControlAcquiredEventArgs
• RadialControllerMenu
• RadialControllerMenuItem
• RadialControllerRotationChangedEventArgs
• RadialControllerScreenContact
• RadialControllerScreenContactContinuedEventArgs
• RadialControllerScreenContactStartedEventArgs
• RadialControllerMenuKnownIcon
• RadialControllerSystemMenuItemKind
• Surface Dial 交互
• 通用 Windows 平台示例（C# 和 C++）
• Windows 桌面示例
• 径向控制器示例