Mac Developer Library

Developer

AppKit Framework Reference NSSpellChecker Class Reference

Options
Deployment Target:

On This Page
Language:

NSSpellChecker

The NSSpellChecker class provides an interface to the Cocoa spell-checking service. To handle all its spell checking, an application needs only one instance of NSSpellChecker, known as the spell checker. Through the spell checker you manage the Spelling panel, in which the user can specify decisions about words that are suspect.

The spell checker also offers the ability to provide word completions to augment the text completion system in OS X v10.3.

  • Returns the NSSpellChecker (one per application).

    Declaration

    Swift

    class func sharedSpellChecker() -> NSSpellChecker

    Objective-C

    + (NSSpellChecker *)sharedSpellChecker

    Return Value

    The spelling checker shared by this application.

    Availability

    Available in OS X v10.0 and later.

  • Returns whether the application’s NSSpellChecker has already been created.

    Declaration

    Swift

    class func sharedSpellCheckerExists() -> Bool

    Objective-C

    + (BOOL)sharedSpellCheckerExists

    Return Value

    YEStrue if the shared spell checker already exists, otherwise NOfalse.

    Availability

    Available in OS X v10.0 and later.

  • Returns the number of words in stringToCount.

    Declaration

    Swift

    func countWordsInString(_ stringToCount: String, language language: String?) -> Int

    Objective-C

    - (NSInteger)countWordsInString:(NSString *)stringToCount language:(NSString *)language

    Parameters

    stringToCount

    The string to count the words in.

    language

    The language of the string.

    Return Value

    The number of words in the string.

    Discussion

    If language is nil, the current selection in the Spelling panel’s pop-up menu is used.

    Availability

    Available in OS X v10.0 and later.

  • Starts the search for a misspelled word in stringToCheck starting at startingOffset within the string object.

    Declaration

    Swift

    func checkSpellingOfString(_ stringToCheck: String, startingAt startingOffset: Int) -> NSRange

    Objective-C

    - (NSRange)checkSpellingOfString:(NSString *)stringToCheck startingAt:(NSInteger)startingOffset

    Parameters

    stringToCheck

    The string to spell check.

    startingOffset

    The offset at which to start checking.

    Return Value

    Returns the range of the first misspelled word.

    Discussion

    Wrapping occurs, but no ignored-words dictionary is used.

    Availability

    Available in OS X v10.0 and later.

  • Starts the search for a misspelled word in a string starting at specified offset within the string.

    Declaration

    Swift

    func checkSpellingOfString(_ stringToCheck: String, startingAt startingOffset: Int, language language: String?, wrap wrapFlag: Bool, inSpellDocumentWithTag tag: Int, wordCount wordCount: UnsafeMutablePointer<Int>) -> NSRange

    Objective-C

    - (NSRange)checkSpellingOfString:(NSString *)stringToCheck startingAt:(NSInteger)startingOffset language:(NSString *)language wrap:(BOOL)wrapFlag inSpellDocumentWithTag:(NSInteger)tag wordCount:(NSInteger *)wordCount

    Parameters

    stringToCheck

    The string object containing the words to spellcheck.

    startingOffset

    The offset within stringToCheck at which to begin spellchecking.

    language

    The language of the words in the string. If language is nil, or if you obtain the value by sending language to self, the current selection in the Spelling panel’s pop-up menu is used. Do not pass in an empty string for language.

    wrapFlag

    YEStrue to indicate that spell checking should continue at the beginning of the string when the end of the string is reached; NOfalse to indicate that spellchecking should stop at the end of the document.

    tag

    An identifier unique within the application used to inform the spell checker which document that text is associated, potentially for many purposes, not necessarily just for ignored words. A value of 0 can be passed in for text not associated with a particular document.

    wordCount

    Returns by indirection a count of the words spell-checked up to and including the first error (if any), or -1 if the spell checker fails or does not support word counting. Specify NULL if you do not want this word count.

    Return Value

    The range of the first misspelled word and optionally (and by reference) the count of words spellchecked in the string in wordCount.

    Availability

    Available in OS X v10.0 and later.

  • - guessesForWord: (OS X v10.6)

    Returns an array of suggested spellings for the misspelled word.

    Declaration

    Objective-C

    - (NSArray *)guessesForWord:(NSString *)word

    Parameters

    word

    A misspelled word.

    Return Value

    An array of suggested spellings for the word.

    Discussion

    If word contains all capital letters, or its first letter is capitalized, the suggested words are capitalized in the same way.

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Initiates a grammatical analysis of a given string.

    Declaration

    Swift

    func checkGrammarOfString(_ stringToCheck: String, startingAt startingOffset: Int, language language: String?, wrap wrapFlag: Bool, inSpellDocumentWithTag tag: Int, details details: AutoreleasingUnsafeMutablePointer<NSArray?>) -> NSRange

    Objective-C

    - (NSRange)checkGrammarOfString:(NSString *)string startingAt:(NSInteger)start language:(NSString *)language wrap:(BOOL)wrap inSpellDocumentWithTag:(NSInteger)documentTag details:(NSArray<NSDictionary<NSString *,id> *> * _Nullable *)outDetails

    Parameters

    string

    String to analyze.

    start

    Location within string at which to start the analysis.

    language

    Language use in string. When nil, the language selected in the Spelling panel is used.

    wrap

    YEStrue to specify that the analysis continue to the beginning of string when the end is reached.

    NOfalse to have the analysis stop at the end of string.

    documentTag

    An identifier unique within the application used to inform the spell checker which document that text is associated, potentially for many purposes, not necessarily just for ignored words. A value of 0 can be passed in for text not associated with a particular document.

    outDetails

    On output, dictionaries describing grammar-analysis details within the flagged grammatical unit. See the NSSpellServer class for information about these dictionaries.

    Return Value

    Location of the first flagged grammatical unit.

    Availability

    Available in OS X v10.5 and later.

  • Requests unified text checking for the given range of the given string.

    Declaration

    Swift

    func checkString(_ stringToCheck: String, range range: NSRange, types checkingTypes: NSTextCheckingTypes, options options: [String : AnyObject]?, inSpellDocumentWithTag tag: Int, orthography orthography: AutoreleasingUnsafeMutablePointer<NSOrthography?>, wordCount wordCount: UnsafeMutablePointer<Int>) -> [NSTextCheckingResult]

    Objective-C

    - (NSArray<NSTextCheckingResult *> *)checkString:(NSString *)stringToCheck range:(NSRange)range types:(NSTextCheckingTypes)checkingTypes options:(NSDictionary<NSString *,id> *)options inSpellDocumentWithTag:(NSInteger)tag orthography:(NSOrthography * _Nullable *)orthography wordCount:(NSInteger *)wordCount

    Parameters

    stringToCheck

    The string to check.

    range

    The range of the string to check.

    checkingTypes

    The type of checking to be performed. The possible constants are listed in NSTextCheckingType and can be combined using the C bit-wise OR operator to perform multiple checks at the same time.

    options

    The options dictionary specifying the types of checking to perform. See Spell Checking Option Dictionary Keys for the possible keys and expected values.

    tag

    An identifier unique within the application used to inform the spell checker which document that text is associated, potentially for many purposes, not necessarily just for ignored words. A value of 0 can be passed in for text not associated with a particular document.

    orthography

    Returns by-reference, the orthography of the range of the string. See NSOrthography for more information.

    wordCount

    Returns by-reference, the word count for the range of the string.

    Return Value

    An array of NSTextCheckingResult objects describing particular items found during checking and their individual ranges, sorted by range origin, then range end, then result type.

    Availability

    Available in OS X v10.6 and later.

  • Requests that the string be checked in the background.

    Declaration

    Swift

    func requestCheckingOfString(_ stringToCheck: String, range range: NSRange, types checkingTypes: NSTextCheckingTypes, options options: [String : AnyObject]?, inSpellDocumentWithTag tag: Int, completionHandler completionHandler: ((Int, [NSTextCheckingResult], NSOrthography, Int) -> Void)?) -> Int

    Objective-C

    - (NSInteger)requestCheckingOfString:(NSString *)stringToCheck range:(NSRange)range types:(NSTextCheckingTypes)checkingTypes options:(NSDictionary<NSString *,id> *)options inSpellDocumentWithTag:(NSInteger)tag completionHandler:(void (^)(NSInteger sequenceNumber, NSArray<NSTextCheckingResult *> *results, NSOrthography *orthography, NSInteger wordCount))completionHandler

    Parameters

    stringToCheck

    The string to check.

    range

    The range of the string to check.

    checkingTypes

    The type of checking to be performed. The possible constants are listed in NSTextCheckingType and can be combined using the C bit-wise OR operator to perform multiple checks at the same time.

    options

    The options dictionary specifying the types of checking to perform. See Spell Checking Option Dictionary Keys for the possible keys and expected values.

    tag

    An identifier unique within the application used to inform the spell checker which document that text is associated, potentially for many purposes, not necessarily just for ignored words. A value of 0 can be passed in for text not associated with a particular document.

    completionHandler

    The completion handler block object will be called (in an arbitrary context) when results are available, with the sequence number and results.

    The block takes four arguments:

    sequenceNumber

    A monotonically increasing sequence number.

    results

    An array of NSTextCheckingResult objects describing particular items found during checking and their individual ranges, sorted by range origin, then range end, then result type..

    orthography

    The orthography of the string.

    wordCount

    The number of words in the range of the string.

    Return Value

    The return value is a monotonically increasing sequence number that can be used to keep track of requests in flight.

    Availability

    Available in OS X v10.6 and later.

  • Returns an array of possible substitutions for the specified string.

    Declaration

    Swift

    func guessesForWordRange(_ range: NSRange, inString string: String, language language: String?, inSpellDocumentWithTag tag: Int) -> [String]?

    Objective-C

    - (NSArray<NSString *> *)guessesForWordRange:(NSRange)range inString:(NSString *)string language:(NSString *)language inSpellDocumentWithTag:(NSInteger)tag

    Parameters

    range

    The range of the string to check.

    string

    The string to guess.

    language

    The language of the string.

    tag

    An identifier unique within the application used to inform the spell checker which document that text is associated, potentially for many purposes, not necessarily just for ignored words. A value of 0 can be passed in for text not associated with a particular document.

    Return Value

    An array of strings containing possible replacement words.

    Availability

    Available in OS X v10.6 and later.

  • Returns whether automatic spelling replacement is enabled.

    Declaration

    Swift

    class func isAutomaticTextReplacementEnabled() -> Bool

    Objective-C

    + (BOOL)isAutomaticTextReplacementEnabled

    Return Value

    Returns YEStrue if automatic spelling correction is enabled; NOfalse otherwise.

    Availability

    Available in OS X v10.7 and later.

