K-Meleon
KMeleonWiki > Documentation > EndUserDocs > MacroLanguage > MacroLanguage2
Смотрите также:
Строка, начинающаяся символом # (Есть несколько названий данного символа: шарп, хэш, октоторп. - прим.Alex.Tarantul), является комментарием и при обработке игнорируется.
Переменные не объявляются явно, но имя переменной обязательно должно начинаться с $ (символ доллара). Переменная может быть как глобальной, то есть доступной из любого макроса, так и локальной, то есть используемой в конкретном макросе. Перед использованием переменной в выражении необходимо присвоить ей значение. В переменных могут использоваться только строковые и целочисленные значения.
$x = 0; $y = "Пример текстовой строки";
Описание макроса состоит из имени макроса, за которым следует совокупность утверждений исполняемых для данного макроса, заключённых в фигурные скобки. Дополнительно может указываться текстовая строка, содержащая значение параметра 'menu', для указания текста, который отображается, если макрос используется в меню браузера.
example { menu = "Текст пункта меню"; $x = 0; }
Для составления выражений доступны следующие операторы:
Оператор | Значение | Пример утверждения | Целочисленный результат |
= | Назначение | $x = 7; | $x = 7 |
. | Конкатенация строк | $x = 7 . 3; | $x = 73 |
+ | Сложение целых чисел | $x = 7 + 3; | $x = 10 |
- | Вычитание целых чисел | $x = 7 - 3; | $x = 4 |
* | Умножение целых чисел | $x = 7 * 3; | $x = 21 |
/ | Деление целых чисел | $x = 7 / 3; | $x = 2 |
% | Целочисленный остаток | $x = 7 % 3; | $x = 1 |
== | Равнество | $x = 7 == 3; | $x = 0 |
!= | Неравенство | $x = 7 != 3; | $x = 1 |
<, <=, >, >= | Сравнение строк | $x = 10 < 2 | $x = 1 |
<, <=, >, >= | Сравнение целых чисел | $x = +10 > +2 | $x = 1 |
? : | Условное выражение | $x = $y==1 ? 2:3; | $x = 2 если y равно 1, в противном случае $x = 3 |
Для изменения порядка вычисления используются скобки. По умолчанию сложение и вычитание имеют больший приоритет, чем операции умножения, деления и вычисления целочисленного остатка.
При необходимости переменная автоматически конвертируется из строковой в целочисленную или наоборот.
$x = 1 + "2"; $x = 3 $y = "Значение x составляет " . x; $y = "Значение x составляет 3"
Строки должны быть заключены в двойные кавычки, но если строка не содержит операторов, то двойные кавычки не требуются. Кроме того, нужно учитывать, что специальные символы требуют использования бэкслеша:
\\ | бэкслеш (\) |
\n | символ новой строки |
\t | символ табуляции |
\" | символ цитирования (") |
Строковые значение "true" и "false" распознаются как логические значения и могут использоваться вместо условного выражения.
$z = "false"; $z ? $x = 1 : $x = 0; $x = 0 $z = "true"; $z ? $x = 1 : $x = 0; $x = 1
TСуществуют предопределённые глобальные переменные, позволяющие макросам K-Meleon получать доступ к некоторой глобальной информации состояния.
Переменная | Тип | Значение | Версия | !Только чтение |
$ARG | Строка | Аргумент, передаваемый от вызывающего плагина (не от вызывающего макроса). | 0.9 | Да |
$CHARSET | Строка | Кодировка текущей страницы. | 1.0 | Нет |
$CommandLine | Строка | Командная строка запуска K-Meleon. | 1.5.2 | Да |
$FrameURL | Строка | URL текущего фрейма. | 0.8.2 | Да |
$ImageURL | Строка | URL текущего изображения. | 0.8 | Да |
$LinkURL | Строка | URL текущей ссылки. | 0.8 | Да |
$macroModules | Строка | Список всех активных kmm модулей, разделяемый точкой с запятой. | ? | Нет |
$SelectedText | Строка | Выделенный текст на текущей странице. | 1.0 | Да |
$TabNumber | Целое | Количество вкладок в текущем окне. | 1.5 | Да |
$TextZoom | Целое | Коэффициент масштабирования текста текущей страницы. | 1.0. | Нет |
$TITLE | Строка | Заголовок текущей страницы. | 0.9 | Нет |
$URL | Строка | URL текущей страницы. | 0.7 | Да |
$URLBAR | Строка | Содержимое адресной строки. | 1.0 | Нет |
Специальные глобальные переменные чувствительны к регистру символов.
Клавиатурные сокращения K-Meleon, его система меню и плагинов (но не сам плагин макросов – файл macros.dll) могут вызывать макрос с аргументом:
setmenu($__m,macro,"&Toolbars","cfg_Skin(toolbars)");
Макрос, вызываемый таким образом, может получить аргумент, прочитав переменную $ARG:
cfg_Skin{ ==macroinfo=_("Правка файла конфигурации темы оформления");== $ext="cfg"; &getExtensionHandler; $cfg_File=$ARG.".".$ext; . . }
Не рекомендуется чтение $ARG after после открытия одного из модальных окон (т.к. существует баг). Присвоение значения переменной $ARG локальной переменной осуществляется так, как было показано в примере.
Плагин Macro Extension поддерживает обработку многих событий.
Событие | Момент срабатывания |
OnActivateWindow | Когда окно оказывается в фокусе. |
OnCloseGroup | При закрытии окна с несколькими вкладками. |
OnCloseTab | При закрытии вкладки. |
OnCloseWindow | При закрытии окна/слоя. |
OnInit | При анализе файлов конфигурации по умолчанию. |
OnLoad | При завершении загрузки (не закачки!) документа. |
OnOpenTab | При открытии вкладки. |
OnOpenWindow | При открытии окна/слоя. |
OnQuit | При завершении работы macro plugin (браузера). |
OnSetup | При анализе файлов конфигурации пользователя. |
OnStartup | При открытии первого окна. |
OnWMAppExit | При вызове команды ID_APP_EXIT для завершения работы. |
myMacro{ # Ваш On<event> код } $On<event>=$On<event>."myMacro;";
Startup всегда сопровождается Load или OpenWindow OpenWindow всегда сопровождается Load. Init, Setup и Quit выполняются лишь один раз за сессию.(1) ActivateWindow обычно выполняется множество раз, - когда окно браузера получает фокус Обработка событий при запуске браузера (в порядке приоритета) Init Setup Startup(1)
Обработка событий при закрытии браузера (в порядке приоритета) CloseGroup или WMAppExit(1) CloseWindow(2) Quit
Утверждения должны завершаться точкой с запятой. Начиная с версии 1.5, утверждения не должны занимать несколько строк! Строки никогда не должны занимать несколько линий.
# ЭТО ПРИМЕР НЕПРАВИЛЬНОГО КОДА $error = 1 + 1;
Несколько утверждений могут быть записаны в одну строку, разделяемые точкой с запятой.
$x = 0; $y = "Здесь нужен умный текст";
Версия браузера 1.5 имеет новый синтаксический анализатор макросов. Это мощный инструмент, сообщающий обо всех ошибках, которые не обнаруживались в предыдущих версиях (особенно это касается «потерянных» точек с запятой и некорректно написанных строк). В настоящее время макросы пишутся в кодировке UTF-8.
Оператор условного утверждения (? :) может использоваться для выполнения единичного утверждения, в зависимости от определённого условия.
Полное утверждение "Если ... То ... Иначе ..." выглядит так:
CONDITION ? STATEMENT_CONDITION_TRUE : STATEMENT_CONDITION_FALSE;
Простое утверждение "Если ... То ..." выглядит так:
CONDITION ? STATEMENT_CONDITION_TRUE : 0;
В вышеприведённом примере при ложности условного утверждения ничего не выполняется (0 = ноль).
Для выполнения множественных утверждений в зависимости от определённого условия, они должны быть записаны во вспомогательном макросе:
CONDITION ? &ConditionTrue : &ConditionFalse; ConditionTrue { ... } ConditionFalse { ... }
if (condition) { statement1; [statement2; [...]] } else { statementA; [statementB; [...]] }
Если логическое утверждение в круглых скобках истинно, выполняются утверждения в блоке if. В противном случае выполняются утверждения в блоке else. Блок else необязателен. Если в каком-либо блоке содержится лишь одно утверждение, фигурные скобки могут быть опущены.
Примеры: if (condition) statement; if (condition) { statement1; statement2; } else { statement3; statement4; } if (condition) statement1; else statement2; statement3;
В последнем примере statement3 может выполняться независимо от значения условия, если if-else утверждение завершено после statement2. Если statement3 относится к блоку else block, statement2 и statement3 должны быть заключены в фигурные скобки.
forcecharset( [charset] ); Начиная с версии 0.9
Установление (определение) кодировки документа в текущем окне. Демонстрацию использования смотри в файле encoding.kmm.
Параметр | Обязателен | Тип | Возможные значения | Примечание |
charset | Нет(1) | Строка | Кодировка | Название требуемой кодировки. |
(1) Если параметр опущен, включается автоматическое определение кодировки. Используемый метод определяется значением ключа настройки intl.charset.detector.
injectCSS( CSS ); Начиная с версии 1.0
Внедряет код Cascading Style Sheet в текущую страницу.
Данный метод наилучшим образом используется совместно с методом readfile(). Учтите, что данный метод предназначен для выполнения CSS кода только по запросу приложения, не используйте его в зависимости от условных событий. Для постоянного применения Ваших собственных стилей к просматриваемому документу используйте файл userContent.css.
Параметр | Обязателен | Тип | Возможные значения | Примечание |
CSS | Да | Строка | CSS код | Внедряемый CSS код. |
injectJS( JS ); Начиная с версии 1.0
Внедряет код JavaScript в текущую страницу.
injectJS( JS [, location ]); Начиная с версии 1.5
Внедряет код JavaScript в текущий документ, в текущий фрейм или во все вкладки в текущем окне.
Данный метод наилучшим образом используется совместно с методом readfile().Учтите, что данный метод предназначен для выполнения JavaScript кода только по запросу приложения, поэтому избегайте его использования в зависимости от условных событий, чтобы не нарушать стабильность и работоспособность K-Meleon.
Параметр | Обязателен | Тип | Возможные значения | Примечание |
JS | Да | Строка | JS код | Внедряемый JavaScript код. |
location | Нет(1) | Предопределённый | alltabs(2) | Адрес всех вкладок в текущем окне. |
frame | Адрес только текущего фрейма. |
(1) Если параметр опущен, указанный код внедряется в текущий документ, который может содержать несколько фреймов. Такие фреймы будут обрабатываться внедряемым кодом самостоятельно. То же самое будет происходить и при внедрении кода во все вкладки.
(2) Для версии 1.5
open( URL ); Начиная с версии 0.4
Открывает URL в текущем окне браузера.
opennew( URL ); Начиная с версии 0.4
Открывает URL в новом окне браузера.
openbg( URL ); Начиная с версии 0.4
Открывает URL в новом фоновом окне.
opentab( URL ); Начиная с версии 1.5
Открывает указанный URL в новой вкладке. Эта новая вкладка получает фокус.
openbgtab( URL ); Начиная с версии 1.5
Открывает указанный URL в новой вкладке. Эта новая вкладка открывается в фоне (текущая вкладка сохраняет фокус).
$I = index( s, t ); Начиная с версии 0.7
Возвращает index строки t в строке s, или -1, если t отсутствует.
$LEN = length( s ); Начиная с версии 0.7
Возвращает длину строки s.
$SUB = substr( s, i [, n] ); Начиная с версии 0.7
Возвращает не более n-символа подстроки s, начиная с i. Если n опущено, используется s полностью.
$TRANSLATION = _( TEXT ); Начиная с версии 1.0
Замещает TEXT определённым переводом, если он указан.
$SUB = gensub( r, s, h, t ); Начиная с версии 0.7
Ищет в целевой строке t совпадения со строкой r. Если строка h начинается символом g или G, все совпадения r заменяются на s. Иначе h будет числом, показывающим, какое совпадение r нужно замещать. Возвращается изменённая строка.
$SUB = gsub( r, s, t ); Начиная с версии 0.7
Замещает строку s для каждого совпадения подстроки со строкой r в строке t и возвращает изменённую строку. Это эквивалентно gensub( r, s, "G", t).
$SUB = sub( r, s, t ); Начиная с версии 0.7
Сходно с gsub(), но замещается только первое совпадение подстроки. Это эквивалентно gensub( r, s, 1, t).
$BASE = basename( URL [, SUFFIX] ); Начиная с версии 0.7
Возвращает URL без предшествующих каталогов. Если указано, удаляется также и завершающий SUFFIX.
$DIR = dirname( URL ); Начиная с версии 0.7
Возвращает URL без конечного символа /. Если URL не содержит символа '/', на выходе возвращается '.' (это обозначает текущую директорию).
$HOST = hostname( URL ); Начиная с версии 0.7
Возвращает имя хоста заданного URL.
$VALID_URL = urlencode( TEXT ); Начиная с версии 1.0
Кодирует TEXT для использования в качестве URL.
$TEXT = urldecode( VALID_URL ); Начиная с версии 1.5
Декодирует закодированный URL.
while( CONDITION ) STATEMENT ; Начиная с версии 1.0
Выполняет единичное STATEMENT в случае истинности CONDITION. Для выполнения нескольких утверждений, они должны быть заключены во вспомогательный макрос:
while( CONDITION ) &Loop;
Loop { ... }
while( CONDITION ) { STATEMENT1 ; [STATEMENT2 ; [ ... ]] } Начиная с версии 1.5
Синтаксис был расширен для поддержки выполнения множественных утверждений.
while ( CONDITION ) { STATEMENT1 ; STATEMENT2 ; }
alert( MESSAGE [, TITLE [, ICON]] ); Начиная с версии 0.8
Показывает диалоговое окно.
ICON = EXCLAIM | INFO | STOP | QUESTION
$RESULT = confirm( MESSAGE [, TITLE [, BUTTONS [, ICON]]] ); Начиная с версии 0.9
Показывает диалоговое окно и запрашивает подтверждение.
BUTTONS = RETRYCANCEL | YESNO | YESNOCANCEL | ABORTRETRYIGNORE
ICON = EXCLAIM | INFO | STOP | QUESTION
RESULT = OK | YES | NO |ABORT | RETRY | IGNORE | 0
$VALUE = prompt( MESSAGE [, TITLE [, DEFAULT]] ); Начиная с версии 0.7
Показывает модальное 'подтверждающее' окно и возвращает строковое значение.
Параметр | Обязателен | Тип | Возможные значения | Примечание |
message | Да | Строка | Сообщение(1) | Текст, отображаемый в диалоговом окне. |
title | Нет | Строка | Заголовок(2) | Текст, отображаемый в заголовке диалогового окна. |
default | Нет(3) | Строка | Заданное | Текст, отображаемый в поле ввода диалогового окна. |
(1) Здесь сообщение НЕ может занимать несколько строк!
(2) Заголовок Не может занимать несколько строк.
(3) Если параметр <default> указан, то и параметр <title> тоже должен быть указан.
setaccel( keys [,command]); Начиная с версии 1.1
Этот метод может использоваться для задания клавиатурных сокращений вместо прямого редактирования файла accel.cfg.
Параметр | Обязателен | Тип | Возможные значения | Примечание |
keys | Да | Строка | Комбинация клавиш(1) | Назначаемая комбинация клавиш. |
command | Да | Строка | Команда(2) | Команда, ассоциируемая с комбинацией клавиш. |
(1) Список предопределённых названий клавиш, разделяемых пробелом.
(2) Команда может быть "ID_..." или "pluginName(pluginCommand)". Если указана пустая строка, это будет обработано как удаление команды.
setcheck( COMMAND, STATE ); Начиная с версии 0.9
Параметр | Обязателен | Тип | Возможные значения | Примечание |
COMMAND | Да | Строка | Команда | Команда, ассоциируемая с пунктом меню. |
STATE | Да | Логическое | Логическое выражение | Состояние 'галочки' (true=видимое, false=скрытое). |
Этот метод используется, чтобы установить галочку для представления команды меню. Используйте the menuchecked statement для обработки галочки пунктов меню, представляющих макросы.
setmenu( MENU_NAME, ITEM_TYPE [, LABEL [, COMMAND]] [, WHERE]); Начиная с версии 1.1
Параметр | Тип | Примечание |
MENU_NAME | Строка | Определяет название меню (обязательно). |
ITEM_TYPE | Предопределённый | Определяет тип пункта меню (обязательно).. Может быть одним из видов строк: inline, popup, command, macro, separator. |
LABEL (1) | Строка | Определяет название конкретного пункта в меню. |
COMMAND (2) | Строка | Определяет команду, ассоциируемую с пунктом меню. |
WHERE (3) | Строка или целое Строка -1 n=0,1,2,... |
Определяет место, в которое помещается пункт меню. Перед пунктом, указанным с помощью label или command В конце указанного меню В позицию n указанного меню (1-я позиция: 0, т.е. отсчёт от нуля!) |
(1) LABEL должен быть указан для всех типов пунктов, кроме "separator". Если LABEL указан как пустая строка, это обрабатывается как удаление.
(2) COMMAND должен быть указан для пунктов типа "command" и "macro". Если COMMAND указан как пустая строка и LABEL отсутствует, это обрабатывается как удаление.
(3) WHERE может быть опущено для всех типов пунктов, кроме "separator" (-1 это значение по умолчанию).
menuchecked = логическое выражение ; Начиная с версии 1.1
Это утверждение используется в макросе для установки 'галочки' для представления меню данного макроса. Состояние 'галочки' динамически обновляется в соответствии со значением логического выражения. Последнее выполняется всякий раз, когда пункт меню, представляющий данный макрос, становится видимым. Используйте это выражение в первых строчках макроса.
Учтите, что к локальным переменным это не имеет никакого отношения, т.к. здесь могут быть использованы лишь глобальные переменные.
menugrayed = логическое выражение ; Начиная с версии 1.1
Это утверждение используется в макросе для включения и отключения («серый» пункт меню) представления меню данного макроса. Состояние включено/отключено динамически обновляется в соответствии со значением логического выражения. Последнее выполняется всякий раз, когда пункт меню, представляющий данный макрос, становится видимым. Используйте это выражение в первых строчках макроса.
Учтите, что к локальным переменным это не имеет никакого отношения, т.к. здесь могут быть использованы лишь глобальные переменные.
rebuildmenu (menuName); Начиная с версии 1.1
Этот метод используется для восстановления меню, созданного утверждением setmenu(). Учтите, что меню должно быть восстановлено с помощью rebuildmenu() внутри того же самого макроса, где оно было создано с помощью setmenu(). Утверждение rebuildmenu() имеет эффект только тогда, когда основной макрос прямо или косвенно вызывается через меню. Для демонстрации использования смотрите proxy.kmm.
Параметр | Обязателен | Тип | Возможные значения | Примечание |
menuName | Да | Строка | Название меню | Это название восстанавливаемого меню. |
macroinfo = строка ; Начиная с версии 1.5
Отображает текст в строке состояния при наведении курсора мышью на пункт меню, вызывающий макрос. Используйте это выражение в первых строчках макроса.
exec( COMMAND_LINE ); Начиная с версии 0.6
Запускает внешнее приложение (любой исполняемый файл).
$VALUE = iniread( SECTION, KEY, VALUE, PATH ); Начиная с версии 1.5.3 Начиная с версии 0.6
Возвращает значение указанной клавиши в определённой секции ini-файла, путь к которому указан.
iniwrite( SECTION, KEY, VALUE, PATH ); Начиная с версии 1.5.3
Записывает ключ и его значение в секции ini-файла, путь к которому указан. Если ключ, секция или файл не существуют, они создаются. Если ключ существует, его значение перезаписывается. Формат ini-файла таков:
[SECTION] KEY=VALUE
$PATH = promptforfile( INITIAL_FOLDER, FILE_TYPE_DESCRIPTION, FILE_EXTENSION_PATTERN ); Начиная с версии 1.0
Пользователю предлагается указать файл. Отображаются лишь файлы, соответствующие шаблону.
$PATH = promptforfolder( CAPTION [, INITIAL_FOLDER] ); Начиная с версии 1.0
Пользователю предлагается указать папку.
$CONTENT = readfile( PATH ); Начиная с версии 1.0
Возвращает содержимое указанного файла (максимальный размер файла - 32 Кб). Только для небольших текстовых файлов.
$VALUE = readreg( ROOT, PATH ); Начиная с версии 1.0
Возвращает значение указанного ключа реестра.
ROOT = HKLM | HKCU | HKCC | HKCR | HKU
$PATH = getfolder( FOLDER_TYPE ); Начиная с версии 1.1
Возвращает путь к указанной папке.
FOLDER_TYPE = RootFolder | SettingsFolder | ProfileFolder | ResFolder | SkinFolder | MacroFolder | UserMacroFolder
id( COMMAND_ID ); Начиная с версии 0.7
Посылает message ID в текущее окно. Смотрите полный список command IDs.
macros( MACRO1 ); Начиная с версии 0.7 Выполняет другой макрос. &MACRO; Эквивалентно macros( MACRO ). macros( MACRO1 [,MACRO2 [,MACRO3 [...]]] ); Начиная с версии 1.1 Расширенная обработка множественных макросов в версии 1.1
delpref( prefName ); Начиная с версии 0.9
Удаляет установленное пользователем значение любой настройки. Восстанавливается значение настройки, имевшееся по умолчанию, если оно было. В противном случае настройка удаляется.
$VALUE = getpref( TYPE, "user.preference.variable" ); Начиная с версии 0.7
Чтение пользовательской настройки.
TYPE = BOOL | INT | STRING
setpref( TYPE, "user.preference.variable", VALUE ); Начиная с версии 0.6
Установка пользовательской настройки.
TYPE = BOOL | INT | STRING
togglepref( TYPE, "user.preference.variable"[, VALUE1, VALUE2, ... ]); Начиная с версии 0.6
Переключение между различными возможными значениями пользовательской настройки (логические переключаются между true и false).
TYPE = BOOL | INT | STRING
plugin( PLUGIN, COMMAND ); Начиная с версии 0.7
pluginmsg( PLUGIN, COMMAND, ARGS ); Начиная с версии 0.7
$REPLY = pluginmsgex( PLUGIN, COMMAND, ARGS, TYPE ); Начиная с версии 0.7
Запуск команды плагина. Возможные значения COMMAND, ARGS и TYPE зависят от специфики конкретного плагина. Смотрите полный список plugin commands.
$TEXT = getclipboard(); Начиная с версии 0.7
Чтение данных из буфера обмена.
setclipboard( TEXT ); Начиная с версии 0.7
Запись данных в буфер обмена.
statusbar( TEXT ); Начиная с версии 0.7
Отображает текстовое сообщение в строке состояния.
* $ARG * $CHARSET * $FrameURL * $ImageURL * $LinkURL * $SelectedText * $TextZoom * $TITLE * $URL * $URLBAR * _() * alert() * basename() * confirm() * delpref() * dirname() * exec() * forcecharset() * gensub() * getclipboard() * getfolder() * getpref() * gsub() * hostname() * id() * if() * index() * iniread() * iniwrite() * injectCSS() * injectJS() * length() * macroinfo * macros() * menuchecked * menugrayed * OnActivateWindow * OnCloseGroup * OnCloseTab * OnCloseWindow * OnInit * OnLoad * OnOpenTab * OnOpenWindow * OnQuit * OnSetup * OnStartup * OnWMAppExit * open() * openbg() * openbgtab() * opennew() * opentab() * plugin() * pluginmsg() * pluginmsgex() * prompt() * promptforfile() * promptforfolder() * readfile() * readreg() * rebuildmenu() * setaccel() * setcheck() * setclipboard() * setmenu() * setpref() * statusbar() * sub() * substr() * togglepref() * urldecode() * urlencode() * while()