panels.text

Свойства и функции для работы с панелями
========================================

Под "*панелями*" понимаются следующие области: файловые панели (`Shell`), информационная панель (`Info`),
панель быстрого просмотра (`QView`), панель дерева папок (`Tree`).

Все плагиновые панели относятся к файловым (`Shell`).

:::wrap
Логические свойства (`boolean`)
-------------------------------


### Файловые панели

`APanel.Bof`, `PPanel.Bof`
:	текущий элемент панели в начале списка?

`APanel.Eof`, `PPanel.Eof`
:	текущий элемент панели в конце списка?

`APanel.Empty`, `PPanel.Empty`
:	панель пуста?

`APanel.Filter`, `PPanel.Filter`
:	на панели включён фильтр?

`APanel.Folder`, `PPanel.Folder`
:	текущий элемент панели - папка?

`APanel.LFN`, `PPanel.LFN`
:	на панели "длинные имена файлов"?

`APanel.Plugin`, `PPanel.Plugin`
:	плагиновая панель?

`APanel.Root`, `PPanel.Root`
:	на панели корневая папка?

`APanel.Selected`, `PPanel.Selected`
:	на панели есть отмеченные файлы/папки?


### Все панели

`APanel.FilePanel`, `PPanel.FilePanel`
:	файловая панель?

`APanel.Left`, `PPanel.Left`
:	панель слева?

`APanel.Visible`, `PPanel.Visible`
:	панель видима?

### Замечания

Префикс `APanel.` относится к активной панели, `PPanel.` - к пассивной.



Свойства
--------


### Файловые панели

`APanel.ColumnCount`, `PPanel.ColumnCount`
:	`number`
:	количество колонок на панели

`APanel.CurPos`, `PPanel.CurPos`
:	`number`
:	содержит порядковый номер файлового объекта на панели

`APanel.Current`, `PPanel.Current`
:	`string`
:	содержит имя файла под курсором

`APanel.DriveType`, `PPanel.DriveType`
:	`number`
:	содержит тип привода на панели:

	`-1`
	:	Плагиновая панель

	`0`
	:	Не удалось определить тип привода

	`2`
	:	Сменный привод

	`3`
	:	Жёсткий диск

	`4`
	:	Сетевой подмапленный диск

	`5`
	:	CD-ROM

	`6`
	:	Виртуальный диск

	`15`
	:	SUBST-диск

`APanel.ItemCount`, `PPanel.ItemCount`
:	`number`
:	содержит количество файловых объектов на панели

`APanel.Path`, `PPanel.Path`
:	`string`
:	содержит путь панели (без заключительного '`\`')

`APanel.SelCount`, `PPanel.SelCount`
:	`number`
:	содержит количество выделенных файлов на панели

`APanel.UNCPath`, `PPanel.UNCPath`
:	`string`
:	содержит UNC-путь панели (без заключительного '`\`');
	для плагиновой панели - `prefix:[hostfile/]path`


### Файловые панели плагинов

`APanel.Format`, `PPanel.Format`
:	`string`
:	содержит имя формата панели плагина

`APanel.HostFile`, `PPanel.HostFile`
:	`string`
:	содержит имя хост-файла панели плагина (или пусто)

`APanel.OPIFlags`, `PPanel.OPIFlags`
:	`number`
:	набор битовых флагов, характеризующих свойства плагиновой панели:

	`0x00000001`
	:	используется фильтр на панели

	`0x00000002`
	:	используются группы сортировки на панели

	`0x00000004`
	:	используется раскраска файлов на панели

	`0x00000010`
	:	папки на панели плагина выбираются независимо от настроек Far

	`0x00000020`
	:	используется стандартная обработка файла FAR'ом,
		если запрошенная операция не поддерживается плагином;

		если этот флаг указан, элементы на панели плагина являются именами реальных файлов

	`0x00000040`
	:	показаны имена без путей

	`0x00000080`
	:	имена файлов выровнены по правому краю

	`0x00000100`
	:	имена файлов показаны в оригинальном регистре (независимо от настроек Far).

		Если панель не плагиновая, то значение будет = `0`

`APanel.Path0`, `PPanel.Path0`
:	`string`
:	содержит путь на реальной файловой системе, до вызова плагинов,
	создающих свою панель (без заключительного '`\`').

	Примечание: путь в корне диска будет содержать заключительный '`\`'.

`APanel.Prefix`, `PPanel.Prefix`
:	`string`
:	содержит префикс плагина или пусто (или несколько префиксов, разделённых символом '`:`')


### Все панели

`APanel.Height`, `PPanel.Height`
:	`number`
:	содержит высоту панели

