Annotations
===========

Annotations are read-only lines of text underneath each line of editable text. 
An annotation may consist of multiple lines separated by '\n'. 
Annotations can be used to display an assembler version of code for debugging 
or to show diagnostic messages inline or to line up different versions of text 
in a merge tool.

Each annotation is referenced by its line.

.. method:: gtkscintilla.Scintilla.annotate(line, text, style=None)

    This annotate a text at the line *line*
    *text* can be:
    
     * A string
     * An instance of :class:`gtkscintilla.StyledText`
    
    If text is a string you can also specify a style_id that will be applied to
    the text.
   
.. method:: gtkscintilla.Scintilla.get_annotation(line)
 
    This returns the text of the annotation at *line*.
   
   
.. method:: gtkscintilla.Scintilla.get_styled_annotation(line)

   Same as :meth:`gtkscintilla.Scintilla.get_annotation` but returns a
   :class:`gtkscintilla.StyledText` instance.
   
.. method:: gtkscintilla.Scintilla.del_annotation(line)

    Remove the annotation at *line*.
    
.. method:: gtkscintilla.Scintilla.annotation_set_display(visible)

.. method:: gtkscintilla.Scintilla.annotation_get_display()

    Annotations can be made visible in a view and there is a choice of display 
    style when visible. The two methods set and get the annotation display mode. 
    The visible argument can be one of:
    
    +--------------------+---+----------------------------------------------+
    |ANNOTATION_HIDDEN   | 0 | Annotations are not displayed.               |
    +--------------------+---+----------------------------------------------+
    |ANNOTATION_STANDARD | 1 | Annotations are drawn left justified with no |
    |                    |   | adornment.                                   |
    +--------------------+---+----------------------------------------------+
    |ANNOTATION_BOXED    | 2 | Annotations are indented to match the text   |
    |                    |   | and are surrounded by a box.                 |
    +--------------------+---+----------------------------------------------+
    
.. method:: gtkscintilla.Scintilla.annotation_set_style_offset(style)

.. method:: gtkscintilla.Scintilla.annotation_get_style_offset()

   Annotation styles may be completely separated from standard text styles 
   by setting a style offset. 
   For example, s.annotation_set_style_offset(512) 
   would allow the annotation styles to be numbered from 512 upto 767 so they 
   do not overlap styles set by lexers (or margins if margins offset is 256). 
   Each style number set with :meth:`gtkscintilla.Scintilla.annotate`
   has the offset added before looking up the style.