Report multi select on list boxes that support it (nvaccess#18409)

Link to issue number:

Closes nvaccess#18365
Summary of the issue:

NVDA does not report whether multiple selection is supported on a list control.
Description of user facing changes:

NVDA now reports multi select for a list that supports multiple selection.
Description of developer facing changes:

None
Description of development approach:

    Add a new MULTISELECTABLE state, analogous to oleacc
    Map that state to the oleacc state for MSAA
    Map the UIA Selection Can Select Multiple property to the new state.

Author: LeonarddeR

source/IAccessibleHandler/__init__.py

@@ -228,6 +228,7 @@
 	oleacc.STATE_SYSTEM_PROTECTED: controlTypes.State.PROTECTED,
 	oleacc.STATE_SYSTEM_SELECTABLE: controlTypes.State.SELECTABLE,
 	oleacc.STATE_SYSTEM_FOCUSABLE: controlTypes.State.FOCUSABLE,
+	oleacc.STATE_SYSTEM_MULTISELECTABLE: controlTypes.State.MULTISELECTABLE,
 }
 
 IAccessible2StatesToNVDAStates = {

source/NVDAObjects/IAccessible/__init__.py

@@ -1080,15 +1080,15 @@ def _get_IAccessibleStates(self) -> int:
 			return 0
 		return res if isinstance(res, int) else 0
 
-	states: typing.Set[controlTypes.State]
+	states: set[controlTypes.State]
 	"""Type info for auto property: _get_states
 	"""
 
 	# C901 '_get_states' is too complex. Look for opportunities to break this method down.
-	def _get_states(self) -> typing.Set[controlTypes.State]:  # noqa: C901
+	def _get_states(self) -> set[controlTypes.State]:  # noqa: C901
 		states = set()
 		if self.event_objectID in (winUser.OBJID_CLIENT, winUser.OBJID_WINDOW) and self.event_childID == 0:
-			states.update(super(IAccessible, self).states)
+			states.update(super().states)
 		try:
 			IAccessibleStates = self.IAccessibleStates
 		except COMError:
@@ -2434,6 +2434,12 @@ class List(IAccessible):
 	def _get_role(self):
 		return controlTypes.Role.LIST
 
+	def _get_states(self) -> set[controlTypes.State]:
+		states = super().states
+		if self.windowStyle & winUser.LBS_EXTENDEDSEL:
+			states.add(controlTypes.State.MULTISELECTABLE)
+		return states
+
 
 class SysLinkClient(IAccessible):
 	def reportFocus(self):

source/NVDAObjects/UIA/__init__.py

@@ -1891,6 +1891,7 @@ def _get_keyboardShortcut(self):
 
 	_UIAStatesPropertyIDs = {
 		UIAHandler.UIA_HasKeyboardFocusPropertyId,
+		UIAHandler.UIA.UIA_SelectionCanSelectMultiplePropertyId,
 		UIAHandler.UIA_SelectionItemIsSelectedPropertyId,
 		UIAHandler.UIA_IsDataValidForFormPropertyId,
 		UIAHandler.UIA_IsRequiredForFormPropertyId,
@@ -1934,6 +1935,8 @@ def _get_states(self):
 					if role == controlTypes.Role.RADIOBUTTON
 					else controlTypes.State.SELECTED,
 				)
+		if self._getUIACacheablePropertyValue(UIAHandler.UIA.UIA_SelectionCanSelectMultiplePropertyId):
+			states.add(controlTypes.State.MULTISELECTABLE)
 		if not self._getUIACacheablePropertyValue(UIAHandler.UIA_IsEnabledPropertyId, True):
 			states.add(controlTypes.State.UNAVAILABLE)
 		try:

source/braille.py

@@ -279,6 +279,8 @@
 	controlTypes.State.ON: "⣏⣿⣹",
 	# Translators: Displayed in braille when a link destination points to the same page
 	controlTypes.State.INTERNAL_LINK: _("smp"),
+	# Translators: Displayed in braille when an object supports multiple selected items.
+	controlTypes.State.MULTISELECTABLE: _("msel"),
 }
 negativeStateLabels = {
 	# Translators: Displayed in braille when an object is not selected.
@@ -706,6 +708,11 @@ def getPropertiesBraille(**propertyValues) -> str:  # noqa: C901
 			states.discard(controlTypes.State.VISITED)
 			# Translators: Displayed in braille for a link which has been visited.
 			roleText = _("vlnk")
+		elif role == controlTypes.Role.LIST and states and controlTypes.State.MULTISELECTABLE in states:
+			states = states.copy()
+			states.discard(controlTypes.State.MULTISELECTABLE)
+			# Translators: Displayed in braille for a multi select list.
+			roleText = _("mslst")
 		elif (
 			name or cellCoordsText or rowNumber or columnNumber
 		) and role in controlTypes.silentRolesOnFocus:

source/config/configSpec.py

@@ -116,6 +116,7 @@
 		reportKeyboardShortcuts = boolean(default=true)
 		reportObjectPositionInformation = boolean(default=true)
 		guessObjectPositionInformationWhenUnavailable = boolean(default=false)
+		reportMultiSelect = boolean(default=false)
 		reportTooltips = boolean(default=false)
 		reportHelpBalloons = boolean(default=true)
 		reportObjectDescriptions = boolean(default=True)

source/controlTypes/processAndLabelStates.py

@@ -73,6 +73,9 @@ def _processPositiveStates(
 			and State.SELECTABLE in states
 		):
 			positiveStates.discard(State.SELECTED)
+			positiveStates.discard(State.MULTISELECTABLE)
+		elif not config.conf["presentation"]["reportMultiSelect"]:
+			positiveStates.discard(State.MULTISELECTABLE)
 	if role not in (Role.EDITABLETEXT, Role.CHECKBOX):
 		positiveStates.discard(State.READONLY)
 	if role == Role.CHECKBOX:

source/controlTypes/state.py

@@ -103,6 +103,7 @@ def negativeDisplayString(self) -> str:
 	HASPOPUP_LIST = setBit(49)
 	HASPOPUP_TREE = setBit(50)
 	INTERNAL_LINK = setBit(51)
+	MULTISELECTABLE = setBit(52)
 
 
 STATES_SORTED = frozenset([State.SORTED, State.SORTED_ASCENDING, State.SORTED_DESCENDING])
@@ -210,6 +211,9 @@ def negativeDisplayString(self) -> str:
 	# Translators: Presented when a link destination points to the page containing the link.
 	# For example, links of a table of contents of a document with different sections.
 	State.INTERNAL_LINK: _("same page"),
+	# Translators: Presented when the control allows multiple selected objects.
+	# For example, a list box that allows selecting multiple items.
+	State.MULTISELECTABLE: _("multi-select"),
 }
 
 

