Copyright ©1995 by NeXT Computer, Inc.  All Rights Reserved.

NXSpellChecker

Inherits From:

Object

Declared In:

appkit/NXSpellChecker.h

Class Description

The NXSpellChecker class gives any application an interface to the NeXT spell-checking service.  To handle all its spell checking, an application needs only one instance of NXSpellChecker.  It provides a panel in which the user can record decisions about words that are suspect.  To check the spelling of a piece of text, the application:

		Includes in its user interface a menu item (or a button or command) by which the user will request spell checking and makes the text available by way of an object that adopts certain protocols.
		Creates an instance of the NXSpellChecker class and sends it a checkSpelling:of: message.  The message's arguments identify the object to be checked and one of several modes of checking.

Typical code to make use of NXSpellChecker might be:

[[NXSpellChecker sharedInstance] checkSpelling:NX_CheckSpelling of:self]

The first argument of the checkSpelling:of: method defines the scope of checking: whether the request is just to count words or actually to search for misspellings, and whether the action applies to the entire text and where to start.  The second argument is the object that provides the text to be checked. The application may choose to split a document's text into segments and check them separately.  This will be necessary when the text has segments in different languages.  Spell checking is invoked for one language at a time, so a document that contains portions in three languages will require at least three checks. The object that provides the text must adopt the following protocols (of which the first two are mandatory, while the others are required only if you want to take advantage of functions they provide):

	NXReadOnlyTextStream	This is how the NXSpellChecker reads the text.
	NXSelectText	This is how the NXSpellChecker highlights a misspelled word in the display.
	NXChangeSpelling	A message in this protocol is sent down the responder chain when the user presses the Correct button.
	NXIgnoreMisspelledWords	When the object being checked responds to this protocol, the spell server keeps a list of words that are acceptable in the document, and enables the Ignore button in the Spelling panel.

Dictionaries and Word Lists The process of checking spelling makes use of three references:

		A dictionary registered with the system's spell-checking service.  When the Spelling panel first appears, by default it shows the dictionary for the user's preferred language.  The user may select a different dictionary from the list in the Spelling Panel.
		The user's "learn" list of correctly-spelled words in the current language.  The NXSpellChecker updates the list when the user presses the Learn or Forget buttons in the Spelling panel.
		The document's list of words to be ignored while checking it.  The NXSpellChecker updates its copy of this list when the user presses the Ignore button in the Spelling panel.

A word is misspelled if none of these three accepts it.  When the spelling server finds such a word, it sends messages to the object being checked telling it to select the misspelled word and scroll the document's display to make the selection visible. Matching a List of Ignored Words with the Document It Belongs To Notice that "object providing text to be checked" isn't quite the same as "document." In the course of processing a document, an application might run several checks, based on different parts or different versions of the text.  But they'd all belong to the same document.  The NXSpellChecker keeps a separate "ignored words" list for each document that it checks.  However, when it receives a checkSpelling:of: message, it doesn't know to what document the text belongs.  To match "ignored words" lists to documents, each time the NXSpellChecker starts a search, it asks the application for a spell client tag.  The tag is an arbitrary integer that lasts only while the application runs; it serves only to distinguish one document from the others being checked, and to match each "ignored words" list to a document. When the application closes a document, it may choose to retrieve the "ignored words" list and save it along with the document. To get back the right list, it sends the NXSpellChecker an ignoredWordsForSpellDocument: message, using the document's tag to identify it.  When the application has closed a document, it should notify the NXSpellChecker that the document's "ignored words" list can now be discarded by sending it a closeSpellDocument: message, again using the tag to identify the document that has closed.

Instance Variables

None declared in this class.

Method Types

Getting the NXSpellChecker

+ sharedInstance

+ sharedInstance:

Modifying the spelling panel

spellingPanel

setAccessoryView: accessoryView setWordFieldValue:

Setting the language

setLanguage

language:

Checking spelling

checkSpelling:of:

checkSpelling:of:wordCount:

Managing ignored words

setIgnoredWordsForSpellDocument:

ignoredWords:forSpellDocument: closeSpellDocument:

Class Methods

sharedInstance

+ sharedInstance

Returns an instance of the NXSpellChecker class.  If the application has not yet asked for an NXSpellChecker object, this method allocates and initializes a new instance.  Invoking sharedIntance has the same effect as invoking sharedInstance: with flag set to YES. See also:  + sharedInstance:

sharedInstance:

+ sharedInstance:(BOOL)flag

Returns an instance of the NXSpellChecker class.  If an instance is already in existence, this method simply returns it.  When the application had not yet asked for an NXSpellChecker object, if flag is YES, this method allocates and initializes a new instance.  When flag is NO, the method does not create a new instance and returns nil.

Instance Methods

accessoryView

accessoryView

Returns the customized View of the Spelling panel previously established by setAccessoryView:. See also:  setAccessoryView:

checkSpelling:of:

(BOOL)checkSpelling:(NXSpellCheckMode)mode

of:(id <NXReadOnlyTextStream, NXSelectRange>)anObject

The first argument mode indicates the mode in which the spelling checker will operate, as defined in the enumeration set NXSpellCheckMode.  Values that can be used with checkSpelling:of: are as follows:

	NX_CheckSpelling	Checks spelling of the entire text stream, in sequence from the current character offset to the end, then from the start to the current character offset.
	NX_CheckSpellingFromStart	Checks spelling of the entire text stream, from start to end.
	NX_CheckSpellingToEnd	Checks spelling from the current character offset to the end of the text stream.
	NX_CheckSpellingInSelection	Checks spelling in the selected portion of the text stream.

