Объекты, методы и свойства JAWS UIA Script API

(По материалам Freedom Scientific)
Дата публикации:06.01.2017
Поделиться в Twitter Поделиться в F******k Поделиться в VKontakte Поделиться в Telegram Поделиться в Mastodon

Введение

JAWS UIA Script API -- это специальный набор объектов, доступных в сценариях программы экранного доступа JAWS for Windows и предоставляющих возможность взаимодействия с инфраструктурой Microsoft User Interface Automation (сокращённо: UI Automation или UIA). Технология UI Automation пришла на смену технологии Microsoft Active Accessibility (MSAA). Подробную информацию о UI Automation можно найти на сайте Microsoft.

Ниже приведено описание объектов, методов, свойств и событий, доступных через JAWS UIA Script API.

Поскольку с каждой версией Microsoft Windows расширяются возможности, предоставляемые средствами UI Automation Automation, то необходимо обращаться к документации Microsoft, чтобы уточнить, какие интерфейсы UIA, методы и свойства поддерживаются в какой версии Windows. Наиболее полная поддержка представленных в этой статье методов и свойств реализована в Windows 8.1, но немало из них поддерживаются даже в Windows XP при условии, что в системе установлен Microsoft .Net Framework 3.5).

Все объекты, методы и события, описанные в этой статье, доступны в JAWS с версии 15.0.5056.

Терминология

Терминология, принятая в этой статье, не отличается универсальностью и очевидностью , поэтому нуждается в пояснении.

UIA-элемент

Чтобы избежать использования такого длинного словосочетания, как "элемент автоматизации пользовательского интерфейса" (UI Automation element), были выбраны варианты "UIA-элемент" или совсем короткий "элемент", если контекст не требует уточнения, о каком виде элементов идёт речь . Стоит принять во внимание, что сам по себе термин "элемент" крайне многозначен -- это может быть и элемент управления, и элемент списка, и многое другое. Но в этой статье основной акцент сделан на элементе автоматизации пользовательского интерфейса.

UIA-элемент -- это COM-объект, предоставляющий возможность взаимодействовать с элементами графического пользовательского интерфейса вспомогательному программному обеспечению (например, программам экранного доступа), а также средствам тестирования.

Шаблоны управления

Шаблоны управления (или просто шаблоны) -- это абстракция для классификации элементов управления в соответствии с их общими функциональными возможностями независимо от типа элемента управления или его внешнего вида.Для того чтобы подчеркнуть последнее обстоятельство, было решено придерживаться термина "шаблон управления", а не "шаблон элемента управления". UI Automation использует шаблоны управления для представления общих форм поведения элементов управления. Например, можно использовать шаблон управления Invoke для элементов управления, которые могут быть активированы (Например, кнопки), а шаблон управления Scroll -- для элементов управления, которые имеют полосы прокрутки (например, ListBox, ListView или ComboBox). Поскольку каждый шаблон управления представляет собой отдельную характеристику, они могут быть объединены, чтобы описать полный набор функциональных возможностей, поддерживаемых конкретным элементом управления.

Получение объекта FSUIA

Главным объектом в JAWS UIA script API является FSUIA. Используя этот объект, вы можете получить другие объекты, которые представляют UIA-элементы, получить возможность обхода дерева UIA элементов, регистрировать UIA-события и многое другое.

Чтобы в сценарии получить объект FSUIA, используйте встроенную функцию JAWS CreateObjectEx следующим образом:

var object myObject = CreateObjectEx ("FreedomSci.UIA", false, "UIAScriptAPI.x.manifest" );

Можно создать несколько объектов FSUIA, но вряд ли в этом возникнет реальная потребность.

Свойства

В UIA Script API все свойства доступны только для чтения, исключая те, для которых в этом документе явно указано "get/put".

Кеширование

в целях повышения производительности системы, когда клиент запрашивает UI Automation, то элемент или данные будут кешированы. JAWS UIA Script API обрабатывает механизм UIA-кеширование внутри. Использование такого подхода позволяет совместить эффективность и простоту API.

Тип bool

В настоящее время язык сценариев JAWS не поддерживает переменные булева типа. Термин bool используется далеедля обозначения целочисленного значения, где 0 означает логическое false, а любое ненулевое значение -- логическое true.

Тип variant

В языке сценариев JAWS тип variant представляет переменную, тип которой неизвестен во время компиляции. Variants может быть int, string, handle или object, и может быть использован, как любой из этих типов. Ещё можно использовать встроенную функцию JAWS GetVariantType, чтобы определить текущий тип переменной variant. Хотя разработчики сценариев, возможно, уже имеют представление о базовом типе на основе контекста. Например, если вы запросили свойство name UIA-элемента, то возвращаемый тип будет variant, но основной тип почти наверняка будет string. Если вы не знаете тип данного variant, вы можете объявить переменную в сценарии как переменную известного типа.Например: если функция GetProperty возвратит variant, но вы знаете, что возвращаемое свойство будет иметь тип string, Можно непосредственно присвоить возвращаемое значение строковой переменной, вместо того чтобы объявлять её с типом variant. Но даже если вы не знаете, что variant подразумевает string, вы можете передать эту переменную функции, которые принимают тип string.

Специальные целые типы

Имеются несколько наборов предопределённых целочисленных значений, используемых в методах и свойствах UI Automation. Они представляют различные типы элементов, типы свойств, идентификаторы шаблонов и так далее. Для разработчиков сценариев JAWS эти типы объявлены в файле UIA.jsh. В этом файле значения каждого из типов, перечисленных ниже, предваряются комментарием, содержащим имя типа, чтобы упростить поиск.

  • AnnotationTypeID
  • ControlTypeID
  • DockPosition
  • Endpoint
  • EventID
  • ExpandCollapseState
  • LegacySelectionFlags
  • LiveSetting
  • OrientationTypeID
  • PropertyID
  • RowOrColumnMajor
  • ScrollAmountID
  • StructureChangeTypeID
  • StyleID
  • SupportedTextSelectionID
  • SynchronizedInputType
  • TextAttributeID
  • TextUnit
  • ToggleState
  • TreeScope
  • WindowInteractionState
  • WindowVisualState
  • ZoomUnit

