Оператор ON MOUSE

Что даёт обработчик

Назначайте обработчики, когда реакцию на ввод удобно выделить в отдельные процедуры. Для вызовов обработчиков нужна графическая поверхность SCREEN 1..10 или CANVAS, но саму регистрацию можно выполнить заранее.

В окне SCREEN координаты события — пиксели клиентской области без преобразования VIEW и WINDOW. На холсте параметры x и y содержат мировые координаты, рассчитанные с учётом VIEWPORT и CAMERA. Порядок вызова процедур и совместное использование очереди описаны ниже; правила фокуса окна приведены в обзоре ввода.

Синтаксис

ON MOUSE(<номер кнопки>), <имя обработчика>

ON MOUSE(<номер кнопки>), ON

ON MOUSE(<номер кнопки>), STOP

ON MOUSE(<номер кнопки>), OFF

ON MOUSE(<номер кнопки>, "UP"), <имя обработчика>

ON MOUSE(<номер кнопки>, "UP"), ON

ON MOUSE(<номер кнопки>, "UP"), STOP

ON MOUSE(<номер кнопки>, "UP"), OFF

ON MOUSE("MOVE"), <имя обработчика>

ON MOUSE("MOVE"), ON

ON MOUSE("MOVE"), STOP

ON MOUSE("MOVE"), OFF

ON MOUSE("WHEEL"), <имя обработчика>

ON MOUSE("WHEEL"), ON

ON MOUSE("WHEEL"), STOP

ON MOUSE("WHEEL"), OFF

Цель события

Вместо buttonNumber указывается выражение с номером кнопки, вместо HandlerName — имя процедуры. Строки "UP", "MOVE" и "WHEEL" выбирают вид события.

Имена событий нечувствительны к регистру; пробелы и дефисы в литерале не меняют выбор события. Имена событий должны быть строковыми литералами: имя, вычисленное из строковой переменной, не заменяет литерал и сообщает MB2036. Для MOVE и WHEEL номер кнопки в цели не передаётся.

Аргумент номера кнопки приводится к INTEGER; для нажатия и отпускания поддерживаются номера 1..3. Номер вне этого диапазона не регистрирует обработчик и не вызывает MB3007.

Процедура-обработчик

Процедура может не принимать аргументов либо принимать три параметра события по значению. Параметры BYREF не допускаются:

SUB HandleMouse()
END SUB

SUB HandleMouse(value AS INTEGER, x AS LONG, y AS LONG)
END SUB

Параметр value содержит номер кнопки при нажатии и отпускании, 0 при перемещении или величину прокрутки колеса. Положительная величина означает прокрутку вверх, отрицательная — вниз. Параметры x и y содержат положение указателя на активной поверхности в момент обработки.

Режимы ON, STOP и OFF

Режимы управляют уже назначенным обработчиком и доступны для каждого вида события: кнопки, "UP", "MOVE" и "WHEEL".

• ON MOUSE(buttonNumber), HandlerName регистрирует и включает обработчик.
• ON MOUSE(...), STOP временно ставит существующий обработчик на паузу для выбранной цели события.
• ON MOUSE(...), ON возобновляет ранее зарегистрированный обработчик для той же формы ON MOUSE.
• ON MOUSE(...), OFF полностью снимает регистрацию для выбранной цели события.

Регистрация, пауза, возобновление и удаление обработчика не открывают графическое окно и допустимы до SCREEN или CANVAS. Пока графическая поверхность не активна, мышиные обработчики не вызываются.

Порядок обработки событий мыши

