Статьи

Редактирование плагинов

Простой плагин
Давайте начнём простой плагин. Вы должны иметь немного основных навыков программирования (например, на BASIC или C), чтобы быть знакомыми с переменными, циклами и т.д.
• Запустите Sibelius.
• В меню Plug-ins выберите Edit Plug-ins, затем нажмите кнопку New.
• Вас попросят ввести внутреннее имя плагина (используемое как имя файла плагина), имя, которое будет отображаться в меню и название категории, в которой ваш плагин появится в меню.
Причина использования двух разных имён в том, что имя файла длиннее 31 символа не может использоваться на Mac’ах под управлением классической Mac OS, а имя в меню может быть настолько длинным, насколько вы захотите.
• Введите Test в качестве внутреннего имени, Test plug-in в качестве имени в меню и название категории Tests, затем нажмите OK.
• Вы увидите, что Test добавлен в список диалога Edit Plug-ins. Нажмите Close.
• Если Вы снова посмотрите меню Plug-ins, то Вы увидите подменю Tests, из которого выпадает Test plug-in.
• Нажмите Test plug-in, и плагин запустится. Что он делает? Пока только появляется диалоговое окно с надписью Test (каждый раз, когда Вы начинаете новый плагин, Sibelius заполняет первую строку программы инструкцией, которая делает это).
• Нажмите OK в диалоговом окне, и плагин остановится.

Три типа данных
Давайте посмотрим, что сейчас находится в плагине. Выберите снова Plug-ins > Edit Plug-ins, затем в диалоговом окне выделите Test и нажмите кнопку Edit (также можно дважды щёлкнуть Test, чтобы начать его редактирование). Вы увидите диалог, показывающий три типа данных, из которых может состоять плагин:
• Методы: подобно функциям и процедурам в других языках.
• Диалоги: любые диалоговые окна, которые Вы проектируете для своего плагина.
• Данные: переменные, которые сохраняют своё значение между запусками плагина. Они подобны глобальным переменным таких языков, как C, но больше похожи на данные-члены в C++ и Java или свойства в Visual BASIC.

Методы
Фактически программа состоит из методов. Как Вы можете увидеть, плагин имеет по крайней мере два метода, которые создаются автоматически при создании нового плагины:
• Initialize: этот метод автоматически вызывается, когда Вы запускаете Sibelius. Обычно он только добавляет имя плагина в меню Plug-ins, хотя, если посмотреть некоторые плагины, Вы увидите, что его иногда используют для установки переменным значения по умолчанию.
• Run: вызывается при запуске плагина (подобен функции main() в C/C++ и Java). Другими словами, когда Вы нажмёте Test plug-in в меню Plug-ins, вызовется его метод Run. Если Вы напишете другие методы, то должны будете их вызывать из метода Run – иначе, как они смогут что-либо сделать?
Выделите Run и нажмите Edit (двойной щелчок по Run делает то же самое). Появится диалог, в котором Вы сможете редактировать метод Run. В верхнем поле Вы можете изменить имя, в следующем параметры (т.е. переменные, в которых хранятся значения, передаваемые методу); ниже следует сам код:
Sibelius.MessageBox("Test1");
Здесь вызывается метод MessageBox, который показывает диалоговое окно с надписью Test1 при запуске плагина. Обратите внимание, что имя метода сопровождается списком параметров в круглых скобках (в данном случае только один параметр): т.к. это строка (т.е. текст) он заключён в двойные кавычки. Заметьте также, что оператор заканчивается точкой с запятой, как в C/C++ и Java. Если Вы её пропустите, произойдёт ошибка при запуске плагина.
Какова роль слова Sibelius в Sibelius.MessageBox? Фактически, это переменная, представляющая программу Sibelius; оператор говорит Sibelius показать диалоговое окно (C++ и Java программисты признают в этой переменной ссылку на ‘объект’). Если сложно, мы вернёмся к этому позже.

Редактирование кода
Теперь попробуйте немного исправить код. Вы можете изменять код точно так же, как в текстовом процессоре, используя мышь и клавиши со стрелками; Вы также можете использовать комбинации Ctrl+X/C/V или XX/C/V, чтобы вырезать, копировать и вставлять соответственно. При щелчке правой кнопкой мыши (Windows) или Control+щелчок (Mac) появится меню с основными командами редактирования.
Измените код на следующий:
x = 1;
x = x + 1;
Sibelius.MessageBox("1 + 1 = " & x);

