2009-03-23 Darin Adler <darin@apple.com>
[WebKit-https.git] / WebKit / mac / WebView / WebTextIterator.h
index e6f77ac..d0c92f9 100644 (file)
@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2008 Apple Inc. All Rights Reserved.
+ * Copyright (C) 2008, 2009 Apple Inc. All Rights Reserved.
  *
  * Redistribution and use in source and binary forms, with or without
  * modification, are permitted provided that the following conditions
 
 #import <Foundation/Foundation.h>
 
+#if MAC_OS_X_VERSION_MAX_ALLOWED <= MAC_OS_X_VERSION_10_4
+#define WebNSUInteger unsigned int
+#else
+#define WebNSUInteger NSUInteger
+#endif
 
 @class DOMRange;
 @class DOMNode;
 @class WebTextIteratorPrivate;
 
-@interface WebTextIterator : NSObject
-{
+@interface WebTextIterator : NSObject {
 @private
     WebTextIteratorPrivate *_private;
 }
 - (id)initWithRange:(DOMRange *)range;
 
 /*!
- @method advance:
- @abstract Makes the WebTextIterator iterate to the next visible text element.
+ @method advance
+ @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 arbitrary pieces.
  */
 - (void)advance;
 
 /*!
- @method currentNode:
- @result The current DOMNode in the WebTextIterator.
+ @method atEnd
+ @result YES if the WebTextIterator has reached the end of the DOMRange.
  */
-- (DOMNode *)currentNode;
+- (BOOL)atEnd;
 
 /*!
- @method currentText:
- @result The current text in the WebTextIterator.
+ @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.
  */
-- (NSString *)currentText;
+- (WebNSUInteger)currentTextLength;
 
 /*!
- @method atEnd:
- @result YES if the WebTextIterator has reached the end of the DOMRange.
+ @method currentTextPointer
+ @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.
  */
-- (BOOL)atEnd;
+- (const unichar *)currentTextPointer;
+
+/*!
+ @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.
+ */
+- (DOMRange *)currentRange;
+
+@end
+
+@interface WebTextIterator (WebTextIteratorDeprecated)
 
+/*!
+ @method currentNode
+ @abstract A convenience method that finds the first node in currentRange; it's almost always better to use currentRange instead.
+ @result The current DOMNode in the WebTextIterator
+ */
+- (DOMNode *)currentNode;
+
+/*!
+ @method currentText
+ @abstract A convenience method that makes an NSString out of the current text; it's almost always better to use currentTextPointer and currentTextLength instead.
+ @result The current text in the WebTextIterator.
+ */
+- (NSString *)currentText;
 
 @end
+
+#undef WebNSUInteger