Mac Developer Library

Developer

AppKit Framework Reference NSTextFinder Class Reference

Options
Deployment Target:

On This Page
Language:

NSTextFinder

The NSTextFinder class provides an optional search and replace find-bar interface inside a view, usually a scroll view. More...

Inheritance


Conforms To


Import Statement


import AppKit @import AppKit;

Availability


Available in OS X v10.7 and later.
  • Initializes and returns a new NSTextFinder instance.

    Declaration

    Swift

    init()

    Objective-C

    - (instancetype)init

    Return Value

    An initialized NSTextFinder instance.

    Discussion

    This is the designated initiator for the NSTextFinder class.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • Performs the specified text finding action.

    Declaration

    Swift

    func performAction(_ op: NSTextFinderAction)

    Objective-C

    - (void)performAction:(NSTextFinderAction)op

    Parameters

    op

    The text finding action. See NSTextFinderAction for the possible values.

    Discussion

    Objects that respond to performTextFinderAction: typically call validateAction: to ensure that the action is valid and then invoke performAction: if validation is successful.

    When invoking the validateAction: and performAction: the item or sender’s tag should be passed as the parameter. By convention, the sender parameter for this method will have an NSTextFinderAction set as its tag. The responder that receives this method should pass the tag as the action for this method:

    • - (void)performTextFinderAction:(id)sender {
    • [self.textFinder performAction:[sender tag]];
    • }

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • Allows validation of the find action before performing.

    Declaration

    Swift

    func validateAction(_ op: NSTextFinderAction) -> Bool

    Objective-C

    - (BOOL)validateAction:(NSTextFinderAction)op

    Parameters

    op

    The sender’s tag.

    Return Value

    YEStrue if the operation is valid; otherwise NOfalse.

    Discussion

    Responders the NSResponder method performTextFinderAction: should call this method.

    This method should be called by an implementation of validateUserInterfaceItem: to properly validate items with an action of performTextFinderAction:. The responder’s validateUserInterfaceItem: or validateMenuItem: implementation should pass the tag as the action for this method..

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • Cancels the find indicator immediately.

    Declaration

    Swift

    func cancelFindIndicator()

    Objective-C

    - (void)cancelFindIndicator

    Discussion

    There may be some circumstances where the find indicator should be immediately cancelled or hidden, such as when the view's content or selection is changed without the knowledge of the text finder. This method will immediately cancel the current find indicator.

    The NSTextFinder and NSView classes will handle the find indicator correctly when a content view is resized, moved, or removed from the view hierarchy. If your content view's scrolling is done by an NSScrollView, the find indicator will also be handled for you during scrolling.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • Specifies the find bar container.

    Declaration

    Swift

    @IBOutlet unowned(unsafe) var findBarContainer: NSTextFinderBarContainer?

    Objective-C

    @property(assign) IBOutlet id<NSTextFinderBarContainer> findBarContainer

    Discussion

    This property must be set to support the find bar.

    When the find bar is to be shown, NSTextFinder invokes showFindBarView: on the findBarContainer object, passing the view for the find bar, which it should display somewhere that is associated appropriately with the content being searched.

    The NSScrollView class implements NSTextFinderBarContainer protocol and is the correct place to display the find bar in most circumstances. The container may freely modify the find bar view's width and origin, but not its height.

    If this property is not set, then the find bar cannot be shown.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • client client Property

    The object that provides the target search string, find bar location, and feedback methods.

    Declaration

    Swift

    @IBOutlet unowned(unsafe) var client: NSTextFinderClient?

    Objective-C

    @property(assign) IBOutlet id<NSTextFinderClient> client

    Discussion

    The NSTextFinder instance class must be associated with a client object that implements the NSTextFinderClient protocol in order to function. The client is responsible for providing the string to be searched, the location for the find bar, and the methods which control feedback to the user about the search results.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • Invoke this method when the searched content will change.

    Declaration

    Swift

    func noteClientStringWillChange()

    Objective-C

    - (void)noteClientStringWillChange

    Discussion

    When incremental search is enabled, this method must be called when it is known that the client's string will be modified. This method must be called before the client string modification takes place.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.7 and later.

    See Also

    client

  • Invoke to specify that the find indicator needs updating when not contained within a scroll view.

    Declaration

    Swift

    var findIndicatorNeedsUpdate: Bool

    Objective-C

    @property BOOL findIndicatorNeedsUpdate

    Discussion

    If the client object’s document is not scrolled by an instance of NSScrollView, then set this property to YEStrue when scrolling occurs to cause the find indicator to be updated appropriately.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • Override this method to draw custom highlighting.

    Declaration

    Swift

    class func drawIncrementalMatchHighlightInRect(_ rect: NSRect)

    Objective-C

    + (void)drawIncrementalMatchHighlightInRect:(NSRect)rect

    Parameters

    rect

    The rectangle that needs to be drawn highlighted in the current coordinate system.

    Discussion

    If incrementalSearchingShouldDimContentView is NOfalse, it is recommended to highlight incremental matches in your own view. However, some applications may choose to show incremental search values in a different manner.

    This method is not recommended to be overridden. The text finder never calls it. The view calls it to get the standard highlight behavior. It is recommended that views use this method do draw the highlight for consistency and to allow Application Kit to tweak the behavior in the future. If the view wants custom drawing, then it should be implemented by the view.

    The common usage pattern for this is: draw the background, draw the incremental match highlights for the incrementalMatchRanges, and then draw the text.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • Array of incremental search matches posted on the main queue, which have been found during a background search. (read-only)

    Declaration

    Swift

    var incrementalMatchRanges: [AnyObject] { get }

    Objective-C

    @property(readonly, copy) NSArray *incrementalMatchRanges

    Discussion

    This array is updated periodically on the main queue as the incremental search operation on a background queue finds matches. You can use this property when incrementalSearchingShouldDimContentView is NOfalse to know where to draw highlights for incremental matches.

    If no incremental search is active, or there are no matches found, this array will be empty. If an incremental search is currently in progress, but not yet complete, this will return all the ranges found so far.

    This array is key-value observing compliant and can be observed to know when to update your highlights. When NSKeyValueObservingOptionNew and NSKeyValueObservingOptionOld options are used, the key-value observing change dictionary provides the ranges (and their indexes) that are added or removed. This allows the invalidation of the minimal region necessary to sync highlights with the receiver’s results.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • Determines if incremental searching is enabled.

    Declaration

    Swift

    var incrementalSearchingEnabled: Bool

    Objective-C

    @property(getter=isIncrementalSearchingEnabled) BOOL incrementalSearchingEnabled

    Discussion

    If YEStrue, then the find bar will do incremental searches. If it returns NOfalse, then the find bar will behave regularly.

    The default value is NOfalse.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • Determines the type of incremental search feedback to be presented

    Declaration

    Swift

    var incrementalSearchingShouldDimContentView: Bool

    Objective-C

    @property BOOL incrementalSearchingShouldDimContentView

    Discussion

    If YEStrue, then when an incremental search begins, the findBarContainer instance’s parent contentView will be dimmed, except for the locations of the incremental matches. If NOfalse, then the incremental matches will not be highlighted automatically, but you can use incrementalMatchRanges to highlight the matches yourself.

    The default value is YEStrue.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.7 and later.

