uk.co.dolphin_com.sscore

Class SScore

java.lang.Object

uk.co.dolphin_com.sscore.SScore

public class SScore
extends java.lang.Object

The main class of the SeeScore API, this encapsulates all information about the score loaded from a MusicXML file

loadXMLFile() or loadXMLData() should be used to load a file and create a SScore object

layout() should be called on a background thread to create a layout, and SSystems are generated sequentially from the top and can be added to the display as they are produced. This is handled by uk.co.dolphin_com.seescoreandroid.SeeScoreView

numBars(), numParts(), getHeader(), getPartNameForPart(), getBarNumberForIndex() all return basic information about the score.

setTranspose() allows you to transpose the score.

Other methods return detailed information about items in the score and require a contents or contents-detail licence.

Field Summary

Fields

Modifier and Type	Field and Description
static int	Bartype_default for default argument
static int	Bartype_full_bar a normal full bar
static int	Bartype_partial_bar_end partial bar missing beat 1 (ie after repeat mark)
static int	Bartype_partial_bar_start partial bar including beat 1 (ie before repeat mark)
static int	Bartype_partial_first_bar partial bar is first bar in score (ie anacrusis)

Method Summary

Modifier and Type	Method and Description
TimeSig	actualBeatsForBar(int barIndex) get the actual number of beats in the bar and the beat type This is normally the same as timeSigForBar, but will have fewer beats for a partial bar (eg anacrusis)
int	barTypeForBar(int barIndex) get the type of the bar
int	convertTempoToBPM(Tempo tempo, TimeSig timesig) get a beats-per-minute value for a given Tempo and TimeSig
BarBeats	getBarBeats(int barIndex, int bpm, int bartype) get the number of beats in a bar and the beat timing
BarGroup	getBarContents(int partindex, int barindex) Get information about the contents of a particular part/bar.
java.lang.String	getBarNumberForIndex(int barindex) Get the bar number (String) given the index.
Header	getHeader() Get the xml score-header information.
TimedItem	getItemForHandle(int partindex, int barindex, int item_h) return detailed information about an item in the score.
LoadWarning[]	getLoadWarnings() Get any warnings about problems with the file consistency discovered during load.
PartName	getPartNameForPart(int partindex) Return the name for the part.
int	getTranspose() Get the current transpose value set with setTranspose.
static Version	getVersion() Get the version of the SeeScore library
java.lang.String	getXmlForBar(int partindex, int barindex) Return the raw XML for this given part/bar index as a String.
java.lang.String	getXmlForItem(int partindex, int barindex, int item_h) return the XML for the item in the part/bar.
boolean	hasDefinedTempo() does the score define any tempo at the start with metronome or sound tempo elements?
void	layout(android.graphics.Canvas canvas, android.content.res.AssetManager am, int displayDPI, float width, float max_system_height, boolean[] parts, LayoutCallback cb, float magnification, LayoutOptions opt) Layout a set of systems and return them through a callback function.
SSystem	layout1System(android.graphics.Canvas canvas, android.content.res.AssetManager am, int displayDPI, int startbarindex, float width, float max_height, int partindex, float magnification) Layout a single system with a single part.
static SScore	loadXMLData(byte[] buffer, LoadOptions loadOptions) Load xml data in UTF-8 byte buffer and return score.
static SScore	loadXMLFile(java.io.File file, LoadOptions loadOptions) Load xml file and return score.
Tempo	metronomeForBar(int barIndex) get information about any metronome defined in the bar
int	numBars() Get the total number of bars in the score.
int	numParts() Get the number of parts in the score.
int	numStavesForPart(int partIndex) Get the number of staves in a given part
void	setTranspose(int semitones) set a transposition for the score.
Tempo	tempoAtBar(int barIndex) get the effective tempo at the bar accounting for any sound tempo elements and metronome elements
Tempo	tempoAtStart() get the effective tempo at start of the score accounting for any sound tempo elements and metronome elements
TimeSig	timeSigForBar(int barIndex) get the applicable time signature for a particular bar

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

Bartype_full_bar

public static final int Bartype_full_bar

a normal full bar

See Also:

Constant Field Values

Bartype_partial_first_bar

public static final int Bartype_partial_first_bar

partial bar is first bar in score (ie anacrusis)

See Also:

Constant Field Values

Bartype_partial_bar_start

public static final int Bartype_partial_bar_start

