# EditorControl

Функция `EditorControl` позволяет запрашивать различную информацию о встроенном редакторе Far Manager и управлять его состоянием.

    intptr_t WINAPI EditorControl(
      intptr_t EditorID,
      enum EDITOR_CONTROL_COMMANDS Command,
      intptr_t Param1,
      void *Param2
    );

### Параметры

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

ВНИМАНИЕ!

- Обращение к текущему редактору безопасно только в контексте ProcessEditorInputW. Во всех остальных случаях текущим внезапно может оказаться совсем не тот редактор, который вы ожидали увидеть. Используйте EditorInfo.EditorID или ProcessEditorEventInfo.EditorID (в зависимости от контекста).

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 | Установить заголовок редактора (верхняя статусная панель). `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