Общие свойства и функции - Макросы

Programming Far Manager plugins

Общие свойства и функции

Эти свойства и функции не зависят от области, в которой исполняется в данный момент макропоследовательность.

Логические свойства (тип: Boolean)

Проверка области, в которой исполняется в данный момент макропоследовательность

Свойство Описание
Shell файловые панели
Info информационная панель
QView панель быстрого просмотра
Tree панель дерева папок
Search быстрый поиск в панелях
FindFolder поиск папок
Viewer внутренняя программа просмотра
Editor редактор
Dialog диалоги
Menu прочие меню
MainMenu основное меню
UserMenu пользовательское меню
Disks меню выбора дисков
Help система помощи
AutoCompletion список автодополнения
Other режим копирования текста с экрана

Разное

Свойство Описание
IsUserAdmin Far Manager запущен под Администратором?
Fullscreen Far Manager работает в оконном режиме?

Свойства

ОператорТипОписание
Macro.Area String наименование текущей макрообласти исполнения
Far.Width Number ширина консоли, в которой работает Far Manager
Far.Height Number высота консоли, в которой работает Far Manager
Far.Title String текущий заголовок консольного окна Far Manager
Far.UpTime Number сколько времени (в миллисекундах) работает Far Manager (своё значение для каждой запущенной копии)
Far.PID Number содержит ИД текущей запущенной копии Far Manager
Far.Cfg.Err Number

Индикатор ошибки после вызова Far.Cfg.Get: =0 - нет ошибок, =1 - ошибка.

Значение константы необходимо проверять сразу после вызова функции Far.Cfg.Get, в других случаях значение константы не имеет смысла.

Title String заголовок текущего объекта
RCounter Number Содержит текущее значение счётчика оператора цикла $Rep. Область видимости - текущий $Rep. За пределами цикла значение константы неопределённое (любое / нет смысла использовать).

Мышь

ОператорТипОписание
MsX Number Координата горизонтального положения курсора мыши с момента последнего поступления мышиного события
MsY Number Координата вертикального положения курсора мыши с момента последнего поступления мышиного события
MsButton Number

Состояние клавиш мыши.

Младший бит соответствует самой левой кнопке, следующий - самой правой, cледующий бит - следующая за левой клавиша. Далее биты соответствуют клавишам слева направо.

Если бит установлен - клавиша нажата.

Определены следующие константы для первых пяти клавиш мыши:

Значение Описание
0x0001 FROM_LEFT_1ST_BUTTON_PRESSED
0x0002 RIGHTMOST_BUTTON_PRESSED
0x0004 FROM_LEFT_2ND_BUTTON_PRESSED
0x0008 FROM_LEFT_3RD_BUTTON_PRESSED
0x0010 FROM_LEFT_4TH_BUTTON_PRESSED
MsCtrlState Number Состояние управляющих клавиш. Может быть комбинацией следующих значений:
Значение Описание
0x0001 RIGHT_ALT_PRESSED
0x0002 LEFT_ALT_PRESSED
0x0004 RIGHT_CTRL_PRESSED
0x0008 LEFT_CTRL_PRESSED
0x0010 SHIFT_PRESSED
0x0020 NUMLOCK_ON
0x0040 SCROLLLOCK_ON
0x0080 CAPSLOCK_ON
0x0100 ENHANCED_KEY
MsEventFlags Number Состояние событий мыши:
Значение Описание
0x0001 MOUSE_MOVED
Перемещение мыши
0x0002 DOUBLE_CLICK
Двойной клик клавиши мыши
0x0004 MOUSE_WHEELED
Перемещение колеса по вертикали
0x0008 MOUSE_HWHEELED
Перемещение колеса по горизонтали

Функции

Математические функции

Функция Описание
N=abs(V) Возвращает абсолютную величину числового аргумента V.
N=max(N1,N2) Возвращает максимальное значение между двумя числовыми аргументами N1 и N2.
N=min(N1,N2) Возвращает минимальное значение между двумя числовыми аргументами N1 и N2.
N=mod(N1,N2) Деление N1 по модулю N2.
N=int(V) Приведение значения выражения V к числу.
N=float(V) Приведение значения выражения V к числу с плавающей точкой.
V=iif(Expr,True,False) Условный оператор. Если условие Expr верно, то возвращается True-выражение, иначе False-выражение.
Если Expr строка и она не пуста, то возвращается True-выражение, иначе False-выражение.

Строковые функции

Функция Описание
N=index(S1,S2[,CaseSensitive])

Если подстрока S2 содержится в строке S1, то возвращается её позиция, иначе -1.

Необязательный параметр CaseSensitive задаёт режим сравнения: 0 (по умолчанию) - без учёта регистра, 1 - с учётом регистра.

N=rindex(S1,S2[,CaseSensitive])

Если подстрока S2 содержится в строке S1, то возвращается её позиция, иначе -1.

Поиск ведётся от конца строки S1.

Необязательный параметр CaseSensitive задаёт режим сравнения: 0 (по умолчанию) - без учёта регистра, 1 - с учётом регистра.

Result=replace(Str,Find,Replace[,Cnt[,CaseSensitive]])

В строке Str заменить подстроку Find на подстроку Replace Cnt раз.

Если параметр Cnt меньше или равен 0, либо опущен, то будут заменены все вхождения Find.

Возвращается результат замены.

Необязательный параметр CaseSensitive задаёт режим сравнения: 0 (по умолчанию) - без учёта регистра, 1 - с учётом регистра.

Замечания:

  • если Find - пустая строка, то возвращается Str без преобразований;
  • если Replace - пустая строка, то возвращается копия Str, в которой удалены все подстроки Find;
N=asc(S) Возвращает код символа S.
S=chr(N) Возвращает символ, заданный кодом N.
S=itoa(N[,Radix])

Конвертирует целое число N в строку.

Значение Radix определяет основание, которое должно использоваться при преобразовании числа N. Допустимые значения Radix от 2 до 36.

Если параметр Radix не указан, то подразумевается основание 10.

N=atoi(S[,Radix])

Конвертирует строку S в число.

Значение Radix определяет основание, которое будет использоваться при преобразовании строки S. Допустимые значения Radix от 2 до 36.

