PanelControl

Функция PanelControl позволяет запрашивать различную информацию и выполнять управляющие действия над панелями и командной строкой.
intptr_t WINAPI PanelControl(
  HANDLE hPanel,
  enum FILE_CONTROL_COMMANDS Command,
  intptr_t Param1,
  void *Param2
);

Параметры

hPanel
Текущий описатель панели. При запросе информации относительно активной панели установите этот параметр равным PANEL_ACTIVE, для пассивной - PANEL_PASSIVE. Это позволяет использовать эту функцию в командах плагина без создания новой панели. Также PANEL_ACTIVE(PANEL_PASSIVE) можно использовать для неплагиновой панели.
Command
Тип команды. Может быть следующим FILE_CONTROL_COMMANDS):
КомандаОписание
Панель
FCTL_CHECKPANELSEXIST Проверить доступность панелей.
Param1 не используется.
Param2 не используется.
Функция возвращает FALSE, если Far Manager запущен с ключами /e или /v (в качестве внешнего редактора или программы просмотра). В этом режиме панели не создаются.

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

  • В режиме, когда Far Manager запущен с ключами /e или /v, функция обрабатывает только одну эту команду - FCTL_CHECKPANELSEXIST.
FCTL_ISACTIVEPANEL Проверяет, является ли панель активной.
Param1 не используется.
Param2 не используется.
Функция возвращает FALSE, если панель не активна.
FCTL_CLOSEPANEL Закрыть текущую панель плагина.
Param1 не используется.
Param2 указывает на имя каталога, который будет показан в панели после закрытия.
FCTL_GETPANELINFO Получить общую информацию о панели.
Param1 не используется.
Param2 указывает на структуру PanelInfo, которая получит информацию о панели.

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

Info.PanelControl(PANEL_ACTIVE,FCTL_GETPANELINFO,0,&PInfo);
Far Manager вызывает экспортируемую функцию GetOpenPanelInfoW того плагина, которому принадлежит панель. Far Manager содержит защиту от бесконечной рекурсии: в случае, когда плагин из обработчика GetOpenPanelInfoW() тоже вызывает Info.PanelControl(...,FCTL_GETPANELINFO), повторного вложенного вызова GetOpenPanelInfoW() не произойдёт.

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

FCTL_GETCOLUMNTYPES Получить строку, описывающую типы колонок.
Param1 размер буфера. Указывает максимальное количество символов, которые могут быть записаны в Param2, включая завершающий '\0'.
Param2 указывает на буфер, выделяемый плагином, в который будет помещено описание типов колонок (например, такая строка "N,SC,D,T").
Функция возвращает необходимый размер буфера в символах, если Param2 = NULL.
FCTL_GETCOLUMNWIDTHS Получить строку, описывающую ширину колонок.
Param1 размер буфера в символах. Указывает максимальное количество символов, которые могут быть записаны в Param2, включая завершающий '\0'.
Param2 указывает на буфер, выделяемый плагином, в который будет помещено описание ширины колонок (например, такая строка "0,8,0,5").
Функция возвращает необходимый размер буфера в символах, если Param2 = NULL.
FCTL_GETPANELDIRECTORY Получить текущий каталог панели.
Param1 размер буфера. Начало буфера - структура типа FarPanelDirectory, затем следуют компоненты структуры.
Param2 указывает на структуру типа FarPanelDirectory.
Функция возвращает необходимый размер буфера, если Param2 = NULL или Param1 меньше реального размера.
FCTL_GETPANELFORMAT Получить формат панели (см. OpenPanelInfo::Format).
Param1 размер буфера в символах. Указывает максимальное количество символов, которые могут быть записаны в Param2, включая завершающий '\0'.
Param2 указывает на буфер, выделяемый плагином, в который будет помещен формат панели.
Если панель не принадлежит плагину, то функция вернет размер пустой строки.
Функция возвращает необходимый размер буфера в символах, если Param2 = NULL.
FCTL_GETPANELHOSTFILE Получить имя файла, на основе которого эмулирована файловая система на панели (см. OpenPanelInfo::HostFile).
Param1 размер буфера в символах. Указывает максимальное количество символов, которые могут быть записаны в Param2, включая завершающий '\0'.
Param2 указывает на буфер, выделяемый плагином, в который будет помещено имя хост-файла.
Если панель не принадлежит плагину, то функция вернет размер пустой строки.
Функция возвращает необходимый размер буфера в символах, если Param2 = NULL.
FCTL_GETPANELITEM Получить файловый элемент панели.
Param1 порядковый номер элемента на панели (подмножество PanelInfo::ItemsNumber).
Param2 указывает на структуру типа FarGetPluginPanelItem.
Функция возвращает размер запрашиваемого элемента панели PluginPanelItem, если Param2 = NULL.

Замечание для FCTL_GETPANELITEM Внимание! Tак делать нельзя:


PluginPanelItem PPI;
Info.PanelControl(PANEL_ACTIVE,FCTL_GETPANELITEM,J,&PPI);
   

Пример правильного использования:

for(int J=0; J < PInfo.ItemsNumber; J++)
{
  size_t Size=Info.PanelControl(PANEL_ACTIVE,FCTL_GETPANELITEM,J,0);
  PluginPanelItem *PPI=(PluginPanelItem*)malloc(Size);
  if (PPI)
  {
    FarGetPluginPanelItem FGPPI={sizeof(FarGetPluginPanelItem),Size,PPI};
    Info.PanelControl(PANEL_ACTIVE,FCTL_GETPANELITEM,J,&FGPPI);
    lstrcpy(CurFile[J],PPI->FileName);
    free(PPI);
  }
}
FCTL_GETPANELPREFIX Получить префикс плагиновой панели.
Param1 размер буфера. Указывает максимальное количество символов, которые могут быть записаны в Param2, включая завершающий '\0'.
Param2 указывает на буфер, выделяемый плагином, в который будет помещено значение префикса плагиновой панели (см. PluginInfo::CommandPrefix).
Если панель не принадлежит плагину, то функция вернет размер пустой строки.
Функция возвращает необходимый размер буфера в символах, если Param2 = NULL.
FCTL_GETSELECTEDPANELITEM Получить выделенный файловый элемент панели.
Param1 порядковый номер элемента на панели (подмножество PanelInfo::SelectedItemsNumber).
Param2 указывает на структуру типа FarGetPluginPanelItem.
Функция возвращает размер запрашиваемого элемента панели PluginPanelItem, если Param2 = NULL.

PanelInfo.SelectedItemsNumber равно 1, если не выделено никаких элементов. В этом случае PluginPanelItem содержит данные для элемента под курсором. Если вы хотите узнать, действительно ли выделен этот файл, то проверьте у него состояние флага PPIF_SELECTED.

FCTL_GETCURRENTPANELITEM Получить текущий файловый элемент панели.
Param1 не используется.
Param2 указывает на структуру типа FarGetPluginPanelItem.
Функция возвращает размер запрашиваемого элемента панели PluginPanelItem, если Param2 = NULL.
FCTL_REDRAWPANEL Перерисовать панель.
Param1 не используется.
Param2 указатель на структуру PanelRedrawInfo, которой можно задать новые позиции курсора и верхнего элемента панели. Если Param2 = NULL, то позиции курсора и верхнего элемента панели при прорисовке не изменяются.
Панель прорисуется только в случае, если в данный момент панель видна.
FCTL_SETACTIVEPANEL Сделать панель активной.
Param1 не используется.
Param2 не используется.
Функция возвращает FALSE, если hPanel отлична от PANEL_ACTIVE или PANEL_PASSIVE и не принадлежит плагину, или панель в данный момент не видима.
Для hPanel = PANEL_ACTIVE никаких действий не происходит, функция вернет TRUE.

Например, установить на пассивной панели каталог TempDirectory и сделать эту панель активной:

FarPanelDirectory dirInfo={sizeof(FarPanelDirectory),TempDirectory,nullptr,{0},nullptr};
Info.PanelControl(PANEL_PASSIVE,FCTL_SETPANELDIRECTORY,0,&dirInfo);
Info.PanelControl(PANEL_PASSIVE,FCTL_SETACTIVEPANEL,0,0);
FCTL_SETNUMERICSORT Задаёт числовой порядок сортировки для панели.
Param1 целое число, задающее числовую сортировку:
0 - отключить числовую сортировку или 1 - включить числовую сортировку.
Param2 не используется.
FCTL_SETCASESENSITIVESORT Задаёт сортировку с учётом регистра для панели.
Param1 целое число, задающее сортировку с учётом регистра:
0 - отключить сортировку с учётом регистра или 1 - включить сортировку с учётом регистра.
Param2 не используется.
FCTL_SETPANELDIRECTORY Установить текущий каталог в панели.
Param1 не используется.
Param2 указывает на структуру типа FarPanelDirectory.
Если плагин поддерживает свою собственную панель, он будет закрыт после выполнения этой команды.

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

FCTL_BEGINSELECTION,
FCTL_ENDSELECTION
Начать/закончить операцию выделения в панели.
Param1 не используется.
Param2 не используется.

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

  • Порядок использования смотрите в примере к FCTL_SETSELECTION
FCTL_SETSELECTION Установить выделение в панели.
Param1 порядковый номер элемента на панели (подмножество PanelInfo::ItemsNumber).
Param2 указывает на переменную типа BOOL (TRUE - выделить элемент, FALSE - снять выделение).

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

Пример:

// начинаем операцию по выделению файлов
Info.PanelControl(PANEL_ACTIVE,FCTL_BEGINSELECTION,0,NULL);

// выделяем
for(int i=0; i < PInfo.ItemsNumber; i++)
{
  Info.PanelControl(PANEL_ACTIVE,FCTL_SETSELECTION,i,(void*)TRUE);
}
// завершаем операцию и перерисовываем панель
Info.Control(PANEL_ACTIVE,FCTL_ENDSELECTION,0,NULL);
Info.Control(PANEL_ACTIVE,FCTL_REDRAWPANEL,0,NULL);
FCTL_CLEARSELECTION
Снять выделение с выделенных элементов панели.
Param1 порядковый номер элемента на панели (подмножество PanelInfo::SelectedItemsNumber).
Param2 не используется.

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

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

  • Порядок использования такой же, что и в примере к FCTL_SETSELECTION
FCTL_SETSORTMODE Установить режим сортировки для панели.
Param1 целое число, содержащее режим сортировки (см. "Режимы сортировки").
Param2 не используется.
FCTL_SETSORTORDER Задаёт порядок сортировки для панели.
Param1 целое число, содержащее порядок сортировки: 0 или 1 (обратная сортировка).
Param2 не используется.
FCTL_SETVIEWMODE Установить режим просмотра панели.
Param1 целое число, которое содержит номер нового режима, от 0 до 9.
Param2 не используется.
FCTL_UPDATEPANEL Обновить содержимое панели.
Если Param1 = 0, текущее выделение файлов будет снято, иначе выделение не изменится.
Param2 не используется.
FCTL_SETDIRECTORIESFIRST Задаёт режим отображения каталогов в начале списка файлов.
Param1 целое число, 1 - каталоги отображаются в начале списка, 0 - нет.
Param2 не используется.
Командная строка
FCTL_GETCMDLINE Получить содержимое командной строки.
Param1 размер буфера в символах. Указывает максимальное количество символов, которые могут быть записаны в Param2, включая '\0'.
Param2 указывает на буфер, выделяемый плагином, который получит данные.
Функция возвращает необходимый размер буфера в символах, если Param2 = NULL.
FCTL_GETCMDLINEPOS Получить позицию курсора в командной строке.
Param1 не используется.
Param2 содержит указатель на переменную типа int, в которую будет помещена позиция курсора.
FCTL_GETCMDLINESELECTION Получить параметры выделенного текста командной строки.
Param1 не используется.
Param2 указывает на структуру CmdLineSelect.
FCTL_INSERTCMDLINE Вставить текст в командную строку, начиная с текущей позиции курсора.
Param1 не используется.
Param2 указывает на строку, оканчивающуюся нулём, которая будет вставлена в командную строку.
FCTL_SETCMDLINE Установить содержимое командной строки.
Param1 не используется.
Param2 указывает на строку, оканчивающуюся нулём, которая будет помещена в командную строку.
FCTL_SETCMDLINEPOS Установить позицию курсора в командной строке.
Param1 содержит переменную с новой позицией курсора.
Param2 не используется.
FCTL_SETCMDLINESELECTION Выделить текст командной строки.
Param1 не используется.
Param2 указывает на структуру CmdLineSelect.
Прочие
FCTL_SETUSERSCREEN Установить обработанную плагином копию Пользовательского экрана под панели Far Manager.
Param1 должен быть 0, Param2 должен быть NULL.
FCTL_GETUSERSCREEN Предоставить для нужд плагина копию Пользовательского экрана Far Manager (он показывается, когда панели убpаны).
Param1 должен быть 0, Param2 должен быть NULL.
Param1
Указывает на параметры1 команды. Смотрите описание Command.
Param2
Указывает на параметры2 команды. Смотрите описание Command.

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

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

Замечания

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