Copyright ã1993 Christopher J. Kane.  All Rights Reserved.

FindPanel

Inherits From:	Panel : Window : Responder : Object

Declared In:	FindPanel.h

Class Description

The FindPanel provides an user interface to text searching and replacing facilities within applications.  Text fields, radio buttons, and switch boxes are provided to allow the user to control the parameters of a search or replace-type operation; buttons are provided to actuate the various operations.  Target methods are provided for standard menu items.  The FindPanel also interacts with the Find pasteboard to provide sharing of search text among applications.  To easily incorporate the FindPanel into an application you are constructing, see the document entitled HowToUse.rtf and the documentation on the FindPanelClass category to the Application class.

Several features of generic panels are disabled in the FindPanel class.  There is only one instance of the FindPanel per application.  The methods allocation, deallocation, and initialization class and instance methods have been overridden to either do nothing, or generate and error and terminate an application if the FindPanel or its class receives one of them.  The methods to copy objects have been similarly disabled.  The FindPanel is also a fixed-size panel; the methods that change a panel's size have also been overridden to limit their functionality (the exception to this is that when the enabled state of the replacement functionality of the FindPanel is changed with the class method setReplacementEnabled:, the window is resized for aesthetic reasons).  Finally, the FindPanel may not be miniaturized, nor may its close button be set to the "document edited" state.

The NX_pasteboardComm and NX_appkitVMError exceptions are ignored when reading from and writing to the Find pasteboard, with an informational message written to the system log.

The First Conformer

The FindPanel provides its user interface facilities only to objects that conform to the SearchableText protocol.  When the panel receives one of its action messages, it searches for the first object that conforms to the protocol in the responder chain.  The search proceeds as follows (the search ends immediately when a conforming object is found):

1.	If the FindPanel is not the key window, the search begins with the first responder of the key window.  The key window's responder chain is searched, ending with the window itself.  If no conformer has been found, the key window's delegate is checked for conformance.

2.	Next, if the main window is different from the key window, the responder chain of the main window, then main window's delegate, are checked.

3.	Lastly, NXApp and its delegate (in that order) are checked for conformance.

If no object conforming to the SearchableText protocol is found, nothing happens.  Otherwise, the conforming object, called the first conformer in this document, is the target of messages sent by the FindPanel's action message.  Note that in the case of the FindPanel's action method replaceAndFind:, that the find message might be sent to a different object than the replace message if the object receiving the replace message changes the key or main windows, or the responder chain, during its operation.  See the documentation on the SearchableText protocol for a list of messages the FindPanel sends to the first conformer.

Interacting with the Find Pasteboard

The FindPanel couples its findTextField and the Find pasteboard so that text to search for is retrieved from and text searched for is saved to the pasteboard.  This allows some "communication" between the searching facilities of different applications.  The user could, for instance, enter a selection in one application, then switch to another and search for that selection.

The Find pasteboard is queried for text in two cases:
·	When it is sent an orderWindow:relativeTo: message, such as when it is ordered onto the screen.
·	When the user initiates a search operation, and there is no text in the findTextField.
The contents of the findTextField are written to the Find pasteboard when the user initiates a search (but after the pasteboard is queried if there was no text in the findTextField).  The Find pasteboard is also examined during an enterSelection: operation, after the first conformer has been given the opportunity to write the current selection to the pasteboard.

The reading from and writing to of text to the Find pasteboard can be enabled and disabled programmatically with the setFindPbEnabled: message to the FindPanel class.  By default, it is enabled.  However, the pasteboard always queried during an enterSelection: operation.

Instance Variables

TextField *findTextField	TextField for the text for which to search
TextField *replaceTextField	TextField to contain the text with which to replace
TextField *messageTextField	TextField used to display messages
Button *ignoreCaseButton	Switch button to specify case sensitivity
Button *regExprButton	Switch button to specify regular expression searches
Matrix *scopeMatrix	Radio matrix used to specify scope for replaceAll:

Method Types

Accessing the panel	+ sharedInstance

Changing panel behavior	+ setReplacementEnabled:
	+ setFindPbEnabled:

Panel actions	- enterSelection:
	- findBackward:
	- findForward:
	- jumpToSelection:
	- replace:
	- replaceAll:
	- replaceAndFind:

Accessing panel objects	- findTextField
	- ignoreCaseButton
	- messageTextField
	- regExprButton
	- replaceTextField
	- scopeMatrix

Class Methods

alloc
	+ alloc

Generates an error message and aborts the application.  This method cannot be used to allocate FindPanel instances.  Use the class method sharedInstance to access the FindPanel.

