Студия/Визуальные события
Визуальные события, описанные в этой статье, отличаются от обычных предопределенных событий языка, они не являются обычными функциями, а располагаются внутри формы и привязаны к форме или визуальному элементу, в зависимости от типа события. Для редактирования таких событий используется редактор форм Студии. Редактирование событий инициируется на закладке "события", при этом визуальный элемент, исходный код события которого необходимо изменить, должен быть выделен. Если требуется изменить исходный код события самой формы, необходимо, чтобы ни один из элементов не был выделен. Большинство событий формы, описанных здесь, могут вызываться несколько раз, если они описаны в подчиненных формах (на закладках группы страниц с закладками или в макросах). К примеру, событие OnOpen вызывается для всех подчиненных форм последовательно, а затем для основной формы, если хоть один из обработчиков события возвратит 0, загрузка формы будет остановлена.
Переменные, передаваемые в тело событий, а также принимаемые назад варьируются для каждого из событий, их наименования фиксированы и не могут быть изменены, в отличие от предопределенных функций, где наименования аргументов задает разработчик. Для всех событий всегда присутствует переменная Result, часто играющая роль результата события, однако, ее функция также зависит от конкретного события.
Визуальные события делятся на асинхронные и прерывающие. Описание каждого события содержит его тип. Принципиальная разница между этими двумя типами следующая:
- Асинхронные события не могут быть инициированы, когда текущий поток уже занят исполнением кода. Обычно такие события выполняют длительные операции, типа подсчета данных или формирования отчета. К примеру, событие OnClick для кнопок является асинхронных событием и может выполнить исходных код, который формируется отчет. Асинхронные события также с легкостью могут изменять пользовательский интерфейс или выполнять любые другие операции.
- Прерывающие (ожидающие или блокирующие) события могут приостановить текущее выполнение асинхронного события и выполнить свой код "вне очереди", после чего выполнение асинхронного события продолжится с того места, где оно было прервано. При инициации такого события, инициированного графическим интерфейсом, последний будет ожидать окончания его выполнения, после чего будет готов снова отвечать на запросы пользователя. Такое поведение связано с тем, что ответ или действие прерывающих событий требуется для продолжения. К примеру, при попытке сохранить строку в строчной части документа, программа события OnBeforeElementSaved решает, корректно ли заполнена строка, и, если что-то заполнено некорректно, возвращает ответ отказа, и операция сохранения отменяется, пользователю необходимо проверить, что он сделал не так и повторить попытку. Из-за того, что графический интерфейс находится в ожидании окончания прерывающего события, оно должно быть выполнено, как можно быстрее, чтобы графический интерфейс отвечал на команды пользователя. В связи с этим запуск длительных обработок во время выполнения таких событий не является правильным подходом. К примеру, в прерывающем (ожидающем) событии OnOpen неправильно будет выполнять формирование отчета, даже если отчет должен быть сформирован сразу после загрузки формы, вместо этого можно воспользоваться функцией InvokeEventAsync или асинхронным событием OnTimer, чтобы инициировать формирование. Прерывающее событие не может быть выполнено, если:
- Другое прерывающее событие уже выполняется в данный момент.
- Асинхронным событием инициирован режим транзакции (транзакция не может быть активна, когда поток находится в режиме ожидания пользователя и не исполняет какой-либо код).
- Форма не полностью инициализирована или уже удалена (деинициалирована).
Существует также особая категория прерывающих событий -- события-выражения. Данные события не могут содержать конструкции языка, а являются вычисляемыми выражениями, результат которых будет возвращен, как результат исполнения события (пример -- OnGetCaption).
Ниже дана таблица с кратким описанием и ссылками на статьи всех доступных визуальных событий.
| Имя события | Тип события | Применимость | Аргументы | Описание |
|---|---|---|---|---|
| OnOpen | Прерывающее | Форма, подчиненные формы | Param (не всегда), Option (не всегда), ModalResult (не всегда) | Событие, возникающее в момент открытия формы до ее полной инициализации, во время выполнения этого события форма все еще не видна на экране. Если во время события произойдет необработанное исключение или будут вызваны функции, типа Form.Close, Form.Destroy, загрузка формы будет остановлена и будет произведена попытка закрытия модуля. |
| OnReopen | Прерывающее | Форма, подчиненные формы | NewParam, NewOption | Событие, возникающее в момент попытки открытия уже существующей свободной формы (к примеру, журнала), вызванной с помощью LoadModule со способом вызова равным 1 (форма будет активирована, событие OnOpen повторно вызвано не будет, однако, будет вызвано данное событие). Форма уже имеет флаг полной инициализации в момент выполнения этого события. |
| OnClose | Прерывающее | Форма, подчиненные формы | Result | Событие, возникающее в момент закрытия формы. Обработчик события может отменить попытку закрыть форму. |
| OnTimer | Асинхронное | Форма, подчиненные формы | Событие, возникающее с периодичностью, указанной в переменной OnTimerInterval. Событие выполняется только в моменты, когда поток не занят другими обработками и ожидает действий оператора. | |
| OnSaveRequest | Прерывающее | Форма, подчиненные формы | Событие, возникающее при попытке пользователя или системы сохранить содержимое формы (к примеру, с помощью кнопки "дискета" на панели инструментов). Система не будет самостоятельно сохранять открытый объект базы данных, даже если это событие не задано, программе необходимо выполнить фрагмент, типа Form.Object.Save() для сохранения объекта при нажатии на кнопку или в подобных случаях.
| |
| OnStatusChange | Прерывающее | Форма, подчиненные формы | Событие, вызываемое при возникновении локальных изменений на форме или изменении объекта, редактируемого с помощью формы. К примеру, событие возникает при записи редактируемого элемента (Form.Object.Save()) или его пометке на удаление. Событие может быть использовано для обновления заголовка формы или каких-либо индикаторов на ней.
| |
| OnTaskbarMenuClick | Асинхронное | Форма | Index, Text, Value, Result | Событие, возникающее после того, как пользователь выберет пункт из встроенного меню на кнопке панели задач. Меню может быть задано программно, если меню не задано, кнопка меню не будет показана. Для задания меню см. атрибут TaskbarMenu. |
| OnMessage | Прерывающее | Форма | CallerThread, CallMode, Message, Param, Option, Result | Событие, возникающее при получении формой сообщений, отсылаемых с помощью функций SendMessageToForm, PostMessageToForm и пр. |
| OnSaveSettings | Прерывающее | Форма | SetName, FolderName, Result | Событие, возникающее до автоматического (либо по требованию пользователя) сохранения установок формы в файл установок на сервере. В понятие установок входят значения полей редактирования, флажков, тегов, позиций таблиц и пр. Автоматическое сохранение установок производится только для форм с флажком IsAutoSaveLoadSettings. Элементы, входящие в файл установок, должны иметь непустое поле Name (позиции таблиц и теги также записываются для любых элементов, связанных с базой данных). |
| OnLoadSettings | Прерывающее | Форма | SetName, FolderName, Result | Событие, возникающее до автоматической (либо по требованию пользователя) загрузки установок формы из файла установок на сервере. В понятие установок входят значения полей редактирования, флажков, тегов, позиций таблиц и пр. Автоматическая загрузка установок производится только для форм с флажком IsAutoSaveLoadSettings. Элементы, входящие в файл установок, должны иметь непустое поле Name (позиции таблиц и теги также загружаются для любых элементов, связанных с базой данных). |
| OnAfterLoadSettings | Прерывающее | Форма | Событие, возникающее после загрузки установок формы из файла установок на сервере. | |
| OnGetCaption | Прерывающее, выражение | Текстовое поле, Кнопка, Группа элементов | Событие, позволяющее получить заголовок элемента программно. Система вызывает событие автоматически для получения заголовка при прорисовке элемента на экране. Событие должно быть занимать минимальное время исполнения, иначе обновление формы может быть замедлено. | |
| OnClick | Асинхронное | Текстовое поле, Кнопка, Флажок, Переключатель, Группа элементов | Событие, возникающее при клике по элементу или нажатии на кнопку (в т.ч. с помощью клавиатуры). | |
| OnChangeOrClick | Прерывающее | Список значений, Группа страниц с закладками, Таблица значений, Дерево значений | Событие, возникающее при визуальном изменении (перемещении курсора) текущей строки, закладки или столбца элемента. | |
| OnDoubleClick | Асинхронное | Текстовое поле, Список значений, Группа элементов, Таблица значений, Внедренная электронная таблица, Дерево значений | Событие, возникающее при двойном клике левой клавишей мыши по элементу либо при нажатии Enter в таблице значений. | |
| OnRightClick | Асинхронное, Прерывающее (внедренная электронная таблица) | Текстовое поле, Редактируемое поле, Кнопка, Флажок, Переключатель, Поле со списком, Список значений, Группа элементов, Группа страниц с закладками, Таблица значений, Внедренная электронная таблица, Дерево значений | Result (не всегда) | Событие, возникающее при клике правой клавишей мыши по элементу. |
| OnAttachedButtons | Прерывающее | Текстовое поле, Редактируемое поле, Поле со списком, Список значений, Группа страниц с закладками, Таблица значений, Внедренная электронная таблица, Дерево значений | Index, Method, Object, Result | Событие, возникающее при нажатии на связанный элемент (саму кнопку или дополнительную кнопку выбора из меню). Событие работает как для линейных, для табличных элементов, так и при редактировании ячеек таблицы или электронной таблицы. |
| OnBeforeChange | Прерывающее | Редактируемое поле, Поле со списком | Key, Modifiers, Result | Событие, возникающее до принятия нажатия клавиши (или комбинацию клавиш) элементом. Нажатие может быть проигнорировано, если событие возвратит соответствующий результат. Для табличных элементов используется событие OnKeyPress. |
| OnAfterChange | Прерывающее | Редактируемое поле, Поле со списком | Событие, возникающее после принятия нажатия клавиши (или комбинацию клавиш), либо после какого-либо другого изменения элемента (выбора объекта для полей имеющих тип объекта базы данных, изменения даты с помощью календаря для полей, имеющих тип даты и т.п.). | |
| OnEnter | Прерывающее | Редактируемое поле, Флажок, Переключатель, Поле со списком, Список значений, Таблица значений, Внедренная электронная таблица, Дерево значений | Событие, возникающее в момент получения фокуса (активации) элементом диалога. | |
| OnExit | Прерывающее | Редактируемое поле, Флажок, Переключатель, Поле со списком, Список значений, Таблица значений, Внедренная электронная таблица, Дерево значений | IsChanged, Result | Событие, возникающее в момент потери фокуса (деактивации) элементом диалога. Потеря фокуса может быть проигнорирована, если событие возвратит соответствующий результат. |
| OnKeyPress | Прерывающее | Форма, Список значений, Таблица значений, Дерево значений | Key, KeyCombo, Char, Result | Событие, возникающее при нажатии на клавишу клавиатуры, когда текущий элемент или форма активны. Не все комбинации могут быть пойманы в этом событии. Для полей используется событие OnBeforeChange. |
| OnBeforeSelect | Прерывающее | Редактируемое поле, Список значений, Таблица значений, Внедренная электронная таблица | Method, Journal, Module, FormName, OutParam, OutOption, Flags, Filters, SortOrder, Columns, CustomSelectList, Result | Событие, возникающее в момент выбора элемента справочника или документа в реквизит диалога или ячейку таблицы (к примеру, при нажатии на связанный элемент ".."). Позволяет изменить свойства диалога выбора, который может быть представлен выпадающей таблицей или отдельным окном. |
| OnBeforeEditObject | Прерывающее | Редактируемое поле, Поле со списком, Список значений, Таблица значений, Внедренная электронная таблица | Object, Method, Module, FormName, OutParam, OutOption, Result | Событие, возникающее до открытия формы редактирования (или просмотра) объекта (при нажатии на связанные элементы _AB_INFO или _ABB_NEWBASED). Позволяет изменить открываемую по умолчанию форму для редактирования на требуемую или запретить открытие формы. |
| OnGetVisualProperties | Прерывающее | Поле со списком, Список значений | Index, ColumnIndex, Font, BackColor, IconIndex | Событие, возникающее до прорисовки пункта меню или элемента списка. Вызывается для получения визуальных параметров (таких как цвет, шрифт и пр.) для элемента. Для больших списков может замедлить обновление интерфейса, рекомендуется пользоваться методами типа Icon. |
| OnGetCellVisualProperties | Прерывающее | Таблица значений | Index, Font, BackColor, IconIndex | Событие, возникающее до прорисовки ячейки таблицы. Вызывается для получения визуальных параметров (таких как цвет, шрифт и пр.) для ячейки. Для больших таблиц может замедлить обновление интерфейса, рекомендуется пользоваться методами Icon, BackgroundColor, FontColor, FontStyle. |
| OnInitCombobox | Прерывающее | Поле со списком | ComboList | Событие, позволяющее заполнить элементы поля со списком до начала работы с ним. Возникает во время загрузки формы до вызова событий OnOpen. |
| OnBeforeEditLine | Прерывающее | Список значений | LineType, Result | Событие, возникающее до начала редактирования строки списка, позволяет разрешить или запретить редактирование. |
| OnAfterEditLine | Прерывающее | Список значений | IsChanged, Value, Result | Событие, возникающее в момент окончания редактирования строки списка, позволяет сохранить или запретить изменения, а также позволяет изменить сохраняемое в список значение. |
| OnChecking | Прерывающее | Список значений, Таблица значений | Index, ColumnIndex, Result | Событие, возникающее в момент (до изменения) установки или снятия флажка в строке списка или таблицы. Позволяет разрешить или запретить установку флажка. |
| OnLeafChecking | Прерывающее | Дерево значений | Leaf, Result | Событие, возникающее в момент (до изменения) установки или снятия флажка в элементе дерева. Позволяет разрешить или запретить установку флажка. |
| OnBeforeResize | Прерывающее | Разделитель групп элементов | NewSize, Result | Событие, возникающее при попытке пользователя передвинуть разделитель. Позволяет запретить или разрешить перемещение. |
| OnAfterResize | Прерывающее | Разделитель групп элементов | Событие, возникающее после передвижения разделителя и изменения размеров областей разделения формы. | |
| OnAfterNewElementCreated | Прерывающее | Таблица значений | IsCopied, Element, Line, Result | Событие, возникающее до начала редактирования нового элемента БД таблицы или строки строчной части элемента. Событие вызывается только для таблиц, связанных со строчной частью редактируемого объекта или таблиц, отображающих элементы справочника или документы, когда их редактирование происходит непосредственно в таблице (форма редактирования не открывается). Событие позволяет запретить создание новой строки (или нового объекта). |
| OnBeforeElementSaved | Прерывающее | Таблица значений | Element, Line, Result | Событие, возникающее непосредственно перед записью элемента БД в таблице элементов, либо строки в строчной части элемента. Событие вызывается только для таблиц, связанных со строчной частью редактируемого объекта или таблиц, отображающих элементы справочника или документы, когда их редактирование происходит непосредственно в таблице (форма редактирования не открывается). Событие позволяет запретить сохранение строки (или объекта). |
| OnAfterElementSaved | Прерывающее | Таблица значений | Element, Line | Событие, возникающее непосредственно после записи элемента БД в таблице элементов, либо строки в строчной части элемента. Событие вызывается только для таблиц, связанных со строчной частью редактируемого объекта или таблиц, отображающих элементы справочника или документы, когда их редактирование происходит непосредственно в таблице (форма редактирования не открывается). |
| OnBeforeEditCell | Прерывающее | Таблица значений | LineType, Result | Событие, возникающее до начала редактирования ячейки таблицы. Позволяет запретить или разрешить редактирование ячейки. |
| OnAfterEditCell | Прерывающее | Таблица значений | IsChanged, Value, Result | Событие, возникающее в момент окончания редактирования ячейки таблицы (т.е., при потере фокуса редактором ячейки). Позволяет запретить или разрешить потерю фокуса редактором ячейки. |
| OnGetRightClickMenu | Прерывающее | Таблица значений | ResultList, Result | Событие, возникающее до вывода на экран всплывающего меню, ассоциированного с текущей таблицей, вызываемого нажатием правой клавиши мыши. Событие позволяет изменить меню по умолчанию. |
| OnBeforeRefresh | Прерывающее | Таблица значений | Result | Событие, возникающее до обновления таблицы из БД (даже при автообновлении). Позволяет выполнить запрос на обновление программно, если обновление таблицы происходит нестандартным образом. |
| OnBeforeLoadElements | Прерывающее | Таблица значений | Result | Событие, возникающее перед загрузкой новых строк в табличный элемент. Позволяет подменить стандартную загрузку желаемой. Не вызывается для фиксированных строк таблицы (структуры родительских папок), которые, при наличии, зависят от атрибута FolderElement и будут уже добавлены в таблицу на момент вызова. |
| OnInitLine | Прерывающее | Таблица значений | IndexFrom, IndexTo | Событие, возникающее после загрузки диапазона новых строк в табличный элемент. Если задано, событие OnShowLine, данное вызываться не будет. Используется для заполнения полей, не принадлежащих базе данных, а также любых других изменений. |
| OnShowLine | Прерывающее | Таблица значений | IndexFrom, IndexTo | Событие, вызываемое для начальной инициализации строк, выводящихся на экран. Не будет вызвано, если задано событие OnInitLine. Используется для заполнения полей, не принадлежащих базе данных, а также любых других изменений. В отличие от OnInitLine, событие выполняется для строк, выводящихся на экран, а не для всех загруженных строк. Это может ускорить вывод таблицы, но замедлить навигацию в ней, что выгоднее для больших таблиц, не связанных с базой данных или строчных частей, имеющих большое количество строк. |
| OnGetFormNameForOperation | Прерывающее | Таблица значений | Index, Journal, Module, FormName, ControlName, OutParam, OutOption, Result | Событие, возникающее при необходимости получить имя модуля и формы для выполнения операции открытия таблицы или журнала. Вызывается для операций, отличающихся от редактирования объектов (при редактировании объектов вызывается OnBeforeEditObject) и открытия формы для выбора объектов (при выборе объектов вызывается OnBeforeSelect), к примеру, при нажатии на связанные элементы _ABB_MOVE, _ABB_OPENCHILDREN или _ABB_OPENPARENT. Позволяет изменить открываемую по умолчанию форму на требуемую или запретить открытие формы. |
| OnMoveToFolder | Прерывающее | Таблица значений | Element, Folder, Result | Событие, возникающее в момент интерактивного перемещения элемента в другую папку. Позволяет запретить или разрешить перемещение. |
| OnAfterFilterChange | Прерывающее | Таблица значений | Событие, возникающее после изменения быстрого фильтра в столбике таблицы. Событие будет вызываться только для таблиц, не связанных с базами данных, с установленной опцией IfQFiltersAlwaysAllowed. | |
| OnAfterSorting | Прерывающее | Таблица значений | Событие, возникающее после визуального изменения сортировки таблицы. | |
| OnBeforeEdit | Прерывающее | Внедренная электронная таблица | EditMode, ObjectType, ObjectIndex, Line, Column, AttButtons, EditValue, EditMask, Result | Событие, возникающее до начала редактирования ячейки или объекта встроенной таблицы. Если данное событие не задано, будет вызвано локальное, а затем глобальное событие OnBeforeEdit, которое также вызывается для свободных таблиц. |
| OnAfterEdit | Прерывающее | Внедренная электронная таблица | EditMode, ObjectType, ObjectIndex, Line, Column, IsChanged | Событие, возникающее после окончания редактирования ячейки или объекта встроенной таблицы. Если данное событие не задано, будет вызвано локальное, а затем глобальное событие OnAfterEdit, которое также вызывается для свободных таблиц. |
| OnDataChange | Прерывающее | Внедренная электронная таблица | Событие, возникающее при изменении любых данных в таблице. | |
| OnSelectionChange | Прерывающее | Внедренная электронная таблица | SelectType | Событие, возникающее при изменении выделенной области таблицы. |
| OnInitLeaf | Прерывающее | Дерево значений | Leaf | Событие, вызываемое для начальной инициализации загруженных элементов дерева. Система сама следит за тем, чтобы это событие было вызвано для каждой ветки всего один раз. |
| <Событие OLE> | Прерывающее | OLE-объект | Зависят от объекта и события | Событие объекта OLE, помещенного на форму. Система описывает набор переменных события, однако, для полного его описания необходимо обратиться к документации по конкретному объекту. |
