Class

# DBKit.SearchField

<div class="rst-class">

forsearch

</div>

DBKit.SearchField

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

## Description

Searches the database table to which it is assigned, using the columns specified.

As you type, the table is searched and the rows shown by the bound controls are filtered to the matching rows. By default every displayed column whose data type matches the value you enter is searched; set `Columns<dbkit.searchfield.columns>` to search only specific columns.

Text values match from the beginning of the value. For an exact match, surround the value with double quotes, for example "Smith". For numeric values use \> and \<, for example \>1000. To search for a range, separate the two numbers or dates with two periods, for example 10..50. Dates are entered in the local short format (two or four digit year), YYYY-MM-DD, or YYYY.MM.DD format. To search a specific column, begin your search with the column name, for example Last Name=Smith.

When the control opens, its tooltip shows the search syntax, and if `AutoHint<dbkit.searchfield.autohint>` is true its hint lists the columns being searched.

Only the members declared by <span class="title-ref">DBKit.SearchField</span> itself are described here; for the inherited members, see `the parent class<dbkit.searchfield.seealso>`.

## Properties

<div class="rst-class">

table-centered_columns_3_and_4

</div>

| Name                                                     | Type                               | Read-Only | Shared |
|----------------------------------------------------------|------------------------------------|-----------|--------|
| `AutoHint<dbkit.searchfield.autohint>`                   | `Boolean</api/data_types/boolean>` |           |        |
| `Columns<dbkit.searchfield.columns>`                     | `String</api/data_types/string>`   |           |        |
| `HintPrefix<dbkit.searchfield.hintprefix>`               | `String</api/data_types/string>`   |           |        |
| `SearchInSelection<dbkit.searchfield.searchinselection>` | `Boolean</api/data_types/boolean>` |           |        |
| `ToolTipMessage<dbkit.searchfield.tooltipmessage>`       | `String</api/data_types/string>`   |           |        |

## Events

<div class="rst-class">

table-centered_column_4

</div>

| Name                                               | Parameters                                      | Returns |
|----------------------------------------------------|-------------------------------------------------|---------|
| `RowChanged<dbkit.searchfield.rowchanged>`         | row As `DBKit.Row</api/databases/dbkit/row>`    |         |
| `RowCreated<dbkit.searchfield.rowcreated>`         | row As `DBKit.Row</api/databases/dbkit/row>`    |         |
| `RowDeleted<dbkit.searchfield.rowdeleted>`         | row As `DBKit.Row</api/databases/dbkit/row>`    |         |
| `RowEditing<dbkit.searchfield.rowediting>`         | row As `DBKit.Row</api/databases/dbkit/row>`    |         |
| `RowLoaded<dbkit.searchfield.rowloaded>`           | row As `DBKit.Row</api/databases/dbkit/row>`    |         |
| `RowNotSelected<dbkit.searchfield.rownotselected>` |                                                 |         |
| `RowSaved<dbkit.searchfield.rowsaved>`             | row As `DBKit.Row</api/databases/dbkit/row>`    |         |
| `RowSaving<dbkit.searchfield.rowsaving>`           | row As `DBKit.Row</api/databases/dbkit/row>`    |         |
| `RowUndone<dbkit.searchfield.rowundone>`           | row As `DBKit.Row</api/databases/dbkit/row>`    |         |
| `SearchComplete<dbkit.searchfield.searchcomplete>` | rowsFound As `Integer</api/data_types/integer>` |         |

## Property descriptions

<div id="dbkit.searchfield.autohint">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

DBKit.SearchField.AutoHint

**AutoHint** As `Boolean</api/data_types/boolean>`

> If `True</api/language/true>`, the control's hint is automatically set to the `HintPrefix<dbkit.searchfield.hintprefix>` followed by the names of the columns being searched when the control opens. Each column name is resolved in this order: the header of the Table column bound to the searched column; if there is no matching Table column, the DisplayName of the bound control whose column matches; and if that DisplayName is blank, the database column name with camel-case words split apart, so LastName is shown as "Last Name".
>
> The default is `True</api/language/true>`.

<div id="dbkit.searchfield.columns">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

DBKit.SearchField.Columns

**Columns** As `String</api/data_types/string>`

> A comma-separated list of the columns to search. If blank, all displayed columns are searched.
>
> Only columns whose data type matches the value entered are searched.

<div id="dbkit.searchfield.hintprefix">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

DBKit.SearchField.HintPrefix

**HintPrefix** As `String</api/data_types/string>`

> The text placed before the column names when `AutoHint<dbkit.searchfield.autohint>` builds the control's hint.
>
> The default is "Search".

<div id="dbkit.searchfield.searchinselection">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

DBKit.SearchField.SearchInSelection

**SearchInSelection** As `Boolean</api/data_types/boolean>`

> If `True</api/language/true>`, the search is limited to the current selection: the WHERE clause of the window, container, or page the control is on is applied to the search in addition to the entered search text.

