From 8764864c6a1adb3845e4cdbb3d38b1d7063de583 Mon Sep 17 00:00:00 2001 From: Raphael Voellmy Date: Thu, 26 Sep 2019 16:54:19 +0200 Subject: [PATCH] docs(readme): improve readme, add more tsdoc to the chord settings --- README.md | 197 +++++++++++++++++++++++++++++++++++++++++++++++- demo/index.html | 10 +-- src/svguitar.ts | 19 +++++ 3 files changed, 216 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index f6d537f..883d361 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# SVGuitar +# SVGuitar - JavaScript Guitar Chord Renderer [![styled with prettier](https://img.shields.io/badge/styled_with-prettier-ff69b4.svg)](https://github.com/prettier/prettier) [![Greenkeeper badge](https://badges.greenkeeper.io/alexjoverm/typescript-library-starter.svg)](https://greenkeeper.io/) @@ -8,16 +8,207 @@ [![Dev Dependencies](https://david-dm.org/omnibrain/svguitar/dev-status.svg)](https://david-dm.org/omnibrain/svguitar?type=dev) [![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release) +JavaScript (TypeScript) library to create beautiful SVG guitar chord charts directly in the browser. -JavaScript (TypeScript) library to create beautiful SVG guitar chord charts. +Demo: https://omnibrain.github.io/svguitar/ [ [source](https://github.com/omnibrain/svguitar/blob/master/demo/index.html) ] ### Getting Started +```html + + +
+ + + + + +``` + +Of course you can also add SVGuitar as a dependency to your project: + ```bash # Add the dependency to your project -npm install svguitar +npm install --save svguitar + +# or +yarn add svguitar +``` + +And then import it in your project: + +```javascript +import { SVGuitarChord } from 'svguitar' + +const chart = new SVGuitarChord('#chart') + +// draw the chart +chart.configure({/* configuration */}) + .chord({/* chord */}) + .draw(); ``` +## Usage + +For a full API documentation have a look at the [TypeScript documentation](https://omnibrain.github.io/svguitar/docs/). + +Here's an example usage: + +```javascript +new SVGuitarChord('#some-selector') + .chord({ + // array of [string, fret, label (optional)] + fingers: [ + [1, 2], + [2, 3], + [3, 3], + [6, 'x'] + ], + + // optional: barres for barre chords + barres: [ + { fromString: 5, toString: 1, fret: 1 }, + ], + }) + .configure({ + /** + * The number of strings + */ + strings: 6, + + /** + * The number of frets + */ + frets: 4, + /** + * The starting fret (first fret is 1) + */ + position: 1, + + /** + * These are the labels under the strings. Can be any string. + */ + tuning: [ 'E', 'A', 'D', 'G', 'B', 'E' ], + + /** + * The position of the fret label (eg. "3fr") + */ + fretLabelPosition: 'right', + + /** + * The font size of the fret label + */ + fretLabelFontSize: 38, + + /** + * The font size of the string labels + */ + tuningsFontSize: 28, + + /** + * Size of a nut relative to the string spacing + */ + nutSize: 0.65, + + /** + * Color of a finger / nut + */ + nutColor: '#000', + + /** + * Height of a fret, relative to the space between two strings + */ + fretSize: 1.5, + + /** + * The minimum side padding (from the guitar to the edge of the SVG) relative to the whole width. + * This is only applied if it's larger than the letters inside of the padding (eg the starting fret) + */ + sidePadding: 0.2, + + /** + * The font family used for all letters and numbers + */ + fontFamily: 'Arial, "Helvetica Neue", Helvetica, sans-serif', + + /** + * The title of the chart. Optional + */ + title: 'F# minor', + + /** + * Font size of the title. This is only the initial font size. If the title doesn't fit, the title + * is automatically scaled so that it fits. + */ + titleFontSize: 48, + + /** + * Space between the title and the chart + */ + titleBottomMargin: 0, + + /** + * Global color of the whole chart. Can be overridden with more specifig color settings such as + * @link titleColor or @link stringColor etc. + */ + color: '#000', + + /** + * Barre chord rectangle border radius relative to the nutSize (eg. 1 means completely round endges, 0 means not rounded at all) + */ + barreChordRadius: 0.25, + + /** + * Size of the Xs and Os above empty strings relative to the space between two strings + */ + emptyStringIndicatorSize: 0.6, + + /** + * Global stroke width + */ + strokeWidth: 2, + + /** + * The width of the top fret (only used if position is 1) + */ + topFretWidth: 10, + + /** + * The color of the title (overrides color) + */ + titleColor: '#000000', + /** + * The color of the strings (overrides color) + */ + stringColor: '#000000', + /** + * The color of the fret position (overrides color) + */ + fretLabelColor: '#000000', + /** + * The color of the tunings (overrides color) + */ + tuningsColor: '#000000', + /** + * The color of the frets (overrides color) + */ + fretColor: '#000000', + + }) + .draw(); +``` + +## Contribute + +Pull Requests are very welcome! ## Projects using SVGuitar diff --git a/demo/index.html b/demo/index.html index cb8071a..85dee88 100644 --- a/demo/index.html +++ b/demo/index.html @@ -20,6 +20,8 @@

SVGuitar Demo

Demo page for SVGuitar. Try to create some SVGs here.

+

For a more elaborate chord editor that also uses SVGuitar check out ChordPic.

+ TypeScript Documentation @@ -104,7 +106,7 @@

Result

} var initialChord = { - // array of [string, fret, label (optional)] + // array of [string, fret | 'x' | 0] fingers: [ [1, 2], [2, 3], @@ -112,16 +114,10 @@

Result

[6, 'x'] ], - // optional: position marker - position: 5, // start render at fret 5 - // optional: barres for barre chords barres: [ { fromString: 5, toString: 1, fret: 1 }, ], - - // optional: tuning keys - tuning: ['E', 'A', 'D', 'G', 'B', 'E'] } $('#chord-input').val(JSON.stringify(initialChord, null, 2)) diff --git a/src/svguitar.ts b/src/svguitar.ts index e0b59a9..8de10a7 100644 --- a/src/svguitar.ts +++ b/src/svguitar.ts @@ -109,10 +109,29 @@ export interface ChordSettings { */ color: string + /** + * The color of the title (overrides color) + */ titleColor?: string + + /** + * The color of the strings (overrides color) + */ stringColor?: string + + /** + * The color of the fret position (overrides color) + */ fretLabelColor?: string + + /** + * The color of the tunings (overrides color) + */ tuningsColor?: string + + /** + * The color of the frets (overrides color) + */ fretColor?: string /**