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.

Method Summary

Methods

Modifier and Type	Method and Description
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.
void	layout(Canvas canvas, 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(Canvas canvas, 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.
int	numBars() Get the total number of bars in the score.
int	numParts() Get the number of parts in the score.
void	setTranspose(int semitones) set a transposition for the score.

Methods inherited from class java.lang.Object

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

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

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(Canvas canvas,
                    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(Canvas canvas,
          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