Class

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 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 is true its hint lists the columns being searched.

Only the members declared by DBKit.SearchField itself are described here; for the inherited members, see the parent class.

Properties

Name	Type	Read-Only	Shared
AutoHint	Boolean
Columns	String
HintPrefix	String
SearchInSelection	Boolean
ToolTipMessage	String

Events

Name	Parameters	Returns
RowChanged	row As DBKit.Row
RowCreated	row As DBKit.Row
RowDeleted	row As DBKit.Row
RowEditing	row As DBKit.Row
RowLoaded	row As DBKit.Row
RowNotSelected
RowSaved	row As DBKit.Row
RowSaving	row As DBKit.Row
RowUndone	row As DBKit.Row
SearchComplete	rowsFound As Integer

Property descriptions

DBKit.SearchField.AutoHint

AutoHint As Boolean

If True, the control's hint is automatically set to the 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.

DBKit.SearchField.Columns

Columns As 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.

DBKit.SearchField.HintPrefix

HintPrefix As String

The text placed before the column names when AutoHint builds the control's hint.

The default is "Search".

DBKit.SearchField.SearchInSelection

SearchInSelection As Boolean

If 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.

DBKit.SearchField.ToolTipMessage

ToolTipMessage As 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

DBKit.SearchField.RowChanged

RowChanged(row As DBKit.Row)

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

DBKit.SearchField.RowCreated

RowCreated(row As DBKit.Row)

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

DBKit.SearchField.RowDeleted

RowDeleted(row As DBKit.Row)

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

DBKit.SearchField.RowEditing

RowEditing(row As DBKit.Row)

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

DBKit.SearchField.RowLoaded

RowLoaded(row As DBKit.Row)

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

DBKit.SearchField.RowNotSelected

RowNotSelected

There is no row currently selected.

DBKit.SearchField.RowSaved

RowSaved(row As DBKit.Row)

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

DBKit.SearchField.RowSaving

RowSaving(row As DBKit.Row)

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

DBKit.SearchField.RowUndone

RowUndone(row As DBKit.Row)

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

DBKit.SearchField.SearchComplete

SearchComplete(rowsFound As 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 matches the layout's TableName. A Table with a blank TableName uses the layout's table name, so the results appear in it.

Localization

Localize the control's user-facing text (HintPrefix and 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