Если параметр Radix не указан или равен 0, то функция попытается сама определить, в каком виде представлено строковое представление числа.

N=len(S) Возвращает длину строки S.
S=string(V) Перевод значения выражения V в строку.
S=substr(V,start[,length])

Возвращает подстроку из выражения V начиная с позиции start длиной length.

Если start >= 0, то вернётся подстрока, начиная с позиции start от начала строки.

Если start < 0, то вернётся подстрока, начиная с позиции start от конца строки.

Если length > 0, то возвращаемая подстрока будет состоять максимум из length символов исходной строки начиная с позиции start.

Если length < 0, то в возвращаемой подстроке будет отсутствовать length символов от конца исходной строки, при том, что она будет начинаться с позиции start.

Если length = 0 или не указан, то возвращается подстрока от start до конца строки.

Примеры

Вызов Результат
substr("abcdef", 1)возвращает "bcdef"
substr("abcdef", 1, 3)возвращает "bcd"
substr("abcdef", 0, 4)возвращает "abcd"
substr("abcdef", 0, 8)возвращает "abcdef"
substr("abcdef", -1)возвращает "f"
substr("abcdef", -2)возвращает "ef"
substr("abcdef", -3, 1)возвращает "d"
substr("abcdef", 0, -1)возвращает "abcde"
substr("abcdef", 2, -1)возвращает "cde"
substr("abcdef", 4, -4)возвращает ""
substr("abcdef", -3, -1)возвращает "de"
S=size2str(Size,Flags[,Width])

Функция форматирует число Size (например, размера файла) по заданным условиям, указанным в Flags, шириной Width.

Параметр Flags может быть комбинацией следующих значений:

Значение Описание
0x0010000000000000 Добавлять суффиксы: K - для килобайтов, M - для мегабайтов, G - для гигабайтов, T - для терабайтов, P - для петабайтов, E - для эксабайтов
0x0800000000000000 Вставлять разделитель между тысячами. Используется значение "Interface/FormatNumberSeparators" из конфигурации или значения OS (LOCALE_STHOUSAND & LOCALE_SDECIMAL), если FormatNumberSeparators не указан.
0x0080000000000000 Показывать размер в виде десятичной дроби, используя наиболее подходящую единицу измерения, например 0,97 К, 1,44 М, 53,2 Г.
0x0040000000000000 Экономичный режим, не показывать пробел перед суффиксом размера файла (т.е. 0.97K)
0x0400000000000000 Вместо делителя 1024 использовать делитель 1000.
0x0020000000000000

Использовать минимально допустимый индекс при форматировании. Индекс указывается в в младшем байте и может быть только 0, 1, 2 или 3 (K,M,G,T).

Например, 0x0020000000000001 означает "размер как минимум в мегабайтах".

Если Width не указан или равен 0, то подразумевается - "сколько получится". Отрицательное значение ширины позволяет выравнивать слева:

Вызов Результат
Size2Str(123,0, 5)' 123'
Size2Str(123,0,-5)'123 '

S=strwrap(Text,Width[,Break[,Flags]])

Форматирует (с выравниваением влево) исходный текст Text по заданной ширине Width, используя разделительную строку Break.

Если Flags равен 0x1, то строка всегда сворачивается по заданной ширине, даже если есть слово, которое больше заданной ширины (в этом случае то оно будет разрезано на части). Если флаг не указан или не равен 0x1 и есть длинное слово, то такое слово не будет разрезано и займет ширину больше чем указано в Width.

Примеры

Вызов Результат
StrWrap("Пример строки, которая будет разбита на несколько строк по ширине в 7 символов.", 7)
 +-------+
 |Пример
 |строки,
 |которая
 |будет
 |разбита
 |на
>|несколько
 |строк
 |по
 |ширине
 |в 7
>|символов.
 +-------+
StrWrap("Пример строки, которая будет разбита на несколько строк по ширине в 7 символов.", 7,,1)
  1234567
 +-------+
 |Пример
 |строки,
 |которая
 |будет
 |разбита
 |на
 |несколь
 |ко
 |строк
 |по
 |ширине
 |в 7
 |символо
 |в.
 +-------+
StrWrap("Эта строка содержит оооооооооооооччччччччеееень длиное слово", 9,,0x1)
  123456789
 +---------+
 |Эта
 |строка
 |содержит
 |ооооооооо
 |ооооччччч
 |чччеееень
 |длиное
 |слово
 +---------+
S=strpad(V,Size[,Fill[,Op]])

Функция возвращает строку V, дополненную до заданной длины Size строкой Fill (по умолчанию пробелами). Способ дополнения зависит от параметра Op:

OpОписание
0заполнение справа от V
1заполнение слева от V
2заполнение вокруг V

Если Size меньше или равна длине V либо опущена, то дополнения не происходит (возвращается V).

Если разность Size и длины V не делится без остатка на длину Fill, дополняющая строка обрезается справа.

Примеры:

Вызов Результат
strpad("Foo",10,"*",2)'***Foo****'
strpad("",10,"-*-",2)'-*--*--*--'
strpad(,10,"-*-")'-*--*--*--'
strpad("Foo",10)'Foo       '
strpad("Foo",10,"-")'Foo-------'
strpad("Foo",10,,1)'       Foo'
strpad("Foo",10,,2)'   Foo    '
strpad("Foo",10,"1234567890",2)'123Foo1234'
S=trim(V[,N]) Удаляет все пробельные символы (пробелы, табуляции, переводы строк и возвраты каретки) из строки V снаружи (N=0 или не указан), слева (N=1) или справа (N=2). S=xlat(S[,Flags])

Возвращает транслитерируемую строку S.

Функция аналогична макрокоманде $XLat, но используется в выражениях. Необязательный аргумент Flags позволяет уточнять поведение функции:

FlagsОписание
1переключить раскладку клавиатуры
2издать системный звук
S=lcase(S) Преобразует строку S в нижний регистр. S=ucase(S) Преобразует строку S в верхний регистр. S=date([format])

Возвращает текущую дату/время по формату format. Этот формат подобен тому, что выдаёт утилита date (Unix).