Передача параметров по ссылке

Когда параметр передаётся функции по ссылке, значение параметра не только передаётся функции, но также возвращается функцией. Таким образом, после того, как функция, которая принимает параметр по ссылке, вернёт управление, значение ссылочного параметра может оказаться другим.Это способ передачи нескольких возвращаемых значений посредством одного вызова функции.В этой статье конструкция ByRef используется для обозначения параметров, которые должны передаваться функции по ссылке. В языке сценариев JAWS, когда параметр передаётся по ссылке, он должен быть передан с использованием одну из ссылочных функций: IntRef, StringRef или IDispatchRef. Последняя функция используется, если тип переменной -- object.

Вот пример вызова метода с параметрами, передаваемыми по ссылке:

var int x;
var int y;
element.GetClickablePoint(IntRef(x), IntRef(y));

Когда эта функция вернёт управление, x и y будут содержать координаты точки щелчка.

Массивы

В таблице ниже перечислены типы массивов, предоставляемых UIA Script API. Хотя типы элементов, содержащихся в каждом массиве различны, все массивы ведут себя одинаково.

Чтобы узнать количество элементов в массиве, используйте свойство Count, например: myArray.Count.

Чтобы получить соответствующий элемент массива по индексу, заключите индекс в круглые скобки после имени массива, например: myArray(5). первому элементу массива соответствует нулевой индекс.

Наконец, массивы можно использовать в цикле ForEach следующим образом:

var string s;
ForEach s in myArray
; что-то делаем с переменной s
EndForEach
Массив Тип элемента
FSUIAElementArray FSUIAElement
FSUIAIntArray int
FSUIARectArray FSUIARect
FSUIAStringArray string
FSUIATextRangeArray FSUIATextRange

Объекты

Напомним, что несмотря на различные имена объектов, о которых речь пойдёт далее, в сценариях JAWS все они представлены типом Object.

Объект FSUIA

Методы
Имя Описание
bool AddAutomationEventHandler( EventID, FSUIAElement, TreeScope ); Регистрирует обработчик, который будет получать события UI Automation. См. раздел События для получения более подробной информации.
bool AddFocusChangedEventHandler(); Регистрирует обработчик, который будет получать события изменения фокуса. См. раздел События для получения более подробной информации.
bool AddPropertyChangedEventHandler( PropertyID, FSUIAElement, TreeScope ); Регистрирует обработчик, который будет получать события изменения свойств. См. раздел События для получения более подробной информации.
bool AddStructureChangedEventHandler( FSUIAElement, TreeScope ); Регистрирует обработчик, который будет получать события изменения структуры. См. раздел События для получения более подробной информации.
bool CheckNotSupported( variant ); Проверяет предоставленный VARIANT на наличие идентификатора Not Supported ("не поддерживается").
bool CompareElements( FSUIAElement, FSUIAElement ); Сравнивает два UIA-элемента, чтобы определить, представляют ли они один и тот же базовый элемент пользовательского интерфейса.
bool CompareRuntimeIds( FSUIAIntArray, FSUIAIntArray ); Сравнивает два целочисленных массива, содержащих идентификаторы времени выполнения (IDs), дабы определить, является ли их содержимое одинаковым и принадлежат ли они одному и тому же элементу пользовательского интерфейса.
FSUIACondition CreateAndCondition( FSUIACondition, FSUIACondition ); Создаёт условие, которое выбирает элементы, которые соответствуют обоим условиям.
FSUIACondition CreateBoolPropertyCondition( PropertyID, bool ); Создаёт условие для свойства Boolean.
FSUIACondition CreateFalseCondition(); Создаёт условие, которое всегда ложно (false).
FSUIACondition CreateIntPropertyCondition( PropertyID, int ); Создаёт условие для свойства integer.
FSUIACondition CreateNotCondition( FSUIACondition ); Создаёт условие, которое отрицает указанное условие.
FSUIACondition CreateOrCondition( FSUIACondition, FSUIACondition ); Создаёт комбинацию двух условий, где существует совпадение, если одно из условий истинно.
FSUIACondition CreateStringPropertyCondition( PropertyID, string ); Создаёт условие для свойства string.
FSUIATreeWalker CreateTreeWalker( FSUIACondition ); Возвращает интерфейс IUIAutomationTreeWalker, который может использоваться для обхода дерева UI Automation. Элементы в дереве соответствует указанному условию.
FSUIACondition CreateTrueCondition(); Возвращает предопределённое условие, которое выделяет все элементы.
FSUIAElement GetElementFromHandle( handle ); Возвращает UIA-элемент для указанного дескриптора окна.
FSUIAElement GetElementFromIAccessible( object, int ); Возвращает UIA-элемент для указанного accessible-объекта из сервера Microsoft Active Accessibility. Параметр 2 -- это идентификатор дочернего MSAA элемента нужного объекта.
FSUIAElement GetElementFromPoint( int, int ); Возвращает интерфейс FSUIAElement для UI элемента в указанной точке на рабочем столе. Параметр 1 -- это координата x указанной точки, а параметр 2 -- это координата y.
FSUIAElement GetFocusedElement(); Возвращает UIA-элемент, который содержит фокус ввода.
string GetPatternProgramaticName( PatternID ); Возвращает зарегистрированное программное имя шаблона управления.
string GetPropertyProgramaticName( PropertyID ); Возвращает зарегистрированное программное имя свойства.
FSUIAElement GetRootElement(); Возвращает the UIA-элемент, который представляет Рабочий стол (desktop).
bool PollForPotentialSupportedPatterns( FSUIAElement, ByRef FSUIAIntArray, ByRef FSUIAStringArray ); Возвращает шаблоны управления, которые могут поддерживаться UIA-элементом. Параметр 2 -- это массив PatternIDs. Параметр 3 -- это массив локализованных строк имён шаблонов.
bool PollForPotentialSupportedProperties( FSUIAElement, ByRef FSUIAIntArray, ByRef FSUIAStringArray ); Возвращает свойства, которые могут поддерживаться UI Automation элементом. Параметр 2 -- это массив PropertyIDs. Параметр 3 -- это массив локализованных строк с именами свойств.
Свойства
Тип Имя Описание
bool AutoSetFocus Вызывает ли UI Automation шаблон управления методы автоматической установки фокуса на целевой элемент. (get/put)
int ConnectionTimeout Время в миллисекундах, в течение которого UI Automation будет ожидать ответ поставщика на запрос клиента для элемента автоматизации. (get/put)
FSUIACondition ContentViewCondition Предопределённый объект-условие для выделения содержащихся элементов.
FSUIATreeWalker ContentViewWalker Интерфейс IUIAutomationTreeWalker, который используется для обнаружения элементов содержимого.
FSUIACondition ControlViewCondition Предопределённое условие для выделения элементов управления.
FSUIATreeWalker ControlViewWalker Интерфейс IUIAutomationTreeWalker, который используется для определения элементов управления.
FSUIACondition RawViewCondition Условие для предопределённого условия, Uкоторое выделяет все элементы пользовательского интерфейса в неотфильтрованном виде.
FSUIATreeWalker RawViewWalker Интерфейс IUIAutomationTreeWalker, который используется для обхода нефильтрованного вида дерева UI Automation .
int TransactionTimeout Время в миллисекундах, в течение которого UI Automation будет ждать ответ поставщика на запрос клиента информации об элементе автоматизации. (get/put)