partial bar including beat 1 (ie before repeat mark)

See Also:

Constant Field Values

Bartype_partial_bar_end

public static final int Bartype_partial_bar_end

partial bar missing beat 1 (ie after repeat mark)

See Also:

Constant Field Values

Bartype_default

public static final int Bartype_default

for default argument

See Also:

Constant Field Values

Method Detail

getVersion

public static Version getVersion()

Get the version of the SeeScore library

Returns:

the version hi.lo

loadXMLData

public static SScore loadXMLData(byte[] buffer,
                                 LoadOptions loadOptions)
                          throws ScoreException

Load xml data in UTF-8 byte buffer and return score. NB cannot handle mxl data which must be decompressed by the caller (use ZipInputStream).

Parameters:

buffer - contains the xml

loadOptions - the options for load, or NULL for default options

Returns:

the score

Throws:

ScoreException - defining any error on load

loadXMLFile

public static SScore loadXMLFile(java.io.File file,
                                 LoadOptions loadOptions)
                          throws ScoreException

Load xml file and return score. NB cannot handle mxl file.

Parameters:

file - the full pathname of the file to load

loadOptions - the options for load including the licence key

Returns:

the score

Throws:

ScoreException - defining any error on load

getLoadWarnings

public LoadWarning[] getLoadWarnings()

Get any warnings about problems with the file consistency discovered during load.

Returns:

the array of warnings

numBars

public int numBars()

Get the total number of bars in the score.

Returns:

the number of bars

numParts

public int numParts()

Get the number of parts in the score.

Returns:

the number of parts

numStavesForPart

public int numStavesForPart(int partIndex)

Get the number of staves in a given part

Parameters:

partIndex - the part index

Returns:

the number of staves (0 or 1)

getPartNameForPart

public PartName getPartNameForPart(int partindex)

Return the name for the part.

Parameters:

partindex - the index of the part [0..numparts-1]

Returns:

PartName (full + abbreviated)

layout1System

public SSystem layout1System(android.graphics.Canvas canvas,
                             android.content.res.AssetManager am,
                             int displayDPI,
                             int startbarindex,
                             float width,
                             float max_height,
                             int partindex,
                             float magnification)

Layout a single system with a single part. You specify a start bar index and a width and magnification and it will display as many bars as will fit into this width.

Useful for display of individual parts for part selection.

Parameters:

canvas - the canvas is used to measure bounds of items

am - the AssetManager is used to load fonts from assets

displayDPI - the dots-per-inch value for the display viz. android.view.Display.getMetrics(android.util.DisplayMetrics).densityDPI

startbarindex - the index of the first bar in the system (usually 0)

max_height - the maximum height available to display the system to control truncation. =0 for no truncation

partindex - the index of the single part to layout [0..numparts-1]

magnification - the scale at which to display this (1.0 is default)

Returns:

the system

layout

public void layout(android.graphics.Canvas canvas,
                   android.content.res.AssetManager am,
                   int displayDPI,
                   float width,
                   float max_system_height,
                   boolean[] parts,
                   LayoutCallback cb,
                   float magnification,
                   LayoutOptions opt)
            throws ScoreException

Layout a set of systems and return them through a callback function.

This should be called on a background thread and it will call cb for each system laid out, from top to bottom. cb will normally add the system to a sscore_systemlist on the foreground (gui event dispatch) thread.

systems are stored in this SScore as they are produced.

This allows the UI to remain active during concurrent layout which may take many seconds

Parameters:

canvas - the canvas is used to measure bounds of items

am - the AssetManager is used to load fonts from assets

displayDPI - the dots-per-inch value for the display viz. android.view.Display.getMetrics(android.util.DisplayMetrics).densityDPI

width - the width available to display the systems in screen coordinates

max_system_height - the maximum height available to display each system to control truncation. =0 for no truncation

parts - array of boolean, 1 per part, true to include, false to exclude

cb - the callback function to be called for each completed system

magnification - the scale at which to display this (1.0 is default)

opt - pointer to options or NULL for default

Throws:

ScoreException - defining any error encountered during layout

getHeader

public Header getHeader()

Get the xml score-header information.

Returns:

the header

getBarNumberForIndex

public java.lang.String getBarNumberForIndex(int barindex)

Get the bar number (String) given the index.

Parameters:

barindex - integer index [0..numBars-1]

Returns:

the score-defined number String (usually "1" for index 0)

setTranspose