The method returns YES when the check has found a misspelled word, NO when it has searched the designated portion of the text without finding one. See also:   checkSpelling:of:wordCount:,   currentCharacterOffset (NXReadOnlyTextStream protocol).

checkSpelling:of:wordCount:

(BOOL)checkSpelling:(NXSpellCheckMode)mode

of:(id <NXReadOnlyTextStream, NXSelectRange>)anObject wordCount:(int *)theCount

This method looks for a misspelled word and at the same time counts the number of words scanned.  mode indicates the mode of search or count, a member of the enumeration type NXSpellCheckMode.  Values that can be used with checkSpelling:of:wordCount: are as follows:

	NX_CheckSpelling	Checks spelling and counts words for the entire text stream, in sequence from the current character offset to the end, then from the beginning to the current character offset.
	NX_CheckSpellingFromStart	Checks spelling and counts words for the entire text stream, from start to end.
	NX_CheckSpellingToEnd	Checks spelling and counts words from the current character offset to the end of the text stream.
	NX_CheckSpellingInSelection	Checks spelling and counts words in the selected portion of the text stream.
	NX_CountWords	Counts the number of words in the entire text stream; doesn't check spelling.
	NX_CountWordsToEnd	Counts the number of words from the position reported by current character offset to the end of the text stream; doesn't check spelling.
	NX_CountWordsInSelection	Counts the number of words in the selected portion of the text stream; doesn't check spelling.

theCount points to an integer where the receiver will put the number of words.  If for some reason the spelling checker is unable to count words, it puts 1 there. The method returns YES when the check has found a misspelled word, NO when it has searched the designated portion of the text without finding one. See also:  checkSpelling:of:, currentCharacterOffset (NXReadOnlyTextStream protocol)

closeSpellDocument:

closeSpellDocument:(int)tag

Notifies the NXSpellChecker object that the user has finished with the document identified by tag.  The NXSpellChecker can then discard the temporary list of ignorable words that it compiled for this document.  The argument identifies the document by a numeric tag, previously returned by spellDocumentTag.  Returns self. See also:  spellDocumentTag (NXIgnoreMisspelledWords protocol)

ignoredWordsForSpellDocument:

(char **)ignoredWordsForSpellDocument:(int)tag

Returns the list of ignored words that the spell checker has accumulated for the document identified by the argument tag.  The application may want to preserve the list of ignored words so that they can be ignored in future checks of the same document. To preserve the ignored word list, it should invoke this method after spelling has been checked but before it sends a closeSpellDocument: message.  The argument identifies the document by the  tag that spellDocumentTag returned previously. See also:  spellDocumentTag (NXIgnoreMisspelledWords protocol)

language

(const char *)language

Returns the character string that identifies the English name of the currently selected language.  If the application elects to temporarily override the current language (by invoking setLanguage:), this method will be useful to record the current language so that it can subsequently be restored.  Otherwise, the application will not ordinarily need to use this method. See also:  setLanguage

setAccessoryView:

setAccessoryView:aView

Adds aView to the contents of the Spelling panel.  An application can invoke this method to add controls that extend the panel's functions.  The Spelling panel is automatically resized to accommodate aView.  This method can be invoked repeatedly to change the accessory View depending on the situation.  When aView is nil, the effect is to remove any accessory View that's already in the panel.  Returns the former accessory view, or nil if there was none. See also:  accessoryView

setIgnoredWords:forSpellDocument:

setIgnoredWords:(const char *const *)someWords forSpellDocument:(int)tag

Initializes the NXSpellChecker's list of acceptable words for the document identified by tag.  The first argument is an array of pointers to the words.  The second argument identifies the document for which the list is being maintained (described above in the section "Matching a List of Ignored Words with the Document It Belongs To"). See also:  spellDocumentTag (NXIgnoreMisspelledWords protocol)

setLanguage:

setLanguage:(const char *)aLanguage

Tells the NXSpellChecker object what language to use in subsequent spell check requests.  This method is needed only if the application sometimes overrides the language established by the user's system defaults or by the user's choice of dictionary in the Spelling panel.  (That might be required while checking a document whose text is distributed among several objects, each in a different language).  Upon completion of the check in a different language, the application should restore the default.  To do so, before using setLanguage:, use language to get the language previously in effect, and afterwards use setLanguage: to restore it. Setting a different language causes corresponding changes to the selected dictionary and to the user's list of acceptable words. Suppose that "checker" is the id of an NXSpellChecker instance, and the application sends the following messages:

[checker setLanguage:"French"]
[checker checkSpelling:how of:textToBeChecked]

During the check invoked by the second message, the spelling system refers to the French dictionary rather than the dictionary selected in the Spelling panel, and adds "learned" words to the user's French word list. If aLanguage is NULL, sets the language to the first language for which there is a dictionary from the list of languages returned by systemLanguages (which reports defaults the user has set for the active application, and if none have been set, the user's global language preference).  Returns self when a language has been set, nil otherwise. See also:  systemLanguages (Application)

spellingPanel

spellingPanel

Returns the Panel in which the user can choose a dictionary or select actions with respect to misspelled words.  You will need to identify the Panel in order to bring it forward when the user selects Spelling... in the application's Services menu.  You may also need it if your application elects to modify the panel with setAccessoryView:. See also:  setAccessoryView: