2009-03-20 Darin Adler <darin@apple.com>
authordarin@apple.com <darin@apple.com@268f45cc-cd09-0410-ab3c-d52691b4dbfc>
Fri, 20 Mar 2009 20:25:34 +0000 (20:25 +0000)
committerdarin@apple.com <darin@apple.com@268f45cc-cd09-0410-ab3c-d52691b4dbfc>
Fri, 20 Mar 2009 20:25:34 +0000 (20:25 +0000)
        Reviewed by Timothy Hatcher.

        * WebView/WebTextIterator.h: Improved comments to point out some of the pitfalls
        of this SPI.

git-svn-id: https://svn.webkit.org/repository/webkit/trunk@41867 268f45cc-cd09-0410-ab3c-d52691b4dbfc

WebKit/mac/ChangeLog
WebKit/mac/WebView/WebTextIterator.h

index c200adf..c3e0dbb 100644 (file)
@@ -1,5 +1,12 @@
 2009-03-20  Darin Adler  <darin@apple.com>
 
+        Reviewed by Timothy Hatcher.
+
+        * WebView/WebTextIterator.h: Improved comments to point out some of the pitfalls
+        of this SPI.
+
+2009-03-20  Darin Adler  <darin@apple.com>
+
         Reviewed by Adele Peterson.
 
         Use a better technique to handle finding out if something responds to a selector
index ab5ca4e..646aacb 100644 (file)
@@ -44,7 +44,9 @@
 
 /*!
  @method advance
- @abstract Makes the WebTextIterator iterate to the next visible text element.
+ @abstract Moves the WebTextIterator to the next bit of text or boundary between runs of text.
+ The iterator can break up runs of text however it finds convenient, so clients need to handle
+ text runs that are broken up into arbitary pieces.
  */
 - (void)advance;
 
 - (BOOL)atEnd;
 
 /*!
- @method currentRange
- @result A range, indicating the position within the document of the current text.
+ @method currentTextLength
+ @result Length of the current text. Length of zero means that the iterator is at a boundary,
+ such as an image, that separates runs of text.
  */
-- (DOMRange *)currentRange;
+- (WebNSUInteger)currentTextLength;
 
 /*!
  @method currentTextPointer
- @result A pointer to the current text. The pointer becomes invalid after any modification is made to the document; it must be used right away.
+ @result A pointer to the current text. Like the WebTextIterator itself, the pointer becomes
+ invalid after any modification is made to the document; it must be used before the document
+ is changed or the iterator is advanced.
  */
 - (const unichar *)currentTextPointer;
 
 /*!
- @method currentTextLength
- @result lengthPtr Length of the current text.
+ @method currentRange
+ @abstract A function that identifies the specific document range that text corresponds to.
+ This can be quite costly to compute for non-text items, so when possible this should only
+ be called once the caller has determined that the text is text it wants to process. If you
+ call currentRange every time you advance the iterator, performance will be extremely slow
+ due to the cost of computing a DOM range.
+ @result A DOM range indicating the position within the document of the current text.
  */
-- (WebNSUInteger)currentTextLength;
+- (DOMRange *)currentRange;
 
 @end