Package org.jjazz.phrase.api

Class Phrase

java.lang.Object
org.jjazz.phrase.api.Phrase
All Implemented Interfaces:
Serializable, Iterable<NoteEvent>, Collection<NoteEvent>, NavigableSet<NoteEvent>, Set<NoteEvent>, SortedSet<NoteEvent>
Direct Known Subclasses:
SizedPhrase, SourcePhrase
public class Phrase extends Object implements Collection<NoteEvent>, SortedSet<NoteEvent>, NavigableSet<NoteEvent>, Serializable
A collection of NoteEvents that are kept sorted by start position.

Fire change events when modified, see the PROP_* values. Fire undoable events.

See Also:

  • Field Details

    • PROP_NOTES_ADDED

      public static final String PROP_NOTES_ADDED
      newValue=collection of added NoteEvents.
      See Also:

    • PROP_NOTES_ADDED_ADJUSTING

      public static final String PROP_NOTES_ADDED_ADJUSTING
      Same as PROP_NOTES_ADDED except this notifies an intermediate operation: a final non-adjusting operation will occur later.
      See Also:

    • PROP_NOTES_REMOVED

      public static final String PROP_NOTES_REMOVED
      newValue=collection of removed NoteEvents.
      See Also:

    • PROP_NOTES_REMOVED_ADJUSTING

      public static final String PROP_NOTES_REMOVED_ADJUSTING
      Same as PROP_NOTES_REMOVED except this notifies an intermediate operation: a final non-adjusting operation will occur later.
      See Also:

    • PROP_NOTES_MOVED

      public static final String PROP_NOTES_MOVED
      newValue=a map with keys=OldNoteEvents and values=NewNoteEvents
      See Also:

    • PROP_NOTES_MOVED_ADJUSTING

      public static final String PROP_NOTES_MOVED_ADJUSTING
      Same as PROP_NOTES_MOVED except this notifies an intermediate operation: a final non-adjusting operation will occur later.
      See Also:

    • PROP_NOTES_REPLACED

      public static final String PROP_NOTES_REPLACED
      Fired when a new NoteEvent replaced another one.

      newValue=a map with keys=OldNoteEvents and values=NewNoteEvents

      See Also:

    • PROP_NOTES_REPLACED_ADJUSTING

      public static final String PROP_NOTES_REPLACED_ADJUSTING
      Same as PROP_NOTES_REPLACED except this notifies an intermediate operation: a final non-adjusting operation will occur later.
      See Also:

    • PARENT_NOTE

      public static final String PARENT_NOTE
      NoteEvent client property set when new NoteEvents are created from existing ones.
      See Also:

  • Constructor Details

    • Phrase

      public Phrase(int channel)
      Construct a new melodic phrase.
      Parameters:
      channel -

    • Phrase

      public Phrase(int channel, boolean isDrums)
      Construct a new melodic or drums phrase.
      Parameters:
      channel -
      isDrums -

  • Method Details

    • isDrums

      public boolean isDrums()
      Check if the phrase is for non-melodic instruments.
      Returns:

    • replace

      public void replace(NoteEvent oldNe, NoteEvent newNe)
      Replace a NoteEvent by another one.

      Same as removing old + adding new, except it only fires a PROP_NOTES_REPLACED change event.

      Parameters:
      oldNe -
      newNe -

    • replace

      public void replace(NoteEvent oldNe, NoteEvent newNe, boolean isAdjusting)
      Replace a NoteEvent by another one.

      Same as removing old + adding new, except it only fires a PROP_NOTES_REPLACED or PROP_NOTES_REPLACED_ADJUSTING change event.

      Parameters:
      oldNe -
      newNe -
      isAdjusting - If true fire a PROP_NOTES_REPLACED_ADJUSTING instead of PROP_NOTES_REPLACED

    • replaceAll

      public void replaceAll(Map<NoteEvent,NoteEvent> mapOldNew, boolean isAdjusting)
      Replace NoteEvents.

      Same as removing old + adding new, except it only fires a PROP_NOTES_REPLACED or PROP_NOTES_REPLACED_ADJUSTING change event.

      Parameters:
      mapOldNew - A map where keys=oldNoteEvents and values=newNoteEvents
      isAdjusting - If true fire a PROP_NOTES_REPLACED_ADJUSTING instead of PROP_NOTES_REPLACED

    • move

      public NoteEvent move(NoteEvent ne, float newPos)
      Move a NoteEvent.

      Same as removing the old one + adding copy at new position , except it only fires a PROP_NOTES_MOVED.

      Parameters:
      ne - Must belong to this phrase
      newPos -
      Returns:
      The new NoteEvent at newPos. Return ne if position unchanged.

    • move

      public NoteEvent move(NoteEvent ne, float newPos, boolean isAdjusting)
      Move a NoteEvent.

      Same as removing the old one + adding copy at new position , except it only fires a PROP_NOTES_MOVED or PROP_NOTES_MOVED_ADJUSTING

      Parameters:
      ne - Must belong to this phrase
      newPos -
      isAdjusting - If true fire a PROP_NOTES_MOVED_ADJUSTING instead of PROP_NOTES_MOVED
      Returns:
      The new NoteEvent at newPos. Return ne if position unchanged.

    • moveAll

      public Set<NoteEvent> moveAll(Map<NoteEvent,Float> mapNoteNewPos, boolean isAdjusting)
      Move NoteEvents.

      Same as removing the old one + adding copy at new position , except it only fires a PROP_NOTES_MOVED or PROP_NOTES_MOVED_ADJUSTING change event.

      Parameters:
      mapNoteNewPos - A map where keys=NoteEvents and values=new positions
      isAdjusting - If true fire a PROP_NOTES_MOVED_ADJUSTING instead of PROP_NOTES_MOVED
      Returns:
      The created NoteEvents at new positions.

    • add

      public void add(Phrase p)
      Clone NoteEvents from the specified Phrase and add them to this Phrase.
      Parameters:
      p -

    • add

      public void add(Phrase p, boolean doNotCloneNotes)
      Add a Phrase from the specified Phrase.
      Parameters:
      p -
      doNotCloneNotes - If true directly add the NoteEvents without cloning them -so client properties might be changed.

    • clone

      public Phrase clone()
      A deep clone: returned phrase contains clones of the original NoteEvents.
      Returns:

    • equalsNearPosition

      public boolean equalsNearPosition(Phrase p, float nearWindow)
      Compare the notes (pitch, velocity), but tolerate slight differences in position and duration.
      Parameters:
      p -
      nearWindow - Used to compare NoteEvents position and duration.
      Returns:
      See Also:
      • NoteEvent#equalsNearPosition(org.jjazz.phrase.api.NoteEvent, float)

    • getChannel

      public int getChannel()
      Returns:
      1-16

    • getNotes

      public List<NoteEvent> getNotes()

    • getNotes

      public List<NoteEvent> getNotes(Predicate<NoteEvent> tester, FloatRange range, boolean excludeUpperBound)
      Get the NoteEvents which match the tester and whose start position is in the [posFrom:posTo] or [posFrom:posTo[ range.
      Parameters:
      tester -
      range -
      excludeUpperBound -
      Returns:

    • getBeatRange

      public FloatRange getBeatRange()
      Get the beat range from start of first note to end of last note.
      Returns:
      FloatRange.EMPTY_FLOAT_RANGE if phrase is empty.

    • getProcessedPhrase

      public Phrase getProcessedPhrase(Predicate<NoteEvent> tester, Function<NoteEvent,NoteEvent> mapper)
      Get a new Phrase with only filtered notes processed by the specified mapper.

      Notes of the returned phrase will have their PARENT_NOTE client property set to:
      - source note's PARENT_NOTE client property if this property is not null, or
      - the source note from this phrase.

      Parameters:
      tester -
      mapper -
      Returns:

    • processNotes

      public void processNotes(Predicate<NoteEvent> tester, Function<NoteEvent,NoteEvent> mapper)
      Transform the notes which satisfy the specified tester.

      Once the mapper has produced a new NoteEvent, the old one is removed and the new one is added. Fire the PROP_NOTES_REPLACED change event.

      Parameters:
      tester - Process the NoteEvent which satisfy this tester.
      mapper - Transform each NoteEvent.

    • getProcessedPhraseVelocity

      public Phrase getProcessedPhraseVelocity(Function<Integer,Integer> f)
      Get a new phrase with notes velocity changed.

      Velocity is always maintained between 0 and 127. Notes of the returned phrase will have their PARENT_NOTE client property set to:
      - source note's PARENT_NOTE client property if this property is not null, or
      - the source note from this phrase

      Parameters:
      f - A function modifying the velocity.
      Returns:
      A new phrase

    • processVelocity

      public void processVelocity(Function<Integer,Integer> f)
      Change the velocity of all notes of this Phrase.

      Velocity is always maintained between 0 and 127. Fire the PROP_NOTES_REPLACED change event.

      Parameters:
      f - A function modifying the velocity.

    • getProcessedPhrasePitch

      public Phrase getProcessedPhrasePitch(Function<Integer,Integer> f)
      Get a new phrase with all notes changed.

      Pitch is always maintained between 0 and 127. Notes of the returned phrase will have their PARENT_NOTE client property set to:
      - source note's PARENT_NOTE client property if this property is not null, or
      - the source note from this phrase

      Parameters:
      f - A function modifying the pitch.
      Returns:
      A new phrase

    • processPitch

      public void processPitch(Function<Integer,Integer> f)
      Change the pitch of all notes of this Phrase.

      Pitch is always maintained between 0 and 127. Fire the PROP_NOTES_REPLACED change event.

      Parameters:
      f - A function modifying the pitch.

    • getLastEventPosition

      public float getLastEventPosition()
      Returns:
      0 If phrase is empty.

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • dump

      public void dump()

    • isAdjustingEvent

      public static boolean isAdjustingEvent(String propertyName)
      Check if propertyName corresponds to one of the adjusting events PROP_NOTES_ADDED_ADJUSTING, PROP_NOTES_REMOVED_ADJUSTING etc.
      Parameters:
      propertyName -
      Returns:

    • add

      public boolean add(NoteEvent ne)
      Add a NoteEvent.

      Fire a PROP_NOTES_ADDED event.

      Specified by:
      add in interface Collection<NoteEvent>
      Specified by:
      add in interface Set<NoteEvent>
      Parameters:
      ne -
      Returns:
      False if ne was already part of this Phrase.

    • add

      public boolean add(NoteEvent ne, boolean isAdjusting)
      Add a NoteEvent.

      Fire a PROP_NOTES_ADDED or PROP_NOTES_ADDED_ADJUSTING event.

      Parameters:
      ne -
      isAdjusting -
      Returns:

    • addAll

      public boolean addAll(Collection<? extends NoteEvent> collection, boolean isAdjusting)
      Add several NoteEvents.

      Fire a PROP_NOTES_ADDED_ADJUSTING or PROP_NOTES_ADDED change event.

      Parameters:
      collection -
      isAdjusting -
      Returns:

    • addAll

      public boolean addAll(Collection<? extends NoteEvent> collection)
      Add several NoteEvents.

      Fire a PROP_NOTES_ADDED event.

      Specified by:
      addAll in interface Collection<NoteEvent>
      Specified by:
      addAll in interface Set<NoteEvent>
      Parameters:
      collection -
      Returns:
      True if at least one element was added.

    • remove

      public boolean remove(Object o)
      Remove a NoteEvent.

      Fire a PROP_NOTES_REMOVED event

      Specified by:
      remove in interface Collection<NoteEvent>
      Specified by:
      remove in interface Set<NoteEvent>
      Parameters:
      o -
      Returns:
      The removed NoteEvent

    • remove

      public boolean remove(Object o, boolean isAdjusting)
      Remove a NoteEvent.

      Fire a PROP_NOTES_REMOVED or PROP_NOTES_REMOVED_ADJUSTING event.

      Parameters:
      o -
      isAdjusting -
      Returns:

    • clear

      public void clear()
      Specified by:
      clear in interface Collection<NoteEvent>
      Specified by:
      clear in interface Set<NoteEvent>

    • removeAll

      public boolean removeAll(Collection<?> collection)
      Remove elements.

      Fire a PROP_NOTES_REMOVED change event.

      Specified by:
      removeAll in interface Collection<NoteEvent>
      Specified by:
      removeAll in interface Set<NoteEvent>
      Parameters:
      collection -
      Returns:
      True if at least one element was removed.

    • removeAll

      public boolean removeAll(Collection<?> collection, boolean isAdjusting)

    • size

      public int size()
      Specified by:
      size in interface Collection<NoteEvent>
      Specified by:
      size in interface Set<NoteEvent>

    • isEmpty

      public boolean isEmpty()
      Specified by:
      isEmpty in interface Collection<NoteEvent>
      Specified by:
      isEmpty in interface Set<NoteEvent>

    • contains

      public boolean contains(Object o)
      Specified by:
      contains in interface Collection<NoteEvent>
      Specified by:
      contains in interface Set<NoteEvent>

    • iterator

      public Iterator<NoteEvent> iterator()
      Specified by:
      iterator in interface Collection<NoteEvent>
      Specified by:
      iterator in interface Iterable<NoteEvent>
      Specified by:
      iterator in interface NavigableSet<NoteEvent>
      Specified by:
      iterator in interface Set<NoteEvent>

    • toArray

      public Object[] toArray()
      Specified by:
      toArray in interface Collection<NoteEvent>
      Specified by:
      toArray in interface Set<NoteEvent>

    • toArray

      public <T> T[] toArray(T[] a)
      Specified by:
      toArray in interface Collection<NoteEvent>
      Specified by:
      toArray in interface Set<NoteEvent>

    • containsAll

      public boolean containsAll(Collection<?> c)
      Specified by:
      containsAll in interface Collection<NoteEvent>
      Specified by:
      containsAll in interface Set<NoteEvent>

    • retainAll

      public boolean retainAll(Collection<?> c)
      Specified by:
      retainAll in interface Collection<NoteEvent>
      Specified by:
      retainAll in interface Set<NoteEvent>

    • shiftAllEvents

      public void shiftAllEvents(float shiftInBeats)
      Shift all events.

      Parameters:
      shiftInBeats - The value added to each event's position.
      Throws:
      IllegalArgumentException - If an event's position become negative.

    • comparator

      public Comparator<? super NoteEvent> comparator()
      Specified by:
      comparator in interface SortedSet<NoteEvent>

    • subSet

      public SortedSet<NoteEvent> subSet(NoteEvent fromElement, NoteEvent toElement)
      Specified by:
      subSet in interface NavigableSet<NoteEvent>
      Specified by:
      subSet in interface SortedSet<NoteEvent>
      Returns:
      Return value is unmodifiable.

    • headSet

      public SortedSet<NoteEvent> headSet(NoteEvent toElement)
      Specified by:
      headSet in interface NavigableSet<NoteEvent>
      Specified by:
      headSet in interface SortedSet<NoteEvent>
      Returns:
      Return value is unmodifiable.

    • tailSet

      public SortedSet<NoteEvent> tailSet(NoteEvent fromElement)
      Specified by:
      tailSet in interface NavigableSet<NoteEvent>
      Specified by:
      tailSet in interface SortedSet<NoteEvent>
      Returns:
      Return value is unmodifiable.

    • first

      public NoteEvent first()
      Specified by:
      first in interface SortedSet<NoteEvent>

    • last

      public NoteEvent last()
      Specified by:
      last in interface SortedSet<NoteEvent>

    • lower

      public NoteEvent lower(NoteEvent e)
      Specified by:
      lower in interface NavigableSet<NoteEvent>

    • floor

      public NoteEvent floor(NoteEvent e)
      Specified by:
      floor in interface NavigableSet<NoteEvent>

    • ceiling

      public NoteEvent ceiling(NoteEvent e)
      Specified by:
      ceiling in interface NavigableSet<NoteEvent>

    • higher

      public NoteEvent higher(NoteEvent e)
      Specified by:
      higher in interface NavigableSet<NoteEvent>

    • pollFirst

      public NoteEvent pollFirst()
      Specified by:
      pollFirst in interface NavigableSet<NoteEvent>

    • pollLast

      public NoteEvent pollLast()
      Specified by:
      pollLast in interface NavigableSet<NoteEvent>

    • descendingSet

      public NavigableSet<NoteEvent> descendingSet()
      Specified by:
      descendingSet in interface NavigableSet<NoteEvent>
      Returns:
      Return value is unmodifiable.

    • descendingIterator

      public Iterator<NoteEvent> descendingIterator()
      Specified by:
      descendingIterator in interface NavigableSet<NoteEvent>
      Returns:
      Return value is unmodifiable.

    • subSet

      public NavigableSet<NoteEvent> subSet(NoteEvent fromElement, boolean fromInclusive, NoteEvent toElement, boolean toInclusive)
      Specified by:
      subSet in interface NavigableSet<NoteEvent>
      Returns:
      Return value is unmodifiable.

    • subSet

      public NavigableSet<NoteEvent> subSet(FloatRange range, boolean excludeUpperBound)
      A subset of all notes in the specified range.
      Parameters:
      range -
      excludeUpperBound -
      Returns:
      Return value is unmodifiable.

    • headSet

      public NavigableSet<NoteEvent> headSet(NoteEvent toElement, boolean inclusive)
      Specified by:
      headSet in interface NavigableSet<NoteEvent>
      Returns:
      Return value is unmodifiable.

    • tailSet

      public NavigableSet<NoteEvent> tailSet(NoteEvent fromElement, boolean inclusive)
      Specified by:
      tailSet in interface NavigableSet<NoteEvent>
      Returns:
      Return value is unmodifiable.

    • saveAsString

      public static String saveAsString(Phrase p)
      Save the specified Phrase as a string.

      Examples:
      - "[8|NoteEventStr0|NoteEventStr1]" means a meodic Phrase for channel 8 with 2 NoteEvents
      - "[drums_9|NoteEventStr0]" means a drums Phrase for channel 9 with 1 NoteEvent
      - "[0]" empty phrase on channel 0

      Parameters:
      p -
      Returns:
      See Also:

    • loadAsString

      public static Phrase loadAsString(String s) throws ParseException
      Create a Phrase from the specified string.

      Example: "[8|NoteEventStr0|NoteEventStr1]" means a meodic Phrase for channel 8 with 2 NoteEvents.
      Example: "[drums_8|NoteEventStr0|NoteEventStr1]" means a drums Phrase for channel 8 with 2 NoteEvents.

      Parameters:
      s -
      Returns:
      Throws:
      ParseException - If s is not a valid string.
      See Also:

    • getFloorNote

      public static NoteEvent getFloorNote(float pos)
      Create a NoteEvent limit to be used as a floor/min position as per NoteEvent.compareTo().

      For use with the subSet(), tailSet() etc. methods.

      Parameters:
      pos -
      Returns:

    • getCeilNote

      public static NoteEvent getCeilNote(float pos)
      Create a NoteEvent limit to be used as a ceil/max position as per NoteEvent.compareTo().

      For use with the subSet(), tailSet() etc. methods.

      Parameters:
      pos -
      Returns:

    • addPropertyChangeListener

      public void addPropertyChangeListener(PropertyChangeListener l)

    • removePropertyChangeListener

      public void removePropertyChangeListener(PropertyChangeListener l)

    • addUndoableEditListener

      public void addUndoableEditListener(UndoableEditListener l)

    • removeUndoableEditListener

      public void removeUndoableEditListener(UndoableEditListener l)