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.

Under Tk4.0 and later, these procedures use the native find method of the Tk Text widget, which does searches line­by­line. 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.

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://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.

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)
-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', `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.)

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 special­purpose 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 general­purpose natural­language text. You can eliminate either history list (and the corresponding buttons) by specifying it as `{}'.

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_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

Future Directions