Автор:	© Анатолий Камынин
Дата публикации:	2004

Язык сценариев Jaws имеет в своём арсенале более десятка функций, позволяющих организовать взаимодействие с пользователем в виде списков выбора (функции, скрипта или произвольного пункта), сообщений и полей ввода текста. Всё это помогает разработчику скриптов запрашивать у пользователя определённую информацию или предоставлять ему выбор из различных вариантов.

• Функция ActivateRunDialog
• Функция DlgSelectControls
• Функция dlgSelectFunctionToRun
• Функция DlgSelectItemInList
• Функция DlgSelectScriptToRun
• Функция DlgSysTray
• Функция ExMessageBox
• Функция InHJDialog
• Функция InputBox
• Функция IsSelectItemDlg
• Функция IsSelectScriptDlg
• Функция MessageBox
• Функция SmartMinimize
• Функция StartJAWSTaskList
• Функция TimedMessageBox

Функция ActivateRunDialog

Описание: Вызывает диалог "Запуск программы", в котором можно непосредственно ввести имя файла, документа или ссылки в интернет, и операционная система либо выполнит файл, либо загрузит указанный документ, либо перейдёт по ссылке.

Возвращаемое значение: Void

Параметры: отсутствуют

Эта функция доступна в следующих версиях:

1. PAC Mate 2.0 и более поздних

Функция DlgSelectControls

Описание: Выводит список элементов управления, с которыми можно произвести одно из следующих действий: щелчок правой кнопкой мыши, щелчок левой кнопкой мыши, двойной щелчок левой кнопкой мыши и перейти к элементу. Можно изменить заголовок этого окна, а также количество и состав кнопок, определённых по умолчанию.

Возвращаемое значение: Int. Число, соответствующее действию, которое произвёл пользователь (щелчок, двойной щелчок и т.п.). Ниже приведен список констант из файла HjConst.jsh, соответствующих определённым возвращаемым значениям:

• iD_RightSingleClick = 7001
• iD_LeftSingleClick = 7002
• iD_LeftDoubleClick = 7003
• iD_MoveTo = 7004

Параметр 1:

String, Список отображаемых элементов. Элементы списка должны быть разделены вертикальной чертой (|). Этот параметр является обязательным.

Параметр 2:

Int. Номер выбранного элемента. В этом параметре функция возвращает номер выбранного элемента. Этот параметр является обязательным.

Параметр 3:

String, Новый заголовок окна. Этот параметр является обязательным.

Параметр 4:

Int, Маска, которая определяет, какие кнопки следует оставить в диалоге. Доступные кнопки представлены в файле HjConst.jsh и имеют префикс bt_. Этот параметр является обязательным. Константы, описывающие кнопки приведены ниже (маска является комбинацией этих констант):

• bt_RightSingleClick = 1
• bt_LeftSingleClick = 2
• bt_LeftDoubleClick = 4
• bt_MoveTo = 8

Параметр 5:

Int, Кнопка по умолчанию, определяется через маску. Этот параметр является обязательным.

Эта функция доступна в следующих версиях:

1. PAC Mate 1.10 и более поздних
2. JAWS 4.51 и более поздних

Пример

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

Include "HjConst.jsh"
Script ExampleUserDialog ()
Var
	Int ret,
	Int nIndex,
	String sList

	let sList = "Первый пункт	|Второй пункт|Третий пункт"
	let ret =DlgSelectControls (sList, nIndex, "ВВам нужно выбрать...",
bt_RightSingleClick + bt_LeftSingleClick + bt_LeftDoubleClick,
bt_LeftSingleClick)
	Pause()
	If ret == iD_RightSingleClick Then
		SayString ("Правый щелчок по пункту с номером ")
	ElIf ret == iD_LeftSingleClick Then
		SayString ("Левый щелчок по пункту с номером ")
	ElIf ret == iD_LeftDoubleClick Then
		SayString ("Двойной щелчок по пункту с номером ")
	EndIf
	SayInteger(nIndex)
EndScript

Функция dlgSelectFunctionToRun

Описание: Выводит список функций для выбора одной из них, её выполнения и отображения результата её работы. Кнопка Execute обновляет отображаемый в списке результат работы выбранной функции. Это очень похоже на функцию dlgSelectScriptToRun, за исключением того, что элементы списка (имена функций) не только озвучиваются, но и результат их работы сразу помещается в список.

Возвращаемое значение: Void

Параметр 1:

