Перейти к содержимому

Введите название инструмента, задачу или имя метода.

Открыть BDE
На этой странице

Добавить инструмент HeadPaint

Добавить собственный инструмент рисования через подтверждённое расширение HeadPaint.

Добавим в HeadPaint однопиксельную кисть. Она получает координаты пикселя от редактора, рисует текущим цветом и сообщает, какая часть текстуры изменилась. Пример показывает само расширение инструмента без собственной системы слоёв и истории.

Скачать полный пример headpaint-tool.js. После установки откройте HeadPaint и выберите инструмент «Учебный пиксель» с иконкой карандаша.

Задача инструмента

Кисть красит один пиксель под указателем. На основном слое результат непрозрачный, на внешнем используется текущая альфа HeadPaint. В режиме замены внешний пиксель сначала очищается, затем получает новый цвет. В остальных режимах пример использует обычное наложение Canvas source-over.

Размер и форма штатной кисти, smart grid и специальные режимы смешивания не переносятся в собственный обработчик автоматически. У примера намеренно одно понятное действие; если нужны эти настройки, их алгоритм потребуется реализовать отдельно.

Проверить доступный API

Публичная точка расширения - window.editorAPI.headPaint.addTool(tool). Редактор принимает объект с уникальным id, подписью, иконкой и синхронным onPaint. Не используйте выдуманные registerBrush() или onPaint как метод самого API.

const paint = window.editorAPI?.headPaint;
if (typeof paint?.addTool !== 'function') {
  throw new Error('HeadPaint API недоступен.');
}

Метод добавляет инструмент в набор HeadPaint, но не включает сам режим рисования и не выбирает инструмент за пользователя. Публичного removeTool() сейчас нет. Повторная регистрация того же id заменяет его описание в списке; отдельный id создаёт отдельный инструмент. addTool() не возвращает handle для удаления.

Все поля и ограничения собраны в справочнике HeadPaint API.

Регистрация и обработчик

Сокращённый пример непрозрачного пикселя:

window.editorAPI.headPaint.addTool({
  id: 'my-plugin.pixel',
  name: 'Мой пиксель',
  icon: 'icon-pencil',
  onPaint({context, drawX, drawY, color}) {
    context.save();
    context.globalAlpha = 1;
    context.globalCompositeOperation = 'source-over';
    context.fillStyle = color;
    context.fillRect(drawX, drawY, 1, 1);
    context.restore();
    return [{drawX, drawY}];
  },
});

Используйте drawX и drawY для координат Canvas: редактор уже учёл вертикальное направление текстуры и выбранный слой. Не заменяйте их напрямую на x и y пересечения с поверхностью. Рисуйте только в пределах canvas.width и canvas.height.

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

onPaint вызывается синхронно. Не делайте его async и не загружайте изображения внутри мазка; подготовьте данные заранее. После регистрации инструмент выбирается обычной кнопкой HeadPaint. Необязательный onSelect получает внутренние editor и headPaint, но пример их не использует.

Полный файл дополнительно сохраняет состояние Canvas через save()/restore(), учитывает альфу внешнего слоя и сравнивает пиксель до и после, чтобы вернуть false при отсутствии изменений.

Цвет, альфа и палитра

Обработчик получает color в формате #RRGGBB и opacity в диапазоне 0-255. Публичный метод позволяет изменить текущий цвет и при необходимости альфу:

window.editorAPI.headPaint.setColor('#f90', 128);

Короткий HEX разворачивается, цвет записывается в верхнем регистре. Числовая альфа округляется и ограничивается диапазоном 0-255. Без второго аргумента текущая альфа сохраняется. Некорректный цвет или нечисловая альфа игнорируются.

setUpdateColorList(false) меняет флаг пополнения палитры там, где штатный инструмент его проверяет; true возвращает это поведение. Метод не очищает палитру и не добавляет в неё переданный цвет. Собственная ветка onPaint не вызывает штатное пополнение палитры автоматически. Пример оставляет флаг пользователя без изменений.

Пользовательские слои и подготовка текстуры описаны в статье рисование в HeadPaint.

Проверить слой, отмену и завершение

  1. Создайте отдельную тестовую голову. На основном слое проведите короткий мазок: пиксели должны получить выбранный цвет с полной непрозрачностью.
  2. Переключитесь на внешний слой и уменьшите альфу. Проверьте обычное наложение и замену пикселя; на краях не должно появляться рисование в соседнем слое.
  3. Выберите штатную кисть и вернитесь к учебному инструменту. Проверьте, что каждая кнопка выбирает своё действие.
  4. Повторно установите файл с тем же namespace и id, затем перезагрузите редактор. В наборе должна быть одна кнопка примера.
  5. Удалите плагин и перезагрузите редактор, чтобы убрать его регистрацию.

В текущем пути собственного инструмента есть уведомления bde:headPaint:paint и обновление текстуры, но нет той же отметки изменённого состояния истории, которая используется штатной кистью. Из наличия paint не следует наличие пары started/ended или поддержка Undo. Пример не исправляет это обращением к внутренней команде истории: такое обращение имело бы отдельные риски совместимости.

Контракт сверён с publicFunctions.js, gui/headPaint.js и commands/headPaint.js. Перед выпуском собственного инструмента пройдите проверку слоёв и истории в используемой версии редактора; регистрация инструмента сама по себе не подтверждает эти свойства.