jfindpanel.tcl
Introduction
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.1/4.2.
Usage
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.
Credits and Copyright
Author
Jay Sekora
js@aq.org
http://shore.net/~js/
Copyright
The library is copyright © 1992-1995 by Jay Sekora, but may be
freely redistributed under the conditions at the top of the file.
Overview
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
j:find
Usage
j:find
[options]
w
Argument
w is the text widget to search in
Option
-replace
bool
(default
1)
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.)
Note that although the find panel is nonmodal, an application
can only have one find panel displayed at a time.
j:find:again
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.
j:find:find_pattern
j:find:replace
j:find:replace_regexp
j:find:replace_all
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
* 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.
Future Directions
* 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.