String, Строка, содержащая список функций, разделенных таким же символом, что и список скриптов в функции DLGSelectScriptToRun (Однако на практике символ с кодом "\007" в качестве разделителя не проходит, но зато проходит вертикальная черта "|" -- см. пример). Этот параметр является обязательным.

Параметр 2:

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

Параметр 3:

Int. True - если необходимо, чтобы список функций был отсортирован по алфавиту, false - если в этом нет нужды. Этот параметр является обязательным.

Эта функция доступна в следующих версиях:

1. PAC Mate 1.10 и более поздних
2. JAWS 4.51 и более поздних

Пример

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

Include "HjConst.jsh"
Script ListOfFunctions()
Var
	string sList

	let sList="GetCurrentSchemeName|GetSystemDefaultLang|GetJFWVersion"
	dlgSelectFunctionToRun (sList, "Список функций для выполнения", TRUE)
EndScript

Функция DlgSelectItemInList

Описание: Выводит на экран диалог, который содержит набор пунктов меню. Если будет нажата кнопка Ок, то функция вернет индекс выбранного пункта.

Возвращаемое значение: Int. Ноль, если пользователь отказался от выбора (нажал Cancel), или номер выбранного пункта в противном случае.

Параметр 1:

String, Набор пунктов меню, разделенных символом с кодом "/007". Этот параметр является обязательным.

Параметр 2:

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

Параметр 3:

Int. Если TRUE, то список пунктов меню будет отсортирован. Этот параметр является обязательным.

Параметр 4:

Int. Номер пункта меню, на котором будет установлен фокус ввода при вызове данного диалога ( для Jaws 5.0 и выше). Этот параметр является необязательным.

Эта функция доступна в следующих версиях:

1. PAC Mate 1.10 и более поздних
2. JAWS 4.51 и более поздних

Пример

В примере представлен скрипт, который выводит диалог из четырёх пунктов меню и после выбора одного из пунктов сообщает его номер. Обратите внимание, что номер выбранного пункта соответствует его порядку в переменной sList, передаваемой в качестве параметра, а не расположению пунктов в диалоге (так как в диалоге они отсортированы по алфавиту).

Script DlgMenuFruits ()
Var
	Int iRet,
	String sList

	let sList = "Яблоко\007	Апельсин\007Груша\007Финики"
	let iRet =DlgSelectItemInList (sList, "Фрукты, сэр!", TRUE, 1)
	SayInteger(iRet)
EndScript

Функция DlgSelectScriptToRun

Описание: Выводит на экран диалог, содержащий набор скриптов, которые могут быть выполнены из этого диалога. Для выполнения выбранного скрипта следует нажать клавишу Execute.

Возвращаемое значение: Void

Параметр 1:

String, Список скриптов, разделенный символом с кодом "\007". Этот параметр является обязательным.

Параметр 2:

String, Строка, которая будет отображаться в заголовке диалога. Если в качестве параметра передается пустая строка (""), то в заголовке диалога будет стоять "Perform Script". Этот параметр является обязательным.

Параметр 3:

Int. Если TRUE, то список скриптов будет отсортирован. Этот параметр является обязательным.

Эта функция доступна в следующих версиях:

1. PAC Mate 1.10 и более поздних
2. JAWS 4.51 и более поздних

Пример

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

Script SelectScript()
Var
	String sList

	let sList="SayActiveCursor\007SayCursorType\007SaySystemTime"
	DlgSelectScriptToRun (sList, "", TRUE)
EndScript

Функция DlgSysTray

Описание: Выводит на экран диалог, содержащий список значков, расположенных в системной панели (System Tray).

Возвращаемое значение: Int. Целое число, показывающее, какое действие следует выполнить, чтобы активировать выбранный элемент в системной панели. Это может быть щелчок левой кнопкой мыши (Left Mouse Button), щелчок правой кнопкой мыши (Right Mouse Button) или двойной щелчок левой кнопкой мыши (double click of the left mouse button).

Параметр 1:

String, Список значков в системной панели. Этот параметр является обязательным.

Параметр 2:

Int. Количество значков в системной панели. Этот параметр является обязательным.

Эта функция доступна в следующих версиях:

1. JAWS 4.51 и более поздних

Функция ExMessageBox

Описание: Выводит на экран стандартное сообщение (Message box) Windows. Это весьма похоже на действие функции MessageBox, за исключением того, что теперь можно указывать заголовок сообщения и тип окна сообщения, то есть количество кнопок и вид отображаемой иконки. (Для тех, кто знаком с Win32 API, не составит труда узнать в этой функции родную функцию Windows API MessageBox).Функция возвращает номер кнопки, которая была нажата пользователем.

