nvda

f7c00604 - UIA objects: introduce a global suggestion list item class for Windows 10. re #6241 (#6274)

UIA objects: introduce a global suggestion list item class for Windows 10. re #6241 (#6274) * UIA handler: add proper copyright header (based on Git log archive) * UIA objects: introduce a global suggestion list item class for Windows 10. re #6241 Windows 10 uses suggestions list for vairious things, including Start menu suggestions, Store recommendations, Settings app and others. Thus introduce NVDAObjects.UIA.SuggestionListItem, which derives its power from searchui.py version (searchui.py version is gone). * SearchUI: remove unneeded imports * UIA: add support for Controller For property. re #6241 Controller For property is used by an element to let another element depend on values given by the source element, useful if suggestions should be listed for a search field among other possibilities. For now, Controller For property has been added to property to event names map in UIA Handler. A UIA object that handles this event (a search box) is next. * Revert "UIA: add support for Controller For property. re #6241" This reverts commit a3b1ce57408fc571b1f92aa38901c243a8171fad. * UIA: add support for Controller For property. re #6241 Controller For property is used by an element to let another element depend on values given by the source element, useful if suggestions should be listed for a search field among other possibilities. For now, Controller For property has been added to property to event names map in UIA Handler. A UIA object that handles this event (a search box) is next. * NVDAObjects.UIA: introduce Search Field that'll handle controller for and announce appearance of suggestions. re #6241 Coming from Windows 10 App Essentials add-on: a Search Field is now available that'll detect controller for property event and announce either 'suggestions' or 'suggestions closed' if suggestions appear or disappear, respectively. This takes care of both Start Menu and other fields in Windows 10 (works best in Anniversary Update and later). * Search Field: check if search field is focused before asking for controller for object. re #6241 Review from Mick Curran (NV Access): Do not waste a function call for fetching focused element. Besides, make sure to check if the focused control is the search field before proceeding to announce appearance of suggestions. * Update copyright years, add a docstring to UIA objects (__init__). * Suggestion: a new behavior to allow NVDA to detect and announce suggestions. re #6241. Reviewed by Mick Curran (NV Access): announcement of search suggestion is something that NVDA should handle for other API's, such as suggestions in Firefox address bar, search suggestions in universal apps and so on. A new behavior named 'Suggestion' has been added that allows subclasses to provide custom routines when suggestions appear and disappear. This is handled by event_suggestionOpened and event_suggestionClosed, and by default NVDA will speak and braille this event. * UIA objects/Search field: use the new NVDAObjects.behaviors.Suggestion to announce suggestion appearance. re #6241. Reviewed by Mick Curran (NV Access): Based on the new Suggestion behavior mix-in, it is now possible for various objects to provide custom routines to let users know the appearance of suggestions. Thus UIA/Search Field is the first object to use this routine. * UIA objects/suggestions list: use raw UIA base tree walker to obtain suggestion list (parent). re #6241. Reviewed by Mick Curran (NV Access): it is better to use raw UIA for obtaining parent element. However, one must be careful to catch COM and value errors (COM because the element might not be there, and value because NULL pointer access is logged). The raw UIA method was also recommended by Derek Riemer. * UIA objects: updated comments, removed reference to Redstone. * UIA objects/Search field: don't allow suggestions detection be announced in Windows 10 Start menu for consistency with earlier versions of Windows. re #6241. iN Windows 10 Start menu, suggestions are announced automaticlaly, so no need to provide suggestion announcements. * NVDAObjects/behaviors: rename 'Suggestion' to 'EditableTextWithSuggestions' so the behavior can be better described. re #6241. If one inherits from 'Suggestion', the overall impression would be that the field is only going to display suggestions nad nothing else. Many suggestions are shown when text is entered, thus it is better to say 'EditableTextWithSuggestions' to better reflect what the behavior actually does. Also, a sound will be played to let users know the appearance of suggestions. (default vlaue). * Auto-suggestions: add a combo box in object presentation settings to configure how auto-suggestions should be announced. re #6241 * User guide: document auto-suggestions notification setting. re #6241. In the user guide, an explanatory text has been added to describe what auto-suggestions are. * Auto-suggestions: either play a sound or do nothing. re #6241. Comments from Mick Curran and Jamie Teh (NV Access): no need for a separate message option when announcing appearance of auto-suggestions, as the sound cue will let the user of this fact. However, braille users should be notified of this regardless of this flag being turned on (deaf-blind users should be notified of this). User guide and settings dialog: changed the control type and label for auto-suggestions setting to reflect change in behavior. * Search suggestions: allow Windows 10 Start menu and Edge to provide search suggestions. re #6241. Reviewed by Mick Curran (NV Access): allow Start menu search box and Edge's address omnibar to participate in providing auto-suggestions announcement. * Config: auto-suggestion setting is now part of configspec module. re #6241 * Update to miscDeps containing auto suggestions sounds. * NVDAObjects.UIA: catch UnboundLocalError for parentElement if parentElement fetcher fails. re #6241. In some cases, when Start menu opens, it isn't announced by NVDA. As a result, parent element fetcher fails when trying to instantiate suggestions list item, with a traceback that ends with UnboundLocalError. Catch this by moving the SuggestionsListItem selector to inside of the try block. * EditableTextWithSuggestions: remove braille message shown when suggestions close for consistency with other situations (such as browse mode toggle). re #6241. * NVDAObjects.UIA.SuggestionListItem: braille suggestion results as flash messages. re #6241. Suggestion from Davy Kager: provide a way to let braille users read search suggestion items. This is done by emulating some parts of speech.SpeakObjectProperties except the name and position info map will be fetched (position info map fetching is contingent on whether report position info setting is enabled from Object Presentation dialog). Ideally, NVDA objects should have a way to fetch braille flash messages for controls. Also reworded docstring for SuggestionListItem so it cna include other UIA-based suggestion list items such as Windows 8.x search results. * NVDAObjects.UIA.SuggestionsListItem: flash suggestion results in braille. re #6241, #6414. Instead of constructing the likely flash message, use a function used as part of Core issue 6414, which is much simpler than constructing the flash message from scratch. * UIA/SuggestionListItem/searchui: also classify Start search results context menu as a suggestions list item. re #6241. Oddly, the same behavior that's applied to suggestion items must work in Start suggestion's context menu, otherwise menu items will not be announced.