allocFromZone:
	+ allocFromZone:(NXZone *)zone

Generates an error message and aborts the application.  This method cannot be used to allocate FindPanel instances.  Use the class method sharedInstance to access the FindPanel.

new
	+ new

Generates an error message and aborts the application.  This method cannot be used to allocate FindPanel instances.  Use the class method sharedInstance to access the FindPanel.

newContent:style:backing:buttonMask:defer:
	+ newContent:(const NXRect *)contentRect
		style:(int)aStyle
		backing:(int)bufferingType
		buttonMask:(int)mask
		defer:(BOOL)flag

Generates an error message and aborts the application.  This method cannot be used to allocate FindPanel instances.  Use the class method sharedInstance to access the FindPanel.

newContent:style:backing:buttonMask:defer:screen:
	+ newContent:(const NXRect *)contentRect
		style:(int)aStyle
		backing:(int)bufferingType
		buttonMask:(int)mask
		defer:(BOOL)flag
		screen:(const NXScreen *)screen

Generates an error message and aborts the application.  This method cannot be used to allocate FindPanel instances.  Use the class method sharedInstance to access the FindPanel.

setReplacementEnabled:
	+ setReplacementEnabled:(BOOL)aBool

Enables or disables the FindPanel objects associated with replace-type operations.  If aBool is YES, the "Replace All", "Replace", and "Replace & Find" buttons, the "Replace All Scope" matrix, and the "Replace with" text field are inserted into the panel, and the panel's height is increased to accommodate the text field.  If aBool is NO, these objects are removed from the panel, and the panel's height is decreased.  If aBool is the same as the current enabled state, this method does nothing.  This method does not create the FindPanel if it does not yet exist; the panel is modified, if necessary, when it is created.  Returns self.

setFindPbEnabled:
	+ setFindPbEnabled:(BOOL)aBool

Enables or disables reading from and writing to the Find pasteboard when searches are performed, or when the panel is brought on-screen.  Note that the pasteboard is always queried by enterSelection:.  Returns self.

sharedInstance
	+ sharedInstance

Returns the FindPanel, creating it if necessary.  An application has at most one FindPanel, which is created by loading it from a .nib file.  If the FindPanel.nib cannot be found or loaded, the user is shown an alert panel, and this method returns nil.  After the FindPanel has been successfully loaded, this method may modify it to enable or disable the replacement-related controls, if the replacement-enabled state has been changed from its default state with the class method setReplacementEnabled:.  This method only attempts to load the FindPanel once; even if loading fails the first time, it will not be attempted again.  If the FindPanel class is part of a dynamically loaded class-bundle, the FindPanel.nib files must be stored in language directories in the bundle.  If the class is part of the main executable, the .nib files must be in the language directories in the same directory as the main executable.

Instance Methods

copyFromZone:
	- copyFromZone:(NXZone *)zone

Returns self, without creating a copy of the FindPanel.  There may only be one instance of the FindPanel.

enterSelection:
	- enterSelection:sender

Sends the writeSelectionToPasteboard:asType: message to the first conformer, if there is one, then replaces the text in the findTextField with the text pasted to the pasteboard, if any.  If no text was pasted to the pasteboard, or there was an error communicating with the pasteboard server, this method does nothing.  Returns self.

findBackward:
	- findBackward:sender

Similar to the method findForward:, except that a backwards search is performed.  The search begins at the start of the current selection and ends (after possibly wrapping around in the text) when the text in the findTextField is found, or when the end of the current selection is reached.  The currently selected text is not searched.  Returns self.

findForward:
	- findForward:sender

Initiates a forward search through the text of the first conformer, if one exists.  The text is searched starting from the end of the current selection, and stops when a match is found or the start of the current selection is reached (after wrapping).  If there is no text in the findTextField, and the use of the Find pasteboard has not been disabled, the pasteboard is checked for text and if some is found, it is placed in the findTextField.  If after this the findTextField is still empty, the panel is merely ordered to the front of its window tier and made the key window.  Otherwise, the panel then places the text of the findTextField into the Find pasteboard (if the use of the pasteboard is enabled), identifies the first conformer, and sends it the SearchableText protocol's
searchFor:mode:reverse:regexpr:cases:position:size: method.  If this method returns an error indication, or no first conformer is found, the system beep is played and a localized "Invalid operation" message is displayed in the panel.  If no match is found, the system beep is played and a localized "Not found" message is displayed.  Otherwise, the matched text is selected, and the selection is displayed for the user.  If the "Regular Expression" switch is checked in the FindPanel, the text of the findTextField is treated as if it were a regular expression, otherwise it is treated as a literal string.  If the "Ignore Case" switch is checked, the search is case insensitive.  Returns self.