Возвращаемое значение: Int. Целое число, показывающее, какая кнопка была нажата пользователем.

Параметр 1:

String, Текст сообщения, выводимый в окне сообщения. Этот параметр является обязательным.

Параметр 2:

String, Текст заголовка окна сообщения. Этот параметр является обязательным.

Параметр 3:

Int. Комбинация констант, определяющих тип окна сообщения. Значения констант находятся в файле HJConst.jsh. Константы следует разделять вертикальной чертой (|), например: MB_YESNOCANCEL|MB_DEFBUTTON1 устанавливает кнопку Yes (Да) в качестве выбранной по умолчанию.

Эта функция доступна в следующих версиях:

1. PAC Mate 1.10 и более поздних
2. JAWS 4.51 и более поздних

Пример

В этом примере приведён фрагмент скрипта, в котором на экране отображается сообщение с двумя кнопками "Да" и "Нет". В зависимости от того, какую кнопку нажал пользователь, озвучивается соответствующее сообщение.

Include "HjConst.jsh"
;...
Script offer ()
Var
	string title,
	string message,
	int type

; текст сообщения
	let message = "Вы согласны слетать на Марс?"
;заголовок окна сообщения
	let title = "Горящие путевки"
;тип диалога: две кнопки и по умолчанию выбрана кнопка "Да"
	let type = MB_YESNO | MB_DEFBUTTON1
; При нажатии "Да" возвращается IDYES
If ( IDYES ==ExMessageBox (message, title, type)) Then
		SayString ("Вы согласились.")
	Else
		SayString("Вы отказались.")
	EndIf
EndScript

Функция InHJDialog

Описание: Проверяет, активен ли один из диалогов, вызываемых функциями JAWS. К таким диалогам относятся JAWSFind, GraphicsLabeler, DlgSelectItemInList и DlgSysTray.

Возвращаемое значение: Int. TRUE - если такой диалог активен, FALSE - в противном случае.

Параметры: отсутствуют

Эта функция доступна в следующих версиях:

1. PAC Mate 1.10 и более поздних
2. JAWS 4.51 и более поздних

Функция InputBox

Описание: Выводит на экран окно простого диалога, содержащего четыре элемента управления. Один элемент управления - это поле редактирования, в которое пользователь может ввести текстовую информацию. Другой элемент управления - это статический текст, который поясняет, какую информацию должен ввести пользователь. Кроме того, диалог содержит две кнопки: Ок и Cancel. После того как пользователь ввёл текст и нажал Enter или кнопку Ок, введённый текст возвращается функцией в своём первом параметре.

Возвращаемое значение: Int. 1 - если нажата кнопка Ок, 0 - если нажата кнопка Cancel.

Параметр 1:

String, Текст подсказки, выводимый рядом с полем редактирования. Этот параметр является обязательным.

Параметр 2:

String, Текст заголовка окна диалога. Этот параметр является обязательным.

Параметр 3:

String, В этом параметре функция возвращает текст, введённый пользователем в поле редактирования, если пользователь нажал кнопку Ок. Если нажата кнопка Cancel, то этот параметр будет содержать нулевую строку. Этот параметр является обязательным.

Эта функция доступна в следующих версиях:

1. PAC Mate 1.10 и более поздних
2. JAWS 4.51 и более поздних

Пример

В этом примере на экран выводится диалог для ввода фразы, которая произносится синтезатором, если пользователь нажал кнопку Ок.

Script InputBoxExample ()
Var
	Int iRet,
	String sText
	
	let iRet = InputBox ("Введите текст и нажмите кнопку Ок:",
"Пример InputBox", sText)
	If iRet Then
		SayString("Введён текст:"+ sText)
	EndIf
EndScript

Функция IsSelectItemDlg

Описание: Сначала проверяет, виден ли фокус ввода в приложении JFW. Затем проверяет Control Id, чтобы определить, является ли окно диалогом, создаваемым функцией DLGSelectItemInList.

Возвращаемое значение: Int. 0 - если не тот диалог, 1 - если это нужный диалог.

Параметры: отсутствуют

Эта функция доступна в следующих версиях:

1. PAC Mate 1.10 и более поздних
2. JAWS 4.51 и более поздних

Функция IsSelectScriptDlg

