Core::ILocatorFilter Class | Extending Qt Creator Manual
Description: The ILocatorFilter class adds a locator filter.

- Extending Qt Creator Manual
- QtCreator
- ILocatorFilter
- Extending Qt Creator Manual 19.0.0

# Core::ILocatorFilter Class

class Core::ILocatorFilter

The ILocatorFilter class adds a locator filter. More...

Header: | `#include <coreplugin/locator/ilocatorfilter.h>`
Inherits: | QObject

- List of all members, including inherited members

## Public Types

enum class | MatchLevel { Best, Better, Good, Normal, Count }
enum | Priority { Highest, High, Medium, Low }

## Public Functions

| ILocatorFilter(QObject *parent = nullptr)
Utils::Id | actionId() const
QString | description() const
QString | displayName() const
Utils::Id | id() const
bool | isConfigurable() const
bool | isEnabled() const
bool | isHidden() const
bool | isIncludedByDefault() const
virtual bool | openConfigDialog(QWidget *parent, bool &needsRefresh)
Core::ILocatorFilter::Priority | priority() const
void | restoreState(const QByteArray &state)
QByteArray | saveState() const
void | setDefaultIncludedByDefault(bool includedByDefault)
void | setDefaultShortcutString(const QString &shortcut)
void | setDescription(const QString &description)
void | setDisplayName(const QString &displayString)
void | setIncludedByDefault(bool includedByDefault)
void | setShortcutString(const QString &shortcut)
QString | shortcutString() const

## Public Slots

void | setEnabled(bool enabled)

## Static Public Members

Qt::CaseSensitivity | caseSensitivity(const QString &str)
QRegularExpression | createRegExp(const QString &text, Qt::CaseSensitivity caseSensitivity = Qt::CaseInsensitive, bool multiWord = false)
Core::LocatorFilterEntry::HighlightInfo | highlightInfo(const QRegularExpressionMatch &match, Core::LocatorFilterEntry::HighlightInfo::DataType dataType = LocatorFilterEntry::HighlightInfo::DisplayName)
bool | ignoreGeneratedFiles()
QString | msgConfigureDialogTitle()
QString | msgIncludeByDefault()
QString | msgIncludeByDefaultToolTip()
QString | msgPrefixLabel()
QString | msgPrefixToolTip()

## Protected Functions

bool | openConfigDialog(QWidget *parent, QWidget *additionalWidget)
int | refreshRecipe() const
virtual void | restoreState(const QJsonObject &object)
virtual void | saveState(QJsonObject &object) const
void | setConfigurable(bool configurable)
void | setHidden(bool hidden)
void | setId(Utils::Id id)
void | setPriority(Core::ILocatorFilter::Priority priority)

## Detailed Description

The filter is added to Tools > Locate.

## Member Type Documentation

### enum class ILocatorFilter::MatchLevel

This enum value holds the level for ordering the results based on how well they match the search criteria.

Constant | Value | Description
--- | --- | ---
`Core::ILocatorFilter::MatchLevel::Best` | `0` | The result is the best match for the regular expression.
`Core::ILocatorFilter::MatchLevel::Better` | `1` |
`Core::ILocatorFilter::MatchLevel::Good` | `2` |
`Core::ILocatorFilter::MatchLevel::Normal` | `3` |
`Core::ILocatorFilter::MatchLevel::Count` | `4` | The result has the highest number of matches for the regular expression.

### enum ILocatorFilter::Priority

This enum value holds the priority that is used for ordering the results when multiple filters are used.

Constant | Value | Description
--- | --- | ---
`Core::ILocatorFilter::Highest` | `0` | The results for this filter are placed above the results for filters that have other priorities.
`Core::ILocatorFilter::High` | `1` |
`Core::ILocatorFilter::Medium` | `2` | The default value.
`Core::ILocatorFilter::Low` | `3` | The results for this filter are placed below the results for filters that have other priorities.

## Member Function Documentation

### ILocatorFilter::ILocatorFilter(QObject *parent = nullptr)

Constructs a locator filter with parent. Call from subclasses.

### Utils::Id ILocatorFilter::actionId() const

Returns the filter's action ID.

### `[static]` Qt::CaseSensitivity ILocatorFilter::caseSensitivity(const QString &str)

Returns whether a case sensitive or case insensitive search should be performed for the search term str.

### `[static]` QRegularExpression ILocatorFilter::createRegExp(const QString &text, Qt::CaseSensitivity caseSensitivity = Qt::CaseInsensitive, bool multiWord = false)

Creates the search term text as a regular expression with case sensitivity set to caseSensitivity. Pass true to multiWord if the pattern is expected to contain spaces.

### QString ILocatorFilter::description() const

Returns a longer, human-readable description of what the filter does.

See also setDescription().

### QString ILocatorFilter::displayName() const

Returns the filter's translated display name.

See also setDisplayName().

### `[static]` Core::LocatorFilterEntry::HighlightInfo ILocatorFilter::highlightInfo(const QRegularExpressionMatch &match, Core::LocatorFilterEntry::HighlightInfo::DataType dataType = LocatorFilterEntry::HighlightInfo::DisplayName)

Returns information for highlighting the results of matching the regular expression, specified by match, for the data of the type dataType.

### Utils::Id ILocatorFilter::id() const

Returns the filter's unique ID.

See also setId().

### `[static]` bool ILocatorFilter::ignoreGeneratedFiles()

Returns if the user requests to ignore generated files in project related searches.

### bool ILocatorFilter::isConfigurable() const

Returns whether a configuration dialog is available for this filter.

The default is `true`.

See also setConfigurable().

### bool ILocatorFilter::isEnabled() const

