Control

Функция Control позволяет запрашивать различную информацию и выполнять управляющие действия над панелями и командной строкой.
int WINAPI Control(
  HANDLE hPlugin,
  int Command,
  void *Param
);

Параметры

hPlugin
Текущий описатель плагина. При запросе информации относительно активной панели установите этот параметр равным INVALID_HANDLE_VALUE. Это позволяет использовать эту функцию в командах плагина без создания новой панели. Так же INVALID_HANDLE_VALUE можно использовать для неплагиновой панели.
Command
Тип команды. Может быть следующим FILE_CONTROL_COMMANDS):
КомандаОписание
Панель
FCTL_CHECKPANELSEXIST Проверить доступность панелей.
Param = 0 (не используется).
Функция возвращает FALSE, если FAR запущен с ключами /e или /v (в качестве внешнего редактора или программы просмотра). В этом режиме панели не создаются.

Замечание для FCTL_CHECKPANELSEXIST Внимание!

  • В режиме, когда FAR запущен с ключами /e или /v, функция обрабатывает только одну эту команду - FCTL_CHECKPANELSEXIST.
FCTL_CLOSEPLUGIN Закрыть текущий плагин.
Param указывает на имя каталога, который будет показан в панели после закрытия.
FCTL_GETPANELINFO
FCTL_GETANOTHERPANELINFO
Получить информацию о активной/пассивной панели плагина.
Param указывает на структуру PanelInfo, которая получит информацию о панели.
PanelInfo.SelectedItemsNumber равно 1, если не выделено никаких элементов. В этом случае PanelInfo.SelectedItems содержит данные для элемента под курсором. Если вы хотите узнать, действительно ли выделен этот файл, то проверьте у него состояние флага PPIF_SELECTED.

В процессе исполнения запроса

Info.Control(INVALID_HANDLE_VALUE,
             FCTL_GETPANELINFO,
             &PInfo);
FAR вызывает экспортируемую функцию GetOpenPluginInfo того плагина, которому принадлежит панель. FAR содержит защиту от бесконечной рекурсии: в случае, когда плагин из обработчика GetOpenPluginInfo() тоже вызывает Info.Control(...,FCTL_GETPANELINFO), повторного вложенного вызова GetOpenPluginInfo() не произойдёт.

В некоторых случаях (пример: поиск в архивах по Alt-F7) физически панель плагина не создается, поэтому необходимо обязательно проверять код возврата у Control, чтобы не упасть в самый не подходящий момент, выполнив работу для панели, которой нет.

Замечание для FCTL_GET[ANOTHER]PANELINFO Внимание!

  • Поля PanelItems и SelectedItems структуры PanelInfo после каждого вызова FCTL_GETPANELINFO или FCTL_GETANOTHERPANELINFO будут иметь разные адреса.
FCTL_GETPANELSHORTINFO
FCTL_GETANOTHERPANELSHORTINFO
Аналогична FCTL_GETPANELINFO/FCTL_GETANOTHERPANELINFO, но поля PanelItems и SelectedItems структуры PanelInfo не заполнены и равны NULL. Эта команда предназначена для получения общей информации о активной/пассивной панели без конкретных сведений об элементах панели.
FCTL_REDRAWPANEL
FCTL_REDRAWANOTHERPANEL
Перерисовать активную/пассивную панель плагина.
Param - указатель на структуру PanelRedrawInfo, которой можно задать новые позиции курсора и верхнего элемента панели. Если Param равен NULL, то позиции курсора и верхнего элемента панели при прорисовке не изменяются.
Если hPlugin равен INVALID_HANDLE_VALUE, то перерисуется активная панель независимо от того, какую команду использовал плагин.
Панель прорисуется только в случае, если в данный момент панелей видны.
FCTL_SETNUMERICSORT
FCTL_SETANOTHERNUMERICSORT
Задает числовой порядок сортировки для активной/пассивной панели.
Param - указатель на целое число, задающий числовую сортировку: 0 (отключить числовую сортировку) или 1 (включить числовую сортировку).
Значение Param равное NULL эквивалентно отключению числовой сортировки.
FCTL_SETPANELDIR
FCTL_SETANOTHERPANELDIR
Установить текущий каталог в активной/пассивной панели плагина.
Param указывает на имя каталога. Если плагин поддерживает свою собственную панель, он будет закрыт после выполнения этой команды.

