NSSpellChecker Class Reference

Inherits from	NSObject
Conforms to	NSObject (NSObject)
Framework	/System/Library/Frameworks/AppKit.framework
Availability	Available in Mac OS X v10.0 and later.
Companion guide	Spell Checking
Declared in	NSSpellChecker.h
Related sample code	SpellingChecker CarbonCocoa Bundled SpellingChecker-CarbonCocoa SpellingChecker-CocoaCarbon

Overview

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 Mac OS X v10.3.

Tasks

Getting the Spell Checker

Configuring Spell Checkers Languages

Managing Panels

Checking Strings for Spelling and Grammar

Managing the Spell-Checking Process

Data Detector Interaction

Class Methods

sharedSpellChecker

Returns the NSSpellChecker (one per application).

+ (NSSpellChecker *)sharedSpellChecker

Return Value

The spelling checker shared by this application.

Availability

Available in Mac OS X v10.0 and later.

Related Sample Code

Declared In

NSSpellChecker.h

sharedSpellCheckerExists

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

+ (BOOL)sharedSpellCheckerExists

Return Value

YES if the shared spell checker already exists, otherwise NO.

Availability

Available in Mac OS X v10.0 and later.

Declared In

NSSpellChecker.h

uniqueSpellDocumentTag

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

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

Availability

Available in Mac OS X v10.0 and later.

Related Sample Code

Declared In

NSSpellChecker.h

Instance Methods

accessoryView

Returns the Spelling panel’s accessory view.

- (NSView *)accessoryView

Return Value

The accessory view or nil if there is none.

Availability

Available in Mac OS X v10.0 and later.

Declared In

NSSpellChecker.h

automaticallyIdentifiesLanguages

Returns whether the spell checker will automatically identify languages.

- (BOOL)automaticallyIdentifiesLanguages

Return Value

YES if languages are automatically identified, otherwise NO.

Availability

Available in Mac OS X v10.6 and later.

Declared In

NSSpellChecker.h

availableLanguages

Provides a list of all available languages.

- (NSArray *)availableLanguages

Return Value

An array containing all the available spell checking languages. The languages are ordered in the user’s preferred order as set in the system preferences.

Discussion

If automaticallyIdentifiesLanguages is YES, then text checking will automatically use this method as appropriate; otherwise, it will use the language set by setLanguage:.

The older checkSpellingOfString:startingAt:language:wrap:inSpellDocumentWithTag:wordCount: and checkGrammarOfString:startingAt:language:wrap:inSpellDocumentWithTag:details:. methods will use the language set by setLanguage:, if they are called with a nil language argument.

Availability

Available in Mac OS X v10.5 and later.

Declared In

NSSpellChecker.h

checkGrammarOfString:startingAt:language:wrap:inSpellDocumentWithTag:details:

Initiates a grammatical analysis of a given string.

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

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

NO 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 Mac OS X v10.5 and later.

Declared In

NSSpellChecker.h

checkSpellingOfString:startingAt:

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

- (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 Mac OS X v10.0 and later.

Related Sample Code

Declared In

NSSpellChecker.h

checkSpellingOfString:startingAt:language:wrap:inSpellDocumentWithTag:wordCount:

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

- (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: YES to indicate that spell checking should continue at the beginning of the string when the end of the string is reached; NO 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 Mac OS X v10.0 and later.

Related Sample Code

Declared In

NSSpellChecker.h

checkString:range:types:options:inSpellDocumentWithTag:orthography:wordCount:

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

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

Availability

Available in Mac OS X v10.6 and later.

Declared In

NSSpellChecker.h

closeSpellDocumentWithTag:

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

- (void)closeSpellDocumentWithTag:(NSInteger)tag

Discussion

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

Availability

Available in Mac OS X v10.0 and later.

Related Sample Code

Declared In

NSSpellChecker.h

completionsForPartialWordRange:inString:language:inSpellDocumentWithTag:

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

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

Availability

Available in Mac OS X v10.3 and later.

Declared In

NSSpellChecker.h

countWordsInString:language:

Returns the number of words in stringToCount.

- (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 Mac OS X v10.0 and later.

Declared In

NSSpellChecker.h

guessesForWordRange:inString:language:inSpellDocumentWithTag:

Returns an array of possible substitutions for the specified string.

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

Availability

Available in Mac OS X v10.6 and later.

Declared In

NSSpellChecker.h

hasLearnedWord:

Indicates whether the spell checker has learned a given word.

- (BOOL)hasLearnedWord:(NSString *)word

Parameters

word: Word in question.

Return Value

YES when the spell checker has learned word, NO otherwise.

Availability

Available in Mac OS X v10.5 and later.

Declared In

NSSpellChecker.h

ignoredWordsInSpellDocumentWithTag:

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

- (NSArray *)ignoredWordsInSpellDocumentWithTag:(NSInteger)tag

Discussion

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

Availability

Available in Mac OS X v10.0 and later.

Related Sample Code

Declared In

NSSpellChecker.h

ignoreWord:inSpellDocumentWithTag:

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

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

Discussion

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

Availability

Available in Mac OS X v10.0 and later.

Related Sample Code

Declared In

NSSpellChecker.h

language

Returns the current language used in spell checking.

- (NSString *)language

Return Value

The current spell checking language, as a string.

Discussion

The result string specifies the language using the language and regional designations described in Language and Locale Designations in Internationalization Programming Topics.

Availability

Available in Mac OS X v10.0 and later.

Declared In

NSSpellChecker.h

learnWord:

Adds the word to the spell checker dictionary.

- (void)learnWord:(NSString *)word

Parameters

word: The word to add.

Availability

Available in Mac OS X v10.5 and later.

Declared In

NSSpellChecker.h

menuForResult:string:options:atLocation:inView:

Provides a menu containing contextual menu items suitable for certain kinds of detected results.

- (NSMenu *)menuForResult:(NSTextCheckingResult *)result string:(NSString *)checkedString options:(NSDictionary *)options atLocation:(NSPoint)location inView:(NSView *)view

Parameters

result: The NSTextCheckingResult instance for the checked string.
checkedString: The string that has been checked.
options: The options dictionary allows clients to pass in information associated with the document. See “Spell Checking Option Dictionary Keys” for possible key-value pairs.
location: The location, in the view’s coordinate system, to display the menu.
view: The view object over which to display the contextual menu.

Return Value

A menu suitable for displaying as a contextual menu, or adding to another contextual menu as a submenu.

Availability

Available in Mac OS X v10.6 and later.

Declared In

NSSpellChecker.h

requestCheckingOfString:range:types:options:inSpellDocumentWithTag:completionHandler:

Requests that the string be checked in the background.

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

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 Mac OS X v10.6 and later.

Declared In

NSSpellChecker.h

setAccessoryView:

Makes an view an accessory of the Spelling panel by making it a subview of the panel’s content view.

- (void)setAccessoryView:(NSView *)aView

Parameters

aView: The accessory view displayed in the receiver.

Discussion

The accessory view can be any custom view you want to display with the spelling panel. The accessory view is displayed below the spelling checker and the panel automatically resizes to accommodate the accessory view.

This method posts a notification named NSWindowDidResizeNotification with the Spelling panel object to the default notification center.

Availability

Available in Mac OS X v10.0 and later.

Declared In

NSSpellChecker.h

setAutomaticallyIdentifiesLanguages:

Sets whether the spell checker will automatically identify languages.

- (void)setAutomaticallyIdentifiesLanguages:(BOOL)flag

Parameters

flag: YES if languages should be automatically identified, otherwise NO.

Availability

Available in Mac OS X v10.6 and later.

Declared In

NSSpellChecker.h

setIgnoredWords:inSpellDocumentWithTag:

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

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

Availability

Available in Mac OS X v10.0 and later.

Related Sample Code

Declared In

NSSpellChecker.h

setLanguage:

Returns whether the specified language is in the Spelling pop-up list.

- (BOOL)setLanguage:(NSString *)language

Parameters

language: The requested language.

Return Value

YES if the language is available in the pop-up list, otherwise NO.

Discussion

Listing 1 shows how languages can be specified in language. If the language specified is listed in the user’s list of preferred languages, the spell checker uses that language to accomplish its task.

Listing 1 Specifying the spell checker language

NSSpellChecker* spell_checker = [NSSpellChecker sharedSpellChecker];

// Sets language to French. The language method returns "fr".

[spell_checker setLanguage:@"fr"];

// Sets language to the one spoken in Netherlands (English). The language method returns "en".

[spell_checker setLanguage:@"NL"];

// Sets language to British English. The language method returns "en_GB".

[spell_checker setLanguage:@"en_GB"]

 // Sets language to German. The language method returns "de".

[spell_checker setLanguage:@"German"];

To learn about the strings you can use to specify a language in language, see Language and Locale Designations in Internationalization Programming Topics.

Availability

Available in Mac OS X v10.0 and later.

Declared In

NSSpellChecker.h

setSubstitutionsPanelAccessoryViewController:

Sets the substitutions panel’s accessory view.

- (void)setSubstitutionsPanelAccessoryViewController:(NSViewController *)accessoryController

Parameters

accessoryController: The accessory view controller or nil if there is none.

Discussion

The accessory view controller can accommodate be any custom view you want to display with the substitutions panel. The accessory view controller’s view is displayed below the substitutions list and the panel automatically resizes to accommodate the accessory view.

This method posts a notification named NSWindowDidResizeNotification with the substitutions panel object to the default notification center.

Availability

Available in Mac OS X v10.6 and later.

Declared In

NSSpellChecker.h

setWordFieldStringValue:

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

- (void)setWordFieldStringValue:(NSString *)aString

Availability

Available in Mac OS X v10.0 and later.

Declared In

NSSpellChecker.h

spellingPanel

Returns the spell checker’s panel.

- (NSPanel *)spellingPanel

Return Value

The spell checking panel.

Availability

Available in Mac OS X v10.0 and later.

Declared In

NSSpellChecker.h

substitutionsPanel

Returns the substitutions panel.

- (NSPanel *)substitutionsPanel

Return Value

The substitutions checking panel.

Availability

Available in Mac OS X v10.6 and later.

Declared In

NSSpellChecker.h

substitutionsPanelAccessoryViewController

Returns the substitutions panel’s accessory view controller.

- (NSViewController *)substitutionsPanelAccessoryViewController

Return Value

The accessory view controller or nil if there is none.

Availability

Available in Mac OS X v10.6 and later.

Declared In

NSSpellChecker.h

unlearnWord:

Tells the spell checker to unlearn a given word.

- (void)unlearnWord:(NSString *)word

Parameters

word: Word to unlearn.

Availability

Available in Mac OS X v10.5 and later.

Declared In

NSSpellChecker.h

updatePanels

Updates the available panels to account for user changes.

- (void)updatePanels

Discussion

This method should be called when a client changes some relevant setting, such as what kind of spelling, grammar checking, or substitutions it uses.

Availability

Available in Mac OS X v10.6 and later.

Declared In

NSSpellChecker.h

updateSpellingPanelWithGrammarString:detail:

Specifies a grammar-analysis detail to highlight in the Spelling panel.

- (void)updateSpellingPanelWithGrammarString:(NSString *)problemString detail:(NSDictionary *)detail

Parameters

problemString: Problematic grammatical unit identified by checkGrammarOfString:startingAt:language:wrap:inSpellDocumentWithTag:details:.
detail: One of the grammar-analysis details provided by checkGrammarOfString:startingAt:language:wrap:inSpellDocumentWithTag:details:.

Availability

Available in Mac OS X v10.5 and later.

Declared In

NSSpellChecker.h

updateSpellingPanelWithMisspelledWord:

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

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

Availability

Available in Mac OS X v10.0 and later.

Declared In

NSSpellChecker.h

userPreferredLanguages

Provides a subset of the available languages to be used for spell checking.

- (NSArray *)userPreferredLanguages

Return Value

An array containing the user’s preferred languages for spell checking. The order is set in the system preferences.

Discussion

If automaticallyIdentifiesLanguages is YES, then text checking will automatically use this method as appropriate; otherwise, it will use the language set by setLanguage:.

Availability

Available in Mac OS X v10.6 and later.

Declared In

NSSpellChecker.h

userQuotesArrayForLanguage:

Returns the default values for quote replacement.

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

Availability

Available in Mac OS X v10.6 and later.

Declared In

NSSpellChecker.h

userReplacementsDictionary

Returns the dictionary used when replacing words.

- (NSDictionary *)userReplacementsDictionary

Return Value

The dictionary.

Discussion

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

Availability

Available in Mac OS X v10.6 and later.

Declared In

NSSpellChecker.h

Constants

Spell Checking Option Dictionary Keys

The constants are optional keys that can be used in the options dictionary parameter of the checkString:range:types:options:inSpellDocumentWithTag:orthography:wordCount:, requestCheckingOfString:range:types:options:inSpellDocumentWithTag:completionHandler:, and menuForResult:string:options:atLocation:inView: methods.

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

Constants

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 Mac OS X v10.6 and later.