Объект FSUIAAnnotation

Этот объект предоставляет доступ к аннотациям в документе. Это могут быть, например, комментарии на документа.

Свойства
Тип Имя Описание
string Author Имя автора аннотации.
string DateTime Дата и время, когда аннотация была создана.
FSUIAElement Target Аннотированный элемент.
AnnotationTypeID TypeID Значение, которое идентифицирует тип аннотации. Смысловые константы и их значения см. в файле UIA.JSH после комментария "; AnnotationTypeID".
string TypeName Локализованное название типа аннотации.

Объект FSUIACondition

Объект FSUIACondition не имеет членов, доступных из кода сценариев.

Объект FSUIADock

используется для взаимодействия с элементами управления, которые могут быть закреплены в док-контейнере, например, панелей инструментов или палитры инструментов.

Методы
Имя Описание
bool SetPosition(DockPosition ); Устанавливает позицию закрепления текущего элемента в док-контейнере. Допустимые значения параметра см. в файле UIA.JSH после комментария "; DockPosition".
Свойства
Тип ИмяОписание
DockPosition Position Позиция закрепления текущего элемента в контейнере. Символические константы и их значения см. в файле UIA>JSH после комментария "; DockPosition".

Объект FSUIADrag

Этот объект представляет элемент, который можно перетаскивать в рамках операции drag-and-drop.

Методы
Имя Описание
FSUIAElementArray GetGrabbedItems(); Возвращает коллекцию -элементов, которые пользователь может перетащить как часть операции перетаскивания.
Свойства
Тип Имя Описание
string DropEffect Локализованная строка, которая указывает на то, что происходит, когда пользователь отпускает этот элемент во время операции drag-and-drop.
FSUIAStringArray DropEffects Возвращает массив локализованных строк, которые перечисляют весь набор эффектов, которые могут произойти, когда над текущим элементом выполняется операция drag-and-drop .
bool IsGrabbed Может ли пользователь схватить текущий элемент в процессе операции drag-and-drop.

Объект FSUIADropTarget

Этот объект предоставляет доступ к элементам управления,которые могут выступать целевыми для операции перетаскивания (drag-and-drop ).

Свойства
Тип Имя Описание
string Effect Локализованная строка, которая описывает то, что происходит, когда пользователь отпускает захваченный элемент на текущей цели.
FSUIAStringArray Effects Возвращает массив локализованных строк, в котором перечислены все эффекты, которые могут произойти, когда пользователь отпускает захваченный элемент на текущей цели.

Объект FSUIAElement

Этот объект служит для доступа к Ui Automation элементу. Как было сказано ранее, один UIA-элемент может сочетать в себе несколько шаблонов управления, по этой причине большинство методов объекта FSUIAElement -- это методы, возвращающие объект соответствующего шаблона управления.

