Package org.jjazz.chordleadsheet.api

Interface ChordLeadSheet

public interface ChordLeadSheet
The model for a chord leadsheet.

The leadsheet is made of sections (a name + a time signature) and items like chord symbols. Implementation must fire the relevant ClsChangeEvents when a method mutates the chord leadsheet.

Regarding sections:
- The first bar must always contain a section
- 2 sections can't have the same name

  • Field Details

  • Method Details

    • addItem

      void addItem(ChordLeadSheetItem<?> item)
      Add an item to the leadsheet.

      Item position might be adjusted to the bar's TimeSignature. This will set the item's container to this ChordLeadSheet.

      Parameters:
      item - The ChordLeadSheetItem to add.
      Throws:
      IllegalArgumentException - If item's position out of leadsheet bounds or item is a section.

    • removeItem

      void removeItem(ChordLeadSheetItem<?> item)
      Remove an item from the leadsheet.
      Parameters:
      item - The item to be removed.
      Throws:
      IllegalArgumentException - If no such item or item is a section.

    • addSection

      void addSection(CLI_Section section) throws UnsupportedEditException
      Add a section to the leadsheet.

      Trailing items' position might be adjusted if it results in a time signature change.

      Parameters:
      section -
      Throws:
      IllegalArgumentException - If section already exists at specified position or invalid section.
      UnsupportedEditException - If a ChordLeadSheet change listener does not authorize this edit. Exception is thrown before any change is done.

    • removeSection

      void removeSection(CLI_Section section) throws UnsupportedEditException
      Remove a section from the leadsheet.

      The section on bar 0 can not be removed. Trailing items' position might be adjusted if it results in a time signature change.

      Parameters:
      section -
      Throws:
      UnsupportedEditException - If a ChordLeadSheet change listener does not authorize this edit. Exception is thrown before any change is done.

    • setSectionName

      void setSectionName(CLI_Section section, String name)
      Change the name of section.
      Parameters:
      section - The section to be changed.
      name -
      Throws:
      IllegalArgumentException - If name already exist, is a reserved name, or section does not belong to this leadsheet.

    • setSectionTimeSignature

      void setSectionTimeSignature(CLI_Section section, TimeSignature ts) throws UnsupportedEditException
      Change the TimeSignature of a section.

      Trailing items' position might be adjusted to fit the new TimeSignature.

      Parameters:
      section - The section to be changed.
      ts -
      Throws:
      IllegalArgumentException - If section does not belong to this leadsheet.
      UnsupportedEditException - If a ChordLeadSheet change listener does not authorize this edit. Exception is thrown before any change is done.

    • moveSection

      void moveSection(CLI_Section section, int newBarIndex) throws UnsupportedEditException
      Move a section to a new position.

      New position must be free of a section. Section on first bar can not be moved. Some items position might be adjusted to the new bar's TimeSignature.

      Parameters:
      section - The section to be moved
      newBarIndex - The bar index section will be moved to
      Throws:
      UnsupportedEditException - If a ChordLeadSheet change listener does not authorize this edit. Exception is thrown before any change is done.
      IllegalArgumentException - If new position is not valid.

    • moveItem

      void moveItem(ChordLeadSheetItem<?> item, Position pos)
      Move an item to a new position.

      Can not be used on a Section. Item position might be adjusted to the bar's TimeSignature.

      Parameters:
      item - The item to be moved
      pos - The new position.
      Throws:
      IllegalArgumentException - If new position is not valid.

    • contains

      boolean contains(ChordLeadSheetItem<?> item)
      Test if specified item belongs to this object.
      Parameters:
      item -
      Returns:

    • changeItem

      <T> void changeItem(ChordLeadSheetItem<T> item, T data)
      Change the data of a specific item.

      Can not be used on Section, use setSectionName() or setSectionTimeSignature() instead.

      Type Parameters:
      T -
      Parameters:
      item -
      data -

    • insertBars

      void insertBars(int barIndex, int nbBars)
      Insert bars from a specific position.

      If there are bars after barIndex, they are shifted accordingly.

      Parameters:
      barIndex - The bar index from which to insert the new bars.
      nbBars - The number of bars to insert.
      Throws:
      IllegalArgumentException - If barIndex < 0 or barIndex > size()

    • deleteBars

      void deleteBars(int barIndexFrom, int barIndexTo) throws UnsupportedEditException
      Delete bars and items from barIndexFrom to barIndexTo (inclusive).

      Bars after the deleted bars are shifted accordingly. Trailing items positions might be adjusted if it results in a time signature change.

      Parameters:
      barIndexFrom -
      barIndexTo -
      Throws:
      UnsupportedEditException - If a ChordLeadSheet change listener does not authorize this edit. IMPORTANT:some undoable changes might have been done before exception is thrown, caller will need to rollback them.

    • cleanup

      void cleanup()
      Cleanup function to be called so that the object can be garbaged.

    • getItems

      <T extends ChordLeadSheetItem<?>> List<T> getItems(Position posFrom, boolean inclusiveFrom, Position posTo, boolean inclusiveTo, Class<T> itemClass, Predicate<T> tester)
      Get the matching items whose position is in the position range.
      Type Parameters:
      T -
      Parameters:
      posFrom -
      inclusiveFrom -
      posTo -
      inclusiveTo -
      itemClass - Accept items which are instance of class itemClass
      tester - Accept items which satisfy the tester.
      Returns:
      A non-modifiable ordered list of items

    • getLastItemBefore

      <T extends ChordLeadSheetItem<?>> T getLastItemBefore(Position posTo, boolean inclusiveTo, Class<T> itemClass, Predicate<T> tester)
      Get the last matching item whose position is before (or equal, if inclusive is true) posHigh.
      Type Parameters:
      T -
      Parameters:
      posTo -
      inclusiveTo -
      itemClass - Accept items which are assignable from aClass
      tester -
      Returns:
      Can be null.

    • getFirstItemAfter

      <T extends ChordLeadSheetItem<?>> T getFirstItemAfter(Position posFrom, boolean inclusiveFrom, Class<T> itemClass, Predicate<T> tester)
      Get the first matching item whose position is after (or equal, if inclusive is true) posFrom.
      Type Parameters:
      T -
      Parameters:
      posFrom -
      inclusiveFrom -
      itemClass -
      tester -
      Returns:
      Can be null

    • getItems

      default List<ChordLeadSheetItem> getItems()
      Get all the items.
      Returns:
      A non-modifiable ordered list of items

    • getItems

      default <T extends ChordLeadSheetItem<?>> List<T> getItems(Class<T> itemClass)
      Get all the matching items of this leadsheet.
      Type Parameters:
      T -
      Parameters:
      itemClass - Accept items which are instance of class itemClass
      Returns:
      A non-modifiable ordered list of items

    • getItems

      default <T extends ChordLeadSheetItem<?>> List<T> getItems(Class<T> itemClass, Predicate<T> tester)
      Get all the matching items of this leadsheet.
      Type Parameters:
      T -
      Parameters:
      itemClass - Accept items which are instance of class itemClass
      tester - Accept items which satisfy the tester.
      Returns:
      A non-modifiable ordered list of items

    • getItems

      default <T extends ChordLeadSheetItem<?>> List<T> getItems(int barFrom, int barTo, Class<T> itemClass, Predicate<T> tester)
      Get the matching items which belong to bars between barFrom and barTo (included).

      Type Parameters:
      T -
      Parameters:
      barFrom -
      barTo -
      itemClass - Accept items which are instance of class aClass.
      tester - Accept items which satisfy the tester.
      Returns:
      A non-modifiable ordered list of items

    • getItems

      default <T extends ChordLeadSheetItem<?>> List<T> getItems(int barFrom, int barTo, Class<T> itemClass)
      Get the matching items which belong to bars between barFrom and barTo (included).

      Type Parameters:
      T -
      Parameters:
      barFrom -
      barTo -
      itemClass - Accept items which are instance of class aClass.
      Returns:
      A non-modifiable ordered list of items

    • getItemsAfter

      default <T extends ChordLeadSheetItem<?>> List<T> getItemsAfter(Position posFrom, boolean inclusive, Class<T> itemClass, Predicate<T> tester)
      Get the matching items whose position is after (or equal, if inclusive is true) posLow.
      Type Parameters:
      T -
      Parameters:
      posFrom -
      inclusive -
      itemClass - Accept items which are instance of class itemClass
      tester - Accept items which satisfy the tester.
      Returns:
      A non-modifiable ordered list of items

    • getItemsBefore

      default <T extends ChordLeadSheetItem<?>> List<T> getItemsBefore(Position posTo, boolean inclusive, Class<T> itemClass, Predicate<T> tester)
      Get the matching items whose position is before (or equal, if inclusive is true) posTo.
      Type Parameters:
      T -
      Parameters:
      posTo -
      inclusive -
      itemClass - Accept items which are instance of class itemClass. Can't be null.
      tester - Accept items which satisfy the tester.
      Returns:
      A non-modifiable ordered list of items

    • getItems

      default <T extends ChordLeadSheetItem<?>> List<T> getItems(CLI_Section cliSection, Class<T> itemClass, Predicate<T> tester)
      Get the matching items which belong to a specific section.

      Type Parameters:
      T -
      Parameters:
      cliSection -
      itemClass - Accept items which are instance of class aClass
      tester - Accept items which satisfy the tester.
      Returns:
      A non-modifiable ordered list of items

    • getItems

      default <T extends ChordLeadSheetItem<?>> List<T> getItems(CLI_Section cliSection, Class<T> itemClass)
      Get the items which belong to a specific section.

      Type Parameters:
      T -
      Parameters:
      cliSection -
      itemClass - Accept items which are instance of class aClass
      Returns:
      A non-modifiable ordered list of items

    • getBarFirstItem

      default <T extends ChordLeadSheetItem<?>> T getBarFirstItem(int barIndex, Class<T> itemClass, Predicate<T> tester)
      Get the first matching item in the specified bar.
      Type Parameters:
      T -
      Parameters:
      barIndex -
      itemClass -
      tester -
      Returns:
      Can be null

    • getBarLastItem

      default <T extends ChordLeadSheetItem<?>> T getBarLastItem(int barIndex, Class<T> itemClass, Predicate<T> tester)
      Get the last matching item in the specified bar.
      Type Parameters:
      T -
      Parameters:
      barIndex -
      itemClass -
      tester -
      Returns:
      Can be null

    • getNextItem

      default <T> ChordLeadSheetItem<T> getNextItem(ChordLeadSheetItem<T> item)
      Get the next similar item (same class or subclass) after the specified item.
      Type Parameters:
      T -
      Parameters:
      item -
      Returns:
      Can be null if item is the last item of its kind.

    • getPreviousItem

      default <T> ChordLeadSheetItem<T> getPreviousItem(ChordLeadSheetItem<T> item)
      Get the previous similar item (same class or subclass) before the specified item.
      Type Parameters:
      T -
      Parameters:
      item -
      Returns:
      Can be null if item is the first item of its kind.

    • getSection

      default CLI_Section getSection(int barIndex)
      Get the Section of a specific bar.

      If the bar is after the end of the leadsheet, return the section of the last bar.

      Parameters:
      barIndex - The index of the bar.
      Returns:
      The section.

    • getSection

      default CLI_Section getSection(String sectionName)
      Get a CLI_Section from its name.
      Parameters:
      sectionName -
      Returns:
      The section or null if not found.

    • getSizeInBars

      int getSizeInBars()
      Get the size of the leadsheet in bars.
      Returns:

    • getBarRange

      default IntRange getBarRange()
      Get the bar range of this chord leadsheet.
      Returns:
      [0; getSizeInBars()-1]

    • getBarRange

      default IntRange getBarRange(CLI_Section cliSection)
      The bar range of the specified section.
      Parameters:
      cliSection -
      Returns:
      Throws:
      IllegalArgumentException - If section does not exist in this ChordLeadSheet.

    • setSizeInBars

      void setSizeInBars(int size) throws UnsupportedEditException
      Set the size of the ChordLeadSheet.
      Parameters:
      size - The numbers of bars, must be >= 1 and < MAX_SIZE.
      Throws:
      UnsupportedEditException - If a ChordLeadSheet change listener does not authorize this edit. Exception is thrown before any change is done.

    • addClsChangeListener

      void addClsChangeListener(ClsChangeListener l)
      Add a listener to item changes of this object.
      Parameters:
      l -

    • removeClsChangeListener

      void removeClsChangeListener(ClsChangeListener l)
      Remove a listener to this object's changes.
      Parameters:
      l -

    • addUndoableEditListener

      void addUndoableEditListener(UndoableEditListener l)
      Add a listener to undoable edits.
      Parameters:
      l -

    • removeUndoableEditListener

      void removeUndoableEditListener(UndoableEditListener l)
      Remove a listener to undoable edits.
      Parameters:
      l -