Skip to main content
[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

Back to the top