EditorControl

главная | сервисные функции | Editor API
Функция EditorControl позволяет запрашивать различную информацию о встроенном редакторе Far Manager и управлять его состоянием. 
intptr_t WINAPI EditorControl(
  intptr_t EditorID,
  enum EDITOR_CONTROL_COMMANDS Command,
  intptr_t Param1,
  void *Param2
);

Параметры

EditorID
Идентификатор экземпляра редактора (текущий редактор: -1). Каждый экземпляр редактора имеет уникальный идентификатор, который не повторяется в текущей сессии Far Manager.

ВНИМАНИЕ! ВНИМАНИЕ!

Command
Тип команды. Может быть одним из следующих (перечисление EDITOR_CONTROL_COMMANDS):
КомандаОписание
ECTL_ADDCOLOR Задать цвет части строки. Эта команда может быть вызвана несколько раз для одной и той же строки для задания нескольких цветных областей.
Param1 не используется.
Param2 указывает на структуру EditorColor.
Если указанная строка отсутствует, то возвращается FALSE, иначе TRUE.
ECTL_ADDSESSIONBOOKMARK Добавить позицию навигации (это особый вид закладок, отличающийся от обычных тем, что действуют в пределах сеанса редактора) в стек, при этом, если добавление идет между элементами стека, то все закладки, с индексом больше текущего, будут удалены.
Param1 и Param2 должны быть NULL.
Функция возвращает TRUE в случае успешного выполнения.
ECTL_CLEARSESSIONBOOKMARKS Удалить все позиции навигации.
Param1 и Param2 должны быть NULL.
ECTL_DELETEBLOCK Удалить блок в редакторе.
Param1 и Param2 должны быть NULL.
Функция вернёт TRUE в случае удачного удаления блока и FALSE, если редактор заблокирован (пользователь нажал Ctrl+L) или нет выделенного блока.
ECTL_DELCOLOR Удалить цветовую область в строке. Эта команда может быть вызвана несколько раз для одной и той же строки.
Param1 не используется.
Param2 указывает на структуру EditorDeleteColor.
Если указанная строка отсутствует, то возвращается FALSE, иначе TRUE.
ECTL_DELETECHAR Удалить символ под курсором.
Param1 и Param2 должны быть NULL.
Функция вернёт TRUE в случае удачного удаления и FALSE, если редактор заблокирован (пользователь нажал Ctrl+L).
ECTL_DELETESESSIONBOOKMARK Удалить указанную позицию навигации.
Param1 не используется.
Param2 должен быть равен индексу удаляемой позиции навигации (0 и более) или -1 для удаления текущей позиции навигации. Количество позиций навигации можно получить, вызвав ECTL_GETSESSIONBOOKMARKS.
Функция возвращает TRUE в случае успешного выполнения.
ECTL_DELETESTRING Удалить текущую строку.
Param1 и Param2 должны быть NULL.
Функция вернёт TRUE в случае удачного удаления и FALSE, если редактор заблокирован (пользователь нажал Ctrl+L).
ECTL_EXPANDTABS Заменить все символы табуляции в строке пробелами.
Param1 не используется.
Param2 указывает на целочисленную переменную которая содержит номер обрабатываемой строки или -1 для обработки текущей строки.
Функция вернёт TRUE в случае удачной замены и FALSE, если редактор заблокирован (пользователь нажал Ctrl+L) или нет такой строки.
ECTL_GETBOOKMARKS Получить информацию о закладках для текущего редактируемого файла.
Param1 не используется.
Param2 указывает на структуру EditorBookmarks - выделенный плагином блок памяти, или равен NULL (если необходимо узнать размер буфера).
Команда возвращает 0, если файл ещё не открыт, в противном случае, возвращается необходимый размер буфера памяти.
ECTL_GETSESSIONBOOKMARKS Получить информацию о позициях навигации для текущего редактируемого файла.
Param1 не используется.
Param2 указывает на структуру EditorBookmarks - выделенный плагином блок памяти, или равен NULL (если необходимо узнать размер буфера).
Команда возвращает 0 в случае ошибки, в противном случае, возвращается необходимый размер буфера памяти.
ECTL_GETCOLOR Получить цвет части строки.
Param1 не используется.
Param2 указывает на структуру EditorColor.
Если указанная строка или часть строки отсутствует, то возвращается FALSE, иначе TRUE.
ECTL_GETFILENAME Получить имя открытого в редакторе файла.
Param1 - размер буфера в символах, который выделил плагин для данных.
Param2 указывает на буфер, выделенный плагином, куда будет помещено имя файла.
Функция возвращает требуемый размер буфера в символах, с учетом завершающего нуля.
Если Param2 = NULL или Param1 меньше требуемого размера, функция просто вернет необходимый размер буфера.
ECTL_GETINFO Получить информацию о редакторе.
Param1 не используется.
Param2 указывает на структуру EditorInfo.
Функция возвращает TRUE в случае успешного выполнения.
ECTL_GETSTRING Получить информацию о строке.
Param1 не используется.
Param2 указывает на структуру EditorGetString. 
// получить первую строку редактируемого файла
struct EditorGetString egs={sizeof(EditorGetString)};
egs.StringNumber=0;
Info.EditorControl(-1,ECTL_GETSTRING,0,&egs);
Если указанная строка отсутствует, то возвращается FALSE, иначе TRUE.
ECTL_GETTITLE Получить заголовок редактора.
Param1 - размер буфера в символах, который выделил плагин для данных.
Param2 указывает на буфер, выделенный плагином, куда будет помещен заголовок редактора.
Функция возвращает требуемый размер буфера в символах, с учетом завершающего нуля.
Если Param2 = NULL или Param1 меньше требуемого размера, функция просто вернет необходимый размер буфера.
ECTL_INSERTSTRING Вставить новую строку (разорвать строку) с текущей позиции курсора и переместить курсор либо на первую позицию новой строки, либо на позицию с учётом отступа.
Param1 не используется.
Если Param2 указывает на целочисленную переменную, равную 1, то при выполнении данной команды будет использоваться отступ. Для его отключения установите Param2 в NULL или установите целую переменную в 0. Поведение при отступе из плагина точно такое же, как и при нажатии Enter пользователем в редакторе, например, в новую строку пробелы (или табуляция) не вставляются, если после нового положения курсора строка не содержит никаких символов. 
// вставить пустую строку без отступа
Info.EditorControl(-1,ECTL_INSERTSTRING,0,0);
Функция вернёт TRUE в случае удачного выполнения операции и FALSE, если редактор заблокирован (пользователь нажал Ctrl+L).
ECTL_INSERTTEXT Вставить текст, начиная с позиции курсора.
Param1 не используется.
Param2 указывает на строку, оканчивающуюся нулём. Команда корректно обрабатывает символ(ы) перевода строки ('\n'). Команда ECTL_INSERTTEXT работает так, как будто текст вводится с клавиатуры. 
// вставить строку "Text" в текущую позицию курсора
Info.EditorControl(-1,ECTL_INSERTTEXT,0,(void*)L"Text");
Функция вернёт TRUE в случае удачного выполнения операции и FALSE, если редактор заблокирован (пользователь нажал Ctrl+L) или строка равна NULL.
ECTL_NEXTSESSIONBOOKMARK Перейти на следующую позицию навигации.
Param1 и Param2 должны быть NULL.
Команда возвращает TRUE в случае успешного выполнения.
ECTL_PREVSESSIONBOOKMARK Перейти на предыдущую позицию навигации.
Если после предыдущего вызова команды ECTL_ADDSESSIONBOOKMARK не выполнялось операций с позициями навигации, то перед переходом запоминается текущая позиция редактора в качестве новой позиции навигации. Param1 и Param2 должны быть NULL.
Команда возвращает TRUE в случае успешного выполнения.
ECTL_PROCESSINPUT Передаёт структуру INPUT_RECORD, указатель на которую передаётся в Param2, внутреннему редактору Far Manager для обработки.
Учтите, что если ваш плагин экспортирует функцию ProcessEditorInputW, то данные из Param2 сразу же будут переданы в ProcessEditorInputW. Param1 не используется.
Схема проста: 
case ECTL_PROCESSINPUT:
if (ProcessEditorInput(Param))
  return(TRUE);
  ...