`APanel.Width`, `PPanel.Width`
:	`number`
:	содержит ширину панели

`APanel.Type`, `PPanel.Type`
:	`number`
:	содержит тип панели:

	`0`
	:	Файловая панель

	`1`
	:	Дерево папок

	`2`
	:	Панель быстрого просмотра

	`3`
	:	Информационная панель
:::

### Замечания

Префикс `APanel.` относится к активной панели, `PPanel.` - к пассивной.


Функции
-------

:::functions
`b=Panel.FAttr(panelType,S)`
:	Возвращает файловые атрибуты файла/папки `S` из активной (`panelType=0`)
	или пассивной (`panelType=1`) панели.

	`0x00000001`
	:	`FILE_ATTRIBUTE_READONLY`. Файл только для чтения.
	:	Приложения могут читать такой файл, но не могут записывать или удалять его.

	`0x00000002`
	:	`FILE_ATTRIBUTE_HIDDEN`. Файл скрыт.
	:	Такой файл не включается в обычный листинг папки.

	`0x00000004`
	:	`FILE_ATTRIBUTE_SYSTEM`. Этот файл - часть операционной системы.

	`0x00000010`
	:	`FILE_ATTRIBUTE_DIRECTORY`. Это папка.

	`0x00000020`
	:	`FILE_ATTRIBUTE_ARCHIVE`. Это архивный файл.
	:	Приложения должны использовать этот флаг для копирования, архивирования или удаления.

	`0x00000080`
	:	`FILE_ATTRIBUTE_NORMAL`. У этого файла не установлены другие атрибуты.
	:	Это значение корректно только при использовании без остальных флагов.

	`0x00000100`
	:	`FILE_ATTRIBUTE_TEMPORARY`. Это временный файл.
	:	Приложения должны записывать в такой файл только в крайней необходимости.
		Большая часть данных файла находится в памяти и не сбрасывается на диск,
		так как файл будет удалён.

	`0x00000200`
	:	`FILE_ATTRIBUTE_SPARSE_FILE`. Файл является разрежённым.

	`0x00000400`
	:	`FILE_ATTRIBUTE_REPARSE_POINT`. Папка является точкой повторной обработки.

	`0x00000800`
	:	`FILE_ATTRIBUTE_COMPRESSED`. Файл или папка сжаты.
	:	Для файла это означает, что все данные его сжаты,
		для папки - что компрессия по умолчанию применяется ко всем её файлам и подпапкам.

	`0x00001000`
	:	`FILE_ATTRIBUTE_OFFLINE`. Данные файла не доступны непосредственно.
	:	Означает, что реальные данные файла были физически перемещены на устройства хранения.

	`0x00002000`
	:	`FILE_ATTRIBUTE_NOT_CONTENT_INDEXED`.
	:	Этот файл или папки не будут индексироваться службой индексирования.

	`0x00004000`
	:	`FILE_ATTRIBUTE_ENCRYPTED`. Файл или папка зашифрованы.
	:	Для файла это означает, что все данные в файле зашифрованы.
		Для папки это означает, что шифрование является умолчанием
		для вновь созданных файлов и подпапок.

	`0x00010000`
	:	`FILE_ATTRIBUTE_VIRTUAL`. Этот файл - виртуальный файл.

	Если файловый объект не существует, функция возвращает `-1`.

	В параметре `S` допускается использование символов масок '`*`' и '`?`'.
	В этом случае функция возвращает атрибуты для первого найденного файла/папки.

	В отличие от `mf.fattr()`, функция работает только с панелями.

`itemIdx=Panel.FExist(panelType,S)`
:	Проверяет существование файла/папки `S` из активной (`panelType=0`)
	или пассивной (`panelType=1`) панели.

	В параметре `S` допускается использование символов '`*`' и '`?`'.
	В этом случае функция проверяет только первое вхождение файла/папки.

	Функция возвращает `0`, если такого объекта на панели нет, или индекс элемента.

	В отличие от `mf.fexist()`, функция работает только с панелями.