После выполнения этой функции пропадет выделение с элементов каталога и его будет невозможно восстановить (комбинация Ctrl-M) по желанию пользователя, даже если новый каталог равен старому.

FCTL_SETSELECTION
FCTL_SETANOTHERSELECTION
Установить выделение в активной/пассивной панели.
Param указывает на структуру PanelInfo, заполненную предыдущими вызовами FCTL_GETPANELINFO или FCTL_GETANOTHERPANELINFO . Нельзя использовать другие функции Control между FCTL_GETPANELINFO и FCTL_SETSELECTION.

Для изменения выделения установите или очистите флаг PPIF_SELECTED у элементов массива, указатель на которое содержится в поле PanelItems структуры PanelInfo. Обратите внимание, что FCTL_GETPANELINFO и FCTL_GETANOTHERPANELINFO устанавливают значение PPIF_SELECTED для элементов массива, соответствующее состоянию панели.

Нужно вызвать FCTL_REDRAWPANEL для показа изменений.

FCTL_SETSORTMODE
FCTL_SETANOTHERSORTMODE
Установить режим сортировки для активной/пассивной панели. Param - указатель на целое число, содержащее режим сортировки (см. "Режимы сортировки").
FCTL_SETSORTORDER
FCTL_SETANOTHERSORTORDER
Задает порядок сортировки для активной/пассивной панели.
Param - указатель на целое число, содержащее порядок сортировки: 0 или 1 (обратная сортировка).
Значение Param равное NULL эквивалентно установки прямого порядка сортировки (0).
FCTL_SETVIEWMODE
FCTL_SETANOTHERVIEWMODE
Установить режим просмотра активной/пассивной панели.
Param указывает на целое значение, которое содержит номер нового режима, от 0 до 9.
Значение Param равное NULL эквивалентно установки режима 0.
FCTL_UPDATEPANEL
FCTL_UPDATEANOTHERPANEL
Обновить содержимое активной/пассивной панели плагина.
Если Param равен NULL, текущее выделение файлов будет снято, иначе выделение не изменится.
Командная строка
FCTL_GETCMDLINE Получить содержимое командной строки.
Param указывает на буфер, который получит данные (должен быть не меньше 1 Kb).
FCTL_GETCMDLINEPOS Получить позицию курсора в командной строке.
Param содержит указатель на переменную типа int, в которую будет помещена позиция курсора.
FCTL_GETCMDLINESELECTEDTEXT Получить выделенный текст из командной строки.
Param указывает на буфер, который получит данные (должен быть не меньше 1 Kb).
FCTL_GETCMDLINESELECTION Получить параметры выделенного текста командной строки.
Param указывает на структуру CmdLineSelect.
FCTL_INSERTCMDLINE Вставить текст в командную строку, начиная с текущей позиции курсора.
Param указывает на строку, оканчивающуюся нулем, которая будет вставлена в командную строку.
FCTL_SETCMDLINE Установить содержимое командной строки.
Param указывает на строку, оканчивающуюся нулем, которая будет помещена в командную строку.
FCTL_SETCMDLINEPOS Установить позицию курсора в командной строке.
Param содержит указатель на переменную типа int - позиция курсора.
FCTL_SETCMDLINESELECTION Выделить текст командной строки.
Param указывает на структуру CmdLineSelect.
Прочие
FCTL_SETUSERSCREEN Копиpует текущее содеpжимое экpана в буфеp пользовательского экрана FAR (он показывается, когда панели убpаны).
Param должен быть NULL.
FCTL_GETUSERSCREEN Выводит буфеp пользовательского экрана FAR (он показывается, когда панели убpаны) на экpан.
Param должен быть NULL.
Param
Указывает на параметры команды. Смотрите описание Command

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

В случае успеха возвращается TRUE, иначе FALSE.

Замечания

Обычно вы не должны обновлять или перерисовывать панель и директивно закрывать плагин. FAR делает это сам, при выполнении стандартных операций. Эти функции могут быть необходимыми для реализации некоторых нестандартных функциональных возможностей.
Смотрите также:
AdvControl, EditorControl