Методы
Возвращает объект шаблона, если соответствующий шаблон управления поддерживается текущим элементом.
Имя Описание
FSUIAElement BuildUpdatedCache(); Возвращает новый объект FSUIAElement с обновлённым кешем.
FSUIAElementArray FindAll( TreeScope, FSUIACondition ); Возвращает все UIA-элементы, которые удовлетворяют указанному условию.
FSUIAElement FindFirst( TreeScope, FSUIACondition ); Возвращает первый дочерний элемент или нисходящий элемент, которые удовлетворяют указанному условию.
bool GetClickablePoint( ByRef int, ByRef int ); Возвращает координаты точки элемента, куда может быть выполнен щелчок. Параметр 1 -- это координата x. Параметр 2 -- это координата y.
FSUIADock GetDockPattern(); Возвращает объект шаблона, если соответствующий шаблон управления поддерживается текущим элементом.
FSUIADrag GetDragPattern(); Возвращает объект шаблона, если соответствующий шаблон управления поддерживается текущим элементом.
FSUIADropTarget GetDropTargetPattern(); Возвращает объект шаблона, если соответствующий шаблон управления поддерживается текущим элементом.
FSUIAExpandCollapse GetExpandCollapsePattern(); Возвращает объект шаблона, если соответствующий шаблон управления поддерживается текущим элементом.
FSUIAGridItem GetGridItemPattern(); Возвращает объект шаблона, если соответствующий шаблон управления поддерживается текущим элементом.
FSUIAGrid GetGridPattern(); Возвращает объект шаблона, если соответствующий шаблон управления поддерживается текущим элементом.
FSUIAInvoke GetInvokePattern(); Возвращает объект шаблона, если соответствующий шаблон управления поддерживается текущим элементом.
FSUIAItemContainer GetItemContainerPattern(); Возвращает объект шаблона, если соответствующий шаблон управления доступен.
FSUIALegacyIAccessible GetLegacyIAccessiblePattern(); Возвращает объект шаблона, если соответствующий шаблон управления доступен.
FSUIAMultipleView GetMultipleViewPattern(); Возвращает объект шаблона, если соответствующий шаблон управления поддерживается текущим элементом.
variant GetPropertyValue(PropertyID ); Возвращает значение указанного свойства UIA-элемента.
FSUIARangeValue GetRangeValuePattern(); Возвращает объект шаблона, если соответствующий шаблон управления поддерживается текущим элементом.
FSUIAIntArray GetRuntimeID(); Возвращает уникальный идентификатор UI элемента.
FSUIAScrollItem GetScrollItemPattern(); Возвращает объект шаблона, если соответствующий шаблон управления поддерживается текущим элементом.
FSUIAScroll GetScrollPattern(); Возвращает объект шаблона, если соответствующий шаблон управления поддерживается текущим элементом.
FSUIASelectionItem GetSelectionItemPattern(); Возвращает объект шаблона, если соответствующий шаблон управления поддерживается текущим элементом.
FSUIASelection GetSelectionPattern(); Возвращает объект шаблона, если соответствующий шаблон управления поддерживается текущим элементом.
FSUIASpreadsheetItem GetSpreadsheetItemPattern(); Возвращает объект шаблона, если соответствующий шаблон управления поддерживается текущим элементом.
FSUIASpreadsheet GetSpreadsheetPattern(); Возвращает объект шаблона, если соответствующий шаблон управления поддерживается текущим элементом.
FSUIAStyles GetStylesPattern(); Возвращает объект шаблона, если соответствующий шаблон управления поддерживается текущим элементом.
FSUIASynchronizedInput GetSynchronizedInputPattern(); Возвращает объект шаблона, если соответствующий шаблон управления поддерживается текущим элементом.
FSUIATableItem GetTableItemPattern(); Возвращает объект шаблона, если соответствующий шаблон управления поддерживается текущим элементом.
FSUIATable GetTablePattern(); Возвращает объект шаблона, если соответствующий шаблон управления поддерживается текущим элементом.
FSUIATextChild GetTextChildPattern(); Возвращает объект шаблона, если соответствующий шаблон управления поддерживается текущим элементом.
FSUIATextEdit GetTextEditPattern(); Возвращает объект шаблона, если соответствующий шаблон управления поддерживается текущим элементом.
FSUIAText GetTextPattern(); Возвращает объект шаблона, если соответствующий шаблон управления поддерживается текущим элементом.
FSUIAToggle GetTogglePattern(); Возвращает объект шаблона, если соответствующий шаблон управления поддерживается текущим элементом.
FSUIATransform GetTransformPattern(); Возвращает объект шаблона, если соответствующий шаблон управления поддерживается текущим элементом.
FSUIAValue GetValuePattern(); Возвращает объект шаблона, если соответствующий шаблон управления поддерживается текущим элементом.
FSUIAVirtualizedItem GetVirtualizedItemPattern(); Возвращает объект шаблона, если соответствующий шаблон управления поддерживается текущим элементом.
FSUIAWindow GetWindowPattern(); Возвращает объект шаблона, если соответствующий шаблон управления поддерживается текущим элементом.
bool SetFocus(); Помещает клавиатурный фокус в данный UIA-элемент.
bool ShowContextMenu(); Программно вызывает контекстное меню для целевого элемента.
Свойства
Тип Имя Описание
string AcceleratorKey Клавиша-ускоритель для элемента.
string AccessKey Клавиша быстрого доступа для элемента.
string AriaProperties Значение свойства ARIA текущего элемента.
string AriaRole Роль текущего элемента.
string AutomationId UI Automation идентификатор текущего элемента.
FSUIARect BoundingRectangle Координаты прямоугольника, который полностью охватывает текущий элемент.
string ClassName Имя класса текущего элемента.
FSUIAElementArray ControllerFor Массив элементов, для которых текущий элемент служит в качестве контроллера.
int ControlType Тип элемента управления.
int Culture Идентификатор культуры.
FSUIAElementArray DescribedBy Массив элементов, которые описывают текущий элемент.
FSUIAElementArray FlowsFrom Массив элементов, которые указывают порядок чтения перед текущим элементом.
FSUIAElementArray FlowsTo Возвращает массив элементов, устанавливающих порядок чтения после текущего элемента.
string FrameworkID Имя базового фреймворка пользовательского интерфейса.
bool HasKeyboardFocus Значение, которое показывает, содержит ли элемент клавиатурный фокус.
string HelpText Текст подсказки для текущего элемента.
bool IsContentElement Является ли элемент содержимым.
bool IsControlElement Является ли элемент пользовательского интерфейса элементом управления.
bool IsDataValidForForm Содержит ли элемент корректные данные для формы.
bool IsEnabled Доступен ли UIA-элемент.
bool IsKeyboardFocusable Может ли UIA-элемент принимать клавиатурный фокус.
bool IsOffscreen Присутствует ли элемент на экране.
bool IsPassword Содержит ли элемент скрываемый пароль.
bool IsRequiredForForm Является ли элемент в форме обязательным для заполнения.
string ItemStatus Описание состояния пункта внутри элемента.
string ItemType Описание типа пункта, представленного элементом пользовательского интерфейса.
FSUIAElement LabeledBy Элемент, который имеет текстовую метку для текущего элемента.
LiveSetting LiveSetting Тип уведомлений, если таковые имеются, которые элемент посылает, когда изменяется его содержимое.
string LocalizedControlType Локализованное описание типа элемента управления. Например, Э"Элемент меню" для пункта в выпадающем меню или "Кнопка" для кнопки.
string Name Имя UI-элемента.
handle NativeWindowHandle Дескриптор окна с текущим элементом.
bool OptimizeForVisualContent Предоставляет ли поставщик только видимые элементы.
OrientationTypeID Orientation Ориентация элемента.
int ProcessId Идентификатор процесса, которому принадлежит элемент.
string ProviderDescription Описание поставщика UI Automation для текущего элемента.

