.. _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. 


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



.. 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** **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:: lilyAttached()

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

        .. method:: lilyEnd()

            returns a string (not LilyString) 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 (not LilyString) containing the lilypond output that comes before the note. 

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

            


Comment
-------



.. 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
    '^"hello"' 

    

    **Comment** **attributes**

        Attributes without Documentation: `position`, `text`

    **Comment** **properties**

        .. attribute:: lily

            No documentation. 