Функция поддерживает следующую спецификацию формата даты (подобен формату функции strftime):

Формат Описание
%% символ %
%a Краткое имя дня недели (Sun или Вск)
%A Полное имя дня недели (Sunday или Воскресенье)
%b Краткое имя месяца (Jan или Янв)
%B Полное имя месяца (January или Январь)
%c Дата и время в формате WDay Mnt Day HH:MM:SS yyyy (Mon Jan 10 04:11:54 2000 или Пнд Янв 10 04:11:54 2000)
%C Столетие как десятичное число (00-99). 1992 => 19
%d Две цифры дня месяца (01-31)
%D Синоним для %x
%e Синоним для %d, но вместо ведущего нуля будет стоять пробел.
%h Синоним для %b
%H Две цифры часа (00-23)
%I Две цифры часа (01-12)
%j Три цифры дня в году (001-366)
%k Синоним для %H, но вместо ведущего нуля будет стоять пробел.
%l Синоним для %I, но вместо ведущего нуля будет стоять пробел.
%L

Триггер, переключающий язык названий месяцев и дней недели - английский/локальный.

Far Manager запрашивает у системы 2 набора наименований:

1) английские наименования месяцев и дней недели

2) наименования, соответствующие настройкам текущего пользователя (LOCALE_USER_DEFAULT)

По умолчанию выставляются английские наименования.

%m Месяц, как десятичное число (1-12)
%m0 Подобно %m, но с ведущим нулём (01-12)
%mh Одна цифра месяца, как шестнадцатеричное число (1-C)
%M Две цифры минут (00-59)
%n

Подобно переводу строки `\\n'

Внимание! В редакторе автоотступ не работает.

%p AM или PM
%r Подобно %I:%M:%S %p
%R Подобно %H:%M
%S Две цифры секунд (00-59)
%t Подобно символу табуляции `\\t'
%T Синоним %X
%U Две цифры номера недели, где Воскресенье (Sunday) является первым днём недели (00-53)
%v Дата в формате dd-mmm-yyyy (mmm - в верхнем регистре)
%V Неделя года в соответствии с ISO 8601: Если неделя, содержащая 1 Января, имеет >= 4 дней в течение нового года, тогда это неделя 1; в противном случае это самая последняя нумерованная неделя прошлого года (52 или 53)
%w День недели где 0 - Воскресенье (Sunday) (0-6)
%W Две цифры номера недели, где Понедельник (Monday) является первым днём недели (00-53)
%x Дата в формате подобно dd<sep>mm<sep>yyyy (разделитель <sep> зависит от локальных настроек; порядок дня, месяца и года зависит от локальных настроек)
%X Время в формате HH<sep>MM<sep>SS (разделитель <sep> зависит от локальных настроек)
%y Две цифры года без столетия (00-99)
%Y Год со столетием (19yy-20yy)
%z Cмещение локального времени относительно UTC в формате ISO 8601
%Z Имя часового пояса
В функции date допускается применение следующих escape-последовательностей:
Формат Описание
\" Символ "
\' Символ '
\\ Символ '\'
\n Перевод строки `\n'
\t Символ табуляции `\t'
\a bell
\b `\b'
\f `\f'
\v `\v'
\N
\NN
\NNN
8-ричные символы из OEM кодировки
\xNN 16-ричные символы из OEM кодировки
Если аргумент format не указан, то Far Manager будет использовать форматную строку "%a %b %d %H:%M:%S %Z %Y" (см.).

Файловые функции

Функция Описание
S=fsplit(path,Flags) Разбивает путь path на компоненты и возвращает их комбинацию, в зависимости от набора флагов Flags:
ФлагиОписание
0x00000001

Текущий диск в формате "C:".

Для сетевых папок - "\\server\share"

0x00000002Путь в формате "\Program Files\Far\"
0x00000004Имя
0x00000008Расширение в формате ".EXT" или пусто, если расширения нет.
B=fexist(S)

Проверяет существование файла/папки S (возвращает 0 или 1).

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

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

N=testfolder(S)

Тестирует папку S.

Возвращает:

ЗначениеОписание
2папка не пустая
1папка пустая
0папка не существует
-1нет доступа
-2ошибка (некорректный параметр или внутренние проблемы с выделением памяти)

Если > 0 - существует и доступна

Если = 0 - не существует, но можно попробовать создать

Если < 0 - ничего обнадеживающего функция не сообщает

b=fattr(S)

Возвращает файловые атрибуты файла/папки S:

АтрибутОписание
0x00000001FILE_ATTRIBUTE_READONLY. Файл только для чтения. Приложения могут читать такой файл, но не могут записывать или удалять его.
0x00000002FILE_ATTRIBUTE_HIDDEN. Файл скрыт. Такой файл не включается в обычный листинг папки.
0x00000004FILE_ATTRIBUTE_SYSTEM. Этот файл - часть операционной системы.
0x00000010FILE_ATTRIBUTE_DIRECTORY. Это папка.
0x00000020FILE_ATTRIBUTE_ARCHIVE. Это архивный файл. Приложения должны использовать этот флаг для копирования, архивирования или удаления.
0x00000080FILE_ATTRIBUTE_NORMAL. У этого файла не установлены другие атрибуты. Это значение корректно только при использовании без остальных флагов.
0x00000100FILE_ATTRIBUTE_TEMPORARY. Это временный файл. Приложения должны записывать в такой файл только в крайней необходимости. Большая часть данных файла находится в памяти и не сбрасывается на диск, так как файл будет удалён.
0x00000200FILE_ATTRIBUTE_SPARSE_FILE. Файл является разрежённым.
0x00000400FILE_ATTRIBUTE_REPARSE_POINT. Папка является точкой повторной обработки.
0x00000800FILE_ATTRIBUTE_COMPRESSED. Файл или папка сжаты. Для файла это означает, что все данные его сжаты, для папки - что компрессия по умолчанию применяется ко всем её файлам и подпапкам.
0x00001000FILE_ATTRIBUTE_OFFLINE. Данные файла не доступны непосредственно. Означает, что реальные данные файла были физически перемещены на устройства хранения.
0x00002000FILE_ATTRIBUTE_NOT_CONTENT_INDEXED. Этот файл или папка не будут индексироваться службой индексирования.
0x00004000FILE_ATTRIBUTE_ENCRYPTED. Файл или папка зашифрованы. Для файла это означает, что все данные в файле зашифрованы. Для папки это означает, что шифрование является умолчанием для вновь созданных файлов и подпапок.
0x00010000FILE_ATTRIBUTE_VIRTUAL. Этот файл - виртуальный файл.

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

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

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

N=fmatch(S,Mask)

Тестирует строку S на соответствие маске Mask.

Mask может быть:

- маской

- списком масок (разделённых запятой или точкой с запятой)

- маской исключения - одной или несколькими масками файлов, которой не должна соответствовать строка S. Маска исключения отделяется от основной маски символом |

- регулярным выражением. Текст регулярного выражения должен быть окружён символами /

Возвращает:

ЗначениеОписание
1строка соответствует маске
0строка не соответствует маске
-1ошибка в регулярном выражении

Примеры

Вызов Результат
FMatch("Readme.txt", "*.txt")возвращает 1
FMatch("Readme.txt", "Readme.*|*.txt")возвращает 0
FMatch(@"c:\Readme.txt", @"/txt$/i")возвращает 1
FMatch(@"c:\Readme.txt", @"/txt$")возвращает -1

Взаимодействие с пользователем

Функция Описание
E=beep([N]) Воспроизвести один из системных звуковых сигналов N.
NОписание
0x00000040Звук Звёздочка
0x00000030Звук Восклицание
0x00000010Звук Критическая ошибка
0x00000020Звук Вопрос
0x0Стандартный звук
0xFFFFFFFFСтандартный звук на встроенный динамик
Функция возвращает 1 или 0 (в случае неудачи).
N=msgbox([Title[,Text[,Flags]]])

Показывает сообщение Text с заголовком Title.

В параметре Text строки разбиваются символом '\n'.

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

FlagsОписание
0x00000001Используются цвета "Предупреждения" (обычно белые буквы на красном фоне).
0x00000008Использовать для строк сообщения выравнивание влево (по умолчанию строки выводятся по центру).
0x00010000Выводится кнопка <Ok>
0x00020000Выводятся кнопки <Ok> и <Cancel>
0x00030000Выводятся кнопки <Abort>, <Retry> и <Ignore>
0x00040000Выводятся кнопки <Yes> и <No>
0x00050000Выводятся кнопки <Yes>, <No> и <Cancel>
0x00060000Выводятся кнопки <Retry> и <Cancel>

Если параметр Flags равен 0 (или не указан), то выводится стандартный диалог с кнопкой <Ok>

Функция возвращает номер выбранной кнопки (начиная с 1), или 0, если пользователь отменил сообщение

S=prompt([Title[,Prompt[,Flags[,Src[,History]]]]])

Функция позволяет ввести одну строку текста.

Параметры: Title - заголовок диалога, Prompt - приглашения для ввода, Src - начальное значение строки ввода, History - имя истории ввода.

Flags может быть набором следующих значений (аналогичных константам FIB_*):

FlagsОписание
0x00000001Даже если строка ввода пуста, функция вернёт значение (пустую строку).
0x00000002Используется для ввода пароля - вводимый текст на экране отрисовывается символами '*'.
0x00000004После успешного ввода, в результирующем значении S идентификаторы переменных окружения заменяются на их значения, например, если пользователь ввёл '%TEMP%', то результат будет содержать 'C:\TEMP'.
0x00000008Не использовать предыдущее значение из истории, оставить строку ввода пустой; актуален, если указан непустой параметр History.
0x00000010

Показать разделительную линию и кнопки [ Ok ] и [ Cancel ]. Диалог увеличится на 2 строки.

0x00000020Не показывать в приглашении ввода амперсанд, использовать его для определения горячей клавиши.

Функция возвращает строку (введённое пользователем значение) или число 0, если пользователь нажал Esc.

Например, запросить пароль и вывести его:

%s=prompt("Password","Input password:",0x02); print(%s)
E=print(Str)

Функция предназначена для вставки произвольного текста Str в редактор, командную строку, элементы ввода в диалогах, etc.

Допускается применение следующих escape-последовательностей:

ФорматОписание
\"Символ '"'
\'Символ '''
\\Символ '\'
\nПереводу строки `\n'
\tТабуляции `\t'
\abell
\b`\b'
\f`\f'
\v`\v'
\N
\NN
\NNN
8-ричный код символа
\xNN16-ричный код символа

