ab5ca4e1e2450b14046b303416563c69e3b24650
[WebKit-https.git] / WebKit / mac / WebView / WebTextIterator.h
1 /*
2  * Copyright (C) 2008, 2009 Apple Inc. All Rights Reserved.
3  *
4  * Redistribution and use in source and binary forms, with or without
5  * modification, are permitted provided that the following conditions
6  * are met:
7  * 1. Redistributions of source code must retain the above copyright
8  *    notice, this list of conditions and the following disclaimer.
9  * 2. Redistributions in binary form must reproduce the above copyright
10  *    notice, this list of conditions and the following disclaimer in the
11  *    documentation and/or other materials provided with the distribution.
12  *
13  * THIS SOFTWARE IS PROVIDED BY APPLE INC. ``AS IS'' AND ANY
14  * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
16  * PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL APPLE INC. OR
17  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
18  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
19  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
20  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
21  * OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
22  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
23  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 
24  */
25
26 #import <Foundation/Foundation.h>
27
28 #if MAC_OS_X_VERSION_MAX_ALLOWED <= MAC_OS_X_VERSION_10_4
29 #define WebNSUInteger unsigned int
30 #else
31 #define WebNSUInteger NSUInteger
32 #endif
33
34 @class DOMRange;
35 @class DOMNode;
36 @class WebTextIteratorPrivate;
37
38 @interface WebTextIterator : NSObject {
39 @private
40     WebTextIteratorPrivate *_private;
41 }
42
43 - (id)initWithRange:(DOMRange *)range;
44
45 /*!
46  @method advance
47  @abstract Makes the WebTextIterator iterate to the next visible text element.
48  */
49 - (void)advance;
50
51 /*!
52  @method atEnd
53  @result YES if the WebTextIterator has reached the end of the DOMRange.
54  */
55 - (BOOL)atEnd;
56
57 /*!
58  @method currentRange
59  @result A range, indicating the position within the document of the current text.
60  */
61 - (DOMRange *)currentRange;
62
63 /*!
64  @method currentTextPointer
65  @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.
66  */
67 - (const unichar *)currentTextPointer;
68
69 /*!
70  @method currentTextLength
71  @result lengthPtr Length of the current text.
72  */
73 - (WebNSUInteger)currentTextLength;
74
75 @end
76
77 @interface WebTextIterator (WebTextIteratorDeprecated)
78
79 /*!
80  @method currentNode
81  @abstract A convenience method that finds the first node in currentRange; it's almost always better to use currentRange instead.
82  @result The current DOMNode in the WebTextIterator
83  */
84 - (DOMNode *)currentNode;
85
86 /*!
87  @method currentText
88  @abstract A convenience method that makes an NSString out of the current text; it's almost always better to use currentTextPointer and currentTextLength instead.
89  @result The current text in the WebTextIterator.
90  */
91 - (NSString *)currentText;
92
93 @end
94
95 #undef WebNSUInteger