Руководство пользователя

События и их обработчики

В ответ на действия пользователя или поведение самой программы с объектами чертежа могут происходить следующие события:

При наступлении любого из перечисленных событий вслед за стандартной реакцией, предусмотренной в системе (например, выделением объекта по событию click), может быть вызвана любая функция на JavaScript, специально написанная для этого пользователем, – обработчик события.

Чтобы «прикрепить» обработчик к нужному объекту и событию, нужно вызвать специальный метод объекта addEventListener (переводится как добавить слушателя события), в который необходимо передать название события и ссылку на функцию-обработчик.

Например: у нас есть функция checkResult(), которую мы хотим вызывать всякий раз, когда пользователь щёлкает по кнопке B. Для этого необходимо выполнить

В.addEventListener("click", checkResult);

или

В.addEventListener("action", checkResult);

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

Вариант 1: записать это в скрипт для какой-нибудь кнопки C; туда же поместить описание функции checkResult(). Его недостаток в том, что пока пользователь не нажал кнопку C, обработчик не работает (не «прослушивает» нужное событие).

Вариант 2: записать это в скрипт для листа; туда же поместить описание функции checkResult(). Тогда обработчик включится сразу, в момент загрузки листа. Но здесь нас подстерегает неприятность: на момент выполнения скрипта на листе ещё нет никаких объектов, а значит, и нашей кнопки B. При загрузке листа скрипт выдаёт ошибку «Ссылка на несуществующий объект».

Но выход всё же есть. Запишем в скрипт листа следующий код:

addEventListener("load",init);
function init () {
B.addEventListener("click",checkResult);
}
function checkResult() {
…
}

Теперь в момент загрузки листа вызывается только метод листа, который устанавливает слушателя для события load, а уже после загрузки, когда все объекты на лиcте появятся и с листом произойдёт load, к кнопке B будет прикреплён обработчик события click. То же самое можно сделать несколько компактнее, если описать функцию-слушатель прямо при вызове addEventListener (в JavaScript допускаются такие неименованные функции):

addEventListener("load", function () {
B.addEventListener("click",checkResult);
});
function checkResult() {
…
}


В приведённом примере мы использовали в качестве обработчиков функции init() и checkResult() без параметров. Это можно делать, если в обработчике нас интересует лишь сам факт, что данное событие произошло, но не его параметры (например, какая именно кнопка мыши была нажата; где в этот момент находился курсор и т.д.). Если же эта информация важна для обработчика, то в него передаётся параметр E – ссылка на соответствующее событие. В зависимости от его типа можно узнать:

Например: пусть K – круг с центром в точке P. Тогда выполнение следующего кода позволяет при каждом щелчке по кругу увидеть расстояние до его центра:

K.addEventListener("mouseDown",distCenter);
function distCenter(e) {
dx = e.logicalX-getX(P);
dy = e.logicalY-getY(P);
alert(sqrt(dx*dx+dy*dy));
}


Пример с добавлением и удалением объекта на листе

События add и remove позволяют реагировать на добавление или удаление объекта. Соответствующие события поддерживают метод getSubject():

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

function processAddEvent(e){
alert("added "+e.getSubject());
}
function processRemoveEvent(e){
alert("removed "+e.getSubject());
}
var sheetRootFrame = workbook.getActiveSheet().getRootFrame();
sheetRootFrame.addEventListener("add",processAddEvent);
sheetRootFrame.addEventListener("remove",processRemoveEvent);


Если на листе есть встроенный фрейм и необходимо отслеживать добавление/удаление объектов в нём, то у него должен быть свой обработчик событий.

Пример с применением инструментов

События invoke, completeConstruction и cancelConstruction позволяют реагировать на включение инструмента, завершение построения или сброс инструмента. У каждого из событий есть свои особые методы.

Обработчик события invoke может использовать следующие свойства события:

Обработчик события completeConstruction может использовать следующие свойства события:

Обработчик события cancelConstruction может использовать следующее свойство события:

Например, добавим диспетчеру действий обработчики, выдающие диалоговые окна с указанием статуса инструмента:

actionDispatcher.addEventListener('invoke', function x(e){
alert(e.getEntry());
});
actionDispatcher.addEventListener('cancelConstruction', function x(e){
alert('Cancelled '+e.getCancelledCommand());
});
actionDispatcher.addEventListener('completeConstruction', function x(e){
alert('completed '+e.getCompletedCommand()+' '+e.getCompletedConstructions());
});