Объект FSUIAExpandCollapse

Этот объект предоставляет доступ к элементам, которые можно развернуть, раскрывая вложенные элементы, и свернуть, скрывая их. Например, элемент управления ComboBox ("Поле со списком").

Методы
Имя Описание
void Collapse(); Скрывает все дочерние элементы, органы управления и прочее содержимое текущего элемента.
void Expand(); Отображает все дочерние элементы, органы управления и прочее содержимое текущего элемента.
Свойства
Тип Имя Описание
ExpandCollapseState ExpandCollapseState Состояние элемента (раскрыт или закрыт).

Объект FSUIAGrid

Этот объект предоставляет доступ к элементам, которые поддерживают "сеточную" функциональность, такую как изменение и перемещение ячеек, например, режим больших значков в Windows Explorer или простая таблица в Microsoft Office Word.

Методы
Имя Описание
FSUIAElement GetItem( int, int ); Возвращает UIA-элемент, представляющий ячейку сетки. Параметр 1 -- это номер строки (отсчитывается, начиная с нуля), параметр 2 -- это номер столбца (отсчитывается, начиная с нуля).
Свойства
Тип Имя Описание
int ColumnCount Количество столбцов в сетке.
int RowCount Количество строк в сетке.

Объект FSUIAGridItem

Этот объект предоставляет доступ к отдельным элементам (ячейкам) "сетки". Например, каждая ячейка в детальном просмотре Windows Explorer.

Свойства
Тип Имя Описание
int Column Индекс столбца, в котором находится элемент. Первому столбцу соответствует нулевой индекс.
int ColumnSpan Количество столбцов, объединённых текущим элементом.
FSUIAElement ContainingGrid Элемент (сетка), включающий в себя текущий элемент.
int Row Индекс строки, в которой находится текущий элемент. Первой строке соответствует нулевой индекс.
int RowSpan Количество строк, объединённых текущим элементом.

Объект FSUIAInvoke

Этот объект предоставляет доступ к шаблону управления для элементов, посредством которых можно вызвать определённое действие, например Button ("Кнопка").

Методы
Имя Описание
bool Invoke(); Вызывает действие, связанное с элементом управления, Например щелчок по кнопке.

Объект FSUIAItemContainer

Методы
Имя Описание
FSUIAElement FindItemByProperty( FSUIAElement, PropertyID, variant ); Возвращает вложенный элемент, найденный на основании указанного значения свойства.

Объект FSUIALegacyIAccessible

Этот объект используется для доступа к свойствам и методам объектов MSAA.

Методы
Имя Описание
void DoDefaultAction(); Выполняет действие по умолчанию (MSAA ).
object GetIAccessible(); Возвращает объект IAccessible, который связан с UIA-элементом.
FSUIAElementArray GetSelection(); Возвращает массив выделенных дочерних элементов (MSAA).
bool Select(LegacySelectionFlags ); Выполняет выделение (MSAA).
bool SetValue( string ); Устанавливает значение свойства Value (MSAA).
Свойства
Тип Имя Описание
int ChildID Дочерний идентификатор текущего элемента (MSAA).
string DefaultAction Действие по умолчанию для текущего элемента (MSAA).
string Description Описание элемента (MSAA).
string Help Строка подсказки для элемента (MSAA).
string KeyboardShortcut Клавиатурное сочетание для элемента (MSAA).
string Name Имя элемента (MSAA).
int Role Идентификатор роли элемента (MSAA).
int State Идентификатор состояния элемента (MSAA).
string Value Значение элемента (MSAA).

Объект FSUIAMultipleView

Этот объект предоставляет доступ к элементам, которые могут переключаться между несколькими представлениями одного и того же набора информации, данных или дочерних элементов, например, элемент управления ListView, в котором данные доступны в виде эскизов, плитки, значков, списка или таблицы.

Методы
Имя Описание
FSUIAIntArray GetSupportedViews(); Возвращает коллекцию идентификаторов видов элементов управления.
string GetViewName( int ); Возвращает имя вида элемента управления.
bool SetCurrentView( int ); Устанавливает вид элемента управления.
Свойства
Тип Имя Описание
int CurrentView Идентификатор вида элемента управления.

Объект FSUIARangeValue

Этот объект предоставляет доступ к элементам, которые имеют диапазон значений. Например, элемент управления, который отображает год может иметь диапазон 1900-2010, в то время как элемент управления, который отображает месяцы будет иметь диапазон 1-12.

Методы
Имя Описание
bool SetValue( int ); Устанавливает значение элемента управления.
Свойства
Тип Имя Описание
bool IsReadOnly Значение только для чтения.
int LargeChange Значение, которое добавляется или вычитается из значения элемента управления, когда сделано большое изменение, например, когда нажата клавиша PAGEDown.
int Maximum Максимальное значение.
int Minimum Минимальное значение.
int SmallChange Значение, которое прибавляется или вычитается из значения элемента управления, когда выполняется минимальное изменение, например, когда нажата клавиша со стрелкой.
int Value Значение элемента управления.

Объект FSUIARect

Этот объект представляет прямоугольную область, ограниченную левым верхним и правым нижним углом.

Свойства
Тип Имя Описание
int Bottom Нижняя координата прямоугольника.
int Left Левая координата прямоугольника.
int Right Правая координата прямоугольника.
int Top The Верхняя координата прямоугольника.

Объект FSUIAScroll

Этот объект предоставляет доступ к элементам, которые поддерживают горизонтальную и/или вертикальную прокрутку, чтобы отобразить всю информацию в области просмотра.