Поэтому используя EditorControl(ECTL_PROCESSINPUT) в функции ProcessEditorInputW следите за тем, чтобы не впасть в бесконечную рекурсию.
ECTL_QUIT Закрыть редактор. Любая не сохраненная информация будет потеряна.
Param1 и Param2 должны быть NULL.
Эта команда всегда возвращает TRUE.
ECTL_READINPUT Заполняет структуру INPUT_RECORD, читая данные со стандартного устройства ввода.
Param1 не используется.
Param2 указывает на структуру INPUT_RECORD (она определена в Windows API и используется в функции ReadConsoleInput).
ECTL_REALTOTAB Конвертировать реальную строковую позицию курсора в экранную позицию. Если строка не содержит символов табуляции, входная и получаемая позиция будут равными.
Param1 не используется.
Param2 указывает на структуру EditorConvertPos.
Если указанная строка отсутствует, то возвращается FALSE, иначе TRUE.
ECTL_REDRAW Перерисовать окно редактора.
Param1 и Param2 должны быть NULL.
Эта команда всегда возвращает TRUE.
ECTL_SAVEFILE Позволяет плагину сохранить редактируемый файл.
Param1 не используется.
Param2 указывает на структуру EditorSaveFile. Если Param2 равен NULL, то будут использованы имя редактируемого файла и текущий формат сохранения (DOS-формат - перевод строки заменяется на "\r\n", Unix-формат - "\n"). При успешном сохранении файла функция вернёт TRUE.
ECTL_SELECT Выделить или снять выделение с блока.
Param1 не используется.
Param2 указывает на структуру EditorSelect.
При успешной операции функция вернёт TRUE.
ECTL_SETKEYBAR Функция, позволяющая управлять поведением строки функциональных клавиш в редакторе.
Param1 не используется.
Param2 = NULL - восстановить предыдущее значение
Param2 = -1 - обновить полосу (перерисовать)
Param2 равен указателю на структуру FarSetKeyBarTitles, новое значение.
Вызывать данную команду в событии EE_READ не имеет смысла, т.к. строки функциональных клавиш, как объекта, в момент загрузки файла в редактор ещё не существует.
Функция возвращает TRUE в случае успешного выполнения или FALSE (когда строка, как объект, не создана).
ECTL_SETPARAM Изменение настроек текущего редактора.
Param1 не используется.
Param2 указывает на структуру EditorSetParameter.
Функция возвращает TRUE в случае успешного изменения параметров.
ECTL_SETPOSITION Установить позицию курсора.
Param1 не используется.
Param2 указывает на структуру EditorSetPosition.
При успешной операции функция вернёт TRUE.
ECTL_SETSTRING Поместить текст в строку.
Param1 не используется.
Param2 указывает на структуру EditorSetString.
При успешной операции функция вернёт TRUE.
ECTL_SETTITLE DrawLine\DrawLine.cpp: Применена функция SetTitle()Установить заголовок редактора (верхняя статусная панель).
Param1 не используется.
Param2 указывает на строку, оканчивающуюся нулём, которая содержит текст заголовка.
Для восстановления статусной строки укажите параметр Param2 = NULL или пустой строке.
Заголовок не будет выведен, если статусная строка погашена.
При показе заголовок будет усечён до размера, не затрагивающего служебную информацию (кодировка, позиция, etc.)
// DrawLine\DrawLine.cpp: функция SetTitle
Info.EditorControl(-1,ECTL_SETTITLE,0,GetMsg(IDTitle));
Эта команда всегда возвращает TRUE.
ECTL_TABTOREAL Конвертировать экранную позицию курсора в реальную строковую позицию. Если строка не содержит символов табуляции, входная и получаемая позиция будут равными.
Param1 не используется.
Param2 указывает на структуру EditorConvertPos.
Если указанная строка отсутствует, то возвращается FALSE, иначе TRUE.
ECTL_UNDOREDO Функция, позволяющая управлять поведением операции Отмена-Возврат действия, т.н. Undo-Redo.
Param1 не используется.
Param2 указывает на структуру EditorUndoRedo.
Команда возвращает TRUE в случае успешного выполнения операции.
ECTL_SUBSCRIBECHANGEEVENT Подписаться на получение EE_CHANGE событий для заданной сессии редактора.
Param1 не используется.
Param2 указывает на структуру EditorSubscribeChangeEvent.
Команда возвращает TRUE в случае успешного выполнения операции.
ECTL_UNSUBSCRIBECHANGEEVENT Отписаться от получения EE_CHANGE событий для заданной сессии редактора.
Param1 не используется.
Param2 указывает на структуру EditorSubscribeChangeEvent.
Команда возвращает TRUE в случае успешного выполнения операции.
Param1
Указывает на параметры1 команды. Смотрите описание Command.
Param2
Указывает на параметры2 команды. Смотрите описание Command.

Возвращаемое значение

Смотрите описание конкретной команды.

Замечания

Far Manager обновляет содержимое окна редактора при активных действиях пользователя. Вызовите ECTL_REDRAW, чтобы принудительно обновить окно после любых активных изменений содержимого редактора.
Смотрите также:
AdvControl, PanelControl