• Оператор ON MOUSE проверяет очередь мышиных событий на границах операторов, как ON KEY; в циклах обработчики также получают шанс выполниться на каждой итерации, даже если тело цикла пустое.
• Если обработчик включён, совпавшее нажатие считается обработанным и не попадёт в последующий MOUSEPRESS.
• Если обработчик на паузе или не зарегистрирован, нажатие остаётся доступным для MOUSEPRESS.
• Отпускание, перемещение и колесо не читаются функцией MOUSEPRESS, но доступны обработчикам ON MOUSE(..., "UP"), ON MOUSE("MOVE") и ON MOUSE("WHEEL").
• При активном SCREEN координаты x и y совпадают с теми же экранными чтениями, которые в этот момент дают MOUSEX и MOUSEY.
• При активном CANVAS координаты x и y совпадают с теми же мировыми чтениями, которые в этот момент дают MOUSEX и MOUSEY.
• Операторы VIEW, WINDOW и PMAP не изменяют координаты события в SCREEN. В CANVAS пересчёт идёт по договору VIEWPORT и CAMERA.
• В панели Output среды разработки уход указателя за пределы поверхности сбрасывает состояние мыши: координаты становятся -1/-1, очередь событий очищается, удержание кнопок снимается.
• В нативном графическом окне SCREEN уход указателя за видимую область сам по себе не создаёт отдельного сброса координат: без нового события ввода сохраняется последняя известная точка.
• Потеря фокуса окна или захвата указателя публикует отпускание удерживаемых кнопок, поэтому обработчик ON MOUSE(..., "UP") получает событие, а MOUSEBUTTON сразу возвращает FALSE. Позднее системное отпускание не создаёт второе событие.
• Наведение указателя и прокрутка колеса не отбирают клавиатурный фокус у окна IDE. Фокус передаётся при открытии окна и явном щелчке.
• Прокрутка в чёрном поле вне изображения не создаёт события колеса.
• В текущем срезе нет обработчиков двойного клика и захвата указателя.

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

Единица колеса

Параметр delta обработчика ON MOUSE("WHEEL") измеряется в единицах колеса Windows: одна обычная ступень равна 120, отрицательное значение означает прокрутку вниз. Это правило одинаково для SCREEN и CANVAS. В CANVAS браузерное событие колеса переводится в ту же единицу; плавный трекпад накапливает дробный остаток до полной ступени. Поэтому один и тот же жест даёт согласованное значение в обеих поверхностях.

Очистка и смена поверхности

Очистка состояния мыши удаляет не только очередь ввода, но и события, уже отложенные обработчиком ON MOUSE. После очистки MOUSEPRESS не возвращает прежние нажатия. Переход между SCREEN и CANVAS, закрытие поверхности и новый запуск программы также начинают очередь мыши заново.

Продвижение очереди событий

Обработка ON MOUSE ограничена числом событий между инструкциями программы. События без включённого обработчика сохраняются для последующего чтения, но не занимают весь опрос: новые события от окна продолжают поступать даже после 64 и более отложенных событий. Сохранённое нажатие можно получить через MOUSEPRESS.

Диагностика

• MB2035: обработчик оператора ON MOUSE не является подходящей процедурой SUB. Для обработчика события допустимы только формы без параметров или с параметрами INTEGER, LONG, LONG.
• MB2036: в операторе ON MOUSE указано недопустимое имя события мыши.

Пример обработчика мыши

ON MOUSE(1), HandleMouse
ON MOUSE(1, "UP"), HandleMouse
ON MOUSE("MOVE"), HandleMouse
ON MOUSE("WHEEL"), HandleMouse
DIM marker AS INTEGER = 1

SUB HandleMouse(value AS INTEGER, x AS LONG, y AS LONG)
    PRINT "MOUSE"
    PRINT value
    PRINT x
    PRINT y
END SUB

Одна и та же процедура назначена на четыре цели, поэтому её параметры получают разный смысл: для нажатия и отпускания в value приходит номер кнопки, для перемещения — 0, для колеса — величина прокрутки.

Запускаемые примеры

• ON MOUSE: обработчик левой кнопки мыши в SCREEN
• ON MOUSE: мировые координаты в CANVAS
• ON MOUSE: отпускание и перемещение
• ON MOUSE: колесо мыши
• ON MOUSE: единицы колеса в CANVAS
• ON MOUSE: отпускание при потере фокуса

См. также