The Text Objects: 7.3 The Controllers: Search and Replace and Spell-Checking

TextSearchInString(), TextSearchInHugeArray(), SearchOptions, WildCard

Text searches are not specifically part of VisTextClass , but are commonly used on text objects, and they are discussed here for that reason.

TextSearchInString() searches in a single text chunk for a passed text string. If a match is found, a pointer to that match (and the length of the match) are returned in buffers. TextSearchInHugeArray() performs the same searching operations, but can return the segment and offset of a found match within a huge array.

The following SearchOptions may affect the search procedure:

SO_NO_WILDCARDS: If set, the search mechanism ignores any passed WildCard values and treats them as the control character values (CTRL_P, CTRL_Q and CTRL_R) which they overlap.
SO_IGNORE_SOFT_HYPHENS: If set, soft hyphens in the "searched-in" text are treated as if they do not exist, therefore allowing the text "hyphenation" to match "hyphen-ation" in the destination text. If the match string contains soft hyphens, do not set this flag as strings will never match.
SO_BACKWARD_SEARCH: If set, the search will propagate backwards.
SO_IGNORE_CASE: If set, case will be ignored in the search criteria.
SO_PARTIAL_WORD: If set, partial words will be matched.
SO_PRESERVE_CASE_OF_DOCUMENT_STRING: If set, the case of the match string will be altered to preserve the case of the before

Both routines may take wild cards (type WildCard ) in the place of any character. These wildcards tell the search mechanism to accept any character in the allotted space. Passing WC_MATCH_MULTIPLE_CHAR instructs the search mechanism to accept any number of random characters in that place in the search string. The values of WildCard are:

WC_MATCH_SINGLE_CHAR: WC_MATCH_MULTIPLE_CHAR
WC_MATCH_WHITESPACE_CHAR

You can set higher-level features of your text objects with the SearchReplaceControlClass and SpellControlClass controllers. These controllers allow spell-checking and search and replace. These two controllers are designed to interact with each other and use common messages.

SearchReplaceControlClass

This controller allows the use of the text object's built-in search and replace features. The controller must be placed on the GAGCNLT_SELF_LOAD_OPTIONS Application GCN list. This controller sends out the following messages to its GCI_output , which may be intercepted to provide custom behavior:

MSG_SEARCH: MSG_REPLACE_CURRENT
MSG_REPLACE_ALL_OCCURENCES
MSG_REPLACE_ALL_OCCURENCES_IN_SELECTION
MSG_META_GET_OBJECT_FOR_SEARCH_SPELL
MSG_META_DISPLAY_OBJECT_FOR_SEARCH_SPELL

Because many of these messages are shared by the SpellControlClass, they are described in Shared Functionality .

The Search & Replace messages make use of a SearchReplaceStruct . This structure is followed by text string(s) that represent the strings to search (and replace if that is the case). These strings may contain WildCard values (unless SO_NO_WILDCARDS is set in params ).The SearchReplaceStruct is shown below:

typedef struct {
	word		searchSize;
	word		replaceSize;
	byte		params;
	optr		replyObject;
	Message		replyMsg;
} SearchReplaceStruct;

searchSize stores the number of characters in the search string, including the null terminator.

replaceSize stores the number of characters in the replace string (if present), including the null terminator.

params stores the SearchOptions in use for this operation.

replyObject stores the optr of the object to send the replyMsg to if the string is not found.

replyMsg stores the message sent to the replyObject above.

The block containing this SearchReplaceStruct will contain either one null-terminated string (if the operation is just a simple search operation) or a null-terminated search string followed by a null-terminated replace string (if the operation is a search & replace).

MSG_SEARCH

@importMessage MetaSearchSpellMessages, void MSG_SEARCH(
        MemHandle		searchInfo);

This message is sent by the SearchReplace controller when an object is starting a search operation. You may intercept this message to find out the nature and specifics of the search.

Source: Search controller.

Destination: GCI_output of the search controller (usually a text object).

Parameters: searchInfo Handle of block containing the SearchReplaceStruct . The search string immediately follows this structure in the passed block. This block should be freed by the message handler.

Interception: Intercept to find out the nature of the search and replace operation.

The features and tools of this controller are shown in SearchReplaceControlClass Features .

Code Display 10-40 SearchReplaceControlClass Features

  typedef WordFlags SRCFeatures;
#define SRCF_CLOSE					0x200
#define SRCF_FIND_NEXT					0x100
#define SRCF_FIND_PREV					0x80
#define SRCF_REPLACE_CURRENT					0x40
#define SRCF_REPLACE_ALL_IN_SELECTION					0x20
#define SRCF_REPLACE_ALL					0x10
#define SRCF_PARTIAL_WORDS					0x08
#define SRCF_IGNORE_CASE					0x04
#define SRCF_WILDCARDS					0x02
#define SRCF_SPECIAL_CHARS					0x01

  typedef WordFlags SRCToolboxFeatures;
