Scintilla icon SciTE Extension Interface
Документация   FAQ   Регулярные выражения   SciTE Extension   LUA   SciTE Director   Команды SciTE и Scintilla   Сборка Ru-Board   Ядро SciTE-Ru   Shell   SciTE Helper   История

Назначение

Любой заинтересованный человек может создать расширенную версию редактора SciTE, обладающую новыми дополнительными возможностями. Так, например, для редактора, разработанного для специфического окружения, можно добавить возможность выполнения скриптов в среде SciTE или позволить другому процессу управлять SciTE посредством механима IPC.

Приведем два примера расширений. SciTE Director Interface позволяет управлять редактором SciTE из внешнего приложения, такого как менеджер проектов. SciTE Lua Scripting Extension является внедрением скриптового языка Lua в SciTE, выполненное посредством интерфейса расширения.

Интерфейс расширения.

bool Initialise(ExtensionAPI *host_);
bool Finalise();
bool Clear();
bool Load(const char *filename);
bool InitBuffer(int index);
bool ActivateBuffer(int index);
bool RemoveBuffer(int index);
bool OnOpen(const char *path);
bool OnSwitchFile(const char *path);
bool OnBeforeSave(const char *path);
bool OnSave(const char *path);
bool OnChar(char ch);
bool OnExecute(const char *s);
bool OnSavePointReached();
bool OnSavePointLeft();
bool OnStyle(unsigned int, int, int, Accessor *);
bool OnDoubleClick();
bool OnUpdateUI();
bool OnMarginClick();
bool OnMacro(const char *, const char *);
bool SendProperty(const char *);
bool OnKey(int keyval, int modifiers);
bool OnDwellStart(int pos, const char *word);
bool OnClose(const char *filename);

Расширение должно реализовать интерфейс Расширения, определенный в scite/src/Extender.h. Только первые 4 метода должны быть реализованы, несмотря на то, что их реализация может быть настолько простой, как просто возвращение false. Остальные методы имеют пустую реализацию по умолчанию. Методы, добавляемые к этому интерфейсу впоследствие, должны иметь такую реализацию по умолчанию, которая позволит компилироваться существующим расширениям.

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

Расширение может использовать методы Initialise и Finalise для выделения и освобождения выделенных ресурсов. Указатель ExtensionAPI может быть сохранен в методе Initialise чтобы обеспечить расширению связь со SciTE.

Методы Clear и Load используются для поддержки расширений, которым необходимо загружать такие ресурсы, как файлы скриптов при открытии файлов. Когда файл открывается в SciTE, то сначала расширение запрашивает очистку любых данных, связанных с предыдущим файлом, через Clear. Затем SciTE приводит свойство "extension" в соответстие с именем файла, так для x.cpp, ищется extension.*.cpp. Файл с таким именем ищется в стандартном месте для размещения файлов свойств (property file), и, если находится, то вызывается Load с путем в качестве аргумента.

Методы InitBuffer, ActivateBuffer и RemoveBuffer обеспечивают необходимые ловушки, так чтобы расширение имело механизм связывания данных с конкретным буфером, образом сходным с тем, которым сам SciTE запоминает каждого буфера. InitBuffer вызывается в момент открытия нового документа в данном буфере. Буфер может быть вновь выделенным или использованным повторно, если достигнуто максимальное количество буферов. Как только буфер инициализирован, он становится активным. Соответственно, ActivateBuffer вызывается всякий раз когда пользователь переключается на другой загруженный буфер. RemoveBuffer вызывается, когда существующий буфер закрывается. Соответственно, индексы буферов, которые следуют за удаляемым буфером, сдвигаются на 1. После RemoveBuffer, расширение получит InitBuffer или ActivateBuffer, чтобы установить новый активный буфер.

OnExecute вызывается только когда выполняется команда расширения. Это указывается в свойствах как subsystem 3.

OnBeforeSave вызывается перед сохранением файла и расширение может реализоавть сохранение файла само и вернет true, чтобы предотвратить выполнение сохранения файла по умолчанию.

Остальные методы вызываются во время событий, происходящих в SciTE, позволяя расширению отвечать на эти события.

Интерфейс ExtensionAPI

enum Pane { paneEditor=1, paneOutput=2, paneFindOutput=3 };
sptr_t Send(Pane p, unsigned int msg, uptr_t wParam=0, sptr_t lParam=0);
char *Range(Pane p, int start, int end);
void Remove(Pane p, int start, int end);
void Insert(Pane p, int pos, const char *s);
void Trace(const char *s);
char *Property(const char *key);
void SetProperty(const char *key, const char *val);
uptr_t GetInstance();
void ShutDown();
void Perform(const char *actions);
void DoMenuCommand(int cmdID);
void UpdateStatusBar(bool bUpdateSlowData);

Расширение может выполнить обратный вызов в SciTE, используя этот интерфейс, который является упрощенным способом вызова функциональности SciTE.

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

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

Range возвращает текст панели. Он должен быть удален посредством delete[]. Remove и Insert используются для удаления и вставки текста в панель.

Trace отображает строку в конце панели вывода.

Свойства SciTE можно читать и записывать через Property и SetProperty. Результат, возвращенный методом Property должен быть удален через delete[].

GetInstance является спецификой Windows и возвращает HINSTANCE приложения, который необходим для получения доступа к услугам платформы.

ShutDown является эквивалентом выбора пользователем пункта меню Quit. Если есть несохраненные файлы, пользователю будет выведен запрос на их сохранение, которое может быть отменено из этого диалога. Таким образом, при определенных обстоятельствах, приложение будет продолжать выполняться после вызова ShutDown.

Perform принимает строку, содержащую действие, символ ':' и аргумент. В настоящее время единственным известным действием является открыть, в качестве аргумента передается путь. Это используется в Director extension для передачи команд от других приложений. В будущем возможна передача других действий через этот метод.

Подключение расширения

Расширение добавляется явно кодом при старте функции. Под Windows DirectorExtension подключается кодом, аналогичным следующему упрощенному примеру:

DirectorExtension director;
Extension *extender = &director;
//...
SciTEWin MainWind(extender);

Было бы лучше сделать механизм неявного подключения сходным со способом, которым лексеры подключаются к Scintilla, определяя, какое расширение используется простым внедрением объектных файлов в SciTE. Также было бы хорошо разрешить подключение расширений во время выполнения расширений, помещенных в DLL или в разделяемые объектные библиотеки.

Уплотнение

SciTE допускает использование нескольких расширений одновременно. Расширение уплотнитель (multiplexer) поддерживает список расширений и вызывает каждое по очереди для каждого метода. Как только расширение возвращает true, указывая, что обработку можно прервать, уплотнитель возвращает управление без прохода по остальным элементам списка. Тем не менее, для некоторых методов, таких как Initialise и Finalise, уплотнитель проходит по оставшимся расширениям независимо от значения, возвращенного предыдущим расширением.

Потоко-безопасность

В общем случае, SciTE является однопоточным приложением. Тем не менее, под Windows, команды вызывают OnExecute из отдельного рабочего потока. Класс SingleThreadExtension может быть использован для "упаковки" расширения так, чтобы вызовы OnExecute направлялись в основной поток. Конечно, потоко-безопасность вашего расширения не обязательна, или оно не реализует OnExecute, или оно является cпецифичным для GTK.

  • Русский перевод: Boris A. Brandin