Методы
Имя Описание
bool Scroll(ScrollAmountID, ScrollAmountID ); Прокрутить видимую область содержимого горизонтально и вертикально. Параметр 1 -- горизонтально. Параметр 2 -- вертикально.
bool SetScrollPercent( int, int ); Устанавливает позицию прокрутки в процентах по горизонтали и вертикали. Параметр 1 -- величина по горизонтали. Параметр 2 -- величина по вертикали.
Свойства
Тип Имя Описание
bool HorizontallyScrollable Поддерживает ли элемент горизонтальную прокрутку.
int HorizontalScrollPercent Текущая позиция (в процентах) горизонтальной прокрутки.
int HorizontalViewSize Текущий размер области просмотра по горизонтали прокручиваемого элемента.
bool VerticallyScrollable Поддерживает ли элемент вертикальную прокрутку.
int VerticalScrollPercent Текущая позиция (в процентах) вертикальной прокрутки.
int VerticalViewSize Текущий размер по вертикали области просмотра прокручиваемого элемента.

Объект FSUIAScrollItem

Этот объект предоставляет доступ к отдельным элементам, содержащимся в прокручиваемой области, например, элемент управления List в элементе управления ComboBox.

Методы
Имя Описание
void ScrollIntoView(); Прокручивает область содержимого объекта-контейнера, чтобы показать UIA-элемент в пределах видимой области (viewport) контейнера.

Объект FSUIASelection

Этот объект предоставляет доступ к элементам, которые поддерживают выделение содержащихся в них объектов, например, разные виды списков (ListBox, ComboBox).

Методы
Имя Описание
FSUIAElementArray GetSelection(); Возвращает массив выделенных элементов внутри объекта-контейнера.
Свойства
Тип Имя Описание
bool CanSelectMultiple Поддерживает ли элемент множественное выделение.
bool IsSelectionRequired Должен ли постоянно быть выбран хотя бы один элемент.

Объект FSUIASelectionItem

Методы
Имя Описание
bool AddToSelection(); Добавляет текущий элемент в коллекцию выделенных элементов.
bool RemoveFromSelection(); Снимает выделение с текущего элемента.
void Select(); Снимает выделение с любых других элементов, а затем выделяет текущий элемент.
Свойства
Тип Имя Описание
bool IsSelected Выделен ли текущий элемент.
FSUIAElement SelectionContainer Элемент, который выступает в качестве контейнера для текущего элемента.

Объект FSUIASpreadsheet

Этот объект представляет шаблон управления для элементов, реализующих функционал электронной таблицы.

Методы
Имя Описание
FSUIAElement GetItemByName( string ); Возвращает UIA-элемент, который представляет ячейку таблицы с указанным именем, например, A1.

Объект FSUIASpreadsheetItem

Методы
Имя Описание
FSUIAElementArray GetAnnotationObjects(); Возвращает массив элементов, предоставляющих аннотации, связанных с данной ячейкой электронной таблицы.
FSUIAIntArray GetAnnotationTypes(); Возвращает массив идентификаторов типов аннотаций, обозначающих типы аннотаций, связанных с данной ячейкой электронной таблицы.
Свойства
Тип Имя Описание
string Formula Формула, содержащаяся в данной ячейке.

Объект FSUIAStyles

Свойства
Тип Имя Описание
string ExtendedProperties Локализованная строка, которая содержит список расширенных свойств элемента в документе.
int FillColor Цвет заливки элемента в документе.
int FillPatternColor Цвет образца, использованного для заливки элемента в документе.
string Shape Форма элемента в документе.
StyleID StyleID Идентификатор визуального стиля, связанного с элементом в документе.
string StyleName Название визуального стиля, связанного с элементом в документе.

Объект FSUIASynchronizedInput

Методы
Имя Описание
bool Cancel(); Заставляет UI Automation поставщика остановить приём событий мыши или клавиатурного ввода.
bool StartListening(SynchronizedInputType ); Заставляет UI Automation поставщика начать приём событий мыши или клавиатурного ввода.

объект FSUIATable

Методы
Имя Описание
FSUIAElementArray GetColumnHeaders(); Возвращает коллекцию UIA-элементов, представляющих все заголовки столбцов в таблице.
FSUIAElementArray GetRowHeaders(); Возвращает коллекцию UIA-элементов, представляющих все заголовки строк в таблице.
Свойства
Тип Имя Описание
RowOrColumnMajor RowOrColumnMajor Основное направление обхода таблицы.

Объект FSUIATableItem

Методы
Имя Описание
FSUIAElementArray GetColumnHeaderItems(); Возвращает заголовки столбца, связанные с текущим элементом таблицы (ячейкой).
FSUIAElementArray GetRowHeaderItems(); Возвращает заголовки строки, связанные с текущим элементом таблицы (ячейкой).

Объект FSUIAText

Методы
Имя Описание
FSUIATextRange GetCaretRange( ByRef int ); Возвращает диапазон текста нулевой длины в позиции курсора (каретки) в поле редактирования. Параметр 1 -- это ссылка на целочисленную переменную, которая указывает, содержит ли поле редактирование клавиатурный фокус; 0 -- ложь, любое другое значение -- истина.
FSUIATextRangeArray GetSelection(); Возвращает коллекцию текстовых диапазонов, которые в данный момент представляют выделенный текст в полях редактирования.
FSUIATextRangeArray GetVisibleRanges(); Возвращает массив непересекающихся текстовых диапазонов в поле редактирования, где каждый текстовый диапазон представляет собой непрерывный видимый участок текста.
FSUIATextRange RangeFromAnnotation( FSUIAElement ); Возвращает текстовыйй диапазон, содержащий текст, который является целью аннотации, связанной с указанным элементом аннотации.
FSUIATextRange RangeFromChild( FSUIAElement ); Возвращает текстовый диапазон, охватывающий дочерний элемент, такой как изображения, гиперссылки, таблицы Microsoft Excel или другой внедрённый объект.
FSUIATextRange RangeFromPoint( int, int ); Возвращает пустой текстовый диапазон, расположенный ближе всего к указанным координатам экрана. Параметр 1 -- это координата x. Параметр 2 -- это координата y.
Свойства
Тип Имя Описание
FSUIATextRange DocumentRange Текстовый диапазон, который охватывает основной текст документа.
SupportedTextSelectionID SupportedTextSelection Значение, указывающее тип выделения текста, который поддерживается элементом управления.

