SciTE Director Interface

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

Назначение

При разработке программ работают не с одним файлом. Разработчик будет работать с группой связанных файлов в рамках одного проекта. Функциональность менеджера проектов должна быть добавлена в SciTE, так другие редакторы имеют её, но это может налагать особое видение того как управлять проектами включая формат файлов проекта. Однако, SciTE имеет интерфейс который можно использовать для менеджеров проектов или подобных приложений для контроля SciTE. Любые приложения которые контролируют SciTE называются "Директор".

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

Сейчас доступно только одно приложение-директор Filerx.

Этот интерфейс реализован поверх интерфейса расширений SciTE, в файле scite\win32\DirectorExtension.cxx.

Прямое соединение, широковещательная рассылка и точное указание адресов возврата

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

Низкоуровневый интерфейс под Windows

Сообщение Windows WM_COPYDATA используется для передачи данных между SciTE и Директором. Сообщения посылаются между окнами созданными двумя приложениями. Окно SciTE принимает только это сообщение. Поля lpData и cbData в структуре COPYDATASTRUCT используются для передачи строки между двумя процессами, поле cbData содержит длину строки которая указана в lpData. Строка не должна заканчиваться '\0'. Поле dwData должно быть 0.

Перед тем как сообщение должно быть послано, необходимо определить дескриптор окна куда посылается сообщение. Обычно он передается когда приложение запускается как аргумент в командной строке. Каждое приложение может запустить другое. SciTE делает свой дескриптор окна доступным в свойстве WindowID и принимает свойство director.hwnd как дескриптор окна в которое посылает сообщения.

Например, для запуска Filerx в меню Tools:

command.name.0.*=Project Editor
command.0.*="C:\os\scite\bin\filerx.exe" "$(FileDir)" "$(WindowID)"
command.subsystem.0.*=2

И наоборот, Filerx может запустить SciTE с командной строки, где указан его десктриптор окна, также как и файл который нужно редактировать:

SciTE -director.hwnd=937846 c:\os\scite\src\SciTEBase.cxx

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

Для того чтобы найти активный интерфейс директора необходимо послать широковещательное сообщение "SciTEDirectorInterface" и смотреть какое окно ответит тем же значением как и это сообщение. Пример кода шировещательной рассылки:

unsigned int SDI = ::RegisterWindowMessage("SciTEDirectorInterface");
HWND w = ::GetWindow(::GetDesktopWindow(),GW_CHILD);
while (w) {
    DWORD res = 0;
    // Неоходимо ограничить время для избежания зависших приложений
    ::SendMessageTimeout(w, SDI, 0, 0,
        SMTO_NORMAL, 1000, &res);
    if (res == static_cast<DWORD>(SDI)) {
        // Replied with same SDI code so should
        // understand SDI's version of WM_COPYDATA
        ::SendMessage(w,WM_COPYDATA,
            (UINT)m_hWnd,(long)&cds);
    }
    w = ::GetWindow(w, GW_HWNDNEXT);
}

Для извещения что окно верхнего уровня поддерживает интерфейс Директора:

LRESULT PASCAL DirectorExtension_WndProc(HWND hWnd,
    UINT iMessage, WPARAM wParam, LPARAM lParam) {
    unsigned int SDI = ::RegisterWindowMessage("SciTEDirectorInterface");
    if (iMessage == SDI) {
        return SDI;
    }
    return ::DefWindowProc(hWnd, iMessage, wParam,lParam);
}

Низкоуровневый интерфейс под GTK+

Еще не внедрен. Предлагаемое решение использует входной буфер fifo для каждого приложения поддерживающего интерфейс SciTe Director, расположенный в /tmp с именем по шаблону "/tmp/SciTE<PID>.director". Это позволяет перечислять все активные интерфейсы директора и также открывать необходимый интерфейс когда буфер fifo общается каким-нибудь другим способом, таким как аргументы командной строки или командами identity:.

Высокоуровневый интерфейс

Сообщения используют эскейп-символы в стиле C для представления управляющих символов. Передаются только видимые символы, команды разделяются '\n'.

