widget

This widget allows for creation of scalable piano controls.
Note that this is a purely graphical control that produces no
sound on it’s own. It is meant to be attached to a musical engine
such as a MIDI playback library.

message

noteOn pNoteNum, pNoteName

on noteOn pNoteNum,pNoteName
	put "noteOn " & pNoteNum && pNoteName
end noteOn

Handle the message in the widget’s object script to respond to
‘note down’ clicks on the piano’s individual note keys.

message

noteOff pNoteNum, pNoteName

on noteOff pNoteNum,pNoteName
	put "noteOff " & pNoteNum && pNoteName
end noteOff

Handle the message in the widget’s object script to respond to
‘note release’ messages from the piano’s individual note keys.

property

get the borderWidth of widget

set the borderWidth of widget to number

The property controls thickness of lines used to draw the
widget’s piano keys outlines.

property

set the borderColor of widget to color

get the borderColor of widget

The property controls the color used to draw the outlinnes of the piano keys.

property

get the accidentalsColor of widget

set the accidentalsColor of widget to color

The property controls the default color used to fill
the piano’s accidentals (black) keys. This property is the same as

property

get the blackKeysColor of widget

set the blackKeysColor of widget to color

The property controls the default color used to fill
the piano’s accidentals (black) keys. This property is the same as

property

get the whiteKeysColor of widget

set the whiteKeysColor of widget to color

The property controls the default color used to fill
the piano’s naturals (white) keys. This property is the same as

property

get the naturalsColor of widget

set the naturalsColor of widget to color

The property controls the default color used to fill
the piano’s naturals (white) keys. This property is the same as

property

get the hiliteColor of widget

set the hiliteColor of widget to color

The property controls the color used to draw the
widget’s piano key fill color while hilighted.

property

get the colorNotes of widget

set the colorNotes of widget to pColorsSpaceNotesPairedLineList

on mouseUp
  -- clear all keys individual color settings:
  set the colorNotes of widget "Piano Widget" to reset
  -- set color white and 50% transparency for ALL C# keys, MIDI note 60, D#4 (same as Eb4), Gb 5th octave
  -- and then also set color to 50% grey, no transparency, for all Ab/G# keys:
  set the colorNotes of widget "Piano Widget" to "255,255,255,127 C#,60,D#4,F#Gb5" & 
   cr & "127,127,127,255 G#"
  put the colorNotes of widget "Piano Widget"
end mouseUp

The property can be used to set colors for individual
piano keys using the format R,G,B,A followed by a comma delimited list
of keys, by MIDI note numbers or note names, seperated by a single space.
If a note name is used without an octave number then that note is colorized
on all 10.5 octaves. Set the to empty, reset or pass an empty
string to clear all key colorization, reverting key colors to those
specified by the / and

/ properties.
Multiple lines of color and note-lists can be set, any duplicates
will ovewrite previously set colorKeys.
The property returns a line delimited list of RGBA, blank space, with
a note number-list, followed by a space, and then the same note list
as note-names, for any keys that have been colorized.

property

get the hilitedNotes of widget

set the hilitedNotes of widget to pHilightNotes

on mouseUp
  -- clear all
  set the hilitedNotes of widget "Piano Widget" to empty
  -- hilte ALL C# keys, MIDI note 60, D#4 (same as Eb4), Gb 5th octave:
  set the hilitedNotes of widget "Piano Widget" to "C#,60,D#4,F#Gb5"
  put the hilitedNotes of widget "Piano Widget"
end mouseUp

The property can be used to set the piano keys
to hilite using a comma seperated list of keys, by MIDI note number or note name.
If a note name is used without an octave number then that note is
hilited on all 10.5 octaves.
Set to empty or pass an empty string to clear all key hilites.
The property returns the list as two lines,
Line one lists MIDI note numbers and the second line list same keys as note names.

lockToTonicWithScale

property

get the lockToTonicWithScale of widget

set the lockToTonicWithScale of widget to pRootAndScaleFormula

on mouseUp
  -- clear any previously set scale:
  set the lockToTonicWithScale of widget "Piano Widget" to empty
  -- the following form locks to a scale of the C,C#,D#,E keys enabled:
  set the lockToTonicWithScale of widget "Piano Widget" to "C 1,3,4"

  -- the following form sets to a same scale of the C,C#,D#,E keys enabled:
  set the lockToTonicWithScale of widget "Piano Widget" to "C H,W,h"

  get the lockToTonicWithScale of widget "Piano Widget"
  -- 'it' now contains "C,C#,D#,E"
end mouseUp

