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

How to use the FindPanel class

Incorporating the FindPanel into a project

Barring the need to debug the FindPanel class itself (and hopefully you won't have to do that), the FindPanel bundle can be compiled once and installed into a project directory and (for the most part) forgotten.  The most difficult part of the process of adding a FindPanel to your project is implementing the methods of the SearchableText protocol.

In this version of the FindPanel class, the FindPanel searches for a "first conformer" (see the document FindPanel.rtf) in the same places a responder is searched for when an action message destined for the first responder is sent (for instance, the "cut:" message from the Edit/Cut menu item).  The objects in the key and main windows' responder chains, those windows' delegates, and the NXApp object and its delegate are the objects that, potentially, the FindPanel might operate on.  This means that, while the SearchableText protocol could be implemented by any object, the only objects that the FindPanel might try to operate on are Responders of some type: views in a window and windows themselves typically (the exceptions being the key and main windows' delegates and NXApp's delegate, which may be objects of any class).  Most commonly, it is a View of some sort in the main window.  For most projects, this is not a problem; the intent in adding a FindPanel to the application is to operate on a view in the main window.

There are  five simple steps to adding the FindPanel to your project:
1.	Implement the SearchableText protocol in one of your objects.

2.	Build the FindPanel.bundle and install it in your project's directory.  Either:
	a.	On the command line: "make install INSTALLDIR=path" within the FindPanel/FindPanel directory, or
	b.	In Project Builder: load the file FindPanel/FindPanel/PB.project and type "install INSTALLDIR=path" in the 'Args:' text field before building.
	Replace path with the path to your project's directory.

3.	Copy or link the files (FindPanelClass.h, FindPanelClass.m, FindPanel.h, SearchableText.h) into your project's directory.

4.	Add the new files to your project:
	a.	Add FindPanel.bundle to "Other Resources".
	b.	Add FindPanelClass.m to "Other Sources".
	c.	Add FindPanelClass.h, FindPanel.h, and SearchableText.h to "Headers".

5.	In Interface Builder, add a Find menu to the Edit menu of the main menu of your application, and enable each of the menu cells (unless you plan on enabling them programmatically).  Using the class inspector, add the methods (findNext:, findPrevious:, enterSelection:, jumpToSelection:, orderFrontFindPanel:) to the FirstResponder class.  Make one connection from each of the Find menu cells to the First Responder object in the File Window, connecting the appropriate method.

Your application must be linked with the shared library libNeXT_s.  It probably already is.  If you want to strip the main executable of your application, or the install process is going to strip it for you, you need to add the line
APP_STRIP_OPTS = $(DYLD_APP_STRIP_OPTS)
to the file Makefile.postamble (creating the file if it doesn't exist).  This will cause those symbols which might be needed by the dynamically loaded FindPanel class to not be removed from the main executable.  See the manual pages rld(3) and strip(1) if you want to know more.

The FindPanel class can also be statically linked into an application, and the localized files added to others in a project's language directories.  In this case, the FindPanelClass category could still be used to "catch" messages and forward them to the FindPanel, but some modifications would have to be made so that the code does not try to dynamically load the FindPanel class.  The FindPanel code itself should work without modification.  In this case, of course, an application could be "fully" stripped.

Notes on localization

The FindPanel.bundle contains translated panels and strings for the languages: English, French, German, Italian, Spanish, and Swedish.  If you are not supporting some or all of these languages in your project, you will want to remove the appropriate .lproj directory(s) in the FindPanel.bundle, so that if, for instance, your application does not support Spanish, a user will never see a Spanish FindPanel and the rest of your application in some other language.

If you are supporting more than one language in your application, you will want the Find menu items to be localized as well.  The following table shows possible translations for the Find menu items.  Copying and pasting the text out of this document may be the easiest way to get the characters with the diacriticals.

English	Find	Find Panel...	Find Next	Find Previous	Enter Selection	Jump to Selection
French	Rechercher	Panneau de recherche...	Rechercher le suivant	Rechercher le prÝcÝdent	Entrer la sÝlection	Aller Õ la sÝlection
German	Suchen	Dialogfenster "Suchen"	Weitersuchen (vorwÙrts)	Weitersuchen (röckwÙrts)	Auswahl öbernehmen	Zur Auswahl springen
Italian	Trova	Pannello di ricerca...	Trova il seguente	Trova il precedente	Riporta la selezione	Salta alla selezione
Spanish	Buscar	Panel de bósqueda...	Buscar siguiente	Buscar anterior	Introducir selecciín	Pasar a selecciín
Swedish	Sðk	Sðkpanel...	Sðk nÙsta	Sðk fðregÚende	Kopiera markering	GÚ till markering

FindPanel miscellanea

Help is not provided for the FindPanel and its controls.  Under NeXTSTEP 3.x, in my opinion, help text from a bundle is not integrated well into the NXHelpPanel, so I've opted not to provide any.  Also, help is much more application-specific than the FindPanel itself, and I also did not want to translate the help text I would have provided into the non-English languages.  Help text similar to that contained in Edit.app for its Find Panel is suitable for this one as well.

The FindPanel does not save its frame to the defaults database.  Simply use the appropriate Window methods if you want this behavior.