#define SRCTF_SEARCH_REPLACE					0x01

#define  SRC_DEFAULT_FEATURES				(SRCF_FIND_NEXT | SRCF_FIND_PREV |
				 SRCF_REPLACE_CURRENT | SRCF_REPLACE_ALL |
				 SRCF_PARTIAL_WORDS | SRCF_IGNORE_CASE |
				 SRCF_WILDCARDS | SRCF_SPECIAL_CHARS | 
				 SRCF_REPLACE_ALL_IN_SELECTION | SRCF_CLOSE)
#define  SRC_DEFAULT_TOOLBOX_FEATURES (SRCTF_SEARCH_REPLACE)

SpellControlClass

This controller allows you to include the advanced spelling-checker features of the text object. The controller must be placed on the GAGCNLT_SELF_LOAD_OPTIONS Application GCN list. The SpellControlClass controller defaults to a state of not enabled; it should be set GS_ENABLED before use.

If the controller will affect a text object within a document object, the SpellControl should be added to the GenDocumentControlClass object's GDCI_enableDisableList . This will ensure that the spell controller is automatically enabled when text appears within the document.

This controller sends out the following messages, which may be intercepted to provide custom behavior:

MSG_SPELL_CHECK: MSG_REPLACE_CURRENT
MSG_REPLACE_ALL_OCCURENCES
MSG_META_GET_CONTEXT
MSG_META_CONTEXT
MSG_META_GET_OBJECT_FOR_SEARCH_SPELL
MSG_META_DISPLAY_OBJECT_FOR_SEARCH_SPELL

MSG_SPELL_CHECK

@importMessage MetaSearchSpellMessages, void MSG_SPELL_CHECK(@stack
        optr		replyObj,
        dword		numCharsToCheck,
        SpellCheckOptions		options,
        MemHandle		ICbuff);

This message is sent by the Spell controller to continue spell checking from the current position in the document.

Source: Spell controller.

Destination: GCI_output of the spell controller.

Parameters: replyObj Object to send MSG_SPELL_CHECK_COMPLETED.

numCharsToCheck: Number of characters to check (if options has SCO_CHECK_NUM_CHARS set).
options: SpellCheckOptions in use for this operation.
IC buff: Handle of buffer to pass spell check library.

Interception: Intercept to find out the nature of the spell checking operation.

MSG_META_GET_CONTEXT

@importMessage MetaSearchSpellMessages, void MSG_META_GET_CONTEXT(@stack
        dword		position,
        ContextLocation		location,
        word		numCharsToGet,
        optr		replyObj);

This message is sent by the Spell controller to find out the current context of the text object. Other objects may also send this message to the text object. The text object will return MSG_META_CONTEXT to the requestor.

Source: The Spell controller. (Other objects may want to send this to retrieve the text context displayed in the spell box.)

Destination: GCI_output of the Spell controller (usually a text object).

Parameters: position Position of the context. The context returned depends on this value and the ContextLocation passed in location .

location: ContextLocation . This may be one of the following values:
CL_STARTING_AT_POSITION: CL_ENDING_AT_POSITION
CL_CENTERED_AROUND_POSITION
CL_CENTERED_AROUND_SELECTION
CL_CENTERED_AROUND_SELECTION_START
CL_SELECTED_WORD
numCharsToGet: Maximum number of characters to return.
replyObj: Optr of the object to reply to via MSG_META_CONTEXT.

Interception: You may intercept to alter the nature of the context request.

MSG_META_CONTEXT

@importMessage MetaSearchSpellMessages, void MSG_META_CONTEXT(
        MemHandle		data);

This message returns the current context to the SpellControl object.

Source: A text object receiving MSG_META_GET_CONTEXT.

Destination: The object that sent the request.

Parameters: data ContextData structure storing information on the context, and the null-terminated context string.

Structures:

typedef struct {
	optr			CD_object;
	dword			CD_numChars;
	dword			CD_startPos;
	VisTextRange			CD_selection;
} ContextData;

CD_object stores the optr of the object that the context is coming from.

CD_numChars stores the number of characters in the text object.

CD_range stores the range of characters that this context represents within the text object.

CD_selection stores the range of characters that represent the current text selection.

The null-terminated context data follows this structure.

Interception: Generally not intercepted.

Its feature and tool definitions are shown in SpellControlClass .

Code Display 10-41 SpellControlClass

  typedef WordFlags SpellFeatures;
