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

Inheritance


Conforms To


Import Statement


import AppKit @import AppKit;

Availability


Available in OS X v10.0 and later.
  • 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.

    Import Statement

    import AppKit

    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.

    Import Statement

    import AppKit

    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.

    Import Statement

    import AppKit

    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.

    Import Statement

    import AppKit

    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.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Import Statement

    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(_ string: String, startingAt start: Int, language language: String?, wrap wrap: Bool, inSpellDocumentWithTag documentTag: Int, details outDetails: AutoreleasingUnsafeMutablePointer<NSArray?>) -> NSRange

    Objective-C

    - (NSRange)checkGrammarOfString:(NSString *)string startingAt:(NSInteger)start language:(NSString *)language wrap:(BOOL)wrap inSpellDocumentWithTag:(NSInteger)documentTag details:(NSArray **)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.

    Import Statement

    import AppKit

    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: [NSObject : AnyObject]?, inSpellDocumentWithTag tag: Int, orthography orthography: AutoreleasingUnsafeMutablePointer<NSOrthography?>, wordCount wordCount: UnsafeMutablePointer<Int>) -> [AnyObject]

    Objective-C

    - (NSArray *)checkString:(NSString *)stringToCheck range:(NSRange)range types:(NSTextCheckingTypes)checkingTypes options:(NSDictionary *)options inSpellDocumentWithTag:(NSInteger)tag orthography:(NSOrthography **)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.

    Import Statement

    import AppKit

    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: [NSObject : AnyObject]?, inSpellDocumentWithTag tag: Int, completionHandler completionHandler: ((Int, [AnyObject]!, NSOrthography!, Int) -> Void)!) -> Int

    Objective-C

    - (NSInteger)requestCheckingOfString:(NSString *)stringToCheck range:(NSRange)range types:(NSTextCheckingTypes)checkingTypes options:(NSDictionary *)options inSpellDocumentWithTag:(NSInteger)tag completionHandler:(void (^)(NSInteger sequenceNumber, NSArray *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.

    Import Statement

    import AppKit

    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) -> [AnyObject]?

    Objective-C

    - (NSArray *)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.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.6 and later.

  • Returns a guaranteed unique tag to use as the spell-document tag for a document.

    Declaration

    Swift

    class func uniqueSpellDocumentTag() -> Int

    Objective-C

    + (NSInteger)uniqueSpellDocumentTag

    Return Value

    Returns a unique tag to identified this spell checked object.

    Discussion

    Use this method to generate tags to avoid collisions with other objects that can be spell checked.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Notifies the receiver that the user has finished with the tagged document.

    Declaration

    Swift

    func closeSpellDocumentWithTag(_ tag: Int)

    Objective-C

    - (void)closeSpellDocumentWithTag:(NSInteger)tag

    Discussion

    The spell checker will release any resources associated with the document, including but not necessarily limited to, ignored words.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Instructs the spell checker to ignore all future occurrences of wordToIgnore in the document identified by tag.

    Declaration

    Swift

    func ignoreWord(_ wordToIgnore: String, inSpellDocumentWithTag tag: Int)

    Objective-C

    - (void)ignoreWord:(NSString *)wordToIgnore inSpellDocumentWithTag:(NSInteger)tag

    Discussion

    You should invoke this method from within your implementation of the NSIgnoreMisspelledWords protocol’s ignoreSpelling: method.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the array of ignored words for a document identified by tag.

    Declaration

    Swift

    func ignoredWordsInSpellDocumentWithTag(_ tag: Int) -> [AnyObject]?

    Objective-C

    - (NSArray *)ignoredWordsInSpellDocumentWithTag:(NSInteger)tag

    Discussion

    Invoke this method before closeSpellDocumentWithTag: if you want to store the ignored words.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Initializes the ignored-words document (a dictionary identified by tag with someWords), an array of words to ignore.

    Declaration

    Swift

    func setIgnoredWords(_ words: [AnyObject], inSpellDocumentWithTag tag: Int)

    Objective-C

    - (void)setIgnoredWords:(NSArray *)words inSpellDocumentWithTag:(NSInteger)tag

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Sets the string that appears in the misspelled word field, using the string object aString.

    Declaration

    Swift

    func setWordFieldStringValue(_ aString: String)

    Objective-C

    - (void)setWordFieldStringValue:(NSString *)aString

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Causes the spell checker to update the Spelling panel’s misspelled-word field to reflect word.

    Declaration

    Swift

    func updateSpellingPanelWithMisspelledWord(_ word: String)

    Objective-C

    - (void)updateSpellingPanelWithMisspelledWord:(NSString *)word

    Discussion

    You are responsible for highlighting word in the document and for extracting it from the document using the range returned by the checkSpelling:... methods. Pass the empty string as word to have the system beep, indicating no misspelled words were found.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Provides a list of complete words that the user might be trying to type based on a partial word in a given string.

    Declaration

    Swift

    func completionsForPartialWordRange(_ partialWordRange: NSRange, inString string: String, language language: String?, inSpellDocumentWithTag spellDocumentTag: Int) -> [AnyObject]?

    Objective-C

    - (NSArray *)completionsForPartialWordRange:(NSRange)partialWordRange inString:(NSString *)string language:(NSString *)language inSpellDocumentWithTag:(NSInteger)spellDocumentTag

    Parameters

    partialWordRange

    Range that identifies a partial word in string.

    string

    String with the partial word from which to generate the result.

    language

    Language to used in string. When nil, this method uses the language selected in the Spelling panel.

    spellDocumentTag

    Identifies the spell document with ignored words to use.

    Return Value

    List of complete words from the spell checker dictionary in the order they should be presented to the user.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.3 and later.

  • Indicates whether the spell checker has learned a given word.

    Declaration

    Swift

    func hasLearnedWord(_ word: String) -> Bool

    Objective-C

    - (BOOL)hasLearnedWord:(NSString *)word

    Parameters

    word

    Word in question.

    Return Value

    YEStrue when the spell checker has learned word, NOfalse otherwise.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.5 and later.

    See Also

    – learnWord:

  • Tells the spell checker to unlearn a given word.

    Declaration

    Swift

    func unlearnWord(_ word: String)

    Objective-C

    - (void)unlearnWord:(NSString *)word

    Parameters

    word

    Word to unlearn.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.5 and later.

    See Also

    – learnWord:

  • forgetWord: forgetWord: (OS X v10.5)

    Remove this word from the spelling dictionary.

    Deprecation Statement

    Use unlearnWord: instead.

    Declaration

    Objective-C

    - (void)forgetWord:(NSString *)word

    Parameters

    word

    The word to remove.

    Import Statement

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.5.

  • Adds the word to the spell checker dictionary.

    Declaration

    Swift

    func learnWord(_ word: String)

    Objective-C

    - (void)learnWord:(NSString *)word

    Parameters

    word

    The word to add.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Returns the default values for quote replacement.

    Declaration

    Swift

    func userQuotesArrayForLanguage(_ language: String) -> [AnyObject]

    Objective-C

    - (NSArray *)userQuotesArrayForLanguage:(NSString *)language

    Parameters

    language

    The language for quote replacement.

    Return Value

    An array of quote replacements used by the NSTextCheckingQuotesKey key-value pair.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.6 and later.

  • Returns the dictionary used when replacing words.

    Declaration

    Swift

    var userReplacementsDictionary: [NSObject : AnyObject] { get }

    Objective-C

    @property(readonly, copy) NSDictionary *userReplacementsDictionary

    Return Value

    The dictionary.

    Discussion

    The key-value pairs in this dictionary are used by the NSTextCheckingQuotesKey when replacing characters and words.

    Import Statement

    import AppKit

    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.

    Import Statement

    import AppKit

    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

    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

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • Declaration

    Swift

    var NSTextCheckingOrthographyKey: NSString! var NSTextCheckingQuotesKey: NSString! var NSTextCheckingReplacementsKey: NSString! var NSTextCheckingReferenceDateKey: NSString! var NSTextCheckingReferenceTimeZoneKey: NSString! var NSTextCheckingDocumentURLKey: NSString! var NSTextCheckingDocumentTitleKey: NSString! var NSTextCheckingDocumentAuthorKey: NSString!

    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.

    Import Statement