[UsedImplicitly]
public sealed class SearchElement : VisualElement, IEventHandler, ITransform, ITransitionAnimations, IExperimentalFeatures, IVisualElementScheduler, IResolvedStyle, INotifyValueChanged<string>

Constructors

SearchElement()

Constructs a new instance of the SearchElement control.

Declaration

public SearchElement()

Properties

FilterPopupWidth

Gets or sets the desired width for the popup element. The default value is 175.

Declaration

public int FilterPopupWidth { get; set; }

Property Value

Type	Description
int

GlobalStringComparison

Global string comparison options for word matching and filter handling (if not overridden).

Declaration

public StringComparison GlobalStringComparison { get; set; }

Property Value

Type	Description
StringComparison

SearchDelay

Gets or sets the search delay. This is the number of millisecond after input is receive for the search to be executed. The default value is 200.

Declaration

public long SearchDelay { get; set; }

Property Value

Type	Description
long

value

Gets or sets the search string value. This is the string that appears in the text box.

Declaration

public string value { get; set; }

Property Value

Type	Description
string

Remarks

Setting this value will trigger the search. To update the value without searching use SetValueWithoutNotify(string).

Methods

AddSearchDataCallback<TData>(Func<TData, IEnumerable<string>>)

Adds a callback which returns values that should be compared against the search string.

Declaration

public void AddSearchDataCallback<TData>(Func<TData, IEnumerable<string>> getSearchDataFunc)

Parameters

Type	Name	Description
Func<TData, IEnumerable<string>>	getSearchDataFunc	Callback used to get the data for the search string.

Type Parameters

Name	Description
TData	The search data type.

AddSearchDataProperty(PropertyPath)

Adds a property who's value should be compared against search string.

Declaration

public void AddSearchDataProperty(PropertyPath path)

Parameters

Type	Name	Description
PropertyPath	path	The property path to pull search data from.

AddSearchFilterCallback<TData, TFilter>(string, Func<TData, TFilter>, SearchFilterOptions)

Adds a search filter based on a callback function. The given token will resolve to the result of the specified getSearchDataFunc.

Declaration

public void AddSearchFilterCallback<TData, TFilter>(string token, Func<TData, TFilter> getSearchDataFunc, SearchFilterOptions options = default)

Parameters

Type	Name	Description
string	token	The identifier of the filter. Typically what precedes the operator in a filter.
Func<TData, TFilter>	getSearchDataFunc	Callback used to get the object that is used in the filter. Takes an object of type TData and returns an object of type TFilter.
SearchFilterOptions	options	The set of filter options.

Type Parameters

Name	Description
TData	The data type being searched.
TFilter	The return type for the filter.

AddSearchFilterPopupItem(string, string, string)

Adds a filter to the filter popup menu. This can be used for discoverability and quick way to add filter text.

Declaration

public void AddSearchFilterPopupItem(string token, string filterText, string filterTooltip = "")

Parameters

Type	Name	Description
string	token	The token for the filter. This should NOT include the operator.
string	filterText	The text or name to display to the user.
string	filterTooltip	An optional tooltip.

AddSearchFilterProperty(string, PropertyPath, SearchFilterOptions)

Adds a filter based on a binding path. The given token will resolve to a property at the specified path.

Declaration

public void AddSearchFilterProperty(string token, PropertyPath path, SearchFilterOptions options = default)

Parameters

Type	Name	Description
string	token	The identifier of the filter. Typically what precedes the operator in a filter.
PropertyPath	path	The property this token should resolve to.
SearchFilterOptions	options	The set of filter options.

AddSearchOperatorHandler<TFilterVariable, TFilterConstant>(string, Func<TFilterVariable, TFilterConstant, bool>)

Add a custom filter operator handler.

Declaration

public void AddSearchOperatorHandler<TFilterVariable, TFilterConstant>(string op, Func<TFilterVariable, TFilterConstant, bool> handler)

Parameters

Type	Name	Description
string	op	The filter operator.
Func<TFilterVariable, TFilterConstant, bool>	handler	Callback to handle the operation. Takes a TFilterVariable (value returned by the filter handler, will vary for each element) and a TFilterConstant (right hand side value of the operator, which is constant), and returns a boolean indicating if the filter passes or not.

Type Parameters

Name	Description
TFilterVariable	The operator's left hand side type. This is the type returned by a filter handler.
TFilterConstant	The operator's right hand side type.

AddSearchOperatorHandler<TFilterVariable, TFilterConstant>(string, Func<TFilterVariable, TFilterConstant, StringComparison, bool>)

Add a custom filter operator handler.

Declaration

public void AddSearchOperatorHandler<TFilterVariable, TFilterConstant>(string op, Func<TFilterVariable, TFilterConstant, StringComparison, bool> handler)

Parameters

Type	Name	Description
string	op	The filter operator.
Func<TFilterVariable, TFilterConstant, StringComparison, bool>	handler	Callback to handle the operation. Takes a TFilterVariable (value returned by the filter handler, will vary for each element), a TFilterConstant (right hand side value of the operator, which is constant), a StringComparison option and returns a boolean indicating if the filter passes or not.

