Piano Widget

New and improved version 1.3

LiveCode Builder Piano Widget

A Graphical Piano Keyboard Widget written in LCB
This Widget is a graphical UI element only. It produces no sound on it’s own and is meant to be attached to a Musical-note play back engine of some kind. See my other GitHub Repos for LiveCode playback engines (for Apple devices so far). There is also a demo stack that uses simple sound playback that should work on any device that LiveCode supports.

Video Demo Here:

https://www.youtube.com/watch?v=xg7rBg8p2zQ&feature=youtu.be

Source Here:

https://github.com/PaulMcClernan/LCB_PianoWidget

Piano Widget

Type

widget

Summary
Widget is a virtual mouse piano
Description

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.


noteOn

Type

message

Syntax
noteOn pNoteNum, pNoteName
Summary
Sent when a key on the piano set to it’s ‘on’ state.
OS
Platforms
Parameters
Name Type Description
pNoteNum The MIDI note number(s) of the note key (exp. 63), this can be an item delimited list of multiple key numbers (chords)
pNoteName The Name of the note key (exp. D#Eb), this can be an item delimited list of multiple key numbers (chords)
Examples
on noteOn pNoteNum,pNoteName
	put "noteOn " & pNoteNum && pNoteName
end noteOn
Description

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

noteOff

Type

message

Syntax
noteOff pNoteNum, pNoteName
Summary
Sent when a key on the piano released from it’s ‘on’ state.
OS
Platforms
Parameters
Name Type Description
pNoteNum The MIDI note number(s) of the note key (exp. 63), this can be an item delimited list of multiple key numbers (chords)
pNoteName The Name of the note key (exp. D#Eb), this can be an item delimited list of multiple key names (chords)
Examples
on noteOff pNoteNum,pNoteName
	put "noteOff " & pNoteNum && pNoteName
end noteOff
Description

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


borderWidth

Type

property

Syntax
get the borderWidth of widget
set the borderWidth of widget to number
Summary
The stroke width for piano keys outlines
Description

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

borderColor

Type

property

Syntax
set the borderColor of widget to color
get the borderColor of widget
Summary
The color used to draw the outlinnes of the piano keys
Description

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


accidentalsColor

Type

property

Syntax
get the accidentalsColor of widget
set the accidentalsColor of widget to color
Synonyms
Summary
The fill color for accidentals (black) keys
Description

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

blackKeysColor

Type

property

Syntax
get the blackKeysColor of widget
set the blackKeysColor of widget to color
Synonyms
Summary
The fill color for accidentals (black) keys
Description

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

whiteKeysColor

Type

property

Syntax
get the whiteKeysColor of widget
set the whiteKeysColor of widget to color
Synonyms
Summary
The fill color for naturals (white) keys
Description

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

naturalsColor

Type

property

Syntax
get the naturalsColor of widget
set the naturalsColor of widget to color
Synonyms
Summary
The fill color for naturals (white) keys
Description

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


hiliteColor

Type

property

Syntax
get the hiliteColor of widget
set the hiliteColor of widget to color
Summary
The fill color when piano keys are hilited
Description

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

colorNotes

Type

property

Syntax
get the colorNotes of widget
set the colorNotes of widget to pColorsSpaceNotesPairedLineList
Summary
The colorNotes piano keys as line list or colors and note pairs
Examples
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
Description

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.

hilitedNotes

Type

property

Syntax
get the hilitedNotes of widget
set the hilitedNotes of widget to pHilightNotes
Summary
The hilighted piano keys as list of notes
Examples
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
Description

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

lockToTonicWithScale

Type

property

Syntax
get the lockToTonicWithScale of widget
set the lockToTonicWithScale of widget to pRootAndScaleFormula
Summary
lockToTonicWithScale are the piano keys that are enabled or empty if no scale
Examples
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
Description

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.

lockToScale

Type

property

Syntax
get the lockToScale of widget
set the lockToScale of widget to pNoteNamesList
Summary
lockToScale are the piano keys that are enabled or empty if no scale
Examples
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
Description

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.

chordFormula

Type

property

Syntax
get the chordFormula of widget
set the chordFormula of widget to pChordFormula
Summary
Specifies additional keys that each key should trigger
Examples
on mouseUp
   -- keys will trigger a 1st-Inversion Major Triad Chord:
  set the chordFormula of widget "Piano Widget" -5,-8
end mouseUp
Description

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.

chordPreset

Type

property

Syntax
set the chordPreset of widget to pChordPresetName
Summary
A name from a list of names of premade chordFormula
Examples
on mouseUp
   -- the chordFormula will be set to "3,7":
  set the chordPreset of widget "Piano Widget" to "Minor Triad"
end mouseUp
Description

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 “…”.

chordPresets

Type

property

Syntax
get the chordPresets of widget
Summary
Line delimited list of preset names of premade chordFormula
Examples
on mouseUp
  put the chordPresets of widget "Piano Widget"
end mouseUp
Description

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


lowOctave

Type

property

Syntax
get the lowOctave of widget
set the lowOctave of widget to number
Summary
The starting, left most octave for the piano’s visible note range
Examples
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
Description

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.

highOctave

Type

property

Syntax
get the highOctave of widget
set the highOctave of widget to number
Summary
The ending, right most octave for the piano’s visible note range
Examples
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
Description

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.

octaveCount

Type

property

Syntax
get the octaveCount of widget
Summary
The amount of octaves in the piano’s current visible note range.
Examples
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
Description

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 .