jfindpanel.tcl
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.
Under Tk4.0 and later, these procedures use the native
find method of the Tk Text widget, which does searches linebyline.
Therefore, search patterns can't cross lines. I consider
this a bug in the find panel, and I hope to work around it in
the future.
This document describes
jfindpanel.tcl version 1998.09.30.
Accessing the Library
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.
Author
Jay Sekora
js@aq.org
http://www.aq.org/~js/
Copyright
The library is copyright © 1992-1998 by Jay Sekora, but may be
freely redistributed under the conditions at the top of the file.
Procedures
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
Usage
j:find
[options]
w
Argument
w is the text widget to search in
Option
-replace
bool
(default
1)
-findhistory
findhist
(default
j_find)
-replacehistory
replhist
(default
j_repl)
Description
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.)
If
findhist or
replhist is specified, they are used as the names of the history lists
for the find and replace entries, respectively. (History lists
are implemented by
jhistory.tcl.) The defaults should be fine unless your users are editing
specialpurpose text. (For instance, it might make sense to
use different history lists for editing program code and email.)
However, I recommend leaving the defaults when your users are
editing generalpurpose naturallanguage text. You can eliminate
either history list (and the corresponding buttons) by specifying
it as `{}'.
Note that although the find panel is nonmodal, an application
can only have one find panel displayed at a time.
Usage
j:find:again
w
Argument
w is the text widget to search in
Description
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.
Bugs and Limitations
- Under Tk3.6 and earlier, searches are done by making copies
of large parts of the text in a widget, so they're extremely wasteful
of memory.
- Under Tk4.0 and later, a search string can't contain a newline.
(Well, it can, but that guarantees that it won't be found,
since the text widget does searches linebyline.)
- The replacement string is always inserted literally; there
should be a way to refer to submatches in a regularexpression
search.
Future Directions
- 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
- You should be able to use more than one Find Panel in an application.
- 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.