[
Date Prev][
Date Next][
Thread Prev][
Thread Next][
Date Index][
Thread Index]
[
List Home]
[platform-swt-dev] Problems with published StyledText API & documentation
|
SWT devlopers:
I'm implementing an Eclipse text editor plugin that derives style
information from a dynamically-updated syntax tree rather than a lexer.
In the course of development, I've run across some issues with the
published StyledText API, where important aspects of the widget's
behavior appear to have been omitted.
A general high-level problem is that I can't find any API specification
describing how the StyledText widget's styling state changes over time.
This is important, since I want to update the StyledText widget
incrementally as my syntax tree changes. I've searched the
"swimming"-themed online articles (feet wet, deep end) and the javadocs,
and came up with the following list if specific specification holes.
Before I dig into the code, I thought I'd share it with you guys. If
these are, indeed, significant omittions, maybe it could get fixed for
the future?
- Un-answered questions:
If I set a styled range from offset A to offset B in the widget, I know
that the displayed characters from A to B will have the corresponding
style immediately after I call setStyleRange(). But what styles will be
displayed after the text buffer changes? Where, for instance, will the
existing style be displayed...
- If I insert/delete N characters at I<A? I=A? A<I<B? I=B? A<B<I?
- If A=B, and I insert I characters at I=A=B?
- If I replace characters in a range that overlaps A and/or B?
If the StyledText widget has to do processing to update ranges after a
text change, how long does that processing take? O(number of ranges),
maybe? (Hopefully not.)
- Specific parts of the javadocs that I didn't understand:
replaceStyleRanges(): says "use 0 [for the length parameter] to insert
text". What does this mean? How can you insert text with this method
at all? I thought this method replaced *styles*, not text... This
doesn't make any sense to me.
setLineBackground(): says "During text changes, when entire lines are
inserted or removed, the line background colors that are associated with
the lines after the change will "move" with their respective text. For
all other text changes, line background colors will remain unchanged."
This description is a little vague... What defines an "entire line"?
- Is it "a line of characters and the newline at the end"?
- Is it "a line of characters and the newline at the beginning"?
- "A newline"?
What about the following situation: The text buffer starts out as
"AB\nCD\nEF". Each line has a different color (X, Y, and Z). Now, text
is deleted to make the buffer "A\nF". What colors are all the lines?
setStyleRange(): The javadoc says: "Overwrites the old style in the
given range." What is the definition of "style in the given range"?
For instance, if I set the range (1,4) to blue, and then call
setStyleRange(2, 6, green), does it result in (1,2)=blue and
(2,6)=green, or just (2,6)=green? Does it overwrite all styles that
intersect with the new style, or just the style for characters covered
by the new range?
In general, how does the StyledText widget maintain style information?
What's the difference between setStyleRanges(StyleRange[]) and
replaceStyleRanges(from, to, StyleRange[])? Both of them claim to
replace existing StyleRanges that conflict with the new StyleRanges. On
the surface, the only difference appears to be that replaceStyleRanges()
lets you specifically say what range of styles should be erased, whereas
setStyleRanges makes that information implicit (anything covering the
ranges will be replaced). But this doesn't make sense, because you
could effectively implement replaceStyleRanges() with setStyleRanges()
then, by constructing null StyleRange objects for all regions that are
specified in from and to, but aren't covered by the StyledRange[]
argument to replaceStyleRanges(). Is this really a duplication in API?
Here are some slightly more pointed questions:
"setStyleRanges(StyleRange[] ranges)
Sets styles to be used for rendering the widget content. All
styles will be replaced with the given set of styles."
Does this mean "all styles in the widget", or just "all styles that are
lying in the way of the ranges being set"? Which ranges, precisely,
will go away?
"public void replaceStyleRanges(int start,
int length,
StyleRange[] ranges)
Replaces the styles in the given range with new styles. This
method effectively deletes the styles in the given range and then
adds the the new styles."
I have the same question here as I did for setStyleRange(StyleRange).
If `start' or `end' overlap an existing StyleRange region, does this
method remove JUST the overlapping part of the StyleRange, or does it
remove the whole range even if only part of it overlaps?
Also, at the top of the StyledWidget javadocs, it says:
"The following StyledText API is not supported if you have defined a
LineStyleListener:
* getStyleRangeAtOffset(int)
* getStyleRanges()
* setStyleRange(StyleRange)
* setStyleRanges(StyleRange[])"
This leaves out replaceStyleRanges(), which can't be used with
LineStyleListeners either.
Thanks for your time,
Michael