Type Parameters

Name	Description
TFilterVariable	The operator's left hand side type. This is the type returned by a filter handler.
TFilterConstant	The operator's right hand side type.

ClearSearchString()

Clears the search string and immediately invokes the search callback.

Declaration

public void ClearSearchString()

GetQueryEngine<TData>()

Returns the underlying QueryEngine_1 for the given TData type.

Declaration

public QueryEngine<TData> GetQueryEngine<TData>()

Returns

Type	Description
QueryEngine<TData>	The QueryEngine_1 for the given data type.

Type Parameters

Name	Description
TData	The data type to get the engine for.

GetUxmlSearchHandler()

Returns the search handler registered through UXML bindings.

Declaration

public ISearchHandler GetUxmlSearchHandler()

Returns

Type	Description
ISearchHandler	The search handler created from UXML bindings.

HideProgress()

Hides the progress bar for the search field.

Declaration

public void HideProgress()

RegisterSearchQueryHandler(BindingContextElement, PropertyPath, PropertyPath)

Registers a high level search handler based on the specified bindings. The collection at sourceDataPath will be read from, filtered and written to the filterDataPath.

Declaration

public ISearchHandler RegisterSearchQueryHandler(BindingContextElement propertyElement, PropertyPath sourceDataPath, PropertyPath filterDataPath)

Parameters

Type	Name	Description
BindingContextElement	propertyElement	The property element to use for the data.
PropertyPath	sourceDataPath	The source data path to read from.
PropertyPath	filterDataPath	The filter data path to write to.

Returns

Type	Description
ISearchHandler	The search handler which can be used to customize the search or unregister the bindings.

Remarks

After the initial setup it is recommended to invoke Search(string) to initialize the filtered data.

RegisterSearchQueryHandler<TData>(Action<ISearchQuery<TData>>)

Adds a search query handler to the element. The specified callback will be invoked whenever a search is performed.

Declaration

public void RegisterSearchQueryHandler<TData>(Action<ISearchQuery<TData>> searchQueryCallback)

Parameters

Type	Name	Description
Action<ISearchQuery<TData>>	searchQueryCallback	The callback to add.

Type Parameters

Name	Description
TData	The search data type.

Exceptions

Type	Condition
Exception	The callback has already been registered.

RegisterSearchQueryHandler<TData>(ISearchQueryHandler<TData>)

Adds a search query handler. The HandleSearchQuery(ISearchQuery<TData>) method will be invoked on the specified ISearchHandler<TData> whenever a search is performed.

Declaration

public void RegisterSearchQueryHandler<TData>(ISearchQueryHandler<TData> searchQueryHandler)

Parameters

Type	Name	Description
ISearchQueryHandler<TData>	searchQueryHandler	The search handler to add.

Type Parameters

Name	Description
TData	The search data type.

Exceptions

Type	Condition
Exception	The specified search handler has already been registered.

Search()

Executes the search using the current search string.

Declaration

public void Search()

Remarks

This method can be used when the underlying data changes and the search must be explicitly run.

Search(string)

Executes the search using the specified search string.

Declaration

public void Search(string searchString)

Parameters

Type	Name	Description
string	searchString	The search string.

Remarks

This method can be used when the underlying data changes and the search must be explicitly run.

SetValueWithoutNotify(string)

Updates the search string value without invoking the search.

Declaration

public void SetValueWithoutNotify(string newValue)

Parameters

Type	Name	Description
string	newValue	The search string value to set.

ShowProgress(float)

Shows and updates the progress bar for the search field.

Declaration

public void ShowProgress(float progress)

Parameters

Type	Name	Description
float	progress	The progress value to show. Range should be 0 to 1.

UnregisterSearchQueryHandler<TData>(Action<ISearchQuery<TData>>)

Removes a search query callback from the element.

Declaration

public void UnregisterSearchQueryHandler<TData>(Action<ISearchQuery<TData>> searchQueryCallback)

Parameters

Type	Name	Description
Action<ISearchQuery<TData>>	searchQueryCallback	The callback to remove.

Type Parameters

Name	Description
TData	The search data type.

Exceptions

Type	Condition
Exception	The callback has not been registered.

UnregisterSearchQueryHandler<TData>(ISearchQueryHandler<TData>)

Removes a search query handler from the element.

Declaration

public void UnregisterSearchQueryHandler<TData>(ISearchQueryHandler<TData> searchQueryHandler)

Parameters

Type	Name	Description
ISearchQueryHandler<TData>	searchQueryHandler	The search handler to remove.

Type Parameters

Name	Description
TData	The search data type.

Exceptions

Type	Condition
Exception	The specified search handler has not been registered.

Implements

IEventHandler

ITransform

ITransitionAnimations

IExperimentalFeatures

IVisualElementScheduler

IResolvedStyle

INotifyValueChanged<T>