Функция возвращает 1.

Например, создание папки с именем, равным текущей дате:

%Folder=date("%d.%m0.%Y");
$If (!panel.fexist(0,%Folder))
  F7
  print(%Folder)
  Enter
$End
V=waitkey([N[,T]])

Ожидает любую клавишу и возвращает её название (T=0) или значение (T=1).

Если время ожидания N (миллисекунды) истекло, функция возвращает пустую строку (T=0) или 0 (T=1).

Если параметр N не указан или равен 0, то функция будет бесконечно ждать нажатия клавиши.

S=key(V)

Преобразует параметр V в строковый эквивалент названия клавиши.

Если V - строка, то проверяется правильность написания клавиши и она же возвращается.

Если V - число, то происходит попытка преобразовать значение в текстовый эквивалент названия клавиши.

В случае ошибок - возвращается пустая строка.

Взаимодействие с системой

Функция Описание
S=env(Name[,Mode[,Value]])

Позволяет работать с переменной среды Name. Если Mode не указан или равен 0, то функция возвращает значение переменной среды (Value в этом случае игнорируется). Если Mode указан и отличен от 0, то функция устанавливает значение или удаляет переменную среды.

Для варианта установки/удаления функция возвращает предыдущее значение (или пустую строку, если переменная была не определена).

Напримеры.

Получить значение переменной среды Foo

Env("Foo")
Env("Foo",0)
Env("Foo",0,любое_значение)
Env("Foo",,любое_значение)

Установить значение переменной среды Foo в "bar"

Env("Foo",1,"Bar")

Удалить переменную среды Foo