Объект FSUIATextChild

Свойства
Тип Имя Описание
FSUIAElement TextContainer Ближайший в иерархии предок текущего элемента, который поддерживает шаблон управления Text.
FSUIATextRange TextRange Текстовый диапазон, охватывающий текущий дочерний элемент.

Объект FSUIATextEdit

Этот объект предоставляет доступ к элементам, которые могут изменять текст программным способом, например, поле редактирования, в котором выполняется автоматическая коррекция текста.

Методы
Имя Описание
FSUIAElement GetActiveComposition(); Возвращает активный состав.
FSUIATextRange GetConversionTarget(); Возвращает текущий целевой диапазон преобразования.

Объект FSUIATextRange

Этот объект используется для получения текстового содержимого, атрибутов текста и внедрённых объектов из текстовых элементов управления, таких как поля редактирования и документы.

Методы
Имя Описание
bool AddToSelection(); Добавляет текстовый диапазон в коллекцию выделенных текстовых диапазонов для элемента управления, который поддерживает множественное, непересекающееся участки выделенного текста.
FSUIATextRange Clone(); Возвращает новый объект IUIAutomationTextRange, идентичный исходному и наследующий все его свойства.
bool Compare( FSUIATextRange ); Возвращает значение, указывающее, имеет ли текущий текстовый диапазон те же самые границы, что и другой текстовый диапазон.
int CompareEndPoints( Endpoint, FSUIATextRange, Endpoint ); Возвращает значение, которое указывает, совпадают ли начальная или конечная точка текущего текстового диапазона с начальной или конечной точкой другого диапазона.
bool ExpandToEnclosingUnit( TextUnit ); Выравнивает текстовый диапазон по границе указанного текстового блока. Диапазон расширяется, если он меньше, чем указанный блок, или сокращается, если он больше, чем указанный блок.
FSUIATextRange FindAttribute( TextAttributeID, variant, bool ); Возвращает подмножество текстовых диапазонов, которые имеют указанное значение текстового атрибута. Параметр 3 должен быть установлен в true, если необходимо выполнить поиск в обратном направлении; иначе false.
FSUIATextRange FindText( string, bool, bool ); Возвращает подмножество текстовых диапазонов, содержащих указанный текст. Параметр 2 должен быть true, если поиск должен выполняться в обратном направлении; иначе false. Параметр 3 должен быть true, если поиск должен быть регистронезависимым; иначе false.
variant GetAttributeValue( TextAttributeID ); Возвращает значение текстового атрибута.
FSUIARectArray GetBoundingRectangles(); Возвращает коллекцию ограничивающих прямоугольников для каждой полностью или частично видимой строки текста в текстовом диапазоне.
FSUIAElementArray GetChildren(); Возвращает коллекцию всех внедрённых объектов, которые расположены в пределах текстового диапазона.
FSUIAElement GetEnclosingElement(); Возвращает UIA-элемент, который охватывает текстовый диапазон.
string GetText( int ); Возвращает только текст из текстового диапазона. Параметр -- предельный размер возвращаемого текста в символах.
int Move( TextUnit, int ); Перемещает текстовый диапазон вперёд или назад на указанное число текстовых блоков. Отрицательное значение параметра 2 означает перемещение назад. Возвращает количество блоков, на которое реально удалось переместить текстовый диапазон.
bool MoveEndpointByRange( Endpoint, FSUIATextRange, Endpoint ); Перемещает конечную точку текущего текстового диапазона в указанную конечную точку второго текстового диапазона.
int MoveEndpointByUnit( Endpoint, TextUnit, int ); Перемещает конечную точку текстового диапазона на указанное количество текстовых блоков внутри документа. Отрицательное значение параметра 3 означает перемещение в обратном направлении. Возвращает количество текстовых блоков, на которое реально было выполнено перемещение.
bool RemoveFromSelection(); Удаляет текущий текстовый диапазон из существующей коллекции выделенных текстов в текстовом контейнере, который поддерживает множественное, непересекающееся выделение.
bool ScrollIntoView( bool ); Заставляет текстовый элемент управления выполнять прокрутку, пока текстовый диапазон не станет виден в области просмотра. Параметр 1 должен быть true, если необходимо прокрутить так, чтобы текстовый диапазон расположился в верхней части области просмотра; false если текстовый диапазон необходимо расположить в нижней части области просмотра.
bool Select(); Выделяет текст в текущем текстовом диапазоне и снимает ранее выполненное выделение с других элементов.
bool ShowContextMenu(); Программно вызывает контекстное меню.

Объект FSUIAToggle

Методы
Имя Описание
void Toggle(); Циклически переключает состояние элемента управления.
Свойства
Тип Имя Описание
ToggleState ToggleState Состояние элемента управления.

Объект FSUIATransform

Методы
Имя Описание
bool Move( int, int ); Перемещает UIA-элемент. Параметр 1 -- это координата левой стороны элемента управления. Параметр 2 -- это координата верхней стороны элемента управления.
bool Resize( int, int ); Изменяет размеры UI-элемента. Параметр 1 -- это новая ширина окна в пикселях. Параметр 2 -- это новая высота окна в пикселях.
bool Rotate( int ); Вращает UI-элемент. Параметр 1 -- это угол поворота в градусах (положительная величина означает вращение по часовой стрелке; отрицательная -- против часовой).
bool Zoom( int ); Масштабирует область просмотра элемента управления. Параметр 1 это величина масштабирования, указанная в процентах. Положительная величина увеличивает уровень масштабирования, а отрицательная -- уменьшает. Масштабирование осуществляется до ближайшего значения, поддерживаемого элементом управления.
bool ZoomByUnit(ZoomUnit ); Масштабирует область просмотра элемента управления, выравнивая её по указанному блоку. В качестве блока могут выступать значения, указанные в файле UIA.JSH после комментария "; ZoomUnit".
Свойства
Тип Имя Описание
bool CanMove Возможно ли переместить элемент.
bool CanResize Возможно ли изменить размеры элемента.
bool CanRotate Возможен ли поворот элемента.
bool CanZoom Поддерживается ли масштабирование области просмотра элемента управления.
int ZoomLevel Уровень масштабирования области просмотра элемента управления.
int ZoomMaximum Максимальный уровень масштабирования области просмотра элемента управления.
int ZoomMinimum Минимальный уровень масштабирования области просмотра элемента управления.

