Skip to main content ↑ ↓
Topic: Documentation for the User Tools API (Read 13178 times) previous topic - next topic

Documentation for the User Tools API

Is there a detailed and comprehensive document describing the User Tools Application Programming Interface?

I am slowly getting the hang of it but I keep encountering new (to me) elements; ArticulationsOnStem is the my latest and in this case I still havn't worked out when it occurs and what effect it has.

On this basis, writing robust User Tool code is a rather uncertain business.

-- Brian

Re: Documentation for the User Tools API

Reply #1 –
G'day Brian,
I don't recall any specific documentation like you describe, but as you will have installed the starter kit you'll have a tool called:
"Variable Dump for Developers (nwsw)"
This will give you a real starting point.

You can also copy and paste to a text editor like Notepad - this will let you see the "clip" structure.

BTW, welcome to the forum.
I plays 'Bones, crumpets, coronets, floosgals, youfonymums 'n tubies.

Re: Documentation for the User Tools API

Reply #2 –
Lawrie,

Indeed, I have found "Variable Dump for Developers (nwsw)" very instructive but of course it only shows the elements I have included in my clip. No doubt I shall discover them all eventually; I was hoping for a quicker and more reliable route.

-- Brian

Re: Documentation for the User Tools API

Reply #3 –
If you select any single object in the notation editor, you can use Copy and Paste into a notepad (or other text window) to get a superset that includes most of the text parameters for that object. This only works for single object copy and paste, but it can be useful when drilling down into the format.

Re: Documentation for the User Tools API

Reply #4 –
ArticulationsOnStem is an Opts flag that may appear on these objects:
  • Note
  • Chord
  • RestChord

It automatically set when a RestChord is created. It is set/unset by the 'Use stem for articulations' CheckBox on the Notes Tab of the Properties... page.

It's stated purpose (from the help file) is:
Quote from: IDH_STEMARTICULATION
When set, any articulations added to the note or chord will appear on the stem side of the note, rather than at the notehead. If the selected note is part of a beam, you might also want to override the note's stem length in order to have any articulations properly appear near the end of the note stem.

An example of its effect:
Quote
!NoteWorthyComposerClip(2.0,Single)
|Chord|Dur:8th|Pos:8|Opts:Stem=Up,Beam=First|Dur2:4th|Pos2:1
|Note|Dur:8th,Accent|Pos:6|Opts:Stem=Up,Beam=End
|Chord|Dur:8th|Pos:8|Opts:Stem=Up,Beam=First|Dur2:4th|Pos2:1
|Note|Dur:8th,Accent|Pos:6|Opts:Stem=Up,Beam=End,ArticulationsOnStem
|Chord|Dur:8th|Pos:8|Opts:Stem=Up,Beam=First|Dur2:4th|Pos2:1
|Note|Dur:8th,Accent|Pos:6|Opts:Stem=Up,StemLength=6,Beam=End,ArticulationsOnStem
!NoteWorthyComposerClip-End

See Tidy.js for a JScript example of how to remove ArticulationsOnStem when it is not needed.

A potential problem is exposed by this clip:
Quote
!NoteWorthyComposerClip(2.0,Single)
|Tempo|Tempo:16|Text:"\|Pos:9"|Pos:10|Wide:Y
|Text|Text:"\|Pos:9"|Font:StaffItalic|Pos:8|Wide:Y
|Instrument|Name:"\|Pos:9"|Trans:0|DynVel:10,30,45,60,75,92,108,127|Pos:8|Wide:Y
!NoteWorthyComposerClip-End
Any routines you write must be able to ignore the contents of Text: and Name: fields to be able to return the proper values. In PHP, this is handled by the supplied libraries in the Tool Kit.
Registered user since 1996