Env("Foo",1)
Env("Foo",1,"")

Установить значение переменной среды Foo в "0"

Env("Foo",1,"0")
Env("Foo",1,0)

Если выбран английский язык интерфейса Far Manager, то что-то делаем

$if (Env("FARLANG") == "English") что-то делаем $end

V=clip(Cmd[,Value]) Позволяет производить разнообразные манипуляции с Clipboard в зависимости от заданного действия Action:
ActionОписание
0Возвращает данные из Clipboard; параметр Value игнорируется; в случае ошибки возвращает 0
1Поместить строку Value в Clipboard; в случае ошибки возвращает 0
2Добавить строку Value к Clipboard; в случае ошибки возвращает 0
3Копировать Windows Clipboard во внутренний буфер обмена; параметр Value игнорируется; в случае ошибки возвращает 0
4Копировать внутренний буфер обмена в Windows Clipboard; параметр Value игнорируется; в случае ошибки возвращает 0
5

Режимы работы с буфером обмена.

По умолчанию в операциях запоминания/вставки данных Far Manager работает с буфером обмена Windows.

Функция 'clip(5)' позволяет в пределах одного макроса переключать внутренние механизмы Far Manager для работы с/без использования буфера обмена Windows.

Value может быть одним из:

ValueОписание
-1Какой буфер обмена сейчас используется
0Переключить работу с буфера обмена OS на внутренний буфер и наоборот (работает как триггер).
1Включить буфер обмена OS
2Включить внутренний буфер обмена

Функция возвращает предыдущее значение: 1 - буфер обмена OS, 2 - внутренний буфер.

Пример см. в разделе Примеры.

Например, поместить в Clipboard список отмеченных файлов в формате CSV (имя и размер):
сlip(1,"Name;Size\r\n")
Home
$While(!APanel.Eof)
  $If(!APanel.Folder && panel.item(0,0,8))
     clip(2,panel.item(0,0,0)+";"+panel.item(0,0,6)+"\r\n")
  $End
  Down
$End
V=flock(Lkey,Action)

Позволяет переключить состояние Lock-клавиш (NumLock, CapsLock и ScrollLock).

Клавиша Lkey:

LkeyОписание
0NumLock
1CapsLock
2ScrollLock
Действие Action:
ActionОписание
-1получить состояние клавиши
0погасить индикатор
1включить индикатор
2переключить индикатор в противоположное состояние

Функция в младшем бите возвращает предыдущее значение выбранной клавиши (или текущее, если Action=-1).

Функция капризная (возможно зависание компьютера), поэтому пользоваться ей надо осторожно.

Например, макрос, повешенный на Ctrl+CapsLock (переключение между окнами) должен иметь некую обвязку:

CtrlShiftTab
%a=flock(1,-1)&1;
$while((flock(1,-1)&1)==%a)
  sleep(50)
  flock(1,2)
$end
N=kbdlayout([V])

Управление раскладкой клавиатуры.

Параметр V:

VОписание
0Вернуть текущее значение раскладки
1Переключиться на следующую раскладку (по кругу)
-1Переключиться на предыдущую раскладку (по кругу)
Прочие значения

Переключиться в конкретную раскладку (например, 0x0409 или 0x4090409 - английская, 0x0419 или 0x04190419 - русская)

В случае указания несуществующей раскладки функция ошибку не выдаст и просто вернёт текущую раскладку.

Функция возвращает предыдущее значение раскладки или 0 в случае ошибки (не удалось определить имя текущей раскладки для консоли или не удалось получить описатель консольного окна).

Например:

print(itoa(kbdLayout(0x421),16))
при текущей русской раскладке просто вернёт 4190419
print(itoa(kbdLayout(),16))
при текущей русской раскладке вернёт 4190419
print(itoa(kbdLayout(0x409),16))
при текущей русской раскладке вернёт 4190419 и переключит рaскладку на английскую
print(itoa(kbdLayout(1),16))
при текущей русской раскладке вернёт 4190419 и переключит на следующую рaскладку (по кругу)
N=Window.Scroll(Lines[,Axis]) Функция позволяет перемещать консольное окно по буферу.
Lines - количество позиций для прокрутки: положительное число - вперёд (вниз/вправо), отрицательное - назад (вверх/влево).
Axis - направление прокрутки (необязательный параметр): 0 - вертикаль (по умолчанию), 1 - горизонталь.
Функция возвращает 0 - перемотка не состоялась (например, Lines был равен 0), иначе 1

Среда исполнения

Функция Описание
E=sleep(N) Организация задержки в макросе на N миллисекунд. Отрицательное значение задержки считается ошибкой и функция возвращает 0.
V=Far.Cfg.Get(Key,Name)

Функция, позволяет получить основные текущие настройки Far Manager.

Состояние ошибки (нет такого Key или Name или внутренняя ошибка) можно проверить с помощью макроконстанты Far.Cfg.Err.

Например,

Far.Cfg.Get("System.KnownIDs","Network")
вернет значение "773B5051-7C5F-4920-A201-68051C4176A4", которое соответствует ID плагина Network.
Far.Cfg.Get("KeyMacros","DateFormat")
вернет значение формат преобразования даты по умолчанию для функции date.
Far.Cfg.Get("KeyMacros","TimeFormat")
вернет вернут пустую строку и выставит Far.Cfg.Err=1, т.к. значения с именем "TimeFormat" не существует.

Внимание! Внимание!

  • В процессе разработки Far Manager настройки (имена ключей и имена значений) могут меняться, добавляться и удаляться, поэтому Вы используете функцию на свой страх и риск. Поддержка функционала (имена ключей и имена значений) со стороны разработчиков не гарантирована.
E=msave(S)

Сохраняет в базу значение глобальной переменной с именем S в область Vars.

В случае неудачи возвращает 0.

Например, после выполения последовательности %%GlobalVars="Foo Bar"; %a=msave("%%GlobalVars"); в базе появится значение %%GlobalVars, содержащее "Foo Bar" (тип "TEXT").
E=mload(S)

Считать из базы значение глобальной переменной с именем S (область Vars).

