»спользование дерева параметров в скриптах JAWS

ƒата публикации:2011
ѕоделитьс€ в Twitter ѕоделитьс€ в Facebook ѕоделитьс€ в VKontakte ѕоделитьс€ в Telegram

»зменени€ в пользовательском интерфейсе

Ќачина€ с JAWS версии 9.0, диалог "Ќастройка информативности JAWS" (Adjust JAWS Verbosity) дл€ активного приложени€ был заменен на диалог "Ќастройка параметров JAWS" (Adjust JAWS Options). Ќовый диалог, как и прежний, можно вызвать при помощи комбинации клавиш Insert+V. ќднако в остальном этот диалог претерпел существенные изменени€. ¬место обычного списка параметров, теперь в диалоге все параметры представлены в виде многоуровневой древовидной структуры, что облегчает навигацию и поиск нужных параметров.

ƒерево параметров может содержать параметры (в документации JAWS может использоватьс€ термин "элемент" (item)) и категории (или узлы(nodes)), которые могут, в свою очередь, содержать вложенные категории и параметры , которые, в свою очередь... ѕараметры могут иметь различные значени€, вли€ющие на поведение JAWS в активном приложении.

ѕо дереву параметров можно перемещатьс€ при помощи клавиш со стрелками вверх и вниз. –аскрыть категорию, чтобы увидеть содержащиес€ в ней вложенные категории и параметры, можно при помощи клавиши со стрелкой вправо. «акрыть категорию можно при помощи клавиши со стрелкой влево.

 роме дерева параметров, в данном диалоге присутствует окно редактора с текстом подсказки. Ётот текст мен€етс€ в зависимости от того, на какой категории или параметре расположен курсор в дереве параметров.

»зменени€ в скриптах

“акие серьезные изменени€ в пользовательском интерфейсе потребовали изменений и в сценари€х JAWS. ’от€ комбинаци€ клавиш дл€ вызова диалога настроек не изменилас, но теперь она св€зана со скриптом AdjustJAWSOptions. —крипт AdjustJAWSVerbosity также присутствует в файле скриптов по умолчанию (default.jss), но дл€ этого скрипта не назначена комбинаци€ клавиш. ѕри желании, ее можно назначить при помощи ƒиспетчера клавиатуры.

–ассмотрим необходимый минимум функций дл€ работы с деревом параметров в скриптах JAWS.

ƒл€ того чтобы в дереве параметров отобразились параметры, которые мы собираемс€ использовать в наших сценари€х, необходимо выполнить следующие шаги:

  • ¬ файле сценариев интересующего нас приложени€ переопределить скрипт AdjustJAWSOptions, в котором необходимо создать список параметров и передать созданный список функции OptionsTreeCore, отвечающей за отображение диалога настроек.
  • ƒл€ каждого добавл€емого параметра определить функции обратного вызова дл€ изменени€ настроек.
  • ƒл€ каждого нашего параметра определить функции обратного вызова дл€ формировани€ текста подсказки.

 роме этого, могут потребоватьс€ дополнительные шаги в том случае,если необходимо создавать свои категории и подкатегории.

«амечание: ¬ угоду простоте изложени€ из нижеследующих примеров исключена обработка ошибок. “акже не используетс€ формат сообщений @msg, об€зательный дл€ корректной локализации скриптов, а также дл€ скриптов, предназначенных дл€ публичного распространени€ (иными словами, все строковые литералы помещены непосредственно в код скриптов, а не вынесены в файл сообщений .jsm).

ѕереопределение скрипта

„тобы вызвать диалог "Ќастройка параметров JAWS" (Adjust JAWS Options) дл€ активного приложени€, необходимо обратитьс€ к функции OptionsTreeCore.

” этой функции первый аргумент €вл€етс€ об€зательным, а второй и третий - необ€зательные. ќстановимс€ пока на первом аргументе, который €вл€етс€ строкой, содержащий список добавл€емых нами параметров JAWS. Ётот список имеет следующий предопределЄнный формат:

  • Ёлементы списка составл€ют одну строку и €вл€ютс€ ее сегментами.
  • —егменты строки отдел€ютс€ друг от друга символом вертикальной черты "|".
  •  аждый сегмент, в свою очередь, делитс€ ещЄ на две части. ѕерва€ часть - это им€ функции, которую JAWS будет вызывать, когда пользователь пытаетс€ изменить конкретный параметр; втора€ часть - это название параметра, которое будет отображатьс€ в дереве параметров. Ёти две части отдел€ютс€ друг от друга символом двоеточи€ ":".е

¬ скриптах вместо символа вертикальной черты можно использовать именованную константу _DLG_SEPARATOR, определЄнную в файле HjConst.jsh. Ёто позволит вашим скриптам не зависеть от конкретного значени€ символа-разделител€.

¬ общем виде строку списка параметров можно представить так:

"»м€_функции1:»м€_параметра1"+_DLG_SEPARATOR
	+"»м€_функции2:»м€_параметра2" +_DLG_SEPARATOR
	; и так далее дл€ всех добавл€емых параметров...
	

