.. _moduleEditorial:

music21.editorial
=================

.. WARNING: DO NOT EDIT THIS FILE: AUTOMATICALLY GENERATED. Edit the .py file directly

.. module:: music21.editorial

Editorial objects store comments and other meta-data associated with specific :class:`~music21.note.Note` objects or other music21 objects.




.. function:: getObjectsWithEditorial(listToSearch, editorialStringToFind, listOfValues=None)


    provided a list of objects (typically note objects) to search through, this method returns
    only those objects that have the editorial attribute defined by the editorialStringToFind.
    An optional parameter, listOfValues, is a list of all the possible values the given
    object's editorialString can have.

    the editorialStringToFind can be any of the pre-defined editorial attributes (such as "ficta" or "harmonicIntervals")
    but it may also be the dictionary key of editorial notes stored in the miscellaneous (misc) dictionary.
    For example, "isPassingTone" or "isNeighborTone"



    >>> from music21 import *
    >>> n1 = note.Note()
    >>> n1.editorial.misc['isPassingTone'] = True
    >>> n2 = note.Note()
    >>> n2.editorial.comment = 'consider revising'
    >>> s = stream.Stream()
    >>> s.repeatAppend(n1, 5)
    >>> s.repeatAppend(note.Note(), 2)
    >>> s.repeatAppend(n2, 3)
    >>> listofNotes = s.getElementsByClass(note.Note)
    >>> listOfValues = ['consider revising', 'remove']
    >>> listofNotesWithEditorialisPassingTone = editorial.getObjectsWithEditorial(listofNotes, "isPassingTone")
    >>> listofNotesWithEditorialComment = editorial.getObjectsWithEditorial(listofNotes, "comment", listOfValues)
    >>> print len(listofNotesWithEditorialisPassingTone)
    5
    >>> print len(listofNotesWithEditorialComment)
    3



NoteEditorial
-------------

Inherits from: :class:`~music21.base.JSONSerializer`

.. class:: NoteEditorial()

    Editorial comments and special effects that can be applied to notes
    Standard ones are stored as attributes.  Non-standard/one-off effects are
    stored in the dict called "misc":



    >>> from music21 import *
    >>> a = editorial.NoteEditorial()
    >>> a.color = "blue"  # a standard editorial effect
    >>> a.misc['backgroundHighlight'] = 'yellow'  # non-standard.


    Every GeneralNote object already has a NoteEditorial object
    attached to it at object.editorial.  Normally you will just change that
    object instead.

    For instance, take the case where a scribe
    wrote F in the score, knowing that a good singer would automatically
    sing F-sharp instead.  We can store the editorial
    suggestion to sing F-sharp as a "musica ficta" accidental object:




    >>> fictaSharp = pitch.Accidental("Sharp")
    >>> n = note.Note("F")
    >>> n.editorial.ficta = fictaSharp
    >>> n.show('lily.png')  # only Lilypond currently supports musica ficta





    .. image:: images/noteEditorialFictaSharp.*
            :width: 103





    **NoteEditorial** **attributes**

        .. attribute:: comment

            a reference to a :class:`~music21.editorial.Comment` object


        .. attribute:: ficta

            a :class:`~music21.pitch.Accidental` object that specifies musica ficta for the note.  Will only be displayed in LilyPond and then only if there is no Accidental object on the note itself


        .. attribute:: melodicInterval

            an :class:`~music21.interval.Interval` object that specifies the melodic interval to the next note in this part/voice/stream, etc.


        .. attribute:: color

            the color of the note (x11 colors and extended x11colors are allowed), only displays properly in lilypond


        .. attribute:: melodicIntervalOverRests

            same as melodicInterval but ignoring rests; MIGHT BE REMOVED SOON


        .. attribute:: misc

            A dict to hold anything you might like to store.


        .. attribute:: hidden

            boolean value about whether to hide the note or not (only works in lilypond)


        .. attribute:: melodicIntervals

            a list for storing more than one melodic interval


        .. attribute:: harmonicIntervals

            a list for when you want to store more than one harmonicInterval


        .. attribute:: harmonicInterval

            an :class:`~music21.interval.Interval` object that specifies the harmonic interval between this note and a single other note (useful for storing information post analysis


        .. attribute:: melodicIntervalsOverRests

            same thing but a list


    **NoteEditorial** **properties**

        Properties inherited from :class:`~music21.base.JSONSerializer`: :attr:`~music21.base.JSONSerializer.json`

    **NoteEditorial** **methods**

        .. method:: colorLilyStart()


            returns \color "theColorName" -- called out so it is more easily subclassed



        .. method:: fictaLilyStart()


            returns \ficta -- called out so it is more easily subclassed



        .. method:: jsonAttributes()

            Define all attributes of this object that should be JSON serialized for storage and re-instantiation.



        .. method:: lilyAttached()

            returns any information that should be attached under the note,
            currently just returns self.comment.lily or ""


        .. method:: lilyEnd()


            returns a string of editorial lily
            instructions to come after the note.  Currently it is
            just info to turn off hidding of notes.



        .. method:: lilyStart()


            A method that returns a string containing the
            lilypond output that comes before the note.



            >>> from music21 import *
            >>> n = note.Note()
            >>> n.editorial.lilyStart()
            u''
            >>> n.editorial.ficta = pitch.Accidental("Sharp")
            >>> n.editorial.color = "blue"
            >>> n.editorial.hidden = True
            >>> print n.editorial.lilyStart()
            \ficta \color "blue" \hideNotes




        Methods inherited from :class:`~music21.base.JSONSerializer`: :meth:`~music21.base.JSONSerializer.jsonComponentFactory`, :meth:`~music21.base.JSONSerializer.jsonPrint`, :meth:`~music21.base.JSONSerializer.jsonRead`, :meth:`~music21.base.JSONSerializer.jsonWrite`


Comment
-------

Inherits from: :class:`~music21.base.JSONSerializer`

.. class:: Comment()


    an object that adds text above or below a note:



    >>> from music21 import *
    >>> n = note.Note()
    >>> n.editorial.comment.text = "hello"
    >>> n.editorial.comment.position = "above"
    >>> n.editorial.comment.lily
    u'^"hello"'




    **Comment** **attributes**

        Attributes without Documentation: `position`, `text`

    **Comment** **properties**

        .. attribute:: lily

            No documentation.


        Properties inherited from :class:`~music21.base.JSONSerializer`: :attr:`~music21.base.JSONSerializer.json`

    **Comment** **methods**

        Methods inherited from :class:`~music21.base.JSONSerializer`: :meth:`~music21.base.JSONSerializer.jsonAttributes`, :meth:`~music21.base.JSONSerializer.jsonComponentFactory`, :meth:`~music21.base.JSONSerializer.jsonPrint`, :meth:`~music21.base.JSONSerializer.jsonRead`, :meth:`~music21.base.JSONSerializer.jsonWrite`