Строка передаваемая через низкоуровневый интерфейс содержит: опционально адрес возврата окруженный символами ':', команду, символ ':' и опционально аргумент. Часто в качестве аргумента передается путь к файлу. Символ ':' должен быть даже если аргументов нет. Например, SciTE понимает сообщение

open:c:\\os\\scintilla\\include\\Scintilla.iface

как команду открыть файл "c:\os\scintilla\include\Scintilla.iface" также как пользователь сделал бы эту операцию.

Если первый символ команды ':' то строка до следующего ':' есть адрес возврата, так SciTE ответит на команду:

:73658:askfilename:

посылкой имени редактируемого файла окну с дескриптором 73658.

Команды понимаемые SciTE:

askfilename:	Вернуть имя редактируемого файла.
askproperty:<key>	Вернуть значение параметра.
close:	Закрыть текущий файл.
closing:	Директор закрывается - SciTE закрывается тоже, если был запущен директором.
currentmacro:<string>	Присвоить текущему макросу имя.
cwd:	Изменить рабочую директорию.
enumproperties:dyn\|local\|user\|base\|embed	Перечислить все параметры в заданном окружении.
exportashtml:<path>	Записать документ в формат HTML по указанному пути.
exportasrtf:<path>	Записать документ в формат RTF по указанному пути.
exportaspdf:<path>	Записать документ в формат PDF по указанному пути.
exportaslatex:<path>	Записать документ в формат LaTeX по указанному пути..
exportasxml:<path>	Записать документ в формат XML по указанному пути.
extender:<command>	Выполнить заданную команду интерфейса расширений.
find:<string>	Найти строку, показать и выделить ее.
goto:<lineNumber>[,<columnNumber>]	Передвинуть курсор на заданную строку и сделать ее видимой. Если задана позиция курсора, то выделяется слово в этой позиции или передвигает каретку если слова нет.
identity:<hwndDirector>	Задать дескриптор окна директора куда SciTE будет посылать сообщения. Значение в десятичном формате.
insert:<value>	В панели редактора заменить выделенный текст.
loadsession:<path>	Load a session as given by the indicated file.
macrocommand:<command>	Выполнить макрокоманду. Смотрите исходные коды SciTE о синтаксисе команд.
macroenable:<enable>	Если "enable", отобразить меню для записи и выполнения макросов.
macrolist:<list>	Отобразить список макросов для выбора пользователем.
menucommand:<cmd>	Выполнить команду меню по номеру ID.
open:<path>	Открыть файл по заданному пути.
output:<value>	Отобразить значение в панели вывода, перезаписывает выделенный текст.
property:<key>=<value>	Присвоить значение параметру.
quit:	Закрыть SciTE.
reloadproperties:	Перезагрузить параметры из файлов.
replaceall:<search>\000<replace>	Заменить все найденные вхождения искомой строки на другую строку.
saveas:<path>	Сохранить документ по указанному пути.
savesession:<path>	Сохранить текущую сессию по указанному пути.

Команды посылаемые SciTE:

closing:	SciTE закрывается.
dyn\|local\|user\|base\|embed:<key>=<value>	Присвоено значение параметру в заданном наборе.
filename:<path>	Файл по данному пути редактируется в данный момент. Это ответ на действие askfilename: command.
identity:<hwndSciTEReceiving>	SciTE показывает директору дескриптор окна в которе следует посылать сообщения. Значение в десятичном формате.
macro:getlist	Возвращает список доступных макросов в ответ на команду macrolist.
macro:record:<details>	Начата запись макроса. Смотрите исходные коды SciTE о синтаксисе аргумента details.
macro:run:<macroName>	Запущен макрос.
macro:stoprecord	Остановлена запись макроса.
opened:<path>	SciTE открыл файл по данному пути.
switched:<path>	SciTE переключил буфер на файл по данному пути.
saved:<path>	SciTE сохранил файл по данному пути.

В будущем, будет доступно больше команд. Приложения должны игнорировать любые команды которые не понимают.

Русский перевод: s_mart