¬от пример простейшей реализации скрипта , в котором в дерево настроек добавл€ютс€ два параметра с именами ѕараметр1 и ѕараметр2 (разумеетс€, в реальных скриптах имена параметров и категорий необходимо выбирать такими, чтобы они характеризовали предназначение параметра или категории):

include "HjConst.jsh"
Script AdjustJAWSOptions ()
var
	string sList
	Let sList = "Option1:ѕараметр1"+_DLG_SEPARATOR
		+"Option2:ѕараметр2"
		
	OptionsTreeCore (sList)
EndScript

“еперь, если попробовать вызвать диалог "Ќастройка параметров JAWS" (Adjust JAWS Options), то в дереве этого диалога в самом начале будет располагатьс€ категори€ с названием "ѕараметры им€_конфигурации" (»м€_конфигурации Options), где им€_конфигурации - это им€ активной конфигурации (которое, как правило, соответствует имени исполн€емого файла активного приложени€). ¬нутри этой категории будут присутствовать два параметра: ѕараметр1 и ѕараметр2.

ќднако получившийс€ диалог нельз€ считать полноценным, так как пользователь не может изменить значени€ параметров (эти значени€ отсутствуют вовсе), а при перемещении по параметрам возникает ошибка вызова неизвестной функции.

„тобы диалог настроек работал корректно, необходимо дл€ каждого из добавленных параметров определить две функции обратного вызова: функцию, измен€ющую значение параметра, и функцию, возвращающую текст дл€ окна подсказки.

‘ункци€, измен€юща€ значение параметра

 огда в дереве диалога настроек пользователь мен€ет значение параметра при помощи клавиши ѕробел, то JAWS пытаетс€ вызвать функцию с именем, которое было указано в строке списка параметров. “акже эта функци€ вызываетс€, когда необходимо отобразить текстовый вариант текущего значени€ данного параметра. ƒл€ ѕараметра1 мы указали им€ функции Option1. ѕредположим, что значение этого параметра хранитс€ в глобальной переменной g_bOption1, котора€ может содержать 0 ("отключено") и 1 ("включено"):

globals
int g_bOption1

ѕростейший вариант определени€ функции, измен€ющей значение параметра, может выгл€деть так:

string Function Option1 (int iState)
; »змен€ем текущее значение.
If iState == 0 Then
	let g_bOption1 = not g_bOption1
EndIf

; ¬озвращаем текстовое описание
; текущего значени€.
If g_bOption1 Then
	return "включено"
EndIf
return "отключено"
EndFunction

 ак видно из примера, функци€ принимает один параметр - целочисленное значение iState. ≈сли это значение равно нулю, то функци€ должна изменить соответствующий параметр (т.е. это, в частном случае, признак того, что пользователь нажал пробел на соответствующем параметре в дереве диалога настроек). Ћогику изменени€ параметра определ€ет сам разработчик скрипта, исход€ из предназначени€ данного параметра. ¬ примере параметр фактически €вл€етс€ булевым, что позвол€ет дл€ его изменени€ использовать операцию инверсии.

–ассматриваема€ функци€ должна возвращать строковое описание текущего значени€. ¬озвращаема€ в этом примере строка будет отображена в дереве параметров напротив ѕараметра1.

“еперь, если вызвать диалог настройки параметров JAWS, то при помощи пробела можно будет измен€ть значение ѕараметра1 с "отключено" на "включено" и наоборот.

ƒл€ ѕараметра2 последовательность действий будет аналогичной, но им€ этой функции должно быть Option2, так как именно это им€ было указано в строке списка параметров. “акже надо предусмотреть глобальную переменную дл€ хранени€ текущего значени€ ѕараметра2.

‘ункци€, возвращающа€ текст подсказки

 ак уже было отмечено, в диалоги "Ќастройка параметров JAWS" (Adjust JAWS Options), кроме дерева параметров, присутствует окно текстового редактора, в котором отображаетс€ текст подсказки дл€ текущей категории или текущего параметра.

„тобы в этом окне дл€ добавл€емых параметров отображалс€ соответствующий текст подсказки, необходимо дл€ каждого параметра определить функцию обратного вызова, возвращающую этот текст.

»мена таких функций состо€т из имени функции, указанной в строке списка параметров, и суффикса "Hlp" (без кавычек). Ќапример, дл€ ѕараметра1 указана функци€ Option1, тогда функци€, возвращающа€ текст подсказки, будет иметь им€ Option1Hlp. ѕростейший вариант этой функции может выгл€деть так:

string Function Option1Hlp (int iState)
	return "ѕодсказка дл€ ѕараметра1."
EndFunction

ƒл€ ѕараметра2, соответственно, им€ функции примет вид Option2Hlp.

—оздание собственных категорий

ѕо умолчанию функци€ OptionsTreeCore помещает добавл€емые параметры в категорию с именем активной конфигурации, которое совпадает с именем исполн€емого файла активного приложени€. ќднако если необходимо €вно задавать категории дл€ своих параметров, то это можно сделать, как минимум, трем€ способами.

