Annotations and text margins
Neil Hodgson
Annotations are read-only text attached as extra lines to document
lines. One use is for displaying the disassembled form of C++ code
following each line of C++ to help in low-level debugging. Merge tools
may wish to use this to line up the different versions being merged.
One submission called a similar feature 'false lines'. Compilation
errors can be shown after the problem code. For example,
http://www.scintilla.org/annotations.png
XCode has a similar feature
(http://www.scintilla.org/XCodeErrors.png) but it is more visually
distinctive and has some limited interaction ("More..."). While the
XCode appearance could be duplicated, I had a quick try and it got
quite messy so gave up. The Scintilla implementation allows styling of
individual characters.
Text margins allow the application to put arbitrary text in a
margin and this text can be styled either per line or per character.
http://www.scintilla.org/styledmargin.png
Additional features could be added in the future. Markers could be
assigned to annotation lines so that when debugging breakpoints and
the current instruction could be placed within disassembled lines.
Mouse clicks inside annotations could be reported to the application.
Annotations do not wrap and it is not possible to select annotation
text to be copied to the clipboard. This is deliberate since you want
to mainly be interacting with the document text but possibly there
should be some way (right click?) to grab the annotations. Only one
text margin is currently supported. Both annotations and margin text
are stored in the document object but the decision on whether they are
visible is made by the view.
The source code can be downloaded from
http://www.scintilla.org/scite_annotations.zip
The version of SciTE in the ZIP has been modified so that double
clicking on an error in the output pane will attempt to load messages
from the output pane as annotations. In the Find Dialog, Mark All will
display some text margins. These demonstrations use styles from 256 so
the following settings help:
style.cpp.256=back:#EFEFEF,fore:#000000,italics,font:Georgia
style.cpp.257=back:#EFEFEF,fore:#000000,font:Georgia
style.cpp.258=back:#FFFFF0,fore:#808000,italics,font:Georgia
style.cpp.259=back:#FFFFF0,fore:#808000,font:Georgia
style.cpp.260=back:#FFF0F0,fore:#800000,italics,font:Georgia
style.cpp.261=back:#FFF0F0,fore:#800000,font:Georgia
style.cpp.262=back:#FFF0FF,fore:#800080,italics,font:Georgia
style.cpp.263=back:#FFF0FF,fore:#800080,font:Georgia
API (included in the download inside scintilla/doc/ScintillaDoc.html)
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.
SCI_ANNOTATIONSETTEXT(int line, char *text)
SCI_ANNOTATIONGETTEXT(int line, char *text)
SCI_ANNOTATIONSETSTYLE(int line, int style)
SCI_ANNOTATIONGETSTYLE(int line)
SCI_ANNOTATIONSETSTYLES(int line, char *styles)
SCI_ANNOTATIONGETSTYLES(int line, char *styles)
SCI_ANNOTATIONGETLINES(int line)
SCI_ANNOTATIONTEXTCLEARALL
A different string may be set for each line with
SCI_ANNOTATIONSETTEXT. To clear annotations call SCI_ANNOTATIONSETTEXT
with a NULL pointer. The whole of the text ANNOTATION on a line may be
displayed in a particular style with SCI_ANNOTATIONSETSTYLE or each
character may be individually styled with SCI_ANNOTATIONSETSTYLES
which uses an array of bytes with each byte setting the style of the
corresponding text byte simlar to SCI_SETSTYLINGEX. The text must be
set first as it specifies how long the annotation is so how many bytes
of styling to read.
The number of lines annotating a line can be retrieved with
SCI_ANNOTATIONGETLINES. All the lines can be cleared of annotations
with SCI_ANNOTATIONTEXTCLEARALL which is equivalent to clearing each
line (setting to 0) and then deleting other memory used for this
feature.
SCI_ANNOTATIONSETVISIBLE(int visible)
SCI_ANNOTATIONGETVISIBLE
Annotations can be made visible in a view and there is a choice of
display style when visible. The two messages 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 40 pixels and are
surrounded by a box.
SCI_ANNOTATIONSETSTYLEOFFSET(int style)
SCI_ANNOTATIONGETSTYLEOFFSET
Annotation styles may be completely separated from standard text
styles by setting a style offset. For example,
SCI_ANNOTATIONSETSTYLEOFFSET(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 SCI_ANNOTATIONSETSTYLE or SCI_ANNOTATIONSETSTYLES has the offset
added before looking up the style.
SCI_MARGINSETTEXT(int line, char *text)
SCI_MARGINGETTEXT(int line, char *text)
SCI_MARGINSETSTYLE(int line, int style)
SCI_MARGINGETSTYLE(int line)
SCI_MARGINSETSTYLES(int line, char *styles)
SCI_MARGINGETSTYLES(int line, char *styles)
SCI_MARGINTEXTCLEARALL
Text margins are created with the type SC_MARGIN_TEXT or
SC_MARGIN_RTEXT. A different string may be set for each line with
SCI_MARGINSETTEXT. The whole of the text margin on a line may be
displayed in a particular style with SCI_MARGINSETSTYLE or each
character may be individually styled with SCI_MARGINSETSTYLES which
uses an array of bytes with each byte setting the style of the
corresponding text byte simlar to SCI_SETSTYLINGEX.
SCI_MARGINSETSTYLEOFFSET(int style)
SCI_MARGINGETSTYLEOFFSET
Margin styles may be completely separated from standard text styles by
setting a style offset. For example, SCI_MARGINSETSTYLEOFFSET(256)
would allow the margin styles to be numbered from 256 upto 511 so they
do not overlap styles set by lexers. Each style number set with
SCI_MARGINSETSTYLE or SCI_MARGINSETSTYLES has the offset added before
looking up the style.
Neil
Armel Asselin
> Annotations are read-only text attached as extra lines to document
> lines. One use is for displaying the disassembled form of C++ code
> following each line of C++ to help in low-level debugging. Merge tools
> may wish to use this to line up the different versions being merged.
> One submission called a similar feature 'false lines'. Compilation
> errors can be shown after the problem code. For example,
> http://www.scintilla.org/annotations.png
are the annotations lines stored inside the document or at the view level?
if stored at document level, it makes it impossible to share the document in
different views with different annotations, unless we can tell an annotation
it has a "source", and then make this a parameter for most SCI_ANNOTATION
functions.
does it make sense to you?
Regards
Armel
Randy Kramer
Thanks for scintilla and scite--I anticipate it becoming my new favorite
editor (after I write a lexer for my variation of TWiki markup
language).
The new features you mentioned are interesting, but I have some similar
(or related) questions to Armel's:
Neil Hodgson wrote:
On Thursday 02 April 2009 05:29:56 am Armel Asselin wrote:
> > Annotations are read-only text attached as extra lines to
> > document lines.
> are the annotations lines stored inside the document or at the view
> level?
Are the annotations stored in some version of the file or an auxiliary
file?
If in the same file, is there a way to maintain the annotations for
future use while at the same time stripping them for submission to a
compiler?
(Those questions may indicate some misunderstanding of your intent, and
should maybe be phrased more generally--maybe I should ask, how do
annotations interact with the compiling activity during development?)
Randy Kramer
--
I didn't have time to write a short letter, so I created a video
instead.--with apologies to Cicero, et.al.
Armel Asselin
From: "Randy Kramer" <rhkr...@gmail.com>
> Neil,
> [...]
>
> Are the annotations stored in some version of the file or an auxiliary
> file?
> [...]
I'm 99.99% sure that they are simply not saved to disk so they won't
interfer with anything :-)
these are (just) visual artifacts to help the developer.
Neil: do you confirm?
my question was oriented "in memory" as we develop here with Scintilla
component.
Regards
Armel
Neil Hodgson
> are the annotations lines stored inside the document or at the view level?
Annotations are stored in the document object.
> if stored at document level, it makes it impossible to share the document in
> different views with different annotations, unless we can tell an annotation
> it has a "source", and then make this a parameter for most SCI_ANNOTATION
> functions.
I see annotations as additional document object data (as are
markers) but with some ability for each view to filter the information
shown. Storing annotations in the view would make it more difficult to
show them in multiple views which wouldn't be so useful in the common
simple case where the window is split into two panes. The only
filtering in the current implementation is to choose between
displaying and not displaying annotations.
Currently each line has a single annotation string but this can
contain line feeds so that there are multiple lines of annotation per
document line. At one stage this was going to be an array of lines
with a style per line but I dropped that as it looked a little more
complex and didn't suit the disassembly case where styling each
character is more useful. Each line could have then had a type ID
(error, disassembly, ...) which could be filtered. That would probably
lead to a larger API since you may want to manipulate just the lines
of a particular type.
Neil
Neil Hodgson
> Are the annotations stored in some version of the file or an auxiliary
> file?
Scintilla never touches a file - it is up to the container to do
all file I/O. Annotations could be saved and loaded if the application
wanted to do this but for the use cases I was thinking of they'd be
transient information you get from running a tool or interpreting some
data.
> If in the same file, is there a way to maintain the annotations for
> future use while at the same time stripping them for submission to a
> compiler?
The primary data is the text in the document and annotations are
separate from this.
> (Those questions may indicate some misunderstanding of your intent, and
> should maybe be phrased more generally--maybe I should ask, how do
> annotations interact with the compiling activity during development?)
I'd expect most environments to only save the text of the document
(without any annotations) and then call the compiler.
Neil
Armel Asselin
From: "Neil Hodgson" <nyama...@gmail.com>
> Armel Asselin:
>
>> are the annotations lines stored inside the document or at the view
>> level?
>
> Annotations are stored in the document object.
>
>> if stored at document level, it makes it impossible to share the document
>> in
>> different views with different annotations, unless we can tell an
>> annotation
>> it has a "source", and then make this a parameter for most SCI_ANNOTATION
>> functions.
>
> I see annotations as additional document object data (as are
> markers) but with some ability for each view to filter the information
> shown. Storing annotations in the view would make it more difficult to
> show them in multiple views which wouldn't be so useful in the common
> simple case where the window is split into two panes. The only
> filtering in the current implementation is to choose between
> displaying and not displaying annotations.
OK
> Currently each line has a single annotation string but this can
> contain line feeds so that there are multiple lines of annotation per
> document line. At one stage this was going to be an array of lines
> with a style per line but I dropped that as it looked a little more
> complex and didn't suit the disassembly case where styling each
> character is more useful. Each line could have then had a type ID
> (error, disassembly, ...) which could be filtered. That would probably
> lead to a larger API since you may want to manipulate just the lines
> of a particular type.
having the type ID per string (and not per line) could be enough from my
point of view, the relative orders of those strings being the ID if a view
ever happen to show more than a single type of annotation.
Regards
Armel
Randy Kramer
Thanks very much for the very clear response(s).
Randy Kramer
On Thursday 02 April 2009 08:45:58 am Neil Hodgson wrote:
---< good stuff snipped>--
Neil Hodgson
> having the type ID per string (and not per line) could be enough from my
> point of view, the relative orders of those strings being the ID if a view
> ever happen to show more than a single type of annotation.
I'm trying to imagine a use case here. Most of the ideas I've
looked at have been modal:
user runs build -> inline error messages
starts debugging -> inline disassembly
Your ideas sounds like accumulating data into a workspace such as a
buffer with a list of SQL statements where you can select a statement,
perform a command on that statement (check it, or execute it, or
display its execution plan) and the results become an annotation.
So that we have a use case that has multiple annotation types
here's a new concept "Variable Trails" that could be used during
debugging at the same time as the disassembly annotations. Variable
Trails shows the value of every assignment stepped though with the
background shade indicating age and thus order. I'd find this useful
myself. Here's a mock up:
http://www.scintilla.org/vartrails.png
Neil
Armel Asselin
>
> Armel Asselin:
>> having the type ID per string (and not per line) could be enough from my
>> point of view, the relative orders of those strings being the ID if a
>> view
>> ever happen to show more than a single type of annotation.
>
> I'm trying to imagine a use case here. Most of the ideas I've
> looked at have been modal:
> user runs build -> inline error messages
> starts debugging -> inline disassembly
> Your ideas sounds like accumulating data into a workspace such as a
> buffer with a list of SQL statements where you can select a statement,
> perform a command on that statement (check it, or execute it, or
> display its execution plan) and the results become an annotation.
why not, and you could switch one or another, keeping the last result of
each type.
> So that we have a use case that has multiple annotation types
> here's a new concept "Variable Trails" that could be used during
> debugging at the same time as the disassembly annotations. Variable
> Trails shows the value of every assignment stepped though with the
> background shade indicating age and thus order. I'd find this useful
> myself. Here's a mock up:
> http://www.scintilla.org/vartrails.png
wow, impressing...
just a note with respect to the "merger" aspect of the question, in order to
make the annotation feature useful in this case, it is mandatory to be able
to put an annotation _in front_ of the first line, could there be an
annotation to "line -1" ? [in the case you diff lines ABCD with CD for
example, the two compensating lines for AB will be before any line of CD
side]
Regards
Armel
Neil Hodgson
> just a note with respect to the "merger" aspect of the question, in order to
> make the annotation feature useful in this case, it is mandatory to be able
> to put an annotation _in front_ of the first line, could there be an
> annotation to "line -1" ? [in the case you diff lines ABCD with CD for
> example, the two compensating lines for AB will be before any line of CD
> side]
Unfortunately, placing something above the top line isn't currently
possible. It didn't work neatly with existing code and may require
changes to much of the display side including ContractionState as well
as storing into the document object. I'm still trying to think of a
good way to do this but haven't found a solution yet. An application
could work around this with a dummy top line but there would then be
more issues caused by this.
For the issue of making different annotations visible in different
views, the style data already in the annotations could be used. There
is already a 'visible' attribute on each style. Each view has a
separate set of styles so one view could define a style as visible and
another define it as invisible. Then the display code could omit lines
that only contained invisible text. To make this simpler and faster,
it could just look at the first style byte for each annotation line
and omit the line if it is invisible.
Neil
almostautomated
> Text margins allow the application to put arbitrary text in a
> Additional features could be added in the future. Markers could be
> assigned to annotation lines so that when debugging breakpoints and
> the current instruction could be placed within disassembled lines.
> Mouse clicks inside annotations could be reported to the application.
>
had talked about regarding undo/redo withing a function. If an
application had a setting to show rev info in annotations and a marker
was set that reported an action the the current text of the line could
be replaced by the text of the revision selected. That'd be nifty.
> Annotations do not wrap and it is not possible to select annotation
> text to be copied to the clipboard. This is deliberate since you want
> to mainly be interacting with the document text but possibly there
> should be some way (right click?) to grab the annotations. Only one
> text margin is currently supported. Both annotations and margin text
> are stored in the document object but the decision on whether they are
> visible is made by the view.
>
never be visible and it could act as a linestate line at the document
level instead of the lexer level. Similar to the style context
linestate that lexers can currently use.
++ on having a way to capture the text. Almost a requirement from an
end-user perspective.
These are going to be put to good use!
Thanks for the awesome addition!
almostautomated
Neil Hodgson
> ++ on having a way to capture the text. Almost a requirement from an
> end-user perspective.
XCode doesn't allow this (AFAICT) and I don't think I'll try to put
generic UI access in the initial release. We should see what
containers want to do in this area first.
Neil
almostautomated
with SCI_ANNOTATIONGETTEXT(int line, char *text), they should be able
to do it.
almostautomated
Neil Hodgson
demonstration code. Boxed annotations are now displayed indented the
same as the line they are annotating. None of the example code in
SciTE is included. Method names were changed a little.
While there are several additions that could be made at some time
such as annotation before first line, some way to extract text to
clipboard, hiding some lines in an annotation, it is unlikely I will
work on these before the next release.
It looks like the most regular way to include an annotation before
the first line is to allow each document line to display a set number
of its annotation lines before its content line and the rest after.
This is a useful feature on its own as some annotations may be more
naturally displayed before the content it is annotating.
Neil