Объект FSUIATreeWalker

Этот объект предоставляет методы и свойства, используемые для перемещения по дереву UIA-элементов. В отношении объекта FSUIATreeWalker в нижеследующей таблице термин "текущий элемент" означает UIA-элемент, который значится в свойстве CurrentElement.

Методы
Имя Описание
bool GoToFirstChild(); Перемещает к первому дочернему элементу относительно текущего. Возвращает True при успешном перемещении; иначе --false.
bool GoToNextSibling(); Перемещает к следующему одноуровнему элементу относительно текущего. Возвращает true при успешном переходе; иначе -- false.
bool GoToParent(); Перемещает к родительскому элементу относительно текущего. Возвращает true при успешном переходе; иначе -- false.
bool GoToPriorSibling(); Переходит к предыдущему одноуровнему элементу относительно текущего. Возвращает true при успешном переходе; иначе -- false.
Свойства
Тип Имя Описание
FSUIACondition Condition Условие, которое определяет, какие из UIA-элементы, будут отобраны при обходе дерева UIA-элементов.
FSUIAElement CurrentElement Текущий элемент в дереве UIA-элементов (get/put).

Объект FSUIAValue

Методы
Имя Описание
bool SetValue( string ); Устанавливает значение элемента.
Свойства
Тип Имя Описание
bool IsReadOnly Значение элемента доступно только для чтения.
string Value Значение элемента.

Объект FSUIAVirtualizedItem

Методы
Имя Описание
bool Realize(); Создаёт полный UIA-элемент для виртуального элемента.

Объект FSUIAWindow

Методы
Имя Описание
bool Close(); Закрывает окно.
bool SetWindowVisualState(WindowVisualState ); Сворачивает, разворачивает или восстанавливает окно. Допустимые значения параметра см. в файле UIA.JSH после комментария "; WindowVisualState".
bool WaitForInputIdle( int ); Заставляет вызывающий код блокировать в течение указанного времени или пока связанный процесс не перейдёт в состояние ожидания, в зависимости от того, что завершится раньше.
Свойства
Тип Имя Описание
bool CanMaximize Можно ли развернуть окно.
bool CanMinimize Можно ли свернуть окно..
WindowInteractionState InteractionState Текущее состояние окна для взаимодействия с пользователем. Смысловые константы и их значения см. в файле UIA>JSH после комментария "; WindowInteractionState".
bool IsModal Является ли окно модальным.
bool IsTopmost Является ли окно верхним элементом в Z-порядке.
WindowVisualState VisualState Внешний вид окна; может быть нормальным (normal), распахнутым (maximized) или свёрнутым (minimized). Смысловые константы и их значения см. в файле UIA>JSH после комментария "; WindowVisualState".

События

Чтобы в сценарии JAWS организовать обработку событий от UIA-элементов, необходимо :

  1. Зарегистрировать соответствующий обработчик события при помощи вызова одного из методов add-event-handler объекта FSUIA. Например, в нижеследующем примере регистрируется обработчик для события изменения свойства Name:
    var object events = CreateObjectEx ("FreedomSci.UIA", false, "UIAScriptAPI.x.manifest" );
    var object element = events.GetFocusedElement();
    events.AddPropertyChangedEventHandler(UIA_NamePropertyId, element, TreeScope_Element | TreeScope_Descendants )
    
  2. Привязать этот обработчик к событийной функции обратного вызова в сценарии JAWS, для чего тот же объект FSUIA должен быть передан встроенной функции JAWS ComAttachEvents.Обратите внимание на второй параметр в следующем примере. Строка, указанная в качестве параметра, должна предварять имя событийной функции обратного вызова в файле сценария (имена функций обратного вызова и их параметры представлены в таблице ниже):
    ComAttachEvents( events, "UIA_");
    
  3. Затем в сценарии JAWS добавить функцию с именем UIA_PropertyChangedEvent, в которой и выполнить обработку события.<
    Теперь, когда произойдёт изменение UIA-свойства,то возникнет событие для свойства Name и в сценарии JAWS будет вызвана функция UIA_PropertyChangedEvent.
  4. var object nullObject; events = nullObject;

Замечание: В примерах выше объекты с именами event и element объявлены в качестве глобальных переменных.Если они были бы объявлены внутри функции, то когда функция завершится , объекты будут автоматически установлены в null, и никакая обработка событий выполняться не будет.

Событийные функции обратного вызова

Следующая таблица содержит имена и типы параметров доступных событийных функций обратного вызова.

Имя Описание
AutomationEvent( FSUIAElement, EventID ); Функция обратного вызова для события автоматизации. Параметр 1 -- это элемент, с которым произошло событие. Параметр 2 -- это идентификатор события.
FocusChangedEvent(FSUIAElement ); Функция обратного вызова для события изменения фокуса. Параметр 1 -- это новый элемент с фокусом.
PropertyChangedEvent( FSUIAElement, PropertyID, variant ); Функция обратного вызова для события изменения свойства. Параметр 1 -- это элемент, связанный с событием. Параметр 2 -- это идентификатор свойства, которое изменилось. Параметр 3 -- это новое значение изменившегося свойства.
StructureChangedEvent( FSUIAElement, StructureChangeTypeID, FSUIAIntArray ); Функция обратного вызова для события изменения структуры. Параметр 1 -- это элемент, с которым связано событие. Параметр 2 -- тип структурных изменений. Параметр 3 -- это run-time идентификаторы элементов, которых затронули изменения. Параметр 3 корректен, если StructureTypeID в параметре 2 имеет значение StructureChangeType_ChildRemoved.


Распространение материалов сайта означает, что распространитель принял условия лицензионного соглашения.
Идея и реализация: © Владимир Довыденков и Анатолий Камынин,  2004-2024