{jfindpanel.tcl

Introduction
The jfindpanel.tcl library is distributed as part of the jstools package.  It consists of procedures to implement a search­and­replace 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.

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@calumet.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 - search­and­replace 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', `Case­sensitive', 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 read­only (-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 non­modal, 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 regular­expression 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 regular­expression 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 multi­window documents.

} {{{jdoc:xref:link {4.57 4.64 12.215 12.236 12.244 12.261 12.265 12.286 25.0 25.6 26.0 26.12 27.0 27.19 28.0 28.14 29.0 29.21 30.0 30.18 43.99 43.121}} {jdoc:xref:manpage {12.131 12.138}} {jdoc:anchor:anchorname {3.0 4.0 10.0 11.0 14.0 15.0 23.0 24.0 32.0 33.0 49.0 50.0 60.0 64.0}} {richtext:font:roman {2.0 3.0 4.0 4.4 4.18 4.57 4.64 4.192 4.198 6.90 6.96 6.359 6.365 8.24 8.38 10.0 12.0 12.20 12.34 12.107 12.116 12.131 12.138 12.219 12.226 12.248 12.253 12.265 12.286 14.0 16.0 17.0 17.14 18.0 18.21 20.0 21.0 23.0 25.6 26.0 26.12 27.0 27.19 28.0 28.14 29.0 29.21 30.0 30.18 32.0 34.8 34.9 34.16 34.17 34.19 35.0 36.0 36.1 36.2 37.0 38.16 38.25 38.26 40.0 41.0 41.126 41.127 41.150 41.154 41.417 41.418 41.424 41.425 43.99 43.121 45.7 45.17 45.222 45.232 45.275 45.290 49.0 51.15 52.0 53.0 53.1 53.2 55.0 56.0 58.99 58.105 60.0 60.19 61.0 61.14 62.0 62.21 63.0 63.18 66.0 67.0 73.0 74.0 74.55 74.61 83.0}} {richtext:font:italic {34.9 34.16 34.18 34.19 36.1 36.2 38.10 38.14 41.126 41.127 41.150 41.154 41.417 41.418 41.424 41.425 51.14 51.15 53.1 53.2}} {richtext:font:bold {4.4 4.18 4.57 4.64 8.24 8.38 12.20 12.34 12.219 12.226}} {richtext:font:bolditalic {12.248 12.253 12.265 12.286 43.99 43.121}} {richtext:font:typewriter {4.192 4.198 6.90 6.96 6.359 6.365 12.107 12.116 12.131 12.138 17.0 17.14 18.0 18.21 25.0 25.6 26.0 26.12 27.0 27.19 28.0 28.14 29.0 29.21 30.0 30.18 34.0 34.8 34.17 34.18 38.0 38.10 38.14 38.16 38.25 38.26 45.7 45.17 45.222 45.232 45.275 45.290 51.0 51.14 58.99 58.105 74.55 74.61}} {richtext:font:heading0 {1.0 2.0}} {richtext:font:heading1 {3.0 4.0 10.0 11.0 14.0 15.0 23.0 24.0 32.0 33.0 49.0 50.0 60.0 60.19 61.0 61.14 62.0 62.21 63.0 63.18 66.0 67.0 73.0 74.0}} {richtext:font:heading2 {11.0 12.0 15.0 16.0 20.0 21.0 24.0 25.0 33.0 34.0 35.0 36.0 37.0 38.0 40.0 41.0 50.0 51.0 52.0 53.0 55.0 56.0}} {jdoc:link:jstools.jdoc {4.57 4.64}} {jdoc:manpage:tclvars {12.131 12.138}} {jdoc:link:jslibraries.tcl {12.215 12.236}} {jdoc:link:jslibraries.jdoc#Usage {12.244 12.261}} {jdoc:link:jslibraries.jdoc {12.265 12.286}} {{} {14.0 21.0 24.0 24.10 72.0 73.0}} {jdoc:link:panels/findpanel.jdoc {43.99 43.121}} {jdoc:anchorname:Introduction {3.0 4.0}} {jdoc:anchorname:Usage {10.0 11.0}} {jdoc:anchorname:Credits_and_Copyright {14.0 15.0}} {jdoc:anchorname:Overview {23.0 24.0}} {jdoc:anchorname:j:find {32.0 33.0}} {jdoc:anchorname:j:find:again {49.0 50.0}} {jdoc:link:#j:find {25.0 25.6}} {jdoc:link:j:find:again.jdoc {26.0 26.12}} {jdoc:anchorname:j:find:find_pattern {60.0 61.0}} {jdoc:link:#j:find:find_pattern {27.0 27.19}} {jdoc:link:#j:find:replace {28.0 28.14}} {jdoc:link:#j:find:replace_regexp {29.0 29.21}} {jdoc:link:#j:find:replace_all {30.0 30.18}} {jdoc:anchorname:j:find:replace {61.0 62.0}} {jdoc:anchorname:j:find:replace_regexp {62.0 63.0}} {jdoc:anchorname:j:find:replace_all {63.0 64.0}}} {{abbrevstart 29.32} {richptr 63.0} {abbrevend 29.50} {insert 1.0} {anchor 1.0} {current 1.0}}}