Skip to content

Commit f22726b

Browse files
Danielku15Danielku15
committed
docs: Update feature docs and release notes
1 parent 2b4c0c9 commit f22726b

12 files changed

Lines changed: 538 additions & 33 deletions

File tree

‎docs/alphatex/bar-metadata.mdx‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -229,3 +229,60 @@ To apply simile marks use the `\simile type` where type is:
229229
<AlphaTexSample player="true">{`
230230
3.3*4 | \\simile simple | 3.3*4 | 4.3*4 | \\simile firstofdouble | \\simile secondofdouble
231231
`}</AlphaTexSample>
232+
233+
## Bar Lines
234+
235+
For some special notation needs, the default bar line can be adjusted on every bar.
236+
The bar line styles are aligned with the ones from [MusicXML](https://www.w3.org/2021/06/musicxml40/musicxml-reference/data-types/bar-style/).
237+
238+
* `\barlineLeft` adjusts the left bar line
239+
* `\barlineRight` adjusts the right bar line
240+
241+
alphaTab attempts to reuse lines on overlapping styles across bars.
242+
243+
<AlphaTexSample tracks="all">{`
244+
\\instrument piano
245+
.
246+
\\track "Overlapping"
247+
\\staff
248+
\\barlineleft dashed
249+
\\barlineright dotted
250+
|
251+
\\barlineleft heavyheavy
252+
\\barlineright heavyheavy
253+
254+
\\staff
255+
\\barlineleft lightlight
256+
\\barlineright lightheavy
257+
|
258+
\\barlineleft heavylight
259+
\\barlineright dashed
260+
\\track "All Styles"
261+
\\staff
262+
\\barlineright dashed |
263+
\\barlineright dotted |
264+
\\barlineright heavy |
265+
\\barlineright heavyHeavy |
266+
\\barlineright heavyLight |
267+
\\barlineright lightHeavy |
268+
\\barlineright lightlight |
269+
\\barlineright none |
270+
\\barlineright regular |
271+
\\barlineright short |
272+
\\barlineright tick |
273+
`}</AlphaTexSample>
274+
275+
* `automatic` - Bar lines are determined automatically based on details like repeats and free time (default).
276+
* `dashed`
277+
* `dotted`
278+
* `heavy`
279+
* `heavyheavy`
280+
* `heavylight`
281+
* `lightheavy`
282+
* `lightlight`
283+
* `none`
284+
* `regular`
285+
* `short`
286+
* `tick`
287+
288+

‎docs/alphatex/beat-effects.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -53,7 +53,7 @@ Please find the list of supported effects in the example below.
5353

5454
## Dynamics
5555

56-
Dynamics are beat effects with the indicator `dy` followed by one of the supported dynamics values FFF, FF, F, MF, MP, P, PP or PPP.
56+
Dynamics are beat effects with the indicator `dy` followed by one of the supported dynamics values PPP, PP, P, MP, MF, F, FF, FFF, PPPP, PPPPP, PPPPPP, FFFF, FFFFF, FFFFFF, SF, SFP, SFPP, FP, RF, RFZ, SFZ, SFFZ, FZ, N, PF, SFZP.
5757

5858
<AlphaTexSample>{`
5959
1.1.8{dy ppp} 1.1{dy pp} 1.1{dy p} 1.1{dy mp} 1.1{dy mf} 1.1{dy f} 1.1{dy ff} 1.1{dy fff}

‎docs/alphatex/metadata.mdx‎

Lines changed: 29 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,9 @@ title: Metadata
33
---
44

55
import { AlphaTexSample } from '@site/src/components/AlphaTexSample';
6+
import { SinceBadge } from '@site/src/components/SinceBadge';
67

7-
Metadata is specified using `\tagname value value` at the beginning of the score.
8+
Metadata is specified using `\tagname value` at the beginning of the score.
89
It can be used to specify global information like title, tempo or track tuning.
910
Metadata is optional, but if specified, it must be followed by a dot to indicate the end
1011
of the metadata.
@@ -39,6 +40,33 @@ Please refer to the [Tracks and Staves](/docs/alphatex/tracks-staves) or details
3940

4041
Strings can contain escape sequences: `\n`, `\r`, `\t`, `\\`, `\"`, `\'`.
4142

43+
<SinceBadge inline={true} since="1.5.0" /> its possible to also change the template and alignment of the song information
44+
via `\tagname value template alignment`.
45+
46+
The `template` is a string which can have following placeholders which are then replaced with the respective info of the song:
47+
48+
* `%TITLE%`
49+
* `%SUBTITLE%`
50+
* `%ARTIST%`
51+
* `%ALBUM%`
52+
* `%WORDS%`
53+
* `%WORDSMUSIC%`
54+
* `%MUSIC%`
55+
* `%TABBER%`
56+
* `%COPYRIGHT%`
57+
58+
The `alignment` is one of the following values:
59+
60+
* `left`
61+
* `center`
62+
* `right`
63+
64+
<AlphaTexSample>{`
65+
\\title "Song Title" "Title: %TITLE%" left
66+
\\artist Artist "Written by %ARTIST%" right
67+
.
68+
`}</AlphaTexSample>
69+
4270
## Instrument
4371
As indicated above, the instrument can be changed via the `\instrument` metadata.
4472
Refer to the table below for all possible values and names. The list represents the General MIDI instrument list.

‎docs/formats/musicxml.mdx‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -108,19 +108,19 @@ import { FileFormatFeatureTable, FileFormatFeatureGroup, FileFormatFeatureRow, F
108108
tex={[FeatureStatus.Supported]} />
109109
<FileFormatFeatureRow feature="credit"
110110
model={[FeatureStatus.Supported]}
111-
reading={[FeatureStatus.NotSupported]}
111+
reading={[FeatureStatus.Supported]}
112112
render={[FeatureStatus.Supported]}
113113
audio={[FeatureStatus.Supported]}
114114
tex={[FeatureStatus.Supported]} />
115115
<FileFormatFeatureRow feature="part-list"
116116
model={[FeatureStatus.Supported]}
117-
reading={[FeatureStatus.NotSupported]}
117+
reading={[FeatureStatus.Supported]}
118118
render={[FeatureStatus.Supported]}
119119
audio={[FeatureStatus.Supported]}
120120
tex={[FeatureStatus.Supported]} />
121121
<FileFormatFeatureRow feature="part"
122122
model={[FeatureStatus.Supported]}
123-
reading={[FeatureStatus.NotSupported]}
123+
reading={[FeatureStatus.Supported]}
124124
render={[FeatureStatus.Supported]}
125125
audio={[FeatureStatus.Supported]}
126126
tex={[FeatureStatus.Supported]} />
@@ -165,19 +165,19 @@ import { FileFormatFeatureTable, FileFormatFeatureGroup, FileFormatFeatureRow, F
165165
tex={[FeatureStatus.Supported]} />
166166
<FileFormatFeatureRow feature="credit"
167167
model={[FeatureStatus.Supported]}
168-
reading={[FeatureStatus.NotSupported]}
168+
reading={[FeatureStatus.Supported]}
169169
render={[FeatureStatus.Supported]}
170170
audio={[FeatureStatus.Supported]}
171171
tex={[FeatureStatus.Supported]} />
172172
<FileFormatFeatureRow feature="part-list"
173173
model={[FeatureStatus.Supported]}
174-
reading={[FeatureStatus.NotSupported]}
174+
reading={[FeatureStatus.Supported]}
175175
render={[FeatureStatus.Supported]}
176176
audio={[FeatureStatus.Supported]}
177177
tex={[FeatureStatus.Supported]} />
178178
<FileFormatFeatureRow feature="measure"
179179
model={[FeatureStatus.Supported]}
180-
reading={[FeatureStatus.NotSupported]}
180+
reading={[FeatureStatus.Supported]}
181181
render={[FeatureStatus.Supported]}
182182
audio={[FeatureStatus.Supported]}
183183
tex={[FeatureStatus.Supported]} />

‎docs/guides/formatting-templates.mdx‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
---
2+
title: Song Details Formatting
3+
since: 1.5.0
4+
---
5+
import Tabs from '@theme/Tabs';
6+
import TabItem from '@theme/TabItem';
7+
8+
import { SinceBadge } from '@site/src/components/SinceBadge';
9+
10+
<SinceBadge since="1.5.0"></SinceBadge>
11+
12+
In the page payout, alphaTab shows the information of the song directly as part of the music sheet.
13+
The display of this song information can be adjusted in 3 ways:
14+
15+
* Colors can be adjusted via the `style` (see [Coloring Music Sheet](./coloring.mdx))
16+
* Alignment and the text template can be adjusted via `style`.
17+
* Fonts can be adjusted via [`settings.display.resources`](/docs/reference/settings/display/resources)
18+
19+
The mechanisms are currently a bit scattered historically. With alphaTab 2.x we plan to consolidate these options.
20+
21+
For some formats like Guitar Pro alphaTab will read the information contained in the file and adjust the alignments and templates.
22+
In any case, the song info can be adjusted by updating the settings and the data model after it has been loaded.
23+
24+
The examples here are written in TypeScript (for clarity on types), the same methods and properties are available on all flavors of alphaTab.
25+
When and what to set as styles depends on your needs. You might have an own custom style applied to all files, or you have the style stored beside
26+
your file and load it along the file itself.
27+
28+
import {FormattingTemplateSample} from '@site/src/components/FormattingTemplateSample'
29+
30+
<FormattingTemplateSample />
31+
32+
The most important parts to know:
33+
34+
* The [`style`](docs/reference/types/model/score/style) on [`alphaTab.model.Score`](/docs/reference/types/model/score) is used to adjust the style of the visual elements.
35+
* The [`headerAndFooter`](/docs/reference/types/model/scorestyle/headerandfooter) on [`alphaTab.model.ScoreStyle`](/docs/reference/types/model/scorestyle/) is used to adjust the text, visibility and alignment of the header and footer elements.
36+
* The [`colors`](/docs/reference/types/model/elementstyle/colors) on `alphaTab.model.ScoreStyle` is used to adjust the color of the header and footer elements (and others).
37+
* The [`alphaTab.model.ScoreSubElement`](/docs/reference/types/model/scoresubelement) defines the possible list of elements to be styled (not all are song info related)
38+

‎docs/reference/settings/core/enablelazyloading.mdx‎

Lines changed: 12 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,8 @@
22
title: core.enableLazyLoading
33
description: "Enables lazy loading of the rendered music sheet chunks."
44
sidebar_custom_props:
5-
javaScriptOnly: true
65
jsOnParent: true
7-
category: Core - JavaScript Specific
6+
category: Core
87
since: 0.9.6
98
---
109

@@ -26,6 +25,17 @@ Enables lazy loading of the rendered music sheet chunks. AlphaTab renders the mu
2625
appended to the DOM due to performance reasons. AlphaTab tries to detect which elements are visible on the screen, and only
2726
appends those elements to the DOM. This reduces the load of the browser heavily but is not working for all layouts and use cases.
2827
This setting set to false, ensures that all rendered items are instantly appended to the DOM.
28+
The lazy rendering of partial might not be available on all platforms.
2929

30+
<Tabs defaultValue="js" values={[{label: "JavaScript", value: "js"},{label: "C#", value: "cs"},{label:"Kotlin", value: "kt"}]}>
31+
<TabItem value="js">
3032
<div className="codeBlockContainer"><div className="codeBlockContent"><pre className="codeBlock"><code className="codeBlockLines" style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}><span style={{"color":"#36acaa"}}>{"enableLazyLoading"}</span><span style={{"color":"#393A34"}}>{":"}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#36acaa"}}>{"boolean"}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#393A34"}}>{"="}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#36acaa"}}>{"true"}</span><span style={{"color":"#393A34"}}>{";"}</span></code></pre></div></div>
33+
</TabItem>
34+
<TabItem value="cs">
35+
<div className="codeBlockContainer"><div className="codeBlockContent"><pre className="codeBlock"><code className="codeBlockLines" style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}><span style={{"color":"#36acaa"}}>{"bool"}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#36acaa"}}>{"EnableLazyLoading"}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#393A34"}}>{"{"}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#00009f"}}>{"get"}</span><span style={{"color":"#393A34"}}>{";"}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#00009f"}}>{"set"}</span><span style={{"color":"#393A34"}}>{";"}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#393A34"}}>{"}"}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#393A34"}}>{"="}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#36acaa"}}>{"true"}</span></code></pre></div></div>
36+
</TabItem>
37+
<TabItem value="kt">
38+
<div className="codeBlockContainer"><div className="codeBlockContent"><pre className="codeBlock"><code className="codeBlockLines" style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}><span style={{"color":"#00009f"}}>{"var"}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#36acaa"}}>{"enableLazyLoading"}</span><span style={{"color":"#393A34"}}>{":"}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#36acaa"}}>{"Boolean"}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#393A34"}}>{"="}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#36acaa"}}>{"true"}</span></code></pre></div></div>
39+
</TabItem>
40+
</Tabs>
3141

‎docs/reference/settings/display/systemlabelpaddingright.mdx‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -25,13 +25,13 @@ The padding left to the track name label of the system.
2525

2626
<Tabs defaultValue="js" values={[{label: "JavaScript", value: "js"},{label: "C#", value: "cs"},{label:"Kotlin", value: "kt"}]}>
2727
<TabItem value="js">
28-
<div className="codeBlockContainer"><div className="codeBlockContent"><pre className="codeBlock"><code className="codeBlockLines" style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}><span style={{"color":"#36acaa"}}>{"systemLabelPaddingRight"}</span><span style={{"color":"#393A34"}}>{":"}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#36acaa"}}>{"number"}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#393A34"}}>{"="}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#36acaa"}}>{"5"}</span><span style={{"color":"#393A34"}}>{";"}</span></code></pre></div></div>
28+
<div className="codeBlockContainer"><div className="codeBlockContent"><pre className="codeBlock"><code className="codeBlockLines" style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}><span style={{"color":"#36acaa"}}>{"systemLabelPaddingRight"}</span><span style={{"color":"#393A34"}}>{":"}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#36acaa"}}>{"number"}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#393A34"}}>{"="}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#36acaa"}}>{"3"}</span><span style={{"color":"#393A34"}}>{";"}</span></code></pre></div></div>
2929
</TabItem>
3030
<TabItem value="cs">
31-
<div className="codeBlockContainer"><div className="codeBlockContent"><pre className="codeBlock"><code className="codeBlockLines" style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}><span style={{"color":"#36acaa"}}>{"double"}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#36acaa"}}>{"SystemLabelPaddingRight"}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#393A34"}}>{"{"}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#00009f"}}>{"get"}</span><span style={{"color":"#393A34"}}>{";"}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#00009f"}}>{"set"}</span><span style={{"color":"#393A34"}}>{";"}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#393A34"}}>{"}"}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#393A34"}}>{"="}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#36acaa"}}>{"5"}</span></code></pre></div></div>
31+
<div className="codeBlockContainer"><div className="codeBlockContent"><pre className="codeBlock"><code className="codeBlockLines" style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}><span style={{"color":"#36acaa"}}>{"double"}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#36acaa"}}>{"SystemLabelPaddingRight"}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#393A34"}}>{"{"}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#00009f"}}>{"get"}</span><span style={{"color":"#393A34"}}>{";"}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#00009f"}}>{"set"}</span><span style={{"color":"#393A34"}}>{";"}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#393A34"}}>{"}"}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#393A34"}}>{"="}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#36acaa"}}>{"3"}</span></code></pre></div></div>
3232
</TabItem>
3333
<TabItem value="kt">
34-
<div className="codeBlockContainer"><div className="codeBlockContent"><pre className="codeBlock"><code className="codeBlockLines" style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}><span style={{"color":"#00009f"}}>{"var"}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#36acaa"}}>{"systemLabelPaddingRight"}</span><span style={{"color":"#393A34"}}>{":"}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#36acaa"}}>{"Double"}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#393A34"}}>{"="}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#36acaa"}}>{"5"}</span></code></pre></div></div>
34+
<div className="codeBlockContainer"><div className="codeBlockContent"><pre className="codeBlock"><code className="codeBlockLines" style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}><span style={{"color":"#00009f"}}>{"var"}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#36acaa"}}>{"systemLabelPaddingRight"}</span><span style={{"color":"#393A34"}}>{":"}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#36acaa"}}>{"Double"}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#393A34"}}>{"="}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#36acaa"}}>{"3"}</span></code></pre></div></div>
3535
</TabItem>
3636
</Tabs>
3737

0 commit comments

Comments
 (0)