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