»мена категорий можно указать в списке параметров, который в виде строки передаетс€ в качестве первого аргумента функции OptionsTreeCore. ¬ этом случае им€ параметра превращаетс€ в своеобразный путь, подобно пути в файловой системе, где через разделители указываютс€ вложенные друг в друга каталоги, а завершаетс€ все именем файла. ¬ случае с деревом параметров, вместо каталогов, выступают категории, а вместо файла - им€ параметра. ¬ качестве разделител€ используетс€ символ крышки "^", например:

let sList = "Option1: атегори€1^ѕодкатегори€1^ѕараметр1" + _DLG_SEPARATOR
	+ "Option2: атегори€1^ѕодкатегори€2^ѕараметр2"

¬место символа "^", можно использовать именованную константу NODE_PATH_DEliMITER, определЄнную в файле UO.jsm.

ќднако такой способ указани€ вложенных категорий не очень удобен.

¬торой способ заключаетс€ в том, что название категории, в которую будут помещены параметры, можно непосредственно передать третьем аргументом функции OptionsTreeCore. ѕри этом второй аргумент этой функции должен быть False или 0. ќднако следует учесть, что в указанную категорию будут помещены только те параметры, дл€ которых не указаны категории в строке списка параметров. Ќапример:

Let sList = "Option1:ѕараметр1"+_DLG_SEPARATOR
	+"Option2:ѕараметр2"+_DLG_SEPARATOR
	+"Option3: атегори€5^ѕараметр3"
	
	OptionsTreeCore (sList,0," атегори€1")

¬ результате выполнени€ этого фрагмента в дереве параметров будут созданы две категории:  атегори€1 и  атегори€5. ¬  атегорию1 будут помещены ѕараметр1 и ѕараметр2, а в  атегории5 окажетс€ ѕараметр3.

“ретий способ предполагает знакомство со специальной функцией ConvertListToNodeList, котора€ переформатирует определЄнный список параметров, добавл€€ ко всем элементам указанную категорию.

ѕри вызове ‘ункции ConvertListToNodeList передаютс€ два аргумента. ѕервый аргумент - это ссылка на строку списка элементов. Ётот список будет преобразован в список с указанием категории.

¬торой аргумент - это им€ категории (включа€ подкатегории, разделенные символом "^"), которое будет добавлено к первому параметру, то есть к списку. «а подробност€ми можно обратитьс€ к справке ƒиспетчера скриптов или FSDN (раздел Strings).

¬от пример использовани€ этой функции:

Let sList = "Option1:ѕараметр1"+_DLG_SEPARATOR
	+"Option2:ѕараметр2"
	
ConvertListToNodeList(sList, "ѕодкатегори€1")
ConvertListToNodeList(sList, " атегори€1")
OptionsTreeCore (sList)

Ётот пример показывает, что при помощи функции ConvertListToNodeList можно создавать иерархию вложенных категорий (причем начинать надо с самой нижней). ¬ результате получим в дереве параметров  атегорию1, в которую будет вложена ѕодкатегори€1, в которой будут располагатьс€ ѕараметр1 и ѕараметр2. “от же результат можно получить однократным вызовом функции ConvertListToNodeList , указав вторым аргументом строку с категорией и подкатегорией:

ConvertListToNodeList(sList, " атегори€1^ѕодкатегори€1")

ƒругие примеры использовани€ можно посмотреть в функци€х TreeCoreGet*Options в файле UserOptions.jss.

ѕодсказка дл€ категории

„тобы передать текст подсказки дл€ созданной категории, надо определить собственный вариант функции NodeHlp . ¬ариант этой функции по умолчанию определЄн в файле UserOptions.jss.

¬от пример пользовательского определени€ в файле скриптов дл€ конкретного приложени€ (подразумеваетс€, что создана категори€ по умолчанию, им€ которой содержит им€ активной конфигурации):

string Function NodeHlp (string sNodeName)
	If StringContains (sNodeName, GetActiveConfiguration()) Then
		return "“екст подсказки дл€ нашей категории!"
	EndIf
	Return NodeHlp (sNodeName)
EndFunction

Ёта функци€ принимает один параметр - строку sNodeName, содержащую им€ категории дл€ которой требуетс€ подсказка. ƒалее выполн€етс€ проверка: если им€ требуемой категории содержит им€ активной конфигурации, то возвращаетс€ текст подсказки дл€ этой категории.

≈сли бы была создана не категори€ по умолчанию, а категори€ с конкретным именем (например, " атегори€1"), то проверку надо было бы выполн€ть на совпадение имЄн категорий:

If 0 == StringCompare(sNodeName, " атегори€1") Then
; ...


–аспространение материалов сайта означает, что распространитель прин€л услови€ лицензионного соглашени€.
»де€ и реализаци€: © ¬ладимир ƒовыденков и јнатолий  амынин,  2004-2021