<div id="dbkit.searchfield.tooltipmessage">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

DBKit.SearchField.ToolTipMessage

**ToolTipMessage** As `String</api/data_types/string>`

> The message shown as the control's tooltip, explaining the search syntax to the user. It is assigned to the control when the control opens.
>
> The default is "Text values are found that begin with the text you enter. For an exact match, surround the value with double quotes (""). for example: ""Smith"". For numeric values use \>, \<. For example \>1000. To search for a range, separate the two numbers or dates with two periods. For example, 10..50. Dates are entered in the local short (two or four digit year), YYYY-MM-DD or YYYY.MM.DD formats. All columns of the same data type as the value entered are searched. To search a specific column, begin your search with the column name. For example: LastName=Smith."

## Event descriptions

<div id="dbkit.searchfield.rowchanged">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

DBKit.SearchField.RowChanged

**RowChanged**(row As `DBKit.Row</api/databases/dbkit/row>`)

> The current row (passed to the event) has been changed.

<div id="dbkit.searchfield.rowcreated">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

DBKit.SearchField.RowCreated

**RowCreated**(row As `DBKit.Row</api/databases/dbkit/row>`)

> A new row (passed to the event) was just created and is now the current row.

<div id="dbkit.searchfield.rowdeleted">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

DBKit.SearchField.RowDeleted

**RowDeleted**(row As `DBKit.Row</api/databases/dbkit/row>`)

> The current row (passed to the event) has been deleted.

<div id="dbkit.searchfield.rowediting">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

DBKit.SearchField.RowEditing

**RowEditing**(row As `DBKit.Row</api/databases/dbkit/row>`)

> The current row (passed to the event) is being edited by the user.

<div id="dbkit.searchfield.rowloaded">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

DBKit.SearchField.RowLoaded

**RowLoaded**(row As `DBKit.Row</api/databases/dbkit/row>`)

> The current row (passed to the event) has been loaded.

<div id="dbkit.searchfield.rownotselected">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

DBKit.SearchField.RowNotSelected

**RowNotSelected**

> There is no row currently selected.

<div id="dbkit.searchfield.rowsaved">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

DBKit.SearchField.RowSaved

**RowSaved**(row As `DBKit.Row</api/databases/dbkit/row>`)

> The current row (passed to the event) has been saved.

<div id="dbkit.searchfield.rowsaving">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

DBKit.SearchField.RowSaving

**RowSaving**(row As `DBKit.Row</api/databases/dbkit/row>`)

> The current row (passed to this event) is about to be saved.

<div id="dbkit.searchfield.rowundone">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

DBKit.SearchField.RowUndone

**RowUndone**(row As `DBKit.Row</api/databases/dbkit/row>`)

> The changes made to the current row (passed to this event) have been undone.

<div id="dbkit.searchfield.searchcomplete">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

DBKit.SearchField.SearchComplete

**SearchComplete**(rowsFound As `Integer</api/data_types/integer>`)

> Raised any time a search is completed. *rowsFound* is the number of rows found by the search.

## Notes

### How searches work

By default, text values are matched from the beginning of the value, so entering "smi" finds "Smith". Each value entered is detected as a number, date, or text, and only columns of the matching type are searched.

### Exact matches

Surround a value with double quotes for an exact match, for example `"Smith"` or `Last Name="Smith"`. A leading equals sign with no column name also gives an exact match, for example `=Smith` or `=42`.

Without quotes, text values match from the beginning of the value, so entering `smi` finds "Smith". To narrow a begins-with search to one column, put the column name first, for example `Last Name=Smi`.

### Searching a specific column

Enter a column name followed by an operator to search only that column, for example `Last Name=Smith`. The column name is matched against the Table column headers case-insensitively.

### Date formats

Dates may be entered in the short format for the current locale, or as YYYY-MM-DD or YYYY.MM.DD.

### Searching a range of values

Enter two values separated by two periods to search a range, for example `1..10`. Both values must be numbers or both must be dates.

### Which Table shows the results

The SearchField displays its search results in the Table whose `TableName<dbkit.table.tablename>` matches the layout's TableName. A Table with a blank `TableName<dbkit.table.tablename>` uses the layout's table name, so the results appear in it.

### Localization

Localize the control's user-facing text (`HintPrefix<dbkit.searchfield.hintprefix>` and `ToolTipMessage<dbkit.searchfield.tooltipmessage>`) the standard Xojo way: assign a dynamic constant to each property and provide translations for as many languages as you need, or localize the property values directly.

## Compatibility

|                       |         |
|-----------------------|---------|
| **Project Types**     | Desktop |
| **Operating Systems** | All     |

<div id="dbkit.searchfield.seealso">

<div class="seealso">

`DesktopSearchField</api/user_interface/desktop/desktopsearchfield>` parent class; `DBKit.Row</api/databases/dbkit/row>` class.

</div>

</div>