2023 Conmajia, 2018 Ajcek84
SN: 23C.1
本中文翻译已获原作者首肯。
简介
PSAM 控件库——波兰音乐文档系统——是用于显示、排版乐谱的强大 WinForm 库，包含用于绘制乐谱的名为 IncipitViewer 控件，乐谱内容可以从 MusicXml 文件读取，或者在程序中添加赋格、音符、小节等。这个控件是为 PSAM 软件（图 1）而开发的组件。当我意识到其他软件开发者也许可能想要用到它的功能，我决定在 BSD 许可下发布这个控件。PSAM 控件库完全由 C# 实现。
使用代码
IncipitViewer 控件需要特殊的音乐字体来绘制音符等。本文提供的下载资源中附带了 Polihymnia 的 TrueType 字体，以便你可以直接安装使用。这个字体基于 Ben Laenen 的 Euterpe 字体，以 Sil 开放字体许可发布。
IncipitViewer（PSAMControlLibrary.dll）是标准的 C# 控件库。将其简单拖放至 Visual Studio 窗体设计器工具箱即可开始使用。控件用法类似普通控件，如 TextBox 等。若是用编程方式创建 IncipitViewer 控件，使用如下代码。
IncipitViewer viewer = new IncipitViewer();
viewer.Dock = DockStyle.Fill;
Controls.Add(viewer);
一般来说 Visual Studio 会自动添加
using PSAMControlLibrary;
本控件提供了从 MusicXML 文件读取乐谱的功能——仅限第一行谱表1，忽略后续谱表。
viewer.LoadFromXmlFile("example.xml");
从文件读取并显示乐谱效果如下。
使用 ClearMusicalIncipit() 方法可清除当前显示内容。
本控件提供了代码用于以编程方式添加音符等内容。例如，下面的代码向乐谱第 2 行添加了一个 G 谱号。
Clef c = new Clef(ClefType.GClef, 2);
viewer.AddMusicalSymbol(c);
以及一个新的 G 调四分音符（1=G4/4）。
Note n = new Note("G", 0, 4, MusicalSymbolDuration.Quarter,
NoteStemDirection.Up, NoteTieType.None,
new List<NoteBeamType>() {NoteBeamType.Single});
viewer.AddMusicalSymbol(n);
音符（Note）构造函数的第一个参数键名（A, B, C, D, E, F, G），第二个参数是升调数（+）或降调数（-）。升降调若为 0 则表示原调。第三个参数是八度。接下来的参数有：音符节拍、音杆方向和延音线类型（如果没有则为 NoteTieType.None）。最后一个参数是符杠列表。如果音符没有任何符杠，即使音符的持续时间大于八分音符，仍然需要有这个列表，只是里面仅有一个元素 NoteBeamType.Single。为了清楚地说明符杠列表是如何工作的，下面的代码将尝试添加一个由两个十六分音符和一个八分音符组成的组：
Note s1 = new Note("A", 0, 4, MusicalSymbolDuration.Sixteenth,
NoteStemDirection.Down, NoteTieType.None,
new List<NoteBeamType>() { NoteBeamType.Start, NoteBeamType.Start});
Note s2 = new Note("C", 1, 5, MusicalSymbolDuration.Sixteenth,
NoteStemDirection.Down, NoteTieType.None,
new List<NoteBeamType>() { NoteBeamType.Continue, NoteBeamType.End });
Note e = new Note("D", 0, 5, MusicalSymbolDuration.Eighth,
NoteStemDirection.Down, NoteTieType.None,
new List<NoteBeamType>() { NoteBeamType.End });
viewer.AddMusicalSymbol(s1);
viewer.AddMusicalSymbol(s2);
viewer.AddMusicalSymbol(e);
显示的乐谱如下。
如果设置符杠为 NoteBeamType.Single，则乐谱如下。
本控件还支持彩色音符，只需要简单地修改音符 MusicalCharacterColor 属性。
尽管 IncipitViewer 只支持单谱表，但它依然支持和弦，因为它们是许多单声部乐器习惯用法的一部分。如果一个音符的 IsChordElement 属性设置为 true，那么它就被视为前一个音符的和弦元素：
Note n1 = new Note("C", 0, 4, MusicalSymbolDuration.Half,
NoteStemDirection.Up, NoteTieType.None,
new List<NoteBeamType>() { NoteBeamType.Single });
Note n2 = new Note("E", 0, 4, MusicalSymbolDuration.Half,
NoteStemDirection.Up, NoteTieType.None,
new List<NoteBeamType>() { NoteBeamType.Single });
Note n3 = new Note("G", 0, 4, MusicalSymbolDuration.Half,
NoteStemDirection.Up, NoteTieType.None,
new List<NoteBeamType>() { NoteBeamType.Single });
n2.IsChordElement = true;
n3.IsChordElement = true;
viewer.AddMusicalSymbol(n1);
viewer.AddMusicalSymbol(n2);
viewer.AddMusicalSymbol(n3);
结果如下。
下面的代码演示了点、休止符和小节符。
Note n4 = new Note("A", 0, 4, MusicalSymbolDuration.Half,
NoteStemDirection.Up, NoteTieType.None,
new List<NoteBeamType>() { NoteBeamType.Single });
n4.NumberOfDots = 1;
Rest r = new Rest(MusicalSymbolDuration.Quarter);
Barline b = new Barline();
viewer.AddMusicalSymbol(n4);
viewer.AddMusicalSymbol(r);
viewer.AddMusicalSymbol(b);
结果如下。
鼠标互动
当鼠标悬停在控件上时，右上角会出现两个按钮：第一个用于保存与控件关联的 MusicXml 文件，第二个用于调用 OnPlayExternalMidiPlayer 事件处理程序，用法如下。
viewer.PlayExternalMidiPlayer +=
new IncipitViewer.PlayExternalMidiPlayerDelegate(viewer_PlayExternalMidiPlayer);
void viewer_PlayExternalMidiPlayer(IncipitViewer sender) {
//Place your code here
}
借此，你可以用代码从已有控件读出音符，并用自定义代码或是其他第三方库播放。IncipitViewer.IncipitElement(int i) 方法可以读取第 i 个音符，而 MusicalSymbol.ToMidiPitch() 方法则可以将空间中的音符转换为 MIDI。
要打印 IncipitViewer 控件的内容，创建一个 PrintDocument 对象并处理其 PrintPage 事件。
private void printDocument1_PrintPage(object sender,
System.Drawing.Printing.PrintPageEventArgs e) {
Graphics g = e.Graphics;
viewer.DrawViewer(g, true);
}
接下来调用 Print() 方法打印音乐文档。
PrintDialog dlg = new PrintDialog();
dlg.Document = printDocument1;
if (dlg.ShowDialog() == DialogResult.OK) {
printDocument1.Print();
}
打印样张如下。
许可
本文及其附属文件、代码均以 BSD 协议发布。
谱表指谱号和五线谱合称，如图所示为高音谱表（上）和低音谱表（下）。
