From b44afa3597603db2d854e00c6fdbda2ddb4b418f Mon Sep 17 00:00:00 2001 From: Steven Kirk Date: Mon, 4 Nov 2024 09:54:21 +0100 Subject: [PATCH] Improve automation XML docs. (#17405) * Add extra docs to AutomationPeer. Detail the mapping of each individual "property" to win32 and macOS APIs. * Add extra docs to AutomationProperties. - Describe which `AutomationPeer` "property" they affect - Describe which properties currently have no effect * Add extra docs to automation providers. Detail the mapping of each individual "property" to win32 and macOS APIs. --- .../Automation/AutomationProperties.cs | 120 ++++++--- .../Automation/Peers/AutomationPeer.cs | 251 +++++++++++++++++- .../Provider/IEmbeddedRootProvider.cs | 8 +- .../Provider/IExpandCollapseProvider.cs | 67 ++++- .../Automation/Provider/IInvokeProvider.cs | 12 + .../Provider/IRangeValueProvider.cs | 92 ++++++- .../Automation/Provider/IRootProvider.cs | 38 +++ .../Automation/Provider/IScrollProvider.cs | 96 +++++++ .../Provider/ISelectionItemProvider .cs | 65 +++++ .../Automation/Provider/ISelectionProvider.cs | 38 +++ .../Automation/Provider/IToggleProvider.cs | 24 ++ .../Automation/Provider/IValueProvider.cs | 38 +++ 12 files changed, 805 insertions(+), 44 deletions(-) diff --git a/src/Avalonia.Controls/Automation/AutomationProperties.cs b/src/Avalonia.Controls/Automation/AutomationProperties.cs index 3ea9c170ff..2762beab6b 100644 --- a/src/Avalonia.Controls/Automation/AutomationProperties.cs +++ b/src/Avalonia.Controls/Automation/AutomationProperties.cs @@ -38,6 +38,9 @@ namespace Avalonia.Automation /// /// Defines the AutomationProperties.AcceleratorKey attached property. /// + /// + /// This property affects the default value for . + /// public static readonly AttachedProperty AcceleratorKeyProperty = AvaloniaProperty.RegisterAttached( "AcceleratorKey", @@ -46,6 +49,11 @@ namespace Avalonia.Automation /// /// Defines the AutomationProperties.AccessibilityView attached property. /// + /// + /// The value of this property affects the default value of the + /// and + /// properties. + /// public static readonly AttachedProperty AccessibilityViewProperty = AvaloniaProperty.RegisterAttached( "AccessibilityView", @@ -54,6 +62,9 @@ namespace Avalonia.Automation /// /// Defines the AutomationProperties.AccessKey attached property /// + /// + /// This property affects the default value for . + /// public static readonly AttachedProperty AccessKeyProperty = AvaloniaProperty.RegisterAttached( "AccessKey", @@ -62,6 +73,9 @@ namespace Avalonia.Automation /// /// Defines the AutomationProperties.AutomationId attached property. /// + /// + /// This property affects the default value for . + /// public static readonly AttachedProperty AutomationIdProperty = AvaloniaProperty.RegisterAttached( "AutomationId", @@ -70,6 +84,10 @@ namespace Avalonia.Automation /// /// Defines the AutomationProperties.ControlTypeOverride attached property. /// + /// + /// This property affects the default value for + /// . + /// public static readonly AttachedProperty ControlTypeOverrideProperty = AvaloniaProperty.RegisterAttached( "ControlTypeOverride", @@ -78,6 +96,9 @@ namespace Avalonia.Automation /// /// Defines the AutomationProperties.HelpText attached property. /// + /// + /// This property affects the default value for . + /// public static readonly AttachedProperty HelpTextProperty = AvaloniaProperty.RegisterAttached( "HelpText", @@ -86,6 +107,9 @@ namespace Avalonia.Automation /// /// Defines the AutomationProperties.IsColumnHeader attached property. /// + /// + /// This property currently has no effect. + /// public static readonly AttachedProperty IsColumnHeaderProperty = AvaloniaProperty.RegisterAttached( "IsColumnHeader", @@ -95,6 +119,9 @@ namespace Avalonia.Automation /// /// Defines the AutomationProperties.IsRequiredForForm attached property. /// + /// + /// This property currently has no effect. + /// public static readonly AttachedProperty IsRequiredForFormProperty = AvaloniaProperty.RegisterAttached( "IsRequiredForForm", @@ -104,6 +131,9 @@ namespace Avalonia.Automation /// /// Defines the AutomationProperties.IsRowHeader attached property. /// + /// + /// This property currently has no effect. + /// public static readonly AttachedProperty IsRowHeaderProperty = AvaloniaProperty.RegisterAttached( "IsRowHeader", @@ -113,6 +143,9 @@ namespace Avalonia.Automation /// /// Defines the AutomationProperties.IsOffscreenBehavior attached property. /// + /// + /// This property affects the default value for . + /// public static readonly AttachedProperty IsOffscreenBehaviorProperty = AvaloniaProperty.RegisterAttached( "IsOffscreenBehavior", @@ -122,6 +155,9 @@ namespace Avalonia.Automation /// /// Defines the AutomationProperties.ItemStatus attached property. /// + /// + /// This property currently has no effect. + /// public static readonly AttachedProperty ItemStatusProperty = AvaloniaProperty.RegisterAttached( "ItemStatus", @@ -130,6 +166,9 @@ namespace Avalonia.Automation /// /// Defines the AutomationProperties.ItemType attached property. /// + /// + /// This property currently has no effect. + /// public static readonly AttachedProperty ItemTypeProperty = AvaloniaProperty.RegisterAttached( "ItemType", @@ -138,6 +177,9 @@ namespace Avalonia.Automation /// /// Defines the AutomationProperties.LabeledBy attached property. /// + /// + /// This property affects the default value for . + /// public static readonly AttachedProperty LabeledByProperty = AvaloniaProperty.RegisterAttached( "LabeledBy", @@ -146,6 +188,9 @@ namespace Avalonia.Automation /// /// Defines the AutomationProperties.LiveSetting attached property. /// + /// + /// This property currently has no effect. + /// public static readonly AttachedProperty LiveSettingProperty = AvaloniaProperty.RegisterAttached( "LiveSetting", @@ -155,6 +200,9 @@ namespace Avalonia.Automation /// /// Defines the AutomationProperties.Name attached attached property. /// + /// + /// This property affects the default value for . + /// public static readonly AttachedProperty NameProperty = AvaloniaProperty.RegisterAttached( "Name", @@ -164,6 +212,8 @@ namespace Avalonia.Automation /// Defines the AutomationProperties.PositionInSet attached property. /// /// + /// NOTE: This property currently has no effect. + /// /// The PositionInSet property describes the ordinal location of the element within a set /// of elements which are considered to be siblings. PositionInSet works in coordination /// with the SizeOfSet property to describe the ordinal location in the set. @@ -178,6 +228,8 @@ namespace Avalonia.Automation /// Defines the AutomationProperties.SizeOfSet attached property. /// /// + /// NOTE: This property currently has no effect. + /// /// The SizeOfSet property describes the count of automation elements in a group or set /// that are considered to be siblings. SizeOfSet works in coordination with the PositionInSet /// property to describe the count of items in the set. @@ -189,7 +241,7 @@ namespace Avalonia.Automation AutomationSizeOfSetDefault); /// - /// Helper for setting AcceleratorKey property on a StyledElement. + /// Helper for setting the value of the on a StyledElement. /// public static void SetAcceleratorKey(StyledElement element, string value) { @@ -198,7 +250,7 @@ namespace Avalonia.Automation } /// - /// Helper for reading AcceleratorKey property from a StyledElement. + /// Helper for reading the value of the on a StyledElement. /// public static string? GetAcceleratorKey(StyledElement element) { @@ -207,7 +259,7 @@ namespace Avalonia.Automation } /// - /// Helper for setting AccessibilityView property on a StyledElement. + /// Helper for setting the value of the on a StyledElement. /// public static void SetAccessibilityView(StyledElement element, AccessibilityView value) { @@ -216,7 +268,7 @@ namespace Avalonia.Automation } /// - /// Helper for reading AccessibilityView property from a StyledElement. + /// Helper for reading the value of the on a StyledElement. /// public static AccessibilityView GetAccessibilityView(StyledElement element) { @@ -225,7 +277,7 @@ namespace Avalonia.Automation } /// - /// Helper for setting AccessKey property on a StyledElement. + /// Helper for setting the value of the on a StyledElement. /// public static void SetAccessKey(StyledElement element, string value) { @@ -234,7 +286,7 @@ namespace Avalonia.Automation } /// - /// Helper for reading AccessKey property from a StyledElement. + /// Helper for reading the value of the on a StyledElement. /// public static string? GetAccessKey(StyledElement element) { @@ -243,7 +295,7 @@ namespace Avalonia.Automation } /// - /// Helper for setting AutomationId property on a StyledElement. + /// Helper for setting the value of the on a StyledElement. /// public static void SetAutomationId(StyledElement element, string? value) { @@ -252,7 +304,7 @@ namespace Avalonia.Automation } /// - /// Helper for reading AutomationId property from a StyledElement. + /// Helper for reading the value of the on a StyledElement. /// public static string? GetAutomationId(StyledElement element) { @@ -261,7 +313,7 @@ namespace Avalonia.Automation } /// - /// Helper for setting ControlTypeOverride property on a StyledElement. + /// Helper for setting the value of the on a StyledElement. /// public static void SetControlTypeOverride(StyledElement element, AutomationControlType? value) { @@ -270,7 +322,7 @@ namespace Avalonia.Automation } /// - /// Helper for reading ControlTypeOverride property from a StyledElement. + /// Helper for reading the value of the on a StyledElement. /// public static AutomationControlType? GetControlTypeOverride(StyledElement element) { @@ -279,7 +331,7 @@ namespace Avalonia.Automation } /// - /// Helper for setting HelpText property on a StyledElement. + /// Helper for setting the value of the on a StyledElement. /// public static void SetHelpText(StyledElement element, string? value) { @@ -288,7 +340,7 @@ namespace Avalonia.Automation } /// - /// Helper for reading HelpText property from a StyledElement. + /// Helper for reading the value of the on a StyledElement. /// public static string? GetHelpText(StyledElement element) { @@ -297,7 +349,7 @@ namespace Avalonia.Automation } /// - /// Helper for setting IsColumnHeader property on a StyledElement. + /// Helper for setting the value of the on a StyledElement. /// public static void SetIsColumnHeader(StyledElement element, bool value) { @@ -306,7 +358,7 @@ namespace Avalonia.Automation } /// - /// Helper for reading IsColumnHeader property from a StyledElement. + /// Helper for reading the value of the on a StyledElement. /// public static bool GetIsColumnHeader(StyledElement element) { @@ -315,7 +367,7 @@ namespace Avalonia.Automation } /// - /// Helper for setting IsRequiredForForm property on a StyledElement. + /// Helper for setting the value of the on a StyledElement. /// public static void SetIsRequiredForForm(StyledElement element, bool value) { @@ -324,7 +376,7 @@ namespace Avalonia.Automation } /// - /// Helper for reading IsRequiredForForm property from a StyledElement. + /// Helper for reading the value of the on a StyledElement. /// public static bool GetIsRequiredForForm(StyledElement element) { @@ -333,7 +385,7 @@ namespace Avalonia.Automation } /// - /// Helper for reading IsRowHeader property from a StyledElement. + /// Helper for reading the value of the on a StyledElement. /// public static bool GetIsRowHeader(StyledElement element) { @@ -342,7 +394,7 @@ namespace Avalonia.Automation } /// - /// Helper for setting IsRowHeader property on a StyledElement. + /// Helper for setting the value of the on a StyledElement. /// public static void SetIsRowHeader(StyledElement element, bool value) { @@ -351,7 +403,7 @@ namespace Avalonia.Automation } /// - /// Helper for setting IsOffscreenBehavior property on a StyledElement. + /// Helper for setting the value of the on a StyledElement. /// public static void SetIsOffscreenBehavior(StyledElement element, IsOffscreenBehavior value) { @@ -360,7 +412,7 @@ namespace Avalonia.Automation } /// - /// Helper for reading IsOffscreenBehavior property from a StyledElement. + /// Helper for reading the value of the on a StyledElement. /// public static IsOffscreenBehavior GetIsOffscreenBehavior(StyledElement element) { @@ -369,7 +421,7 @@ namespace Avalonia.Automation } /// - /// Helper for setting ItemStatus property on a StyledElement. + /// Helper for setting the value of the on a StyledElement. /// public static void SetItemStatus(StyledElement element, string? value) { @@ -378,7 +430,7 @@ namespace Avalonia.Automation } /// - /// Helper for reading ItemStatus property from a StyledElement. + /// Helper for reading the value of the on a StyledElement. /// public static string? GetItemStatus(StyledElement element) { @@ -387,7 +439,7 @@ namespace Avalonia.Automation } /// - /// Helper for setting ItemType property on a StyledElement. + /// Helper for setting the value of the on a StyledElement. /// public static void SetItemType(StyledElement element, string? value) { @@ -396,7 +448,7 @@ namespace Avalonia.Automation } /// - /// Helper for reading ItemType property from a StyledElement. + /// Helper for reading the value of the on a StyledElement. /// public static string? GetItemType(StyledElement element) { @@ -405,7 +457,7 @@ namespace Avalonia.Automation } /// - /// Helper for setting LabeledBy property on a StyledElement. + /// Helper for setting the value of the on a StyledElement. /// public static void SetLabeledBy(StyledElement element, Control value) { @@ -414,7 +466,7 @@ namespace Avalonia.Automation } /// - /// Helper for reading LabeledBy property from a StyledElement. + /// Helper for reading the value of the on a StyledElement. /// public static Control GetLabeledBy(StyledElement element) { @@ -423,7 +475,7 @@ namespace Avalonia.Automation } /// - /// Helper for setting LiveSetting property on a StyledElement. + /// Helper for setting the value of the on a StyledElement. /// public static void SetLiveSetting(StyledElement element, AutomationLiveSetting value) { @@ -432,7 +484,7 @@ namespace Avalonia.Automation } /// - /// Helper for reading LiveSetting property from a StyledElement. + /// Helper for reading the value of the on a StyledElement. /// public static AutomationLiveSetting GetLiveSetting(StyledElement element) { @@ -441,7 +493,7 @@ namespace Avalonia.Automation } /// - /// Helper for setting Name property on a StyledElement. + /// Helper for setting the value of the on a StyledElement. /// public static void SetName(StyledElement element, string? value) { @@ -450,7 +502,7 @@ namespace Avalonia.Automation } /// - /// Helper for reading Name property from a StyledElement. + /// Helper for reading the value of the on a StyledElement. /// public static string? GetName(StyledElement element) { @@ -459,7 +511,7 @@ namespace Avalonia.Automation } /// - /// Helper for setting PositionInSet property on a StyledElement. + /// Helper for setting the value of the on a StyledElement. /// public static void SetPositionInSet(StyledElement element, int value) { @@ -468,7 +520,7 @@ namespace Avalonia.Automation } /// - /// Helper for reading PositionInSet property from a StyledElement. + /// Helper for reading the value of the on a StyledElement. /// public static int GetPositionInSet(StyledElement element) { @@ -477,7 +529,7 @@ namespace Avalonia.Automation } /// - /// Helper for setting SizeOfSet property on a StyledElement. + /// Helper for setting the value of the on a StyledElement. /// public static void SetSizeOfSet(StyledElement element, int value) { @@ -486,7 +538,7 @@ namespace Avalonia.Automation } /// - /// Helper for reading SizeOfSet property from a StyledElement. + /// Helper for reading the value of the on a StyledElement. /// public static int GetSizeOfSet(StyledElement element) { diff --git a/src/Avalonia.Controls/Automation/Peers/AutomationPeer.cs b/src/Avalonia.Controls/Automation/Peers/AutomationPeer.cs index 7a53ee001d..0b4653cddb 100644 --- a/src/Avalonia.Controls/Automation/Peers/AutomationPeer.cs +++ b/src/Avalonia.Controls/Automation/Peers/AutomationPeer.cs @@ -63,99 +63,335 @@ namespace Avalonia.Automation.Peers /// Gets the accelerator key combinations for the element that is associated with the UI /// Automation peer. /// + /// + /// An accelerator key (sometimes called a shortcut key) exposes a key combination for + /// which can be used to invoke an action, for example, an "Open..." menu item on Windows + /// often has an accelerator key of "Ctrl+O". + /// + /// + /// + /// Windows + /// UIA_AcceleratorKeyPropertyId + /// + /// + /// macOS + /// No mapping + /// + /// + /// public string? GetAcceleratorKey() => GetAcceleratorKeyCore(); /// /// Gets the access key for the element that is associated with the automation peer. /// + /// + /// An access key (sometimes called a mnemonic) is a character in the text of a menu, menu + /// item, or label of a control such as a button, that activates the associated function. + /// For example, to open the File menu, for which the access key is typically F, the user + /// would press ALT+F. + /// + /// + /// + /// Windows + /// UIA_AccessKeyPropertyId + /// + /// + /// macOS + /// No mapping + /// + /// + /// public string? GetAccessKey() => GetAccessKeyCore(); /// /// Gets the control type for the element that is associated with the UI Automation peer. /// + /// + /// Gets the type of the element. + /// + /// + /// + /// Windows + /// UIA_ControlTypePropertyId + /// + /// + /// macOS + /// NSAccessibilityProtocol.accessibilityRole + /// + /// + /// public AutomationControlType GetAutomationControlType() => GetControlTypeOverrideCore(); /// /// Gets the automation ID of the element that is associated with the UI Automation peer. /// + /// + /// + /// + /// Windows + /// UIA_AutomationIdPropertyId + /// + /// + /// macOS + /// NSAccessibilityProtocol.accessibilityIdentifier + /// + /// + /// public string? GetAutomationId() => GetAutomationIdCore(); /// /// Gets the bounding rectangle of the element that is associated with the automation peer /// in top-level coordinates. /// + /// + /// + /// + /// Windows + /// IRawElementProviderFragment.get_BoundingRectangle + /// + /// + /// macOS + /// NSAccessibilityProtocol.accessibilityFrame + /// + /// + /// public Rect GetBoundingRectangle() => GetBoundingRectangleCore(); /// /// Gets the child automation peers. /// + /// + /// + /// + /// Windows + /// IRawElementProviderFragment.Navigate + /// + /// + /// macOS + /// NSAccessibilityProtocol.accessibilityChildren + /// + /// + /// public IReadOnlyList GetChildren() => GetOrCreateChildrenCore(); /// /// Gets a string that describes the class of the element. /// + /// + /// A string containing the class name for the automation element as assigned by the + /// control developer. This is often the C# class name of the control. + /// + /// + /// + /// Windows + /// UIA_ClassNamePropertyId + /// + /// + /// macOS + /// No mapping. + /// + /// + /// public string GetClassName() => GetClassNameCore() ?? string.Empty; /// /// Gets the automation peer for the label that is targeted to the element. /// - /// + /// + /// Identifies an automation peer representing an element which that contains the text + /// label for this element. + /// + /// + /// + /// Windows + /// UIA_LabeledByPropertyId (not yet implemented) + /// + /// + /// macOS + /// NSAccessibilityProtocol.accessibilityLabelUIElements (not yet implemented) + /// + /// + /// public AutomationPeer? GetLabeledBy() => GetLabeledByCore(); /// /// Gets a human-readable localized string that represents the type of the control that is /// associated with this automation peer. /// + /// + /// + /// + /// Windows + /// UIA_LocalizedControlTypePropertyId (not yet implemented) + /// + /// + /// macOS + /// No mapping. + /// + /// + /// public string GetLocalizedControlType() => GetLocalizedControlTypeCore(); /// /// Gets text that describes the element that is associated with this automation peer. /// + /// + /// + /// + /// Windows + /// UIA_NamePropertyId (not yet implemented) + /// + /// + /// macOS + /// + /// When the control type is , this value is + /// exposed by both NSAccessibilityProtocol.accessibilityTitle and + /// NSAccessibilityProtocol.accessibilityValue . + /// + /// + /// + /// public string GetName() => GetNameCore() ?? string.Empty; - + /// /// Gets text that provides help for the element that is associated with this automation peer. /// + /// + /// + /// + /// Windows + /// UIA_HelpTextPropertyId + /// + /// + /// macOS + /// NSAccessibilityProtocol.accessibilityHelp + /// + /// + /// public string GetHelpText() => GetHelpTextCore() ?? string.Empty; /// /// Gets the that is the parent of this . /// + /// + /// + /// + /// Windows + /// IRawElementProviderFragment.Navigate + /// + /// + /// macOS + /// NSAccessibilityProtocol.accessibilityParent + /// + /// + /// public AutomationPeer? GetParent() => GetParentCore(); /// /// Gets the that is the root of this 's /// visual tree. /// + /// + /// + /// + /// Windows + /// No mapping, but used internally to translate coordinates. + /// + /// + /// macOS + /// NSAccessibilityProtocol.accessibilityTopLevelUIElement + /// + /// + /// public AutomationPeer? GetVisualRoot() => GetVisualRootCore(); /// /// Gets a value that indicates whether the element that is associated with this automation /// peer currently has keyboard focus. /// + /// + /// + /// + /// Windows + /// UIA_HasKeyboardFocusPropertyId + /// + /// + /// macOS + /// NSAccessibilityProtocol.isAccessibilityFocused + /// + /// + /// public bool HasKeyboardFocus() => HasKeyboardFocusCore(); /// /// Gets a value that indicates whether the element that is associated with this automation /// peer contains data that is presented to the user. /// + /// + /// + /// + /// Windows + /// UIA_IsContentElementPropertyId + /// + /// + /// macOS + /// No mapping. + /// + /// + /// public bool IsContentElement() => IsContentElementOverrideCore(); /// /// Gets a value that indicates whether the element is understood by the user as /// interactive or as contributing to the logical structure of the control in the GUI. /// + /// + /// + /// + /// Windows + /// UIA_IsControlElementPropertyId + /// + /// + /// macOS + /// NSAccessibilityProtocol.isAccessibilityElement + /// + /// + /// public bool IsControlElement() => IsControlElementOverrideCore(); /// /// Gets a value indicating whether the control is enabled for user interaction. /// + /// + /// + /// + /// Windows + /// UIA_IsEnabledPropertyId + /// + /// + /// macOS + /// NSAccessibilityProtocol.isAccessibilityEnabled + /// + /// + /// public bool IsEnabled() => IsEnabledCore(); /// /// Gets a value that indicates whether the element can accept keyboard focus. /// /// + /// + /// + /// + /// Windows + /// UIA_IsKeyboardFocusablePropertyId + /// + /// + /// macOS + /// No mapping. + /// + /// + /// public bool IsKeyboardFocusable() => IsKeyboardFocusableCore(); /// @@ -166,6 +402,17 @@ namespace Avalonia.Automation.Peers /// an element is on the screen but is still not visible. For example, if the element is /// on the screen but obscured by other elements, it might not be visible. In this case, /// the method returns false. + /// + /// + /// + /// Windows + /// UIA_IsOffscreenPropertyId + /// + /// + /// macOS + /// No mapping. + /// + /// /// public bool IsOffscreen() => IsOffscreenCore(); diff --git a/src/Avalonia.Controls/Automation/Provider/IEmbeddedRootProvider.cs b/src/Avalonia.Controls/Automation/Provider/IEmbeddedRootProvider.cs index 1b1caef182..4bbb2669d7 100644 --- a/src/Avalonia.Controls/Automation/Provider/IEmbeddedRootProvider.cs +++ b/src/Avalonia.Controls/Automation/Provider/IEmbeddedRootProvider.cs @@ -4,13 +4,13 @@ using Avalonia.Automation.Peers; namespace Avalonia.Automation.Provider { /// - /// Exposure methods and properties to support UI Automation client access to the root of an + /// Exposes methods and properties to support UI Automation client access to the root of an /// automation tree hosted by another UI framework. /// /// - /// This interface is implemented by the class, and can be used - /// to embed an automation tree from a 3rd party UI framework that wishes to use Avalonia's - /// automation support. + /// This interface can be implemented by an , and is used to embed + /// an automation tree from a 3rd party UI framework that wishes to use Avalonia's automation + /// support. /// public interface IEmbeddedRootProvider { diff --git a/src/Avalonia.Controls/Automation/Provider/IExpandCollapseProvider.cs b/src/Avalonia.Controls/Automation/Provider/IExpandCollapseProvider.cs index a4691180a3..f96b60f496 100644 --- a/src/Avalonia.Controls/Automation/Provider/IExpandCollapseProvider.cs +++ b/src/Avalonia.Controls/Automation/Provider/IExpandCollapseProvider.cs @@ -1,4 +1,6 @@ -namespace Avalonia.Automation.Provider +using Avalonia.Controls; + +namespace Avalonia.Automation.Provider { /// /// Exposes methods and properties to support UI Automation client access to controls that @@ -9,6 +11,18 @@ /// /// Gets the state, expanded or collapsed, of the control. /// + /// + /// + /// + /// Windows + /// IExpandCollapseProvider.ExpandCollapseState + /// + /// + /// macOS + /// NSAccessibilityProtocol.isAccessibilityExpanded + /// + /// + /// ExpandCollapseState ExpandCollapseState { get; } /// @@ -16,18 +30,65 @@ /// such as drop-down list. /// /// - /// Used in OSX to enable the "Show Menu" action on the element. + /// Used in OSX to allow accessibilityPerformShowMenu to open expandable controls such as a + /// ; in macOS, a combo box drop-down is considered a menu. + /// + /// + /// + /// Windows + /// No mapping. + /// + /// + /// macOS + /// + /// When true, NSAccessibilityProtocol.accessibilityPerformShowMenu will cause the + /// method to be triggered. + /// + /// + /// /// bool ShowsMenu { get; } - + /// /// Displays all child nodes, controls, or content of the control. /// + /// + /// + /// + /// Windows + /// IExpandCollapseProvider.Expand + /// + /// + /// macOS + /// + /// Called by setting NSAccessibilityProtocol.setAccessibilityExpanded to + /// true, by calling NSAccessibilityProtocol.accessibilityPerformPress, or + /// by calling NSAccessibilityProtocol.accessibilityPerformShowMenu + /// when is true. + /// + /// + /// + /// void Expand(); /// /// Hides all nodes, controls, or content that are descendants of the control. /// + /// + /// + /// + /// Windows + /// IExpandCollapseProvider.Collapse + /// + /// + /// macOS + /// + /// Called by setting NSAccessibilityProtocol.setAccessibilityExpanded to + /// false. + /// + /// + /// + /// void Collapse(); } } diff --git a/src/Avalonia.Controls/Automation/Provider/IInvokeProvider.cs b/src/Avalonia.Controls/Automation/Provider/IInvokeProvider.cs index 47d7211c92..bb517bbb98 100644 --- a/src/Avalonia.Controls/Automation/Provider/IInvokeProvider.cs +++ b/src/Avalonia.Controls/Automation/Provider/IInvokeProvider.cs @@ -10,6 +10,18 @@ /// /// Sends a request to activate a control and initiate its single, unambiguous action. /// + /// + /// + /// + /// Windows + /// IInvokeProvider.Invoke + /// + /// + /// macOS + /// NSAccessibilityProtocol.accessibilityPerformPress + /// + /// + /// void Invoke(); } } diff --git a/src/Avalonia.Controls/Automation/Provider/IRangeValueProvider.cs b/src/Avalonia.Controls/Automation/Provider/IRangeValueProvider.cs index 43a877a21a..0cdeeb3065 100644 --- a/src/Avalonia.Controls/Automation/Provider/IRangeValueProvider.cs +++ b/src/Avalonia.Controls/Automation/Provider/IRangeValueProvider.cs @@ -9,39 +9,129 @@ /// /// Gets a value that indicates whether the value of a control is read-only. /// + /// + /// + /// + /// Windows + /// IRangeValueProvider.get_IsReadOnly + /// + /// + /// macOS + /// No mapping. + /// + /// + /// bool IsReadOnly { get; } /// /// Gets the minimum range value that is supported by the control. /// + /// + /// + /// + /// Windows + /// IRangeValueProvider.get_Minimum + /// + /// + /// macOS + /// NSAccessibilityProtocol.accessibilityMinValue + /// + /// + /// double Minimum { get; } /// /// Gets the maximum range value that is supported by the control. /// + /// + /// + /// + /// Windows + /// IRangeValueProvider.get_Maximum + /// + /// + /// macOS + /// NSAccessibilityProtocol.accessibilityMaxValue + /// + /// + /// double Maximum { get; } /// /// Gets the value of the control. /// + /// + /// + /// + /// Windows + /// IRangeValueProvider.get_Value + /// + /// + /// macOS + /// NSAccessibilityProtocol.accessibilityValue + /// + /// + /// double Value { get; } /// /// Gets the value that is added to or subtracted from the Value property when a large /// change is made, such as with the PAGE DOWN key. /// + /// + /// + /// + /// Windows + /// IRangeValueProvider.get_LargeChange + /// + /// + /// macOS + /// No mapping. + /// + /// + /// double LargeChange { get; } /// /// Gets the value that is added to or subtracted from the Value property when a small /// change is made, such as with an arrow key. /// + /// + /// + /// + /// Windows + /// IRangeValueProvider.get_SmallChange + /// + /// + /// macOS + /// + /// Used by NSAccessibilityProtocol.accessibilityPerformIncrement and + /// NSAccessibilityProtocol.accessibilityPerformDecrement to determine the + /// changed value. + /// + /// + /// + /// double SmallChange { get; } - + /// /// Sets the value of the control. /// /// The value to set. + /// + /// + /// + /// Windows + /// IRangeValueProvider.SetValue + /// + /// + /// macOS + /// + /// NSAccessibilityProtocol.setAccessibilityValue (not implemented) + /// + /// + /// + /// public void SetValue(double value); } } diff --git a/src/Avalonia.Controls/Automation/Provider/IRootProvider.cs b/src/Avalonia.Controls/Automation/Provider/IRootProvider.cs index 6a266da5c5..8452574df2 100644 --- a/src/Avalonia.Controls/Automation/Provider/IRootProvider.cs +++ b/src/Avalonia.Controls/Automation/Provider/IRootProvider.cs @@ -23,17 +23,55 @@ namespace Avalonia.Automation.Provider /// /// Gets the currently focused element. /// + /// + /// + /// + /// Windows + /// IRawElementProviderFragmentRoot.GetFocus + /// + /// + /// macOS + /// UIAccessibility.accessibilityFocusedUIElement + /// + /// + /// AutomationPeer? GetFocus(); /// /// Gets the element at the specified point, expressed in top-level coordinates. /// /// The point. + /// + /// + /// + /// Windows + /// + /// IRawElementProviderFragmentRoot.ElementProviderFromPoint + /// + /// + /// + /// macOS + /// UIAccessibility.accessibilityHitTest + /// + /// + /// AutomationPeer? GetPeerFromPoint(Point p); /// /// Raised by the automation peer when the focus changes. /// + /// + /// + /// + /// Windows + /// UIA_AutomationFocusChangedEventId + /// + /// + /// macOS + /// NSAccessibilityFocusedUIElementChangedNotification + /// + /// + /// event EventHandler? FocusChanged; } } diff --git a/src/Avalonia.Controls/Automation/Provider/IScrollProvider.cs b/src/Avalonia.Controls/Automation/Provider/IScrollProvider.cs index 1055a2f1e1..0acd32b3dd 100644 --- a/src/Avalonia.Controls/Automation/Provider/IScrollProvider.cs +++ b/src/Avalonia.Controls/Automation/Provider/IScrollProvider.cs @@ -18,31 +18,103 @@ /// /// Gets a value that indicates whether the control can scroll horizontally. /// + /// + /// + /// + /// Windows + /// IScrollProvider.HorizontallyScrollable + /// + /// + /// macOS + /// No mapping. + /// + /// + /// bool HorizontallyScrollable { get; } /// /// Gets the current horizontal scroll position. /// + /// + /// + /// + /// Windows + /// IScrollProvider.HorizontalScrollPercent + /// + /// + /// macOS + /// No mapping. + /// + /// + /// double HorizontalScrollPercent { get; } /// /// Gets the current horizontal view size. /// + /// + /// + /// + /// Windows + /// IScrollProvider.HorizontalViewSize + /// + /// + /// macOS + /// No mapping. + /// + /// + /// double HorizontalViewSize { get; } /// /// Gets a value that indicates whether the control can scroll vertically. /// + /// + /// + /// + /// Windows + /// IScrollProvider.VerticallyScrollable + /// + /// + /// macOS + /// No mapping. + /// + /// + /// bool VerticallyScrollable { get; } /// /// Gets the current vertical scroll position. /// + /// + /// + /// + /// Windows + /// IScrollProvider.VerticalScrollPercent + /// + /// + /// macOS + /// No mapping. + /// + /// + /// double VerticalScrollPercent { get; } /// /// Gets the vertical view size. /// + /// + /// + /// + /// Windows + /// IScrollProvider.VerticalViewSize + /// + /// + /// macOS + /// No mapping. + /// + /// + /// double VerticalViewSize { get; } /// @@ -50,6 +122,18 @@ /// /// The horizontal increment specific to the control. /// The vertical increment specific to the control. + /// + /// + /// + /// Windows + /// IScrollProvider.Scroll + /// + /// + /// macOS + /// No mapping. + /// + /// + /// void Scroll(ScrollAmount horizontalAmount, ScrollAmount verticalAmount); /// @@ -66,6 +150,18 @@ /// should be passed in if the control /// cannot be scrolled in this direction. /// + /// + /// + /// + /// Windows + /// IScrollProvider.SetScrollPercent + /// + /// + /// macOS + /// No mapping. + /// + /// + /// void SetScrollPercent(double horizontalPercent, double verticalPercent); } } diff --git a/src/Avalonia.Controls/Automation/Provider/ISelectionItemProvider .cs b/src/Avalonia.Controls/Automation/Provider/ISelectionItemProvider .cs index 6cea1d1350..22fd4d33d4 100644 --- a/src/Avalonia.Controls/Automation/Provider/ISelectionItemProvider .cs +++ b/src/Avalonia.Controls/Automation/Provider/ISelectionItemProvider .cs @@ -9,27 +9,92 @@ /// /// Gets a value that indicates whether an item is selected. /// + /// + /// + /// + /// Windows + /// ISelectionItemProvider.IsSelected + /// + /// + /// macOS + /// NSAccessibilityProtocol.isAccessibilitySelected + /// + /// + /// bool IsSelected { get; } /// /// Gets the UI Automation provider that implements and /// acts as the container for the calling object. /// + /// + /// + /// + /// Windows + /// ISelectionItemProvider.SelectionContainer + /// + /// + /// macOS + /// No mapping. + /// + /// + /// ISelectionProvider? SelectionContainer { get; } /// /// Adds the current element to the collection of selected items. /// + /// + /// + /// + /// Windows + /// ISelectionItemProvider.AddToSelection + /// + /// + /// macOS + /// + /// NSAccessibilityProtocol.accessibilityPerformPick (not implemented). + /// NSAccessibilityProtocol.setAccessibilitySelected (not implemented). + /// + /// + /// + /// void AddToSelection(); /// /// Removes the current element from the collection of selected items. /// + /// + /// + /// + /// Windows + /// ISelectionItemProvider.RemoveFromSelection + /// + /// + /// macOS + /// + /// NSAccessibilityProtocol.setAccessibilitySelected (not implemented). + /// + /// + /// + /// void RemoveFromSelection(); /// /// Clears any existing selection and then selects the current element. /// + /// + /// + /// + /// Windows + /// ISelectionItemProvider.Select + /// + /// + /// macOS + /// No mapping. + /// + /// + /// void Select(); } } diff --git a/src/Avalonia.Controls/Automation/Provider/ISelectionProvider.cs b/src/Avalonia.Controls/Automation/Provider/ISelectionProvider.cs index bf21c0151f..26b961314a 100644 --- a/src/Avalonia.Controls/Automation/Provider/ISelectionProvider.cs +++ b/src/Avalonia.Controls/Automation/Provider/ISelectionProvider.cs @@ -13,17 +13,55 @@ namespace Avalonia.Automation.Provider /// Gets a value that indicates whether the provider allows more than one child element /// to be selected concurrently. /// + /// + /// + /// + /// Windows + /// ISelectionProvider.CanSelectMultiple + /// + /// + /// macOS + /// No mapping. + /// + /// + /// bool CanSelectMultiple { get; } /// /// Gets a value that indicates whether the provider requires at least one child element /// to be selected. /// + /// + /// + /// + /// Windows + /// ISelectionProvider.IsSelectionRequired + /// + /// + /// macOS + /// No mapping. + /// + /// + /// bool IsSelectionRequired { get; } /// /// Retrieves a provider for each child element that is selected. /// + /// + /// + /// + /// Windows + /// ISelectionProvider.GetSelection + /// + /// + /// macOS + /// + /// NSAccessibilityProtocol.accessibilitySelectedChildren (not implemented). + /// + /// + /// + /// IReadOnlyList GetSelection(); } } diff --git a/src/Avalonia.Controls/Automation/Provider/IToggleProvider.cs b/src/Avalonia.Controls/Automation/Provider/IToggleProvider.cs index 67913e3204..fa589c1eb9 100644 --- a/src/Avalonia.Controls/Automation/Provider/IToggleProvider.cs +++ b/src/Avalonia.Controls/Automation/Provider/IToggleProvider.cs @@ -30,11 +30,35 @@ /// /// Gets the toggle state of the control. /// + /// + /// + /// + /// Windows + /// IToggleProvider.ToggleState + /// + /// + /// macOS + /// NSAccessibilityProtocol.accessibilityValue + /// + /// + /// ToggleState ToggleState { get; } /// /// Cycles through the toggle states of a control. /// + /// + /// + /// + /// Windows + /// IToggleProvider.Toggle + /// + /// + /// macOS + /// NSAccessibilityProtocol.accessibilityPerformPress + /// + /// + /// void Toggle(); } } diff --git a/src/Avalonia.Controls/Automation/Provider/IValueProvider.cs b/src/Avalonia.Controls/Automation/Provider/IValueProvider.cs index e025e28782..093327fa71 100644 --- a/src/Avalonia.Controls/Automation/Provider/IValueProvider.cs +++ b/src/Avalonia.Controls/Automation/Provider/IValueProvider.cs @@ -10,11 +10,35 @@ /// /// Gets a value that indicates whether the value of a control is read-only. /// + /// + /// + /// + /// Windows + /// IValueProvider.IsReadOnly + /// + /// + /// macOS + /// No mapping. + /// + /// + /// bool IsReadOnly { get; } /// /// Gets the value of the control. /// + /// + /// + /// + /// Windows + /// IValueProvider.Value + /// + /// + /// macOS + /// NSAccessibilityProtocol.accessibilityValue + /// + /// + /// public string? Value { get; } /// @@ -24,6 +48,20 @@ /// The value to set. The provider is responsible for converting the value to the /// appropriate data type. /// + /// + /// + /// + /// Windows + /// IValueProvider.SetValue + /// + /// + /// macOS + /// + /// NSAccessibilityProtocol.setAccessibilityValue (not implemented) + /// + /// + /// + /// public void SetValue(string? value); } }