Data Types

  • These constants allow an application to specify the correction indicator type displayed.

    Declaration

    Swift

    enum NSCorrectionIndicatorType : Int { case Default case Reversion case Guesses }

    Objective-C

    enum { NSCorrectionIndicatorTypeDefault = 0, NSCorrectionIndicatorTypeReversion, NSCorrectionIndicatorTypeGuesses }; typedef NSInteger NSCorrectionIndicatorType;

    Constants

    • Default

      NSCorrectionIndicatorTypeDefault

      The default indicator that shows a proposed correction.

      Available in OS X v10.7 and later.

    • Reversion

      NSCorrectionIndicatorTypeReversion

      Provides the option to revert to the original form after a correction has been made.

      Available in OS X v10.7 and later.

    • Guesses

      NSCorrectionIndicatorTypeGuesses

      Shows multiple alternatives from which the user may choose the appropriate spelling.

      Available in OS X v10.7 and later.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • The correction response passed to therecordResponse:toCorrection:forWord:language:inSpellDocumentWithTag: method.

    Declaration

    Swift

    enum NSCorrectionResponse : Int { case None case Accepted case Rejected case Ignored case Edited case Reverted }

    Objective-C

    enum { NSCorrectionResponseNone, NSCorrectionResponseAccepted, NSCorrectionResponseRejected, NSCorrectionResponseIgnored, NSCorrectionResponseEdited, NSCorrectionResponseReverted }; typedef NSInteger NSCorrectionResponse;

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • Declaration

    Swift

    let NSTextCheckingOrthographyKey: String let NSTextCheckingQuotesKey: String let NSTextCheckingReplacementsKey: String let NSTextCheckingReferenceDateKey: String let NSTextCheckingReferenceTimeZoneKey: String let NSTextCheckingDocumentURLKey: String let NSTextCheckingDocumentTitleKey: String let NSTextCheckingDocumentAuthorKey: String

    Objective-C

    NSString *NSTextCheckingOrthographyKey; NSString *NSTextCheckingQuotesKey; NSString *NSTextCheckingReplacementsKey; NSString *NSTextCheckingReferenceDateKey; NSString *NSTextCheckingReferenceTimeZoneKey; NSString *NSTextCheckingDocumentURLKey; NSString *NSTextCheckingDocumentTitleKey; NSString *NSTextCheckingDocumentAuthorKey;

    Constants

    • NSTextCheckingOrthographyKey

      NSTextCheckingOrthographyKey

      An NSOrthography instance indicating an orthography to be used as a starting point for orthography checking, or as the orthography if orthography checking is not enabled.

      Available in OS X v10.6 and later.

    • NSTextCheckingQuotesKey

      NSTextCheckingQuotesKey

      An NSArray containing four strings to be used with NSTextCheckingTypeQuote (opening double quote, closing double quote, opening single quote, and closing single quote in that order); if not specified, values will be taken from user's preferences.

      Available in OS X v10.6 and later.

    • NSTextCheckingReplacementsKey

      NSTextCheckingReplacementsKey

      An NSDictionary containing replacements to be used with NSTextCheckingTypeReplacement; if not specified, values will be taken from user's preferences.

      Available in OS X v10.6 and later.

    • NSTextCheckingReferenceDateKey

      NSTextCheckingReferenceDateKey

      An NSDate to be associated with the document, used as a referent for relative dates; if not specified, the current date will be used.

      Available in OS X v10.6 and later.

    • NSTextCheckingReferenceTimeZoneKey

      NSTextCheckingReferenceTimeZoneKey

      An NSTimeZone to be associated with the document, used as a reference for dates without time zones; if not specified, the current time zone will be used.

      Available in OS X v10.6 and later.

    • NSTextCheckingDocumentURLKey

      NSTextCheckingDocumentURLKey

      An NSURL to be associated with the document.

      Available in OS X v10.6 and later.

    • NSTextCheckingDocumentTitleKey

      NSTextCheckingDocumentTitleKey

      An NSString containing the title to be associated with the document.

      Available in OS X v10.6 and later.

    • NSTextCheckingDocumentAuthorKey

      NSTextCheckingDocumentAuthorKey

      An NSString containing the name of an author to be associated with the document

      Available in OS X v10.6 and later.