Data Types

  • These constants specify the user interface item tags that correspond find action. These constants are passed to the performTextFinderAction: method, the responder will call the appropriate method for the tag. That method will, in turn, determine the desired action and invoke the appropriate method in the NSTextFinder object’s NSTextFinderClient protocol.

    Declaration

    Swift

    enum NSTextFinderAction : Int { case ShowFindInterface case NextMatch case PreviousMatch case ReplaceAll case Replace case ReplaceAndFind case SetSearchString case ReplaceAllInSelection case SelectAll case SelectAllInSelection case HideFindInterface case ShowReplaceInterface case HideReplaceInterface }

    Objective-C

    enum { NSTextFinderActionShowFindInterface = 1, NSTextFinderActionNextMatch = 2, NSTextFinderActionPreviousMatch = 3, NSTextFinderActionReplaceAll = 4, NSTextFinderActionReplace = 5, NSTextFinderActionReplaceAndFind = 6, NSTextFinderActionSetSearchString = 7, NSTextFinderActionReplaceAllInSelection = 8, NSTextFinderActionSelectAll = 9, NSTextFinderActionSelectAllInSelection = 10, NSTextFinderActionHideFindInterface = 11, NSTextFinderActionShowReplaceInterface = 12, NSTextFinderActionHideReplaceInterface = 13 }; typedef NSInteger NSTextFinderAction;

    Constants

    • ShowFindInterface

      NSTextFinderActionShowFindInterface

      The find bar interface is displayed.

      Available in OS X v10.7 and later.

    • NextMatch

      NSTextFinderActionNextMatch

      The next match, if any, is displayed.

      Available in OS X v10.7 and later.

    • PreviousMatch

      NSTextFinderActionPreviousMatch

      The previous match, if any, is displayed.

      Available in OS X v10.7 and later.

    • ReplaceAll

      NSTextFinderActionReplaceAll

      All occurrences of the string are replaced.

      Available in OS X v10.7 and later.

    • Replace

      NSTextFinderActionReplace

      Replaces a single instance of the string.

      Available in OS X v10.7 and later.

    • ReplaceAndFind

      NSTextFinderActionReplaceAndFind

      Replaces a single instance of the string and searches for the next match.

      Available in OS X v10.7 and later.

    • SetSearchString

      NSTextFinderActionSetSearchString

      Sets the search string.

      Available in OS X v10.7 and later.

    • ReplaceAllInSelection

      NSTextFinderActionReplaceAllInSelection

      Replaces all occurrences of the string within the current selection.

      Available in OS X v10.7 and later.

    • SelectAll

      NSTextFinderActionSelectAll

      Selects all matching search strings.

      Available in OS X v10.7 and later.

    • SelectAllInSelection

      NSTextFinderActionSelectAllInSelection

      Selects all matching search strings within the current selection.

      Available in OS X v10.7 and later.

    • HideFindInterface

      NSTextFinderActionHideFindInterface

      Hides the find bar interface.

      Available in OS X v10.7 and later.

    • ShowReplaceInterface

      NSTextFinderActionShowReplaceInterface

      Displays the find bar interface including the replace functionality.

      Available in OS X v10.7 and later.

    • HideReplaceInterface

      NSTextFinderActionHideReplaceInterface

      Displays the find bar interface including the replace functionality.

      Available in OS X v10.7 and later.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • The following constants indicate the type of search anchor an action should perform.

    Declaration

    Swift

    enum NSTextFinderMatchingType : Int { case Contains case StartsWith case FullWord case EndsWith }

    Objective-C

    enum { NSTextFinderMatchingTypeContains = 0, NSTextFinderMatchingTypeStartsWith = 1, NSTextFinderMatchingTypeFullWord = 2, NSTextFinderMatchingTypeEndsWith = 3 }; typedef NSInteger NSTextFinderMatchingType;

    Constants

    • Contains

      NSTextFinderMatchingTypeContains

      The match contains the string.

      Available in OS X v10.7 and later.

    • StartsWith

      NSTextFinderMatchingTypeStartsWith

      The match begins with the string.

      Available in OS X v10.7 and later.

    • FullWord

      NSTextFinderMatchingTypeFullWord

      The match exactly matches the string.

      Available in OS X v10.7 and later.

    • EndsWith

      NSTextFinderMatchingTypeEndsWith

      The match ends with the string.

      Available in OS X v10.7 and later.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • The following keys are used for communicating NSTextFinder search options via pasteboard. Use the NSPasteboardTypeTextFinderOptions type

    Declaration

    Swift

    let NSTextFinderCaseInsensitiveKey: NSString! let NSTextFinderMatchingTypeKey: NSString!

    Objective-C

    NSString *const NSTextFinderCaseInsensitiveKey; NSString *const NSTextFinderMatchingTypeKey;

    Constants

    • NSTextFinderCaseInsensitiveKey

      NSTextFinderCaseInsensitiveKey

      The value of this key must be an Boolean NSValue object that indicates if the search should be case sensitive.

      Available in OS X v10.7 and later.

    • NSTextFinderMatchingTypeKey

      NSTextFinderMatchingTypeKey

      The value of this key must be an NSNumber containing an NSTextFinderMatchingType value that indicates the type of search matching to perform..

      Available in OS X v10.7 and later.

    Import Statement