Extending Qt Creator Manual | ILocatorFilter

Extending Qt Creator Manual 4.4.0

# ILocatorFilter Class

(Core::ILocatorFilter)

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

Header: | #include <ILocatorFilter>

- List of all members, including inherited members

## Public Types

enum | Priority { Highest, High, Medium, Low }

## Public Functions

| ILocatorFilter(QObject *parent = 0)
virtual | ~ILocatorFilter()
virtual void | accept(LocatorFilterEntry selection, QString *newText, int *selectionStart, int *selectionLength) const = 0
Id | actionId() const
QString | displayName() const
Id | id() const
bool | isConfigurable() const
bool | isEnabled() const
bool | isHidden() const
bool | isIncludedByDefault() const
virtual QList<LocatorFilterEntry> | matchesFor(QFutureInterface<LocatorFilterEntry> &future, const QString &entry) = 0
virtual bool | openConfigDialog(QWidget *parent, bool &needsRefresh)
virtual void | prepareSearch(const QString &entry)
Priority | priority() const
virtual void | refresh(QFutureInterface<void> &future) = 0
virtual void | restoreState(const QByteArray &state)
virtual QByteArray | saveState() const
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)
bool | containsWildcard(const QString &str)
QString | msgConfigureDialogTitle()
QString | msgIncludeByDefault()
QString | msgIncludeByDefaultToolTip()
QString | msgPrefixLabel()
QString | msgPrefixToolTip()

## Protected Functions

void | setConfigurable(bool configurable)
void | setDisplayName(const QString &displayString)
void | setHidden(bool hidden)
void | setId(Id id)
void | setPriority(Priority priority)

## Detailed Description

The ILocatorFilter class adds a locator filter.

The filter is added to Tools > Locate.

## Member Type Documentation

### 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 = 0)

Constructs a locator filter with parent. Call from subclasses.

### `[virtual]` ILocatorFilter::~ILocatorFilter()

Destroys the instance of ILocatorFilter. The destructor is virtual.

### `[pure virtual]` void ILocatorFilter::accept(LocatorFilterEntry selection, QString *newText, int *selectionStart, int *selectionLength) const

Called with the entry specified by selection when the user activates it in the result list. Implementations can return a new search term newText, which has selectionLength characters starting from selectionStart preselected, and the cursor set to the end of the selection.

### Id ILocatorFilter::actionId() const

### `[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]` bool ILocatorFilter::containsWildcard(const QString &str)

Returns whether the search term str contains wildcard characters. Can be used for choosing an optimal matching strategy.

### QString ILocatorFilter::displayName() const

Returns the filter's translated display name.

See also setDisplayName().

### Id ILocatorFilter::id() const

Returns the filter's unique ID.

See also setId().

### 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().

### `[pure virtual]` QList<LocatorFilterEntry> ILocatorFilter::matchesFor(QFutureInterface<LocatorFilterEntry> &future, const QString &entry)

Returns the list of results of this filter for the search term entry. This is run in a separate thread, but is guaranteed to only run in a single thread at any given time. Quickly running preparations can be done in the GUI thread in prepareSearch().

Implementations should do a case sensitive or case insensitive search depending on caseSensitivity(). If future is `canceled`, the search should be aborted.

See also prepareSearch(), caseSensitivity(), and containsWildcard().

### `[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.

### `[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 refresh().

### `[virtual]` void ILocatorFilter::prepareSearch(const QString &entry)

Performs actions that need to be done in the main thread before actually running the search for entry.

Called on the main thread before matchesFor() is called in a separate thread.

The default implementation does nothing.

See also matchesFor().

### 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().

### `[pure virtual]` void ILocatorFilter::refresh(QFutureInterface<void> &future)

Refreshes cached data asynchronously.

If future is `canceled`, the refresh should be aborted.

### `[virtual]` void ILocatorFilter::restoreState(const QByteArray &state)

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

See also saveState().

### `[virtual]` 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) with a data stream.

See also restoreState().

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

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

See also isConfigurable().

### `[protected]` void ILocatorFilter::setDisplayName(const QString &displayString)

Sets the translated display name of this filter.

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.

See also isEnabled().

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

Hides the filter in the Locator filters filter, menus, and locator settings. Call in the constructor of subclasses.

See also isHidden().

### `[protected]` void ILocatorFilter::setId(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. Call from the constructor of subclasses to change the default.

See also isIncludedByDefault().

### `[protected]` void ILocatorFilter::setPriority(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 shortcut string that can be used to explicitly choose this filter in the locator input field. Call from the constructor of subclasses to set the default setting.

See also shortcutString().

### 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().