public void setTranspose(int semitones)
                  throws ScoreException

set a transposition for the score. Call layout() after calling setTranspose for a new transposed layout.

Requires the transpose licence.

Parameters:

semitones - (- for down, + for up)

Throws:

ScoreException

getTranspose

public int getTranspose()

Get the current transpose value set with setTranspose.

Requires the transpose licence.

Returns:

the current transpose

getItemForHandle

public TimedItem getItemForHandle(int partindex,
                                  int barindex,
                                  int item_h)
                           throws ScoreException

return detailed information about an item in the score.

Requires contents-detail licence.

Parameters:

partindex - 0-based part index - 0 is the top part

barindex - 0-based bar index

item_h - unique id for item

Returns:

TimedItem which can be cast to the specific derived type - NoteItem/DirectionItem etc.

Throws:

ScoreException

getXmlForItem

public java.lang.String getXmlForItem(int partindex,
                                      int barindex,
                                      int item_h)
                               throws ScoreException

return the XML for the item in the part/bar.

Requires contents licence.

Parameters:

partindex - the 0-based part index - 0 is top

barindex - the 0-based bar index

item_h - the unique id of the item

Returns:

the XML as a String

Throws:

ScoreException

getBarContents

public BarGroup getBarContents(int partindex,
                               int barindex)
                        throws ScoreException

Get information about the contents of a particular part/bar.

Requires contents licence.

Parameters:

partindex - the index of the part (0-based)

barindex - the index of the bar (0-based)

Returns:

the BarGroup containing an array of Item

Throws:

ScoreException

getXmlForBar

public java.lang.String getXmlForBar(int partindex,
                                     int barindex)
                              throws ScoreException

Return the raw XML for this given part/bar index as a String.

Requires contents-detail licence.

Parameters:

partindex - the index of the part (0-based)

barindex - the index of the bar (0-based)

Returns:

the XML as a String

Throws:

ScoreException

hasDefinedTempo

public boolean hasDefinedTempo()

does the score define any tempo at the start with metronome or sound tempo elements?

Returns:

true if the score defines tempo. Use this to determine whether the user defines the absolute tempo or the tempo scaling

barTypeForBar

public int barTypeForBar(int barIndex)

get the type of the bar

Parameters:

barIndex -

Returns:

Bartype_*

timeSigForBar

public TimeSig timeSigForBar(int barIndex)
                      throws ScoreException

get the applicable time signature for a particular bar

Parameters:

barIndex - the index of the bar. 0 is the first bar

Returns:

the applicable TimeSig

Throws:

ScoreException - on error

actualBeatsForBar

public TimeSig actualBeatsForBar(int barIndex)
                          throws ScoreException

get the actual number of beats in the bar and the beat type This is normally the same as timeSigForBar, but will have fewer beats for a partial bar (eg anacrusis)

Parameters:

barIndex - the index of the bar. 0 is the first bar

Returns:

the effective TimeSig

Throws:

ScoreException - on error

metronomeForBar

public Tempo metronomeForBar(int barIndex)
                      throws ScoreException

get information about any metronome defined in the bar

Parameters:

barIndex - the index of the bar. 0 is the first bar

Returns:

metronome information

Throws:

ScoreException - on error

tempoAtBar

public Tempo tempoAtBar(int barIndex)
                 throws ScoreException

get the effective tempo at the bar accounting for any sound tempo elements and metronome elements

Parameters:

barIndex - the index of the bar (0 is 1st)

Returns:

the effective Tempo

Throws:

ScoreException - on error

tempoAtStart

public Tempo tempoAtStart()
                   throws ScoreException

get the effective tempo at start of the score accounting for any sound tempo elements and metronome elements

Returns:

the effective Tempo

Throws:

ScoreException - on error

convertTempoToBPM

public int convertTempoToBPM(Tempo tempo,
                             TimeSig timesig)

get a beats-per-minute value for a given Tempo and TimeSig

Parameters:

tempo - the score-defined or user-defined tempo

timesig - the effective time signature

Returns:

beats per minute

getBarBeats

public BarBeats getBarBeats(int barIndex,
                            int bpm,
                            int bartype)
                     throws ScoreException

get the number of beats in a bar and the beat timing

Parameters:

barIndex - the index of the bar (0 is 1st)

bpm - the effective beats-per-minute value

bartype - one of Bartype_?

Returns:

beat number and timing

Throws:

ScoreException