Функция вернёт 1 - есть такая переменная и она успешно считана в память, 0 - неудача, нет такой переменной в базе (в этом случае переменная не создаётся). Если переменная была в памяти, а из базы запись удалили, то значение в памяти не изменяется.

Например, в базе была переменная "%%GlobalVars" со значением 20 (тип "INTEGER"). После выполения последовательности %%GlobalVars="Foo Bar"; %a=mload("%%GlobalVars"); %%GlobalVars будет равна 20.
V=akey(Mode[,Type])

Возвращает название или код клавиши, вызвавшей макропоследовательность.

Mode = 0 - возвращается код клавиши, Mode = 1 - возвращается наименование клавиши.

Type = 0 - возвращает реально нажатое сочетание, которым вызывался макрос, Type = 1 - возвращает клавишу, на которую назначен макрос.

Пример см. в описании $AKey.

E=eval(S[,Mode]) Выполнить или проверить макропоследовательность.
ModeОписание
0

Выполнить макропоследовательность, заданную строкой S.

Если S содержит синтаксические ошибки, то макропоследовательность исполняться не будет.

Far Manager компилирует последовательность S. Если нет ошибок, то состояние текущего макроса сохраняется и начинает выполняться последовательность S. После исполнения S прерванный макрос продолжает работать.

1Проверить макропоследовательность, заданную строкой S, и вернуть код ошибки компиляции. Последовательность S исполняться не будет.
2

Выполнить макрос, назначенный на сочетание клавиш S.

Параметр S задаётся форматом "[Area/]Key". Здесь "Area" - макрообласть, из которой будет исполнен макрос; "/" - разделитель; "Key" - название клавиши.

  • Если "Area/" указан, то будет вызван макрос, назначенный на "Key" только в указанной области "Area".

    Пример: eval("Shell/CtrlP",2)

  • Если в качестве "Area/" указана строка "./", то будет вызван макрос, назначенный на "Key" только в текущей области.

    Пример: eval("./CtrlP",2)

  • Если "Area/" не указан, то будет вызван макрос, назначенный на "Key" в текущей области. Если в текущей области "Key" не обнаружен, то будет выполнен макрос, назначенный на "Key" из области Common.

    Пример: eval("CtrlP",2)

Если "Key" не обнаружен, то функция вернёт целочисленное значение "-2".

Если "Key" обнаружен, то состояние текущего макроса сохраняется и начинает выполняться макрос, назначенный на сочетание клавиш S. После исполнения S прерванный макрос продолжает работать.

3Проверить макропоследовательность, заданную строкой S, и вернуть строку-сообщение с ошибкой компиляции. Последовательность S исполняться не будет.

Строка-сообщение будет пустой, если ошибок нет, или содержать 4 подстроки (разделенных символом '\n'):

  1. строка и позиция в строке (например, Line 1, Pos 1)
  2. текст сообщения об ошибке (например, Unrecognized keyword 'foo')
  3. кусок проблемной макропоследовательности (например, "foo")
  4. указатель на проблемное место - символ с кодом \x2191 ().
Для отображения строк разумнее применять msgbox с флагом 8 (выравнивание влево), например, msgbox(,eval("foo",3),8)

Для всех режимов, кроме Mode=3, функция возвращает 0 в случае успешной компиляции последовательности S или код ошибки:

ОшибкаОписание
-1Указаны недопустимые параметры функции
-2Для Mode=2 сочетание клавиш S не найдено или макрос заблокирован
1Неизвестное ключевое слово 'ключевое слово'
2Неизвестная функция 'функция'
3Неверное количество параметров у функции 'функция'
4Неожиданное появление $Else
5Неожиданное появление $End
6Неожиданный конец строки
7Ожидается 'ключевое слово'
8Неизвестный шестнадцатеричный управляющий символ
9Неправильный управляющий символ
10Переменная 'переменная' не найдена
11Ошибка синтаксиса
12Пустая макропоследовательность

Локальные переменные - общие для текущего исполняемого макроса и макропоследовательности, исполняемой функцией eval.

Пример см. в разделе Примеры.

N=mmode(Action[,Value])

Управление параметрами текущего макроса.

Параметр Action:

ActionОписание
1позволяет изменять режим перерисовки экрана во время проигрывания макропоследовательности (запрещает вывод)
2вернуть информацию (область и флаги) об условиях запуска исполняемой в данный момент макропоследовательности.

Параметр Value игнорируется.

Функция возвращает в младшем байте номер макрообласти, из которой стартовал макрос:

ValueОписание
0Other - Режим копирования текста с экрана, вертикальные меню
1Shell - Файловые панели
2Viewer - Внутренняя программа просмотра
3Editor - Редактор
4Dialog - Диалоги
5Search - Быстрый поиск в панелях
6Disks - Меню выбора дисков
7MainMenu - Основное меню
8Menu - Прочие меню
9Help - Система помощи
10Info - Информационная панель
11QView - Панель быстрого просмотра
12Tree - Панель дерева папок
13FindFolder - Поиск папок
14UserMenu - Меню пользователя
15Shell.AutoCompletion - список автодополнения в панелях
16Dialog.AutoCompletion - список автодополнения в диалогах
255Common - Общая область

Остальные значения - флаги условий запуска (в т.ч. некоторые служебные флаги).

Условия запуска:

ValueОписание
0x000000200НЕ передавать плагинам клавиши во время записи/воспроизведения макроса
0x000000800этот макрос запускается при старте ФАРа
0x000001000запускать, если командная линия пуста
0x000002000запускать, если командная линия не пуста
0x000004000запускать, если есть выделение в редакторе
0x000008000запускать, если есть нет выделения в редакторе
0x000010000панель активная: запускать, если есть выделение
0x000020000панель пассивная: запускать, если есть выделение
0x000040000панель активная: запускать, если есть нет выделения
0x000080000панель пассивная: запускать, если есть нет выделения
0x000100000панель активная: запускать, если это плагиновая панель
0x000200000панель пассивная: запускать, если это плагиновая панель
0x000400000панель активная: запускать, если это файловая панель
0x000800000панель пассивная: запускать, если это файловая панель
0x001000000панель активная: запускать, если текущий объект "файл"
0x002000000панель пассивная: запускать, если текущий объект "файл"
0x004000000панель активная: запускать, если текущий объект "папка"
0x008000000панель пассивная: запускать, если текущий объект "папка"

