# 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 (в качестве внешнего редактора или программы просмотра). В этом режиме панели не создаются. Внимание! В режиме, когда 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)` то можно за один вызов и без динамического выделения памяти получить все поля, не являющиеся указателями. Внимание! 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_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_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