# The jstools Find Panel

## Introduction

The jstools package provides a Find Panel, shared by several applications, which lets you search for a string of text, and optionally replace it with another string of text. The full functionality of the Find Panel is available if you're searching in a text window you can edit (as in the editor, `jedit`); a subset of the features is available if you're searching in a text window you can't edit (as in `jdoc` or `jmore`).

The Find Panel is implemented by the jfindpanel.tcl library; if you're a Tk programmer, you can use it in your own applications.

This document describes the Find Panel provided by version 4.1/4.4 of the jstools libraries.

## What window the Find panel searches in

Depending on the application you're using, the Find panel might search in a specific window (the one whose `Find...' menu entry or button you selected, for instance), or it might search in the last window (of the application the Find panel belongs to) that you were typing in.

(In the latter case, the rule is that it searches in the last Text widget that had the keyboard focus, so if your keyboard focus follows the mouse and you don't have to click in windows to type in them, this is the last Text widget in the application that your mouse pointer was over. Yes, this is often annoying. I may change it.)

## Usage

The Find Panel has two fields for you to type the search string (or pattern) and the replacement string into, and four buttons: `Search', `Replace', `Replace All', and `Cancel'. There are also some checkbuttons which control the Find Panel's behaviour, which are described under Find Panel Options below. (Not all these features will be available if the window you're searching in isn't editable; see Searching in NonEditable Windows for details.)

If all you want to do is find the next occurrence of a string, you can just type the string you want to search for in the `Search for:' field, and click `Search' (or just press Return). The Find Panel will find the next occurrence of the string in the text after the insertion point (the blinking vertical bar) and select it. (If the string you typed didn't appear in the text after the insertion point, an alert panel will tell you so.)

If you want to search repeatedly through the text for a particular string, you can keep clicking on the `Search' button (or pressing Return).

To replace a string, type the search string in the `Search for:' field, and type the replacement string in the `Replace with:' field. Then click on Search to find and select the next ocurrence of the search string, and click on `Replace' to replace it and continue the search. Clicking `Replace' replaces whatever the current selection is (it doesn't necessarily have to be the result of a search) with the text in the `Replace with:' field.

You can click on `Replace All' to replace the search string (the contents of the `Search for:' field) with the replacement string (the contents of the `Replace with:' field) everywhere in the text. This should be done with some caution, of course.

(If you need to search for or substitute a newline or a tab, you can type them in the search and replace fields as Control-J and Control-I, respectively. No, it's not intuitive, but it works.)

The `Cancel' button makes the find panel go away and returns you to editing your text.

## History Lists

Typically, each entry field (the Find: field and the Replace: field) will have two buttons with arrows to the right of it, an up arrow and a down arrow. These let you move back and forth among elements in a history list, so you can easily search again for items you've recently searched for, and replace them with text you've recently replaced something with. It's similar to the command history in shells such as `bash`(1) or `tcsh`(1). Clicking the up arrow button moves back (to older values) in the history list; clicking the down arrow button moves forward (to more recent values). (You can also use the up and down arrows on the keyboard.)

The history lists last across invocations of the same application, so if you find something in a program, quit the program, and start it up again, you still have access to the same history list. Whether the history list lasts across applications depends on the particular applications.

## Searching in NonEditable Windows

If the text window you're searching in is not editable (as in the `jmore` application), then the Find Panel features that allow you to replace text are not available. The `Replace with:' field, the `Replace' button, and the `Replace All' button will not be displayed in this case.

Using the Find Panel with a noneditable window is a little tricky, because the Find Panel searches from the insertion point in a text window. In an editable window, the insertion point is displayed as a blinking vertical bar, but in a noneditable window it's invisible. So it may be hard to tell where the search is starting from. If you can't find a string you're fairly sure is in the text, you can try scrolling the text window up to the top and clicking in the upperleft corner to set the insertion point at the beginning of the text.

## Find Panel Options

If the `Backwards' checkbutton is selected, the search will be backwards in the text from the current insertion point; otherwise it will be forwards.

If the `Casesensitive' checkbutton is selected, then the Find Panel will only search for an exact match, so that if you search for `because', you won't find `Because'. Normally, case is ignored when searching, so `because' and `Because' (and `BECAUSE' and `becausE') will match.

In any case, if you search for `because of' with one space, you won't find `because of' with two spaces.

If the `Regex' checkbutton is selected, then searching and replacement will be done using regular expressions rather than fixed strings. Regular expressions allow you to express more complicated patterns than just specific sequences of characters; for instance, you could search for all words that are in all capitals, or all occurrences of a number in parentheses. You can also use fragments of the matched text in the replacement text. For the details of regular expressions, see the Tcl `regexp`(n) and `regsub`(n) manual pages. (Another place to look for information is the REGULAR EXPRESSIONS section of the `ed`(1) manual page, although the regular expressions in `ed`(1) differ slightly from those used by Tcl.)

Currently, you can only search forward for regular expressions; if you have both `Regex' and `Backwards' selected, you'll get a notice telling you so when you click `Search'.

If the `EOL' checkbutton is selected, then if a match is found at the end of a line, the newline that follows the match will be selected as well as the matching text. For instance, if you had a file with a number of lines that consisted solely of the word `EXAMPLE', and you selected the `EOL' checkbutton when searching for `EXAMPLE', then whenever a matching line was found, the entire line (including the newline) would be selected. (If you had paragraphs with the word `EXAMPLE' in the middle of them, then whenever one of those words matched, only the word itself would be highlighted.) This is particularly useful for searching for and deleting or reformatting entire paragraphs. I tend to use it mostly with the `Regex' checkbutton.

When `EOL' is selected, be careful about replacing text. The `EOL' checkbutton does not add a newline to the replacement string, so unless you've actually typed a trailing newline into the `Replace with:' field (with <Control-j>), you'll be merging the paragraph that ends with the search string with the following paragraph.

## Evolution

Feel free to report bugs (and feature requests) to me, `<js@aq.org>`, and I will try to deal with them. Also, feel free to fix bugs or add features on your own and let me know how you did it.

### Bugs and Limitations

- Depending on the search, the Find Panel sometimes makes copies of the text in the text window to search in, so it may be wasteful of memory and slow with windows containing lots of text.
- You can't search backwards for a regular expression.
- History lists interact oddly with the `current values' of the Find and Replace entry fields. You sometimes have to press the up arrow or click the up button twice when you'd only expect to have to press it once.

### Future Directions

###

###

There should be a way to highlight all occurrences of a string, rather than just jumping to each one in succession.

`
`