`V=Panel.Item(panelType,itemIdx,Property)`
:	Возвращает различную информацию для элемента панели `itemIdx` из активной (`panelType=0`)
	или пассивной (`panelType=1`) панели.

	В зависимости от запрашиваемого `Property` функция возвращает следующие свойства элемента:

	`0`
	:	`string`
	:	Имя файла/папки

	`1`
	:	`string`
	:	Короткое имя

	`2`
	:	`number`
	:	Файловые атрибуты

	`3`
	:	`string`
	:	Дата/время создания

	`15`
	:	`number`
	:	Дата/время создания

	`4`
	:	`string`
	:	Дата/время последнего доступа

	`16`
	:	`number`
	:	Дата/время последнего доступа

	`5`
	:	`string`
	:	Дата/время модификации

	`17`
	:	`number`
	:	Дата/время модификации

	`20`
	:	`string`
	:	Дата/время последнего изменения

	`21`
	:	`number`
	:	Дата/время последнего изменения

	`6`
	:	`number`
	:	Размер

	`7`
	:	`number`
	:	Выделенный размер

	`8`
	:	`boolean`
	:	*"Выделен?"*

	`9`
	:	`number`
	:	Количество жёстких ссылок (*hard links*)

	`10`
	:	`number`
	:	*SortGroup*

	`11`
	:	`string`
	:	*Diz*-текст

	`12`
	:	`string`
	:	Владелец

	`13`
	:	`number`
	:	CRC32 - контрольная сумма, может использоваться панельными плагинами.
		(Far Manager не использует это поле)

	`14`
	:	`number`
	:	Позиция элемента в процессе чтения файловой системы

	`18`
	:	`number`
	:	Количество потоков

	`19`
	:	`number`
	:	Размер потоков

	`22`
	:	~~Var~~
	:	~~Значение Custom-колонки~~
		(Не адаптировано для текущего API колонок)

	`23`
	:	`number`
	:	Значение [`ReparseTag`](https://docs.microsoft.com/en-us/openspecs/windows_protocols/ms-fscc/c8e77b37-3909-4fe6-a4ea-2b9d423b1ee4) (актуально только для ссылок)

	Для панели "*Дерево папок*" возвращается только имя файла (`Property=0`),
	остальные значения `Property` игнорируются.

	Для получения данных о текущем элементе (под курсором) `itemIdx` должен быть равен `0`.

	Дата/время могут возвращаться в форматах:

	1. как строка вида "`DD.MM.YYYY HH:MM:SS`". Разделители и порядок в дате зависят
	   от региональных настроек.
	2. как 64-разрядное число. В старших 32-х битах - дата, в младших - время.

	Пример - выделить все файлы/папки новее текущего:

	~~~lua
	local APANEL,CUR_ITEM = 0,0  -- common
	local MOD_TIME = 17          -- Panel.Item
	local SELECT,MODE_IDX = 1,1  -- Panel.Select
	Macro {
	  description="выделить все файлы/папки новее текущего";
	  area="Shell"; key="CtrlShiftAdd";
	  action=function()
	    local d = Panel.Item(APANEL,CUR_ITEM,MOD_TIME)
	    for i=1,APanel.ItemCount do
	      if Panel.Item(APANEL,i,MOD_TIME)>d then
	        Panel.Select(APANEL,SELECT,MODE_IDX,i)
	      end
	    end
	  end;
	}
	~~~

`N=Panel.Select(panelType,Action[,Mode[,Items]])`
:	Операции с выделением элементов на активной (`panelType=0`)
	или пассивной (`panelType=1`) панели.

	`Action` может быть одним из следующих значений:

	`0`
	:	снять выделение

	`1`
	:	выделить

	`2`
	:	инвертировать выделение

	`3`
	:	восстановить выделение (аналог ~Ctrl+M~).

		Возвращает количество восстановленных элементов.

	Необязательный параметр `Mode` может принимать следующие значения:

	`0` / или не указан
	:	`Items`: игнорируется
	:	выполнить действие `Action` для всех элементов

	`1`
	:	`Items`: `number` - индекс элемента панели.
	:	Выполнить действие `Action` для элемента с индексом `Items`.

		Если `Items = 0` (или отсутствует) - выполнить действие `Action` для текущего элемента.

	`2`
	:	`Items`: `string` - список имён файловых объектов (возможно с полными путями).
	:	Выполнить действие `Action` для элементов, указанных в `Items`.

	`3`
	:	`Items`: `string` - список файловых масок.
	:	Выполнить действие `Action` для элементов, подходящих под маски, указанные в `Items`.

	Для строковых значений `Items`:

	* Элементы должны быть разделены с помощью *Lf* ("`\n`") или *CrLf* ("`\r\n`").
	* В случае если `Items` равно `""` (или отсутствует) - действие не выполняется.

	Функция возвращает количество элементов, над которыми производилось `Action`.

	Примеры:

	:::examples
	`Panel.Select(0,0)`
	:	полное снятие выделения

	`Panel.Select(0,1)`
	:	выделить все элементы

	`Panel.Select(0,2)`
	:	инверсия всего

	`Panel.Select(0,2,1)`
	:	инверсия того, что под курсором

	`Panel.Select(0,1,1,10)`
	:	"вдогонку" выделить 10-й элемент панели

	`Panel.Select(0,0,3)`
	:	ничего не делать

	`Panel.Select(0,1,2,mf.clip(0))`
	:	выделить элементы, имена которых содержатся в буфере обмена
	:::

`E=Panel.SetPath(panelType,path[,filename])`
:	На активной (`panelType=0`) или пассивной (`panelType=1`) панели выставляет путь `path`
	и позиционирует курсор на элемент с именем `filename` (если указан).

	Возвращает `true` в случае успешной установки пути, и `false`, если папка не существует.

	Например, на активной панели выставить папку `C:\WINDOWS`, на пассивной - `C:\Program Files`,
	активную панель сделать слева и установить курсор на папку `FAR`:

	~~~lua
	if APanel.Left then Keys("CtrlU") end
	Panel.SetPath(1,"C:\\WINDOWS")
	Panel.SetPath(0,"C:\\Program Files","FAR")
	~~~

`itemIdx=Panel.SetPos(panelType,filename)`
:	Позиционирует курсор на элемент с именем `filename` на активной (`panelType=0`)
	или пассивной (`panelType=1`) панели.

	Возвращает позицию (индекс) элемента или `0`, если такого элемента на панели нет.

	См. [Примеры]

`itemIdx=Panel.SetPosIdx(panelType,PosIdx[,InSelection])`
:	Позиционирует курсор на элемент с индексом `itemIdx` на активной (`panelType=0`)
	или пассивной (`panelType=1`) панели.

	Параметр `PosIdx` может принимать отрицательные значения,
	в этом случае элементы панели нумеруются от конца к началу.

	Если задать `itemIdx=0`, то перехода не происходит, просто возвращается текущая позиция.

	С помощью необязательного параметр `InSelection` можно осуществить позиционирование
	среди отмеченных элементов (для этого нужно указать `InSelection=1`).

	Функция возвращает позицию элемента или `0`, если такого элемента на панели нет.


### Работа с пользовательскими режимами сортировки

Функции, позволяющие определять и устанавливать пользовательские режимы сортировки,
доступны если в качестве движка [Lua] используется [LuaJIT] 2.

`Panel.CustomSortMenu()`
:	Выводит меню со списком загруженных пользовательских сортировок.

	Параметры: Нет

	Возвращает: Ничего

	Нажатие ~Enter~ устанавливает выбранный режим сортировки на активной панели,
	нажатие ~Ctrl+Enter~ - на пассивной, ~Ctrl+Shift+Enter~ - на обеих.

	Клавиши ~Add~ и ~Subtract~ работают так же, как в меню выбора режима сортировки Far.
	При этом также поддерживаются модификаторы ~Ctrl~- и ~Ctrl+Shift~-, определяющие выбор панелей
	для установки режима сортировки.


`Panel.LoadCustomSortMode(Mode,Settings)`
:	Функция загружает (или выгружает) пользовательский режим сортировки для панелей.
	Если режим загружен, он может быть установлен в панели посредством вызова функции
	`Panel.SetCustomSortMode`.

	Параметры:

	`Mode`
	:	режим сортировки, целое число >=`SM_USER` и <=`0x7FFFFFFF`

	`Settings`
	:	таблица, содержит следующие поля:

		:::wide
		`Condition`
		:	Функция. Если задана, то будет вызвана с одним аргументом - режим сортировки.
			Если возвращаемое значение ложно, то сортировка отменяется.
			Следует отметить, что данная функция может перезагрузить все параметры сортировки,
			снова вызвав `Panel.LoadCustomSortMode()`.

		`Compare`
		:	Функция, см. её описание ниже.

		`DirectoriesFirst`, `SelectedFirst`, `RevertSorting`, `SortGroups`
		:	Данные опциональные поля задают соответствующие опции сортировки:
			`0` - опция выключена, `1` - опция включена, любое другое значение
			или отсутствие данного поля означают "использовать текущую
			установку Far Manager".

		`InvertByDefault`
		:	Включать ли по умолчанию обратную сортировку.

		`Indicator`
		:	Индикация режима сортировки на панели, строка из двух символов
			(первый - для прямой, второй - для обратной сортировки).

		`NoSortEqualsByName`
		:	По умолчанию, равные с точки зрения алгоритма сортировки элементы
			сортируются по имени. Если это нежелательно, установите данное поле
			в `true`.

		`Description`
		:	Текстовое описание режима сортировки. Если данное поле задано,
			оно используется в меню (см. `Panel.CustomSortMenu`).

		`SortFunction`
		:	Опция выбора функции сортировки из двух встроенных.
			Задаётся строкой: "`shellsort`" (значение по умолчанию) или "`qsort`".

		`InitSort`
		:	Функция. Если задана, то вызывается перед началом сортировки.
			Получает один параметр: таблицу `FarOptions` (см. ниже одноимённый
			параметр функции `Compare`).

		`EndSort`
		:	Функция. Если задана, то вызывается после окончания сортировки.

		Если значение `Settings` равно `nil` или `false`, это означает выгрузку
		(удаление) данного режима сортировки.
		:::

	Возвращает: Ничего

	:::examples
	Функция `Compare`
	:	`result=Compare(Pi1,Pi2,FarOptions)`

		Параметры:

		`Pi1` и `Pi2`
		:	сравниваемые элементы панели, структуры типа [`SortingPanelItem`][SortingPanelItem].

		`FarOptions`
		:	таблица, содержащая текущие опции сортировки панели в Far Manager
			(все значения - булевые): `DirectoriesFirst`, `SelectedFirst`,
			`RevertSorting`, `SortGroups`, `NumericSort`, `CaseSensitiveSort`.

		Возвращает:

		`result`:
			если 1-й элемент должен оказаться после прямой сортировки выше 2-го,
			нужно возвратить отрицательное число, если ниже - положительное,
			а если элементы по критерию сортировки равны - ноль.
	:::
	Примечания:

	1. Пользовательская сортировка использует библиотеку [FFI] от [LuaJIT] 2. Программирование
	   с использованием *LuaJIT FFI* требует предварительного освоения документации.

	2. Пользовательские режимы сортировок панелей восстанавливаются при перезапуске Far,
	   если текущая конфигурация была сохранена, при условии, что соответствующие вызовы
	   `Panel.LoadCustomSortMode()` производятся в процессе загрузки макросов.
	   Восстановление происходит после окончания загрузки макросов, до начала исполнения
	   автостартующих макросов.

	3. Пользовательские режимы сортировки принудительно выгружаются при выгрузке макросов.


	Пример:

	~~~lua
	-- Загрузить сортировку по длине имени файла.
	local ffi = require "ffi"
	local C = ffi.C
	local F = far.Flags
	Panel.LoadCustomSortMode (F.SM_USER+10,
	  { 
	    Compare = function(p1, p2, opt)
	      local l1, l2 = C.wcslen(p1.FileName), C.wcslen(p2.FileName)
	      return l1<l2 and -1 or l1>l2 and 1 or 0
	    end;
	    Description = "sorting by file name length";
	    Indicator = "bB";
	  })
	~~~

`Panel.SetCustomSortMode(Mode,whatpanel[,order])`
:	установка пользовательского режима сортировки `Mode` в заданной панели

	Заданный режим сортировки `Mode` должен быть предварительно  загружен (см. `Panel.LoadCustomSortMode`).
	Иначе не будет произведено никаких действий.

	Параметры

	`Mode`
	:	режим сортировки, целое число >=`SM_USER` и <=`0x7FFFFFFF`

	`whatpanel`
	:	`0`=активная панель, `1`=пассивная панель

	`order`
	:	"`auto`"    - стандартный выбор направления сортировки (значение по умолчанию)
	:	"`current`" - сохранить текущее направление сортировки в панели
	:	"`direct`"  - установить прямую сортировку
	:	"`reverse`" - установить обратную сортировку

	Возвращает: Ничего

	Пример:

	~~~lua
	-- Установить заданную пользовательскую сортировку в активной панели.
	Macro {
	  description="Sort files by their name length";
	  area="Shell"; key="CtrlShiftF1";
	  action=function() Panel.SetCustomSortMode(F.SM_USER+10,0) end;
	}
	~~~
:::

### Замечания

1. Панельные функции работают только с видимыми файловыми элементами,
   с учётом применённых фильтров на панели.
2. Нумерация элементов начинается с `1`.
3. Во время вызова макрофункций `Panel.SetPos()`, `Panel.SetPath()` и `Panel.SetPosIdx()`
   макросы замораживаются до момента выполнения этих функций.

На "больших" папках (например, сетевые, с большим количеством файловых объектов и/или медленных каналах)
эти функции могут выводить сообщения о процессе сбора данных о файлах/папках,
с возможностью отменить процесс по ~Esc~.


- - -
Смотрите также:

[Примеры]

[Примеры]: examples.md
[Lua]: https://www.lua.org/about.html
[LuaJIT]: http://luajit.org/luajit.html
[FFI]: http://luajit.org/ext_ffi.html
[SortingPanelItem]: https://api.farmanager.com/ru/structures/sortingpanelitem.html