The property can be set to Root Note as a NoteName followed
by a space and then by a comma delimited list of either numeric offsets,
between 1 and 11 that represent half-steps from the root note, or using the
style H,W,WH (case insenstive) often used to describe musical scales or modes.
H meaning Halfstep, W for Wholestep, and combining H and W for Halfstep+Wholestep.
Piano keys that will be enabled are then determine from this root + formula pair
and any keys that are not in the resulting note-name list will be locked.
Set to empty to clear the scale and unlock all piano keys.
Getting the returns a comma delimited list of notes in the
scale, rather than the formula used, or empty. This returned list can then be
used with the property.

property

get the lockToScale of widget

set the lockToScale of widget to pNoteNamesList

on mouseUp
  -- clear any previously set scale:
  set the lockToScale of widget "Piano Widget" to empty
  --  and then lock all piano keys that are NOT in the list of Note Names,
  -- any octave number on the end of NoteNames will be ignored, and the full
  -- Sharp AND Flat NoteName will appear in the returned list
  set the lockToScale of widget "Piano Widget" to "C#,D#4,F#Gb,G#"
  get the lockToScale of widget "Piano Widget"
  -- 'it' now contains "C#Db,D#Eb,F#Gb,G#Ab"
end mouseUp

The property can be set to a comma delimited list of Note Names
(ie C#,D,Eb,A#Bb,etc.) any piano keys with note names that are NOT in the list
will be disabled. Use this property to lock the Piano to a musical scale.
Get the lockToScale property to see a list of notes that are currently enabled.
If no scale has been applied then the property will contain empty.

property

get the chordFormula of widget

set the chordFormula of widget to pChordFormula

on mouseUp
   -- keys will trigger a 1st-Inversion Major Triad Chord:
  set the chordFormula of widget "Piano Widget" -5,-8
end mouseUp

The property if optionally specified, can be set to a list
of integers to indicate which additional piano key(s) should be triggered
based on the half-step distance from the origin root key. For example,
to trigger the same note name as the root key but 1 octave lower set
this property to -12, for one octave lower and one octave higher set
this property to -12,12. To clear the current set it to empty.

property

set the chordPreset of widget to pChordPresetName

on mouseUp
   -- the chordFormula will be set to "3,7":
  set the chordPreset of widget "Piano Widget" to "Minor Triad"
end mouseUp

The is a convience property that can be set to a chord
name from a list of premade named . Use the
property to retreive a line delimited list of valid chord names.

is a “write-only” property, after a name is passed
and the is updated, this property is reset and returns “…”.

property

get the chordPresets of widget

on mouseUp
  put the chordPresets of widget "Piano Widget"
end mouseUp

Use the property to retreive a line delimited list of
valid names to use in conjunction with the property.

property

get the lowOctave of widget

set the lowOctave of widget to number

on mouseUp
  -- set the left most octave to start at MIDI Note Number 0 (C-1)
  set the lowOctave of widget "Piano Widget" to -1
  -- set the right most octave to start at MIDI Note Number 36 (C2)
  set the highOctave of widget "Piano Widget" to 2
  get the octaveCount of of widget "Piano Widget" -- octaveCount containss 4
end mouseUp

The property is used in conjunction with to
specify the visible note range of the piano’s keyboard by specifying the
starting octave and ending octave between -1 (which starts at MIDI note 0 C)
to 9 (Which starts at MIDI number 120 C and is actually 7/12th of an octave
ending at the MIDI Note 127 G). If lowOctave is greater than highOctave or
highOctave is less than lowOctave then the opposite property will
automatically be ajusted to match, resulting in a single octave range.

property

get the highOctave of widget

set the highOctave of widget to number

on mouseUp
  -- set the left most octave to start at MIDI Note Number 0 (C-1)
  set the lowOctave of widget "Piano Widget" to -1
  -- set the right most octave to start at MIDI Note Number 36 (C2)
  set the highOctave of widget "Piano Widget" to 2
  get the octaveCount of of widget "Piano Widget" -- octaveCount containss 4
end mouseUp

The property is used in conjunction with to
specify the visible note range of the piano’s keyboard by specifying the
starting octave and ending octave between -1 (which starts at MIDI note 0 C)
to 9 (Which starts at MIDI number 120 C and is actually 7/12th of an octave
ending at the MIDI Note 127 G). If lowOctave is greater than highOctave or
highOctave is less than lowOctave then the opposite property will
automatically be ajusted to match, resulting in a single octave range.

property

get the octaveCount of widget

on mouseUp
  -- set the left most octave to start at MIDI Note Number 0 (C-1)
  set the lowOctave of widget "Piano Widget" to -1
  -- set the right most octave to start at MIDI Note Number 36 (C2)
  set the highOctave of widget "Piano Widget" to 2
  get the octaveCount of of widget "Piano Widget" -- octaveCount containss 4
end mouseUp

The is a read-only property that returns the amount of
octaves that are currently visible on the Piano’s keyboard. It is the
same as the count from to .