Описание: Сначала проверяет виден ли фокус в приложениях JFW. Потом проверяет control ID, чтобы определить, активен ли диалог SelectScriptList control.

Возвращаемое значение: Int. 0 - если false и 1 - если true.

Параметры: отсутствуют

Эта функция доступна в следующих версиях:

1. PAC Mate 1.10 и более поздних
2. JAWS 4.51 и более поздних

Пример

Пример содержит два скрипта, которым необходимо назначить две различные комбинации клавиш. Один скрипт выводит на экран диалог со списком скриптов. Если в этот момент вызвать второй скрипт, то он сообщит, что активен диалог выбора скрипта. Если второй скрипт вызвать в любой другой момент (когда диалог не является активным), то скрипт сообщит об этом. Это бывает необходимо, чтобы не допустить выполнение каких-либо других скриптов, пока пользователь не выбрал скрипт в нужном диалоге.

Include "HjConst.jsh"

Script IsScriptDialog()
; Определяет активен ли диалог выбора скрипта
If IsSelectScriptDlg ()Then
	SayString("Вы в диалоге выбора скрипта")
Else
	SayString("Диалога для выбора скрипта нет")
EndIf
EndScript
;Выводит диалог со списком из трех скриптов
Script SimpleDialog ()
Var
	String sList
	
	let sList = "SaySystemTray\007SayAppVersion\007SayActiveCursor"
	DlgSelectScriptToRun (sList, "", TRUE)
EndScript

Функция MessageBox

Описание: Функция используется для вывода сообщения (message box) на экран. Это может быть использовано в конструкции If...Then...Else..., чтобы при определённом условии вывести на экран сообщение.

Возвращаемое значение: Void

Параметр 1:

String, Строка, заключённая в двойные кавычки, или переменная типа String, или функция возвращающая значение типа String, содержащие текст, который будет выведен в окне сообщения. Этот параметр является обязательным.

Эта функция доступна в следующих версиях:

1. PAC Mate 1.10 и более поздних
2. JAWS 4.51 и более поздних

Функция SmartMinimize

Описание: Закрывает активное окно. Если активным является окно диалога, то вызов этой функции аналогичен нажатию кнопки Ок (или кнопки по умолчанию). Если у активного окна есть в правом верхнем углу (в строке заголовка) кнопка с крестиком (Закрыть), то вызов этой функции аналогичен щелчку по указанной кнопке. Функция также полезна для закрытия некоторых окон, которые не реагируют на нажатие клавиши Escape или щелчки по кнопке Закрыть в верхнем правом углу заголовка.

Возвращаемое значение Void

Параметры: отсутствуют

Эта функция доступна в следующих версиях:

1. PAC Mate 2.01 и более поздних

Функция StartJAWSTaskList

Описание: Позволяет пользователю сворачивать, разворачивать, запускать приложения и переключаться между ними.

Возвращаемое значение: Int. 0 - если JAWSTaskList.dll не может быть загружена, 1 - если эта функция успешно вызвана из dll.

Параметры: отсутствуют

Эта функция доступна в следующих версиях:

1. JAWS 4.51 и более поздних

Функция TimedMessageBox

Описание: Позволяет выводить на экран сообщение, в течение определённого времени ожидающего действий пользователя.

Возвращаемое значение: Void

Параметр 1:

Int. Комбинация констант с префиксом MB_ из файла HjConst.jsh или просто 0 (для установок по умолчанию), определяющих вид и поведение окна сообщения. Можно использовать ICONERROR или другие константы, определяющие вид иконки, чтобы наделить сообщение общепринятыми знаками и звуковыми сигналами. Этот параметр является обязательным.(Следует заметить, что поскольку тип возвращаемого значения void, то бессмысленно использовать константы, определяющие количество кнопок в сообщении. Кроме того, почему-то нерабочими оказались попытки получить окно сообщения с любыми константами, кроме нуля).

Параметр 2:

String, Текст, который будет выведен в окне сообщения. Этот параметр является обязательным.

Параметр 3:

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

Параметр 4:

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

Эта функция доступна в следующих версиях:

1. JAWS 4.51 и более поздних

Пример

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

Include "HjConst.jsh"
Script Message()
Var
	String sMessage,
	String sTitle

	Let sMessage = "Нажмите кнопку Ок, чтобы закрыть это окно. Или же оно исчезнет само собой через 1 минуту."
	Let sTitle = "Пример сообщения"
	TimedMessageBox (0, sMessage, sTitle, 60000)
EndScript