findTextField
	- (TextField *)findTextField

Returns the id of the TextField into which the user types the text for which to search.

free
	- free

Returns self, without freeing the FindPanel.  The instance may not be freed once it has been created within an application.

ignoreCaseButton
	- (Button *)ignoreCaseButton

Returns the id of the Button with which the user specifies the case sensitivity of a search.

init
	- init

Generates an error message and aborts the application.  The FindPanel is initialized automatically when it is created.

initContent:style:backing:buttonMask:defer:
	- initContent:(const NXRect *)contentRect
		style:(int)aStyle
		backing:(int)bufferingType
		buttonMask:(int)mask
		defer:(BOOL)flag

Generates an error message and aborts the application.  The FindPanel is initialized automatically when it is created.

initContent:style:backing:buttonMask:defer:screen:
	- initContent:(const NXRect *)contentRect
		style:(int)aStyle
		backing:(int)bufferingType
		buttonMask:(int)mask
		defer:(BOOL)flag
		screen:(const NXScreen *)screen

Generates an error message and aborts the application.  The FindPanel is initialized automatically when it is created.

jumpToSelection:
	- jumpToSelection:sender

Sends the makeSelectionVisible message to the first conformer, if there is one.  Returns self.

messageTextField
	- (TextField *)messageTextField
 
Returns the id of the TextField used to display text messages to the user.

miniaturize:
	- miniaturize:sender

Returns self.  This method is overridden to prevent the FindPanel from being miniaturized.

orderWindow:relativeTo:
	- orderWindow:(int)place relativeTo:(int)otherWin

If the FindPanel is being ordered onto the screen, or is having its position above or below other windows changed, the panel is first "reset": any message it is displaying is removed, the pasteboard is checked for new text (and the new text is possibly put into the findTextField), and the text in the findTextField is selected.  Returns self.

placeWindow:
	- placeWindow:(const NXRect *)aRect

Overridden to prevent the FindPanel from being resized.  The panel is moved to the location specified in aRect, but the size information is ignored.  Returns self.

placeWindow:screen:
	- placeWindow:(const NXRect *)aRect screen:(const NXScreen *)aScreen

Overridden to prevent the FindPanel from being resized.  The panel is moved to the location specified in aRect and the screen indicated by aScreen, but the size information is ignored.  Returns self.

placeWindowAndDisplay:
	- placeWindowAndDisplay:(const NXRect *)aRect

Overridden to prevent the FindPanel from being resized.  The panel is moved to the location specified in aRect and sent a display message, but the size information is ignored.  Returns self.

read:
	- read:(NXTypedStream *)stream

Unarchives the FindPanel.  This message should never be sent directly to the FindPanel; it is sent by the system when unarchiving is required.  Returns self.

regExprButton
	- (Button *)regExprButton

Returns the id of the Button with which the user specifies whether or not the text in the findTextField is a regular expression.

replace:
	- replace:sender

Sends the replaceSelection: message to the first conformer, if there is one, passing a pointer to the text in the replaceTextField.  Returns self.

replaceAll:
	- replaceAll:sender

If there is text in the findTextField, sends the replaceAll:with:mode:regexpr:cases: to the first conformer, if there is one, with parameters generated from the current settings of the controls in the  FindPanel; otherwise, does nothing.  If the replace-all operation is successful, the number of replacements is displayed in the panel, otherwise the message "Invalid operation" is displayed and the panel beeps.  Returns self.

replaceAndFind:
	- replaceAndFind:sender

This method is a shorthand for [[[FindPanel new] replace:sender] findForward:sender].  Returns self.

replaceTextField
	- (TextField *)replaceTextField

Returns the id of the TextField into which the user types the text used in replace-type operations.

scopeMatrix
	- (Matrix *)scopeMatrix

Returns the id of the Matrix in which the user specifies the scope for the replaceAll: method.

setDocEdited:
	- setDocEdited:(BOOL)aBool

Returns self.  This method is overridden to prevent the close button in the title bar of the FindPanel from being marked with an open 'X'.

sizeWindow::
	- sizeWindow:(float)x :(float)y

Returns self.  This method is overridden to prevent the FindPanel from being resized.

write:
	- write:(NXTypedStream *)stream

Archives the FindPanel.  This message should never be sent directly to the FindPanel; it is sent by the system when archiving is required.  Returns self.