-
Notifications
You must be signed in to change notification settings - Fork 1
Expand file tree
/
Copy pathplugins.text
More file actions
148 lines (105 loc) · 8.64 KB
/
plugins.text
File metadata and controls
148 lines (105 loc) · 8.64 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
Взаимодействие с плагинами
==========================
:::functions
`...=Plugin.Call(PluginId,...)`
: Вызвать плагин, имеющий идентификатор `PluginId` с параметрами `...`.
Параметры:
`PluginId`
: `string` (GUID плагина в текстовом представлении)
`...`
: ноль или более дополнительных параметров
Параметры передаются плагину [в соответствии][FARMACROVARTYPE] с их Lua-типами:
- `nil` -> `FMVT_NIL`
- `boolean` -> `FMVT_BOOLEAN`
- `number` -> `FMVT_DOUBLE`
- `int64` -> `FMVT_INTEGER` (`int64` - тип `userdata`, создаваемый библиотекой `bit64`)
- `string` -> `FMVT_STRING` (автоматически преобразуется из `UTF-8` в `UTF-16LE`)
- `{string}` -> `FMVT_BINARY` (для того, чтобы передать произвольный стринг без
преобразования `UTF-8` -> `UTF16LE`, его нужно передавать,
помещённым в таблицу как элемент с ключом `1`)
Возвращает:
`...`
: ноль или более возвращаемых значений
Величины, возвращаемые плагином через структуру [`FarMacroCall`][FarMacroCall],
[передаются][FARMACROVARTYPE] макросу следующим образом:
- `FMVT_NIL` -> `nil`
- `FMVT_BOOLEAN` -> `boolean`
- `FMVT_DOUBLE` -> `number`
- `FMVT_INTEGER` -> `number`, если "укладывается" в 53 бита, иначе `int64`
- `FMVT_STRING` -> `string` (автоматически преобразуется из `UTF-16LE` в `UTF-8`)
- `FMVT_BINARY` -> `table` (в таблице передаётся строка как элемент с ключом `1`;
передаётся как есть, без преобразования)
- `FMVT_POINTER` -> `light userdata`
- `FMVT_ARRAY` -> `table`: массив элементов; в таблице установлено два поля:
+ `["type"]` = `"array"`, и
+ `["n"]` = количество элементов массива
`Plugin.Call` вызывает экспортируемую функцию [`OpenW`][OpenW] требуемого плагина,
передавая указанные параметры.
Дальнейшие действия зависят от того, как плагин обработал этот параметр.
Функция возвращает `false`, если вызываемого плагина нет.
В других случаях функция возвращает значения, полученные от плагина.
1. Функция осуществляет "асинхронный" вызов плагина.
Если вызов в действительности оказался асинхронным (например, если плагин вывел
диалог на экран), функция возвращает true, не дожидаясь возврата от плагина,
и макрос продолжает исполнение.
2. Если вызов в действительности оказался синхронным, макросу возвращаются величины
в соответствии с тем, что вернул плагин:
- Если плагин не найден или вернул `0`, макросу возвращается `false`.
- Если плагин вернул `1` или `INVALID_HANDLE_VALUE`, макросу возвращается `true`.
- Если плагин вернул указатель на структуру [`FarMacroCall`][FarMacroCall],
см. выше.
`...=Plugin.SyncCall(PluginId,...)`
: Синхронный вызов плагина
Данная функция работает идентично `Plugin.Call`, за исключением того, что:
1. Её вызов - всегда синхронный, то есть возврат управления макросу происходит
только после возврата функции [`OpenW`][OpenW] плагина.
2. Данная функция не имеет [ограничений][async_limits] в использовании,
которые есть у `Plugin.Call`.
`N=Plugin.Command(Guid,Command)`
: Аналог вызова плагина по префиксу из панелей без необходимости
запоминать/очищать/восстанавливать текущее содержимое командной строки.
`Guid` можно посмотреть в диалоге *"Plugin information"* (~F3~ в списке ~F11~ или ~Alt+Shift+F9~):
поле "Plugin GUID".
Если плагин с таким `Guid` не поддерживает вызов по префиксу или при вызове не из панелей - функция вернёт ошибку.
Функция возвращает `true` - плагин/пункт найден или `false` - в случае ошибки.
`N=Plugin.Config(Guid[,MenuGuid])`
: Аналог вызова плагина из меню "Параметры плагинов" без необходимости задавать горячие клавиши
или искать плагин в списке.
Работает только в панелях.
`Guid` и `MenuGuid` можно посмотреть в диалоге *"Plugin information"* (~F3~ в списке):
поля *"Plugin GUID"* и *"Plugin item GUID"* соответственно.
Обязательно нужно указать `Guid` плагина.
`MenuGuid` требуется указывать в том случае, если плагин экспортирует более одного пункта меню.
Если плагин отсутствует в списке *"Параметры плагинов"* или при вызове не из панелей - функция вернёт ошибку.
Функция возвращает `true` - плагин/пункт найден или `false` - в случае ошибки.
`N=Plugin.Exist(Guid)`
: Позволяет узнать наличие в системе плагина с идентификатором `Guid`.
Функция возвращает `true` - плагин/пункт найден или `false` - в случае ошибки.
`N=Plugin.Menu(Guid[,MenuGuid])`
: Аналог вызова плагина из меню плагинов по ~F11~ без необходимости задавать горячие клавиши
или искать плагин в списке.
`Guid` и `MenuGuid` можно посмотреть в диалоге *"Plugin information"* (~F3~ в списке):
поля *"Plugin GUID"* и *"Plugin item GUID"* соответственно.
Обязательно нужно указать `Guid` плагина.
`MenuGuid` требуется указывать в том случае, если плагин экспортирует более одного пункта меню.
Если плагин отсутствует в списке ~F11~ для текущей макрообласти - функция вернёт ошибку.
Функция возвращает `true` - плагин/пункт найден или `false` - в случае ошибки.
Пример использования - открыть *FarColorer\\Outliner list*:
~~~lua
local ColorerID = "D2F36B62-A470-418D-83A3-ED7A3710E5B5"
local ColorerMenuID = "45453CAC-499D-4B37-82B8-0A77F7BD087C"
if Plugin.Menu(ColorerID,ColorerMenuID) then
Keys("5")
end
~~~
`N=Plugin.Load(DllPath[,ForceLoad])`
: Загрузить плагин с именем dll-модуля `DllPath`.
Если указан `ForceLoad` (число, отличное от 0), то плагин загружается сразу в память.
Функция возвращает число, отличное от 0 - плагин загружен или `0` - в случае ошибки.
`N=Plugin.Unload(DllPath)`
: Выгрузить плагин с именем dll-модуля `DllPath`.
Функция возвращает `1` - плагин выгружен или `0` - в случае ошибки.
:::
[OpenW]: https://api.farmanager.com/ru/exported_functions/openw.html
[FarMacroCall]: https://api.farmanager.com/ru/structures/farmacrocall.html
[FARMACROVARTYPE]: https://api.farmanager.com/ru/structures/farmacrovalue.html#FARMACROVARTYPE