Returns whether the filter is currently available. Disabled filters are neither visible in menus nor included in searches, even when the search is prefixed with their shortcut string.

The default is `true`.

See also setEnabled().

### bool ILocatorFilter::isHidden() const

Returns whether the filter should be hidden in the Locator filters filter, menus, and locator settings.

The default is `false`.

See also setHidden().

### bool ILocatorFilter::isIncludedByDefault() const

Returns whether using the shortcut string is required to use this filter. The default is `false`.

See also shortcutString() and setIncludedByDefault().

### `[static]` QString ILocatorFilter::msgConfigureDialogTitle()

Specifies a title for configuration dialogs.

### `[static]` QString ILocatorFilter::msgIncludeByDefault()

Specifies a label for the include by default input field in configuration dialogs.

### `[static]` QString ILocatorFilter::msgIncludeByDefaultToolTip()

Specifies a tooltip for the include by default input field in configuration dialogs.

### `[static]` QString ILocatorFilter::msgPrefixLabel()

Specifies a label for the prefix input field in configuration dialogs.

### `[static]` QString ILocatorFilter::msgPrefixToolTip()

Specifies a tooltip for the prefix input field in configuration dialogs.

### `[protected]` bool ILocatorFilter::openConfigDialog(QWidget *parent, QWidget *additionalWidget)

Shows the standard configuration dialog with options for the prefix string and for isIncludedByDefault(). parent is used as the dialog's parent. The additionalWidget is added at the top. Ownership of additionalWidget stays with the caller, but its parent is reset to `nullptr`.

Returns `false` if the user canceled the dialog.

### `[virtual]` bool ILocatorFilter::openConfigDialog(QWidget *parent, bool &needsRefresh)

Opens a dialog for the parent widget that allows the user to configure various aspects of the filter. Called when the user requests to configure the filter.

Set needsRefresh to `true`, if a refresh should be done after closing the dialog. Return `false` if the user canceled the dialog.

The default implementation allows changing the shortcut and whether the filter is included by default.

See also refreshRecipe().

### Core::ILocatorFilter::Priority ILocatorFilter::priority() const

Returns the priority that is used for ordering the results when multiple filters are used.

The default is ILocatorFilter::Medium.

See also setPriority().

### `[protected]` int ILocatorFilter::refreshRecipe() const

Returns the refresh recipe for refreshing cached data. By default, the locator filter has no recipe set, so that it won't be refreshed.

### void ILocatorFilter::restoreState(const QByteArray &state)

Restores the state of the filter from data previously created by saveState().

See also saveState().

### `[virtual protected]` void ILocatorFilter::restoreState(const QJsonObject &object)

Reads the filter settings and state from the JSON object

The default implementation does nothing.

Implementations should read their custom settings from the object, resetting any missing setting to its default value.

### QByteArray ILocatorFilter::saveState() const

Returns data that can be used to restore the settings for this filter (for example at startup). By default, adds the base settings (shortcut string, included by default) and calls saveState() with a JSON object where subclasses should write their custom settings.

See also restoreState().

### `[virtual protected]` void ILocatorFilter::saveState(QJsonObject &object) const

Saves the filter settings and state to the JSON object.

The default implementation does nothing.

Implementations should write key-value pairs to the object for their custom settings that changed from the default. Default values should never be saved.

### `[protected]` void ILocatorFilter::setConfigurable(bool configurable)

Sets whether the filter provides a configuration dialog to configurable. Most filters should at least provide the default dialog.

See also isConfigurable().

### void ILocatorFilter::setDefaultIncludedByDefault(bool includedByDefault)

Sets the default setting for whether using the shortcut string is required to use this filter to includedByDefault.

Call for example from the constructor of subclasses.

See also isIncludedByDefault().

### void ILocatorFilter::setDefaultShortcutString(const QString &shortcut)

Sets the default shortcut string that can be used to explicitly choose this filter in the locator input field. Call for example from the constructor of subclasses.

See also shortcutString().

### void ILocatorFilter::setDescription(const QString &description)

Sets the longer, human-readable description of what the filter does.

See also description().

### void ILocatorFilter::setDisplayName(const QString &displayString)

Sets the translated display name of this filter to displayString.

Subclasses must set the display name in their constructor.

See also displayName().

### `[slot]` void ILocatorFilter::setEnabled(bool enabled)

Sets whether the filter is currently available to enabled.

See also isEnabled().

### `[protected]` void ILocatorFilter::setHidden(bool hidden)

Sets the filter in the Locator filters filter, menus, and locator settings to hidden. Call in the constructor of subclasses.

See also isHidden().

### `[protected]` void ILocatorFilter::setId(Utils::Id id)

Sets the filter's unique id. Subclasses must set the ID in their constructor.

See also id().

### void ILocatorFilter::setIncludedByDefault(bool includedByDefault)

Sets whether using the shortcut string is required to use this filter to includedByDefault. Use setDefaultIncludedByDefault() if you want to set the default value instead.

See also isIncludedByDefault() and setDefaultIncludedByDefault().

### `[protected]` void ILocatorFilter::setPriority(Core::ILocatorFilter::Priority priority)

Sets the priority of results of this filter in the result list.

See also priority().

### void ILocatorFilter::setShortcutString(const QString &shortcut)

Sets the current shortcut string of the filter to shortcut. Use setDefaultShortcutString() if you want to set the default shortcut string instead.

See also shortcutString() and setDefaultShortcutString().

### QString ILocatorFilter::shortcutString() const

Specifies a shortcut string that can be used to explicitly choose this filter in the locator input field by preceding the search term with the shortcut string and a whitespace.

The default value is an empty string.

See also setShortcutString().