Проверить правильность кода можно, нажав кнопку Check syntax. Если имеются явные ошибки (например, пропущена точка с запятой), вам сообщат - где.
Закройте диалоги, нажав OK, OK снова и затем Close. Запустите ваш исправленный плагин из меню Plug-ins, и появится диалоговое окно с надписью "1 + 1 = 2".
Как это работает? Смысл первых двух операторов должен быть очевиден. В последнем операторе используется &, чтобы соединить две строки вместе. Нельзя использовать +, т.к. он работает только с цифрами (если использовать его в этом примере, получится интересный ответ!).
Одна ловушка: попробуйте изменить второй оператор на:
x += 1;
и нажмите Check syntax. Вы получите ошибку: этот синтаксис (и синтаксис x++) допускается в различных языках, но не в ManuScript. Вы должны делать x = x+1;.

Где хранятся плагины
Плагины хранятся в папке с названием Plugins в папке Sibelius(в Windows, обычно, C:\Program Files\Sibelius Software\Sibelius 3\Plugins). Это нужно знать, если Вы захотите дать свой плагин кому-либо ещё. Плагины располагаются в подпапках, которые соответствуют подменю, где они расположены в меню Plug-ins. Имя файла плагина такое же, как и внутреннее имя плюс расширение .plg, например, Test.plg.

Перенос строк и комментарии
Как в C/C++и Java, Вы можете переносить строки везде, где захотите (кроме середины слов), не забывая при этом ставить точку с запятой в конце оператора. Можно поместить несколько операторов на одной строке или один оператор на нескольких строках.
Можно добавлять комментарии в вашу программу также, как в C/C++ и Java. Всё, что расположено после // игнорируется до конца строки. Также игнорируется всё, что расположено между /* и */, даже если занимает только часть строки или несколько строк:
// комментарий длится до конца линии
/* здесь можно вставить
многострочный комментарий
*/

Например:
Sibelius.MessageBox("Hi!"); // комментарий
или:
Sibelius/* комментарий */.MessageBox("Hi!");

Переменные
x в плагине Test – это переменная. В ManuScript имя переменной может состоять из букв, цифр и _ (символ подчёркивания), но не начинаться с цифры.
Переменная может содержать число (целое или с плавающей точкой), строку (текст) или объект (например, ноту) – больше об объектах Вы узнаете далее. В отличие от большинства языков, в ManuScript переменная может содержать любой тип данных – Вы не должны объявлять, какой это будет тип. Таким образом, Вы можете сначала сохранить в переменной число, потом какой-либо текст, а потом объект. Попробуйте это:
x = 56; x = x+1;
Sibelius.MessageBox(x); // напечатает ‘57’ в диалоговом окне
x = "now this is text"; // теперь это число потеряно
Sibelius.MessageBox(x); // напечатает ‘now this is text’ в диалоговом окне
x = Sibelius.ActiveScore; // теперь она содержит партитуру
Sibelius.MessageBox(x); // ничего не напечатает

Переменные, объявленные в методе, являются локальными для этого метода; другими словами, они не могут использоваться другими методами того же плагина. Глобальные переменные, определённые в редакторе плагинов, доступны для всех методов плагина и сохраняют своё значение между его вызовами.
Небольшое отступление о строках в ManuScript. Как и в большинстве языков программирования, в ManuScript строки используют обратный слэш \ в качестве ‘экранирующего символа’ для отображения некоторых специальных символов. Для добавления одинарной кавычки в строку необходимо использовать \’ , а для сивола перехода на новую строку - \n. Чтобы добавить сам обратный слэш, необходимо писать \\ (два обратных слэша).

Преобразования между числами, текстом и объектами
Заметьте, что метод MessageBox принимает какой-либо текст, чтобы отобразить его. Если Вы передадите ему число
(как в первом вызове MessageBox ниже), оно будет преобразовано в текст. Если передать ему объект (как, например, партитура), не получится никакого текста.
Точно также, если при вычислении требуется число, а имеется текст, то он будет преобразован в число:
x = 1 + "1"; // + означает, что ожидается число
Sibelius.MessageBox(x); // покажет ‘2’

Если текст не начинается с цифры (или если переменная содержит объект), он будет рассматриваться как 0:
x = 1 + "fred";
Sibelius.MessageBox(x); // покажет ‘1’