Mac Developer Library

Developer

AppKit Framework Reference NSTextFinderClient Protocol Reference

Options
Deployment Target:

On This Page
Language:

NSTextFinderClient

The NSTextFinderClient protocol is implemented by objects that wish to support searching using the NSTextFinder class and the in-window text finder bar.

See NSTextFinder Class Reference for details.

Inheritance


Not Applicable

Import Statement


Swift

import AppKit

Objective-C

@import AppKit;

Availability


Available in OS X v10.7 and later.
  • string string Property

    Allows the client to specify a single string for searching. (read-only)

    Declaration

    Swift

    optional var string: String { get }

    Objective-C

    @property(readonly, strong) NSString *string

    Discussion

    If the client cannot logically or efficiently flatten itself into a single string, then the stringAtIndex:effectiveRange:endsWithSearchBoundary: and stringLength methods should be implemented instead.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • Returns the found string that is created by conceptually mapping its content to a single string, which is composed of a concatenation of all its substrings.

    Declaration

    Swift

    optional func stringAtIndex(_ characterIndex: Int, effectiveRange outRange: NSRangePointer, endsWithSearchBoundary outFlag: UnsafeMutablePointer<ObjCBool>) -> String

    Objective-C

    - (NSString *)stringAtIndex:(NSUInteger)characterIndex effectiveRange:(NSRangePointer)outRange endsWithSearchBoundary:(BOOL *)outFlag

    Parameters

    characterIndex

    The given character index the client should return.

    outRange

    Returns, by reference, the "effective range" of that substring in the full conceptually concatenated string

    outFlag

    Returns, by-reference, whether the substring ends with a "search boundary", meaning that NSTextFinder should not attempt to find any matches that overlap this boundary.

    Return Value

    Returns the found string.

    Discussion

    See NSTextFinder Class Reference for more information.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • Returns the full length of the conceptually concatenated string return by the stringAtIndex:effectiveRange:endsWithSearchBoundary: method.

    Declaration

    Swift

    optional func stringLength() -> Int

    Objective-C

    - (NSUInteger)stringLength

    Return Value

    Returns the full length of the conceptually concatenated string in the second model, that is, the sum of the lengths of all of its substrings.

    Discussion

    See NSTextFinder Class Reference for more information.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • Returns whether the specified strings should be replaced.

    Declaration

    Swift

    optional func shouldReplaceCharactersInRanges(_ ranges: [AnyObject], withStrings strings: [AnyObject]) -> Bool

    Objective-C

    - (BOOL)shouldReplaceCharactersInRanges:(NSArray *)ranges withStrings:(NSArray *)strings

    Parameters

    ranges

    The ranges of the strings to replace.

    strings

    The replacement strings.

    Return Value

    Returns YEStrue if the replacement should occur; otherwise NOfalse.

    Discussion

    See NSTextFinder Class Reference for a complete description.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • Replaces the text in the specified range with the new string.

    Declaration

    Swift

    optional func replaceCharactersInRange(_ range: NSRange, withString string: String)

    Objective-C

    - (void)replaceCharactersInRange:(NSRange)range withString:(NSString *)string

    Parameters

    range

    The specified range of the text to replace.

    string

    The replacement string.

    Discussion

    See NSTextFinder Class Reference for a complete description.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • Specifies whether text characters were replaced.

    Declaration

    Swift

    optional func didReplaceCharacters()

    Objective-C

    - (void)didReplaceCharacters

    Discussion

    See NSTextFinder Class Reference for a complete description.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • Returns whether the text is selectable. (required) (read-only)

    Declaration

    Swift

    optional var selectable: Bool { get }

    Objective-C

    @property(getter=isSelectable, readonly) BOOL selectable

    Discussion

    If this properties is not implemented, the text finder will act as if they returned YEStrue.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • Returns whether multiple items can be selected. (read-only)

    Declaration

    Swift

    optional var allowsMultipleSelection: Bool { get }

    Objective-C

    @property(readonly) BOOL allowsMultipleSelection

    Discussion

    If this properties is not implemented, the text finder will act as if they returned YEStrue.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • Returns the currently selected range. (read-only)

    Declaration

    Swift

    optional var firstSelectedRange: NSRange { get }

    Objective-C

    @property(readonly) NSRange firstSelectedRange

    Discussion

    This property is required for the next match, previous match, replace, replace and find and set search string actions.. The client should return its first selected range, or {index, 0} to indicate the location of the insertion point if there is no selection.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • Returns an array of selected ranges.

    Declaration

    Swift

    optional var selectedRanges: [AnyObject] { get set }

    Objective-C

    @property(copy) NSArray *selectedRanges

    Discussion

    This property is required for the replace all in selection, select all, and select all in selection actions. The returned NSArray object should contain NSRanges wrapped by NSValues.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • editable editable Property

    Returns whether the text is editable. (read-only)

    Declaration

    Swift

    optional var editable: Bool { get }

    Objective-C

    @property(getter=isEditable, readonly) BOOL editable

    Discussion

    The text finder uses this property to validate actions. If is it not implemented, the value is assumed to be YEStrue .

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • Returns the view the context is displayed in.

    Declaration

    Swift

    optional func contentViewAtIndex(_ index: Int, effectiveCharacterRange outRange: NSRangePointer) -> NSView

    Objective-C

    - (NSView *)contentViewAtIndex:(NSUInteger)index effectiveCharacterRange:(NSRangePointer)outRange

    Parameters

    index

    The index of the view containing the located text.

    outRange

    Returns, by reference, the entire range of the string displayed by the view

    Return Value

    Returns the view the contains the found text.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • An array containing the located text in the content view’s coordinate system.

    Declaration

    Swift

    optional func rectsForCharacterRange(_ range: NSRange) -> [AnyObject]?

    Objective-C

    - (NSArray *)rectsForCharacterRange:(NSRange)range

    Parameters

    range

    The range of the located character string.

    Return Value

    An array containing the rectangles containing the located text in the content view object’s coordinate system and return that array. The rectangles are return wrapped as NSValue objects.

    Discussion

    The text finder uses this method to determine the location to display the find indicator.

    The given range is guaranteed not to overlap multiple views.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • Scrolls the specified range such that it is visible.

    Declaration

    Swift

    optional func scrollRangeToVisible(_ range: NSRange)

    Objective-C

    - (void)scrollRangeToVisible:(NSRange)range

    Parameters

    range

    The range to display.

    Discussion

    This method is used by all actions, but is not strictly required by any.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • An array of visible character ranges. (read-only)

    Declaration

    Swift

    optional var visibleCharacterRanges: [AnyObject] { get }

    Objective-C

    @property(readonly, copy) NSArray *visibleCharacterRanges

    Discussion

    The text finder uses this property's value to determine which ranges it should search to show all of the incremental matches that are currently visible.

    If this property is not implemented, then the incremental matches cannot be shown.

    The array contains NSValue objects that wrap NSRect structures.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • Draw the glyphs for the requested character range as they are drawn in the given content view. (required)

    Declaration

    Swift

    optional func drawCharactersInRange(_ range: NSRange, forContentView view: NSView)

    Objective-C

    - (void)drawCharactersInRange:(NSRange)range forContentView:(NSView *)view

    Parameters

    range

    The character range.

    view

    The content view.

    Discussion

    If the character range partially intersects a glyph range, then the full glyph is drawn to avoid additional layout.

    The given range is guaranteed to be completely contained by the given view. When this method is called, a drawing context effectively identical to the one provided to the view’s drawRect: method is configured. This method is mainly used to draw find indicator contents, so implementations should check -the view property isDrawingFindIndicator to ensure that the text will be easily readable against the background of the find indicator when it returns YEStrue. If this method is not implemented, then the find indicator will be drawn using the content view’s drawRect: method instead.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.