source/gui/settingsDialogs.py

@@ -2478,6 +2478,15 @@ def makeSettings(self, settingsSizer):
 			config.conf["presentation"]["guessObjectPositionInformationWhenUnavailable"],
 		)
 
+		# Translators: This is the label for a checkbox in the
+		# object presentation settings panel.
+		reportMultiSelectText = _("Report when lists support &multiple selection")
+		self.reportMultiSelectCheckBox = sHelper.addItem(wx.CheckBox(self, label=reportMultiSelectText))
+		self.bindHelpEvent("ReportMultiSelect", self.reportMultiSelectCheckBox)
+		self.reportMultiSelectCheckBox.SetValue(
+			config.conf["presentation"]["reportMultiSelect"],
+		)
+
 		# Translators: This is the label for a checkbox in the
 		# object presentation settings panel.
 		descriptionText = _("Report object &descriptions")
@@ -2542,6 +2551,7 @@ def onSave(self):
 		config.conf["presentation"]["guessObjectPositionInformationWhenUnavailable"] = (
 			self.guessPositionInfoCheckBox.IsChecked()
 		)
+		config.conf["presentation"]["reportMultiSelect"] = self.reportMultiSelectCheckBox.IsChecked()
 		config.conf["presentation"]["reportObjectDescriptions"] = self.descriptionCheckBox.IsChecked()
 		config.conf["presentation"]["progressBarUpdates"]["progressBarOutputMode"] = self.progressLabels[
 			self.progressList.GetSelection()

source/winUser.py

@@ -154,6 +154,7 @@ class GUITHREADINFO(Structure):
 LBS_OWNERDRAWFIXED = 0x0010
 LBS_OWNERDRAWVARIABLE = 0x0020
 LBS_HASSTRINGS = 0x0040
+LBS_EXTENDEDSEL = 0x0800
 CBS_OWNERDRAWFIXED = 0x0010
 CBS_OWNERDRAWVARIABLE = 0x0020
 CBS_HASSTRINGS = 0x00200

user_docs/en/changes.md

@@ -11,6 +11,9 @@ Windows 10 is the minimum Windows version supported.
 
 ### New Features
 
+* Added the possibility to report when multiple items can be selected in a list control.
+This can be enabled using the "Report when lists support multiple selection" setting in NVDA's object presentation settings. (#18365 @LeonarddeR)
+
 ### Changes
 
 * Added a button to the About dialog to copy the NVDA version number to the clipboard. (#18667)