The jfindpanel.tcl library is distributed as part of the jstools package. It consists of procedures to implement a searchandreplace dialogue box for text widgets. The central procedure is j:find, which creates the dialogue box and calls the other procedures as necessary.
Currently, these procedures all communicate via global variables with the contents of the j:find fields and checkboxes. I hope to change this in the future so that they will take arguments, to make them more useful independently of each other. This means that you shouldn't count on the calling conventions for these procedures staying constant, except for j:find itself.
This document describes jfindpanel.tcl version 4.0/4.0.
In order to use the jfindpanel.tcl library, it (and any other libraries it depends on) must be in your Tcl auto_path, described in tclvars(n). Information about how to arrange that, and other conventions common to the jstools libraries, is in the Usage section of The jstools Libraries.
Jay Sekora
js@calumet.org
http://shore.net/~js/
The library is copyright © 1992-1995 by Jay Sekora, but may be freely redistributed under the conditions at the top of the file.
j:find - searchandreplace panel
j:find:again - search again for same string
j:find:find_pattern - find and select string in text widget
j:find:replace - replace selection in text widget with string
j:find:replace_regexp - replace regular expression in text widget with string
j:find:replace_all - change all occurences of string in text widget
j:find [options] w
w is the text widget to search in
-replace bool (default 1)
This procedure brings up a find panel that allows the user to search for text (and, optionally, replace it) in a text widget, w. By default, i.e. if bool is not false, the panel has two entry widgets labelled `Search for:' and `Replace with:', three checkbuttons labelled `Backwards', `Casesensitive', and `Regex', and four buttons labelled `Search', `Replace', `Replace All', and `Cancel'. (The default button is `Search'.)
Complete usage documentation for the Find Panel itself (as opposed to the library) is available in The jstools Find Panel.
Unless -replace 0 has been specified, the user will be able to replace the found string by typing a replacement in the `Replace with:' field and clicking on the `Replace' or `Replace All' button. You will want to specify -replace 0 when using the find panel with readonly (-state disabled) text widgets. If you don't do this, the user will be able to hang your application by trying to replace text in a disabled widget. (This should probably be considered a bug.)
Note that although the find panel is nonmodal, an application can only have one find panel displayed at a time.
j:find:again w
w is the text widget to search in
This procedure is used to search for the next occurrence of a string previously entered into a find panel. It has the same effect as clicking on the `Search' button in the find panel, but it doesn't require the find panel to be displayed. It's convenient as a keyboard shortcut.
If no value has been entered into a find panel when this procedure is invoked, it will simply call j:find to display a find panel.
These procedures are used by the Find Panel. Their communication conventions are not very mature at this point, so you shouldn't rely on them yet. They (or something like them) will become public procedures in a future version of the library.
* There's no way to do a backwards regularexpression search.
* Searches are done by making copies of large parts of the text in a widget, so they're extremely wasteful of memory.
* The replacement string is always inserted literally; there should be a way to refer to submatches in a regularexpression search.
* Under Tk 4.0, searching should use the text widget's search subcommand; this should make it much more efficient.
* The procedures that actually do the searches should be public, and they should take options rather than looking at global variables to decide what kind of search to perform
* Searches should (perhaps optionally) wrap around.
* You should be able to use more than one Find Panel in an application. The name of a Find Panel should be based on the name of the text widget it searches in. (Perhaps it should be a child, so it'll automatically be destroyed when the text widget is.)
* You should be able to provide a window name for the find panel. If the window doesn't exist, it should be created as a new toplevel; if it does exist, the new find panel should be packed into it (and the `Cancel' button shouldn't be displayed). That would let people created find panels attached to text windows, which might be more intuitive for multiwindow documents.