#define SF_CLOSE				0x2000
#define SF_CONTEXT				0x1000
#define SF_SIMPLE_MODAL_BOX				0x0800
#define SF_SUGGESTIONS				0x0400
#define SF_CHECK_ALL				0x0200
#define SF_CHECK_TO_END				0x0100
#define SF_CHECK_SELECTION				0x0080
#define SF_SKIP				0x0040
#define SF_SKIP_ALL				0x0020
#define SF_REPLACE_CURRENT				0x0010
#define SF_REPLACE_ALL				0x0008
#define SF_ADD_TO_USER_DICTIONARY				0x0004
#define SF_EDIT_USER_DICTIONARY				0x0002
#define SF_STATUS				0x0001

  typedef WordFlags SpellToolboxFeatures;
#define STF_SPELL				0x01

#define  SC_DEFAULT_FEATURES					(SF_STATUS | SF_EDIT_USER_DICTIONARY | 
		SF_ADD_TO_USER_DICTIONARY | SF_REPLACE_ALL | SF_REPLACE_CURRENT |
		SF_SKIP_ALL | SF_SKIP | SF_CHECK_SELECTION | SF_CHECK_TO_END |
		SF_SUGGESTIONS | SF_CLOSE | SF_CONTEXT)
#define  SC_DEFAULT_TOOLBOX_FEATURES					STF_SPELL

Shared Functionality

The SearchReplace and Spell controllers share a common range of messages (MetaSearchSpellMessages ) imported from MetaClass . (The messages MSG_SEARCH and MSG_SPELL_CHECK are specific to their respective controllers and were described earlier.) These messages common to both controllers are listed and described here.

MSG_REPLACE_CURRENT

@importMessage MetaSearchSpellMessages, void MSG_REPLACE_CURRENT(
        MemHandle		replaceInfo);

This message is sent by the SearchReplace controller when an object is starting a search operation that should replace the found match with the passed replacement string. This message involves a single replacement operation. To perform a replace-all operation, use MSG_REPLACE_ALL_OCCURENCES.

Source: Search controller.

Destination: GCI_output of the search controller (usually a text object).

Parameters: replaceInfo Handle of block containing the SearchReplaceStruct . The null-terminated search string immediately follows this structure. The null-terminated replace string follows that string. This block should be freed by the message handler.

Interception: Intercept to find out the nature of the replacement operation.

MSG_REPLACE_ALL_OCCURRENCES

@importMessage MetaSearchSpellMessages, void MSG_REPLACE_ALL_OCCURRENCES(
        MemHandle		replaceInfo,
        Boolean		replaceFromBeginning);

This message is sent by the SearchReplace controller when an object is starting a search operation that should replace all found matches (in the search string) with the passed replacement string.

Source: Search controller.

Destination: GCI_output of the search controller (usually a text object).

replaceFromBeginning: Non-zero if the replace-all operation should proceed from the beginning of the document; normally, the replace-all operation begins after the current position.

Interception: Intercept to find out the nature of the replacement operation.

MSG_REPLACE_ALL_OCCURRENCES_IN_SELECTION

@importMessage MetaSearchSpellMessages, void MSG_REPLACE_ALL_OCCURRENCES_IN_SELECTION(
        MemHandle		replaceInfo,
        Boolean		replaceFromBeginning);

This message is sent by the SearchReplace controller when an object is starting a search operation that should replace all found matches within a selection (in the search string) with the passed replacement string.

Source: Search controller.

Destination: GCI_output of the search controller (usually a text object).

replaceFromBeginning: Non-zero if the replace-all operation should proceed from the beginning of the selection; normally, the replace-all operation begins after the current position.

Interception: Intercept to find out the nature of the replacement operation.

MSG_META_GET_OBJECT_FOR_SEARCH_SPELL

@importMessage MetaSearchSpellMessages, void MSG_META_GET_OBJECT_FOR_SEARCH_SPELL(
        GetSearchSpellObjectOption					option,
        optr					curObject);

This message is sent by a text object to itself when a search reaches the end of the current object and needs to determine where to continue the search.

Source: Any text object.

Destination: The text object sends this to itself.

Parameters: option GetSearchSpellObjectOption specifying the next object to continue the search at. This value may be GSSOT_FIRST_OBJECT, GSSOT_LAST_OBJECT, GSSOT_NEXT_OBJECT, or GSSOT_PREV_OBJECT.

curObject: Optr of the object that is currently being searched through. If you intercept this message, you can use this information to set the option above.

Interception: May intercept if you want to direct where a search or spell check operation should continue to.

MSG_META_DISPLAY_OBJECT_FOR_SEARCH_SPELL

@importMessage MetaSearchSpellMessages, void MSG_META_DISPLAY_OBJECT_FOR_SEARCH_SPELL();

This message is sent by the text object to itself when a matching word (or misspelled word if the controller is a Spell controller) has been found and should be displayed.

Source: The text object.

Destination: The text object sends this to itself.

Interception: You may intercept this message at the text object to receive notification of a match.

GEOS SDK TechDocs |

7.2 Paragraph Attribute Controllers