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_GETUSERSCREEN и FCTL_SETUSERSCREEN.
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 или указывает на корректно заполненную структуру.

Примечание: если установить значение FarGetPluginPanelItem::Size меньше необходимого размера (но при этом не меньше размера PluginPanelItem), то будет записано столько полей, сколько поместится целиком, а остальным будет присвоено значение NULL. В частности, если установить FarGetPluginPanelItem::Size в sizeof(PluginPanelItem) то можно за один вызов и без динамического выделения памяти получить все поля, не являющиеся указателями.

Замечание для 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);
  }
}
Более эффективным при переборе большого количества элементов панели будет иметь на стеке буфер размером, скажем, 16 КиБ и использовать его, когда этот размер достаточен. В тех же редких случаях, когда это не так, можно выделять буфер требуемого размера в динамической памяти (и можно также его не освобождать сразу, а перевыделять по мере необходимости, например, каждый раз не менее чем удваивая размер.)

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_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 - дополнительно добавить перевод строки (при повторном вызове), 1 - не добавлять.
Param2 должен быть NULL.
FCTL_GETUSERSCREEN Предоставить для нужд плагина копию Пользовательского экрана Far Manager (он показывается, когда панели убpаны).
Param1: 0 - дополнительно добавить перевод строки, 1 - не добавлять.
Param2 должен быть NULL.
Param1
Указывает на Параметр 1 команды - смотрите описание параметра Command выше.
Param2
Указывает на Параметр 2 команды - смотрите описание параметра Command выше.

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

Если иное не оговорено в описании Команды выше, в случае успеха возвращается TRUE, иначе FALSE.

Замечания

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