Loading document parsing libraries...
# Search
Class
## About
`Search` finds and replaces text in the editor's document, and controls the search popover. Each `Editor` creates one when it is constructed; read it from the editor's read-only `Search` property.
```xojo
If Editor.Search.Find("draft") <> Nil Then Call Editor.Search.Replace("final")
Var count As Integer = Editor.Search.ReplaceAll("colour", "color")
Editor.Search.Show
```
`Query` is the text to find. `Find`, `FindNext`, and `FindPrevious` select a match and make it `Current`; they start from the current match while it is still selected, or from the caret, and wrap around the document. `FindAll` returns every match without changing the selection. `Replace(replacement)` replaces the current match and selects the next one; `Replace(result, replacement)` replaces any match; `ReplaceAll` replaces every match. Methods that take a query set `Query` first.
`CaseSensitive`, `WholeWord`, and `UseRegEx` apply to every search. With `UseRegEx`, `Query` is a regular expression, and `$1` to `$9` or `\1` to `\9` in a replacement insert the match's groups (`$0` inserts the whole match; `$$` and `\\` insert one `$` or `\`). An invalid pattern finds nothing and sets `PatternError` instead of raising an exception. `MatchCount` and `CurrentIndex` describe the last search.
Replacing does nothing while the editor is `ReadOnly`; finding still works.
The editor does not handle menu-bar items itself. To connect an application's Find menu, enable its items from `Query` and `ReadOnly` in the window's `MenuBarSelected` event and call these methods from the menu handlers. The demo project's `windowProEditor` does this for Edit > Find.
```xojo
Sub MenuBarSelected()
Var hasQuery As Boolean = Editor.Search.Query <> ""
EditFindNext.Enabled = hasQuery
EditReplaceAll.Enabled = hasQuery And Not Editor.ReadOnly
End Sub
Function EditFind() As Boolean Handles EditFind.MenuItemSelected
Editor.Search.Show
Return True
End Function
Function EditReplaceAll() As Boolean Handles EditReplaceAll.MenuItemSelected
'// Replacement is the text in the popover's replace field.
Call Editor.Search.ReplaceAll(Editor.Search.Replacement)
Return True
End Function
```
## Enumerations
| Name | Value | Description |
| --- | :---: | --- |
| Commands | ShowPopover = 0 <br > ClosePopover = 1 <br > Refresh = 2 | (None) |
## Delegates
| Name | Parameters | Return Type | Description |
| --- | :---: | :---: | --- |
| CommandHandler | command As GraffitiProEditor . Search . Commands <br> perform As Boolean) As Boolean | command As GraffitiProEditor . Search . Commands, perform As Boolean) As Boolean | (None) |
| ReplaceHandler | result As GraffitiProEditor . FindResult <br> value As String) As Boolean | result As GraffitiProEditor . FindResult, value As String) As Boolean | (None) |
| SelectHandler | result As GraffitiProEditor . FindResult) | (None) | (None) |
## Methods
| Name | Parameters | Return Type | Description |
| --- | :---: | :---: | --- |
| Close | (None) | (None) | Ends the popover if it is open. |
| Find | query As String | GraffitiProEditor.FindResult | Sets Query and selects the first match at or after the current match or the caret, wrapping to the start of the document. Returns the match, or Nil when there is none. |
| FindAll | (None) | GraffitiProEditor.FindResult | Returns every match of Query in document order, without changing the selection. |
| FindAll | query As String | GraffitiProEditor.FindResult | Sets Query and returns every match in document order, without changing the selection. |
| FindNext | (None) | GraffitiProEditor.FindResult | Selects the next match of Query after the current match or the caret, wrapping to the start of the document. Returns the match, or Nil when there is none. |
| FindPrevious | (None) | GraffitiProEditor.FindResult | Selects the match of Query before the current match or the caret, wrapping to the end of the document. Returns the match, or Nil when there is none. |
| Replace | result As GraffitiProEditor.FindResult <br> replacement As String | Boolean | Replaces the supplied match and returns whether it succeeded. In regular-expression mode, $1 to $9 or \1 to \9 in the replacement insert the match's groups. Does nothing while the editor is read-only. |
| Replace | replacement As String | Boolean | Replaces the current match when it is still selected, then selects the next match. When no match is selected, selects the next one instead and returns False. In regular-expression mode, $1 to $9 or \1 to \9 in the replacement insert the match's groups. Does nothing while the editor is read-only. |
| ReplaceAll | replacement As String | Integer | Replaces every match of Query and returns the number of replacements. Does nothing while the editor is read-only. |
| ReplaceAll | query As String <br> replacement As String | Integer | Sets Query, replaces every match, and returns the number of replacements. Does nothing while the editor is read-only. |
| SelectResult | result As GraffitiProEditor.FindResult | (None) | Selects and reveals the supplied match, entering text editing when its node is editable, and makes it the current match. |
| Show | (None) | (None) | Opens the search popover below the editor's toolbar, or moves focus to its find field when it is already open. |
## Properties
| Name | Type | Default Value | Description |
| --- | :---: | :---: | --- |
| CaseSensitive | Boolean | (None) | Gets or sets whether matches must have the same letter case as Query. The default is False. |
| Current | GraffitiProEditor.FindResult | (None) | Returns the current match: the last one selected by Find, FindNext, FindPrevious, or SelectResult, or Nil. |
| CurrentIndex | Integer | (None) | Returns the zero-based position of Current among the matches, or -1 when there is no current match or it no longer matches. |
| MatchCount | Integer | (None) | Returns the number of matches of Query in the document. |
| Owner | GraffitiProEditor.Editor | (None) | Returns the editor this search belongs to. |
| PatternError | String | (None) | Returns the error message of an invalid regular expression in Query, or an empty string. |
| Query | String | (None) | Gets or sets the text to find. Line breaks are removed. |
| Replacement | String | (None) | Gets or sets the replacement text shown in the popover's replace field. Replace and ReplaceAll set it. |
| UseRegEx | Boolean | (None) | Gets or sets whether Query is a regular expression. The default is False. |
| Visible | Boolean | (None) | Returns True while the search popover is open. |
| WholeWord | Boolean | (None) | Gets or sets whether a match must be a whole word, with no letter, digit, or underscore directly before or after it. The default is False. |
## Notes
### Popover
`Show` opens a small popover below the toolbar with a find field, a replace field, toggles for case sensitivity, whole words, and regular expressions, the match count, and Replace, Replace All, and Next buttons. Command-F (Control-F elsewhere) opens it, and Command-G and Shift-Command-G find the next and previous match.
In the find field, Return finds the next match and Shift-Return the previous one. In the replace field, Return replaces the current match. Tab moves between the fields, and Escape or a press outside the popover closes it. The popover and the properties stay in step: changes made in one show in the other.
Hovering over a toggle shows its tooltip. `Close` closes the popover, and `Visible` is True while it is open.
The popover's text comes from the editor's localized strings, such as `TextFindHint`, `TextReplaceAllCaption`, `TextMatchCountFormat`, and `TextMatchCaseTooltip`.