NSTextFinderClient Protocol Reference

Conforms to
NSObject
Framework
/System/Library/Frameworks/AppKit.framework
Availability
Available in OS X v10.7 and later.
Declared in
NSTextFinder.h

Overview

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.

Tasks

String Searching

Replacing Text

Selection Information

Text Edibility

Determining and Displaying Text Locations

Drawing Glyphs

Properties

allowsMultipleSelection

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

@property(readonly) BOOL allowsMultipleSelection
Discussion

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

Availability
  • Available in OS X v10.7 and later.
Declared In
NSTextFinder.h

editable

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

@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 YES .

Availability
  • Available in OS X v10.7 and later.
Declared In
NSTextFinder.h

firstSelectedRange

Returns the currently selected range. (read-only)

@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.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSTextFinder.h

selectable

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

@property(getter=isSelectable, readonly) BOOL selectable
Discussion

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

Availability
  • Available in OS X v10.7 and later.
Declared In
NSTextFinder.h

selectedRanges

Returns an array of selected ranges.

@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.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSTextFinder.h

string

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

@property(readonly) 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.

Availability
  • Available in OS X v10.7 and later.
See Also
Declared In
NSTextFinder.h

visibleCharacterRanges

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

@property(readonly) 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.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSTextFinder.h

Instance Methods

contentViewAtIndex:effectiveCharacterRange:

Returns the view the context is displayed in.

- (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.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSTextFinder.h

didReplaceCharacters

Specifies whether text characters were replaced.

- (void)didReplaceCharacters
Discussion

See NSTextFinder Class Reference for a complete description.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSTextFinder.h

drawCharactersInRange:forContentView:

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

- (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 YES. If this method is not implemented, then the find indicator will be drawn using the content view’s drawRect: method instead.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSTextFinder.h

rectsForCharacterRange:

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

- (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.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSTextFinder.h

replaceCharactersInRange:withString:

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

- (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.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSTextFinder.h

scrollRangeToVisible:

Scrolls the specified range such that it is visible.

- (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.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSTextFinder.h

shouldReplaceCharactersInRanges:withStrings:

Returns whether the specified strings should be replaced.

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

The ranges of the strings to replace.

strings

The replacement strings.

Return Value

Returns YES if the replacement should occur; otherwise NO.

Discussion

See NSTextFinder Class Reference for a complete description.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSTextFinder.h

stringAtIndex:effectiveRange:endsWithSearchBoundary:

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.

- (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.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSTextFinder.h

stringLength

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

- (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.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSTextFinder.h


© 2011 Apple Inc. All Rights Reserved. (Last updated: 2011-06-06)

Did this document help you? Yes It's good, but... Not helpful...