diff --git a/README.md b/README.md index 327f692..dbeed09 100644 --- a/README.md +++ b/README.md @@ -21,19 +21,23 @@ $ bower install ## Usage -The library provides the function `render_notation` which takes four +The library provides the function `render_notation` which takes up to six arguments: - - `score` should be a markup fragment containing the MEI + - `xmlDoc` (XMLDocument) should be a markup fragment containing the MEI - - `target` should be an HTML element onto which the notation + - `target` (Element) should be an HTML or element onto which the notation will be drawn - - `width` should be the width of the canvas (optional) + - `width` (Number) should be the width of the canvas in pixels. Defaults to 800 (optional) - - `height` should be the height of the canvas (optional) + - `height` (Number) should be the height of the canvas in pixels. Defaults to 350 (optional) -For sample function calls see the test cases in the 'tests' directory! + - `backend` (Vex.Flow.Renderer.Backends.CANVAS|Vex.Flow.Renderer.Backends.RAPHAEL) specifies the VexFlow backend to use. Defaults to Vex.Flow.Renderer.Backends.CANVAS (optional) + + - `options` (Object) may contain additional conversion and rendering options; see the comments on the default options in `src/Converter.js` for details (optional) + +For sample function calls see the test runs in the 'tests' directory! ## MeiLib.js @@ -61,7 +65,7 @@ comments within the source file meilib.js Only a small subset of MEI has so far been implemented. Many conventional aspects of common practice notation have been ignored -(such as repeat accidentals, stem directions). It's also important to +(such as repeat accidentals). It's also important to remember that VexFlow is a moving target, it's in constant development and so this code could break at any time. diff --git a/bower.json b/bower.json index 0ee183e..db726e3 100644 --- a/bower.json +++ b/bower.json @@ -3,7 +3,7 @@ "version": "0.1.0", "homepage": "http://tei-music-sig.github.io/MEItoVexFlow/", "authors": [ - "irochicken raffazizzi zolaemil aerhard" + "ironchicken raffazizzi zolaemil aerhard" ], "description": "MEI to VexFlow bridge library", "main": "meitovexflow.js", @@ -17,9 +17,7 @@ "ignore": [ "**/.*", "node_modules", - "bower_components", - "test", - "tests" + "bower_components" ], "dependencies": { "jquery": "~2.1.0", diff --git a/src/Converter.js b/src/Converter.js index 296420b..a1f0439 100644 --- a/src/Converter.js +++ b/src/Converter.js @@ -1046,9 +1046,9 @@ var MEI2VF = ( function(m2v, MeiLib, VF, $, undefined) { * @method processChord */ processChord : function(element, staff, staff_n) { - var me = this, i, j, hasDots, $children, keys = [], duration, durations = [], durAtt, xml_id, chord, chord_opts, atts; + var me = this, i, j, hasDots, children, keys = [], duration, durations = [], durAtt, xml_id, chord, chord_opts, atts; - $children = $(element).children(); + children = $(element).children(); atts = m2v.Util.attsToObj(element); durAtt = atts.dur; @@ -1061,16 +1061,16 @@ var MEI2VF = ( function(m2v, MeiLib, VF, $, undefined) { if (durAtt) { duration = me.translateDuration(+durAtt); } else { - for ( i = 0, j = $children.length; i < j; i += 1) { - durations.push(+$children[i].getAttribute('dur')); + for ( i = 0, j = children.length; i < j; i += 1) { + durations.push(+children[i].getAttribute('dur')); } duration = me.translateDuration(Math.max.apply(Math, durations)); } - for ( i = 0, j = $children.length; i < j; i += 1) { - keys.push(me.processAttsPitch($children[i])); - // dots.push(+$children[i].getAttribute('dots')); - if ($children[i].getAttribute('dots') === '1') + for ( i = 0, j = children.length; i < j; i += 1) { + keys.push(me.processAttsPitch(children[i])); + // dots.push(+children[i].getAttribute('dots')); + if (children[i].getAttribute('dots') === '1') hasDots = true; } @@ -1089,7 +1089,7 @@ var MEI2VF = ( function(m2v, MeiLib, VF, $, undefined) { var allNoteIndices = []; - $children.each(function(i) { + children.each(function(i) { me.processNoteInChord(i, this, element, chord); allNoteIndices.push(i); }); diff --git a/src/Interface.js b/src/Interface.js index 3d2f9d8..ffac98a 100644 --- a/src/Interface.js +++ b/src/Interface.js @@ -2,66 +2,108 @@ * @class MEI2VF * @singleton */ -var MEI2VF = ( function(m2v, MeiLib, VF, $, undefined) { +var MEI2VF = (function(m2v, MeiLib, VF, $, undefined) { return { + /** + * enables or disables MEI2VF logging + * @method setLogging + * @param {Boolean} value True if logging should be enabled, false if not. Defaults to false. + */ setLogging : m2v.setLogging, + /** + * The methods in Converter can be used to manually address distinct + * processing steps and retrieve the created data. Can be used in + * addition or as a supplement to {@link render_notation} and + * {@link rendered_measures} + */ Converter : { - initConfig : function(c) { - return m2v.Converter.prototype.initConfig(c); + /** + * initializes the converter + * @method initConfig + * @param {Object} config The options passed to the converter. For a list, see + * {@link MEI2VF.Converter#defaults} + */ + initConfig : function(config) { + m2v.Converter.prototype.initConfig(config); }, - process : function(c) { - return m2v.Converter.prototype.process(c); + /** + * Processes the specified MEI document or document fragment. The generated + * objects can be processed further or drawn immediately to a canvas via + * {@link #draw}. + * @method process + * @param {XMLDocument} xmlDoc the XML document + */ + process : function(xmlDoc) { + m2v.Converter.prototype.process(xmlDoc); }, - draw : function(c) { - return m2v.Converter.prototype.draw(c); + /** + * Draws the processed data to a canvas + * @method draw + * @param ctx The canvas context + */ + draw : function(ctx) { + m2v.Converter.prototype.draw(ctx); }, + /** + * returns a 2d array of all Vex.Flow.Stave objects, arranged by + * [measure_n][staff_n] + * @method getAllVexMeasureStaffs + * @return {Vex.Flow.Stave[][]} see {@link MEI2VF.Converter#allVexMeasureStaffs} + */ getAllVexMeasureStaffs : function() { return m2v.Converter.prototype.getAllVexMeasureStaffs(); }, + /** + * Returns the width and the height of the area that contains all drawn + * staves as per the last processing. + * + * @method getStaffArea + * @return {Object} the width and height of the area that contains all staves. + * Properties: width, height + */ getStaffArea : function() { return m2v.Converter.prototype.getStaffArea(); } - } - }; - }(MEI2VF || {}, MeiLib, Vex.Flow, jQuery)); + }, + /** + * Contains all Vex.Flow.Stave objects created when calling {@link #render_notation}. + * Addressing scheme: [measure_n][staff_n] + * @property {Vex.Flow.Stave[][]} rendered_measures + */ + rendered_measures: null, + /** + * Main rendering function. + * @param {XMLDocument} xmlDoc The MEI XML Document + * @param {Element} target An svg or canvas element + * @param {Number} width The width of the print space in pixels. Defaults to 800 (optional) + * @param {Number} height The height of the print space in pixels. Defaults to 350 (optional) + * @param {Number} backend Set to Vex.Flow.Renderer.Backends.RAPHAEL to + * render to a Raphael context; if falsy, Vex.Flow.Renderer.Backends.CANVAS + * is set (optional) + * @param {Object} options The options passed to the converter. For a list, see + * {@link MEI2VF.Converter#defaults} (optional) + */ + render_notation: function (xmlDoc, target, width, height, backend, options) { + var ctx; + var cfg = options || {}; -/** - * @property - */ -MEI2VF.rendered_measures = null; + ctx = new VF.Renderer(target, backend || VF.Renderer.Backends.CANVAS).getContext(); -/** - * Basic rendering function. Uses the m2v.Converter's prototype as a - * singleton. No scaling; page layout information in the MEI code is ignored. - * @param {XMLDocument} xmlDoc The MEI XML Document - * @param {XMLElement} target An svg or canvas element - * @param {Number} width The width of the print space in pixels - * @param {Number} height The height of the print space in pixels - * @param {Number} backend Set to Vex.Flow.Renderer.Backends.RAPHAEL to - * render to a Raphael context; if falsy, Vex.Flow.Renderer.Backends.CANVAS - * is set - * @param {Object} options The options passed to the converter. For a list, see - * {@link MEI2VF.Converter MEI2VF.Converter} - */ -MEI2VF.render_notation = function(xmlDoc, target, width, height, backend, options) { - var ctx; - var cfg = options || {}; + width = width || 800; + height = height || 350; - ctx = new Vex.Flow.Renderer(target, backend || Vex.Flow.Renderer.Backends.CANVAS).getContext(); - - width = width || 800; - height = height || 350; - - if (+backend === Vex.Flow.Renderer.Backends.RAPHAEL) { - ctx.paper.setSize(width, height); - } + if (+backend === VF.Renderer.Backends.RAPHAEL) { + ctx.paper.setSize(width, height); + } - cfg.page_width = width; + cfg.page_width = width; - this.Converter.initConfig(cfg); - this.Converter.process(xmlDoc[0] || xmlDoc); - this.Converter.draw(ctx); - this.rendered_measures = this.Converter.getAllVexMeasureStaffs(); + this.Converter.initConfig(cfg); + this.Converter.process(xmlDoc[0] || xmlDoc); + this.Converter.draw(ctx); + this.rendered_measures = this.Converter.getAllVexMeasureStaffs(); -}; + } + }; + }(MEI2VF || {}, MeiLib, Vex.Flow, jQuery));