Дополнительная информация:

ValueОписание
0x000000100подавить обновление экрана во время выполнения макроса
0x010000000текст макроса многострочный
0x040000000этот макрос необходимо запомнить при сохранении макросов
0x080000000этот макрос отключен (помеченные этим флагом макросы не запускаются - ни с клавиатуры, ни из eval())
0x100000000разрешено исполнение макросов из плагина при вызове plugin.call

3

разрешает или запрещает исполнение макросов при вызове плагина макрофункцией plugin.call.

Например, в редакторе с помощью плагина DrawLine нарисовать небольшой прямоугольник (макропоследовательность передается плагину, который отдает её в Far Manager):

mmode(3,1)
plugin.call("C941E865-9C29-485C-99B3-0C710940F2D8",
  "ShiftRight ShiftRight ShiftDown ShiftDown ShiftLeft ShiftLeft ShiftUp ShiftUp ShiftRight Esc") 
вариант без mmode:
plugin.call("C941E865-9C29-485C-99B3-0C710940F2D8")
  ShiftRight ShiftRight ShiftDown ShiftDown ShiftLeft ShiftLeft ShiftUp ShiftUp ShiftRight Esc 

Параметр Value:

ValueОписание
-1получить текущее значение
0выключить значение Action
1включить значение Action
2переключить значение Action (триггер)
Функция возвращает предыдущее значение.
N=history.disable([State])

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

Необязательный параметр State:

БитОписание
0история командной строки
1история папок
2история редактора/вьюера
3история диалогов

Если соответствующий бит выставлен, то история блокируется.

Если параметр не указан, то просто возвращает текущую маску.

Функция возвращает предыдущее значение.

При старте макроса разрешено добавление во все истории.

Примеры

Вызов Результат
history.disable()получить текущее состояние блокировок историй
history.disable(-1)выключить все истории
history.disable(5)выключить истории командной строки и редактора/вьюера, остальные включить
N=keybar.show([Mode])

Позволяет управлять видимостью линейки функциональных клавиш.

Необязательный параметр Mode:

ModeОписание
0получить состояние видимости
1показать линейку
2скрыть линейку
3изменить состояние видимости на обратное

Функция возвращает предыдущее состояние видимости линейки:

ValueОписание
0скрыта
1показана
-1в этой макрообласти линейка клавиш не найдена
Действие функции актуально только для текущих панелей, редакторов, вьюеров.

Например, Esc при погашенных панелях гасить и кейбар:

CtrlO $if (APanel.Visible && PPanel.Visible) KeyBar.Show(1) $else KeyBar.Show(2) $end

N=plugin.call(Guid[,param])

Вызвать плагин, имеющий идентификатор Guid с параметром param.

Plugin.call вызывает экспортируемую функцию OpenW требуемого плагина.

Параметр param может быть числом или строкой и будет передан плагину в функцию OpenW как есть. Дальнейшие действия зависят от того, как плагин обработал этот параметр.
Функция возвращает 0, если вызываемого плагина нет или плагин вернул 0. В других случаях функция возвращает значение, отличное от 0.

N=plugin.config(Guid[,MenuGuid])

Аналог вызова плагина из меню "Параметры плагинов" без необходимости задавать горячие клавиши или искать плагин в списке. Работает только в панелях.

Guid и MenuGuid можно посмотреть в диалоге "Plugin information" (F3 в списке): поля "Plugin GUID" и "Plugin item GUID" соответственно.

Обязательно нужно указать Guid плагина. MenuGuid требуется указывать в том случае, если плагин экспортирует более одного пункта меню.

Если плагин отсутствует в списке "Параметры плагинов" или при вызове не из панелей - функция вернет ошибку.

Функция возвращает 1 - плагин/пункт найден или 0 - в случае ошибки.

N=plugin.exist(Guid)

Позволяет узнать наличие в системе плагина с идентификатором Guid.

Функция возвращает 1 - есть такой плагин или 0 - в случае ошибки.

N=plugin.load(DllPath[,ForceLoad])

Загрузить плагин с именем dll-модуля DllPath. Если указан ForceLoad, отличный от 0, то плагин загружается сразу в память.

Функция возвращает 1 - плагин загружен или 0 - в случае ошибки.

N=plugin.menu(Guid[,MenuGuid])

Аналог вызова плагина из меню плагинов по F11 без необходимости задавать горячие клавиши или искать плагин в списке.

Guid и MenuGuid можно посмотреть в диалоге "Plugin information" (F3 в списке): поля "Plugin GUID" и "Plugin item GUID" соответственно.

Обязательно нужно указать Guid плагина. MenuGuid требуется указывать в том случае, если плагин экспортирует более одного пункта меню.

Если плагин отсутствует в списке F11 для текущей макрообласти - функция вернет ошибку.

Функция возвращает 1 - плагин/пункт найден или 0 - в случае ошибки.

Пример использования - открыть FarColorer\Outliner list:

%I = plugin.menu("D2F36B62-A470-418D-83A3-ED7A3710E5B5","45453CAC-499D-4B37-82B8-0A77F7BD087C");
$If (%I==1) 5 $End
N=plugin.command(Guid,Command)

Аналог вызова плагина по префиксу из панелей без необходимости запоминать/очищать/восстанавливать текущее содержимое командной строки.

Guid можно посмотреть в диалоге "Plugin information" (F3 в списке F11 или AltShiftF9): поле "Plugin GUID".

Если плагин с таким Guid не поддерживает вызов по префиксу или при вызове не из панелей - функция вернет ошибку.

Функция возвращает 1 - плагин/пункт найден или 0 - в случае ошибки.

N=plugin.unload(DllPath)

Выгрузить плагин с именем dll-модуля DllPath.

Функция возвращает 1 - плагин выгружен или 0 - в случае ошибки.

V=Menu.Show(Items
[,TitleAndFooter
[,Flags
[,SelectOrFilter
[,X
[,Y]]]]])

Создаёт и отображает на экране меню.

Параметр Items: пункты меню, разделённые Lf ("\n") или CrLf ("\r\n")

Могут начинаться (возможны некоторые комбинации) со специальных символов:

Символ+пробелОписание
\1сепаратор; не участвует в автонумерации/сортировке/удалении дубликатов.
\2пункт отмечен (возможна комбинация с \3 и \4)
\3пункт недоступен для навигации и выбора
\4серый, недоступен для выбора

Необязательный параметр TitleAndFooter: заголовок и футер меню, разделённые Lf ("\n") или CrLf ("\r\n"). Один или оба могут отсутствовать.

Необязательный параметр Flags - набор битов, управляющих поведением и отображением меню:

Бит
установлен(ы)
Описание
0-2Тип рамки меню: (по умолчанию == 100)
ValueОписание
001 (0x1)без рамки
010 (0x2)одинарная, с окружающими пробелами
011 (0x3)одинарная, без окружающих пробелов
100 (0x4)двойная, с окружающими пробелами
101 (0x5)двойная, без окружающих пробелов
3 (0x8)возвращаемый результат - индекс выбранного пункта меню
4 (0x10)разрешена отметка нескольких пунктов и её снятие
5 (0x20)отсортировать (производится регистронезависимая числовая сортировка)
6 (0x40)убрать дублирующиеся пункты меню (с учетом регистра)
7 (0x80)автоматически назначить "горячие" клавиши
8 (0x100)как трактовать SelectOrFilter: (по умолчанию == 0)
ValueОписание
0позиционировать (если SelectOrFilter - число),
либо найти (если SelectOrFilter - строка) пункт меню
1установить фильтр меню
9 (0x200)автоматически пронумеровать пункты меню
10 (0x400)выйти из меню при изменении выбранного пункта

Необязательный параметр SelectOrFilter - на какой пункт меню позиционировать курсор, либо фильтрация пунктов.
Может быть:

ValueОписание
числомесли бит 8 == 0, то позиционировать на указанный пункт меню.
Если число отрицательное, то отсчёт ведётся с конца меню
строкойесли бит 8 == 0, то найти пункт меню.
Поиск регистронезависим, возможны маски
строкойесли бит 8 == 1, то установить фильтр меню

Необязательные параметры X и Y - координаты левого верхнего угла меню. Если одна (или обе) равны -1 (по умолчанию), то производится центрирование меню по этой координате.

Возвращаемый результат функции:

ТипОписание
пустая строкавыход из меню по Esc, F10 или при клике вне меню
число == 0 (если установлен бит 3)выход из меню по Esc, F10 или при клике вне меню
число > 0индекс выбранного пункта
число < 0если установлен бит 10, то индекс выбранного пункта со знаком минус
строкавыбранный пункт меню.
Если установлен бит 4, то список отмеченных пунктов меню, разделённых \n.
Если установлены и бит 3 и бит 4, то список индексов отмеченных пунктов меню, разделённых \n

В меню доступны следующие сочетания клавиш: (пометка возможна только при установленном бите 4)

СочетаниеДействие
Insпометка пункта
Ctrl-Addпометка всех видимых пунктов
Ctrl-Subtractснятие пометки со всех видимых пунктов
Ctrl-Multiplyинверсия пометки у всех видимых пунктов
Ctrl-Aподогнать меню по высоте
Пример использования - навигация по установленным закладкам редактора:
%I = 1;
%S = "";
$While (%I <= Bm.Stat(0))
  Bm.Goto(%I);
  %S = %S + Editor.Value + "\n";
  %I = %I + 1;
$End

%I = 1;
$While (%I!=0)
  %I=Menu.Show(%S, "Стековые закладки\nНавигация - Up/Down, Выход - Esc, F10", 0x600, abs(%I),80,FAR.Height-Bm.Stat(0)-5);
  $If (%I > 0)
    Bm.Goto(%I);
    $SelWord;
  $Else
    %I=0;
  $End
$End
S=macro.func(Index[,Type])

Возвращает информацию о функции с индексом Index (начинается с 1). Если Index=0, то возвращается количество зарегистрированных макрофункций (число).

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

ТипОписание
0имя функции
1синтаксис функции
2GUID плагина, предоставляющего функцию

Функция вернет пустую строку, если функция с индексом Index отсутствует.

S=macro.keyword(Index[,Type])

Возвращает ключевое слово с индексом Index (начинается с 1). Если Index=0, то возвращается количество слов (число).

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

ТипОписание
0имена ключевых слов, например, "Far.Width", "PPanel.OPIFlags" и т.п.
1имена макрообластей, например, "Shell", "MainMenu" и т.п.
2имена флагов макросов, например, "DisableOutput", "NoPluginPanels" и т.п.
3имена макрокоманд, начинающихся с символа '$', например, "$if", "$selword" и т.п.
4имена типа переменой/константы, например, "unknown","integer","text","real"

Функция вернет пустую строку, если ключевое слово с индексом Index отсутствует.

V=macro.const(Index[,Type])

Возвращает информацию о константе с индексом Index (начинается с 1). Если Index=0, то возвращается количество констант (число).

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

ТипОписание
0имя константы
1значение константы
2числовое значение типа константы
3имя типа константы

Типы и значения констант могут быть:

ЗначениеИмя
0unknown
1integer
2text
3real

Функция вернет 0, если константа с индексом Index отсутствует. В этом случае тип возвращаемого значения будет "unknown".

Тип возвращаемого значения для Type=1 зависит от типа константы.

V=macro.var(Index[,Type])

Возвращает информацию о глобальной переменной с индексом Index (начинается с 1). Если Index=0, то возвращается количество глобальной переменных (число).

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

ТипОписание
0имя переменной
1значение переменной
2числовое значение типа переменной
3имя типа переменной

Типы и значения переменных могут быть:

ЗначениеИмя
0unknown
1integer
2text
3real

Функция вернет 0, если глобальной переменная с индексом Index отсутствует. В этом случае тип возвращаемого значения будет "unknown".

Тип возвращаемого значения для Type=1 зависит от типа перменной.

Замечания

Для строковых функций: нумерация символов в строке начинается с 0 (см. index(), rindex(), substr()).

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