Commit 38763bf1 authored by Eike Ziller's avatar Eike Ziller

Locator: Move some API documentation to qdoc

Change-Id: Ic7c822ccc31285398bbf23b470abaf479f9b1e55
Reviewed-by: Eike Ziller's avatarEike Ziller <eike.ziller@qt.io>
parent dfe73432
......@@ -37,26 +37,73 @@
using namespace Core;
/*!
\class Core::ILocatorFilter
\inmodule Qt Creator
\brief The ILocatorFilter class adds a locator filter.
The filter is added to \uicontrol Tools > \uicontrol Locate.
*/
/*!
Constructs a locator filter with \a parent. Call from subclasses.
*/
ILocatorFilter::ILocatorFilter(QObject *parent):
QObject(parent)
{
}
/*!
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.
\sa setShortcutString()
*/
QString ILocatorFilter::shortcutString() const
{
return m_shortcut;
}
/*!
Performs actions that need to be done in the main thread before actually
running the search for \a entry.
Called on the main thread before matchesFor() is called in a separate
thread.
The default implementation does nothing.
\sa matchesFor()
*/
void ILocatorFilter::prepareSearch(const QString &entry)
{
Q_UNUSED(entry)
}
/*!
Sets the \a 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.
\sa shortcutString()
*/
void ILocatorFilter::setShortcutString(const QString &shortcut)
{
m_shortcut = shortcut;
}
/*!
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.
\sa restoreState()
*/
QByteArray ILocatorFilter::saveState() const
{
QByteArray value;
......@@ -66,6 +113,12 @@ QByteArray ILocatorFilter::saveState() const
return value;
}
/*!
Restores the \a state of the filter from data previously created by
saveState().
\sa saveState()
*/
void ILocatorFilter::restoreState(const QByteArray &state)
{
QString shortcut;
......@@ -79,6 +132,19 @@ void ILocatorFilter::restoreState(const QByteArray &state)
setIncludedByDefault(defaultFilter);
}
/*!
Opens a dialog for the \a parent widget that allows the user to configure
various aspects of the filter. Called when the user requests to configure
the filter.
Set \a needsRefresh to \c true, if a refresh() should be done after
closing the dialog. Return \c false if the user canceled the dialog.
The default implementation allows changing the shortcut and whether the
filter is included by default.
\sa refresh()
*/
bool ILocatorFilter::openConfigDialog(QWidget *parent, bool &needsRefresh)
{
Q_UNUSED(needsRefresh)
......@@ -117,107 +183,269 @@ bool ILocatorFilter::openConfigDialog(QWidget *parent, bool &needsRefresh)
return false;
}
/*!
Returns whether a case sensitive or case insensitive search should be
performed for the search term \a str.
*/
Qt::CaseSensitivity ILocatorFilter::caseSensitivity(const QString &str)
{
return str == str.toLower() ? Qt::CaseInsensitive : Qt::CaseSensitive;
}
/*!
Returns whether the search term \a str contains wildcard characters.
Can be used for choosing an optimal matching strategy.
*/
bool ILocatorFilter::containsWildcard(const QString &str)
{
return str.contains(QLatin1Char('*')) || str.contains(QLatin1Char('?'));
}
/*!
Specifies a title for configuration dialogs.
*/
QString ILocatorFilter::msgConfigureDialogTitle()
{
return tr("Filter Configuration");
}
/*!
Specifies a label for the prefix input field in configuration dialogs.
*/
QString ILocatorFilter::msgPrefixLabel()
{
return tr("Prefix:");
}
/*!
Specifies a tooltip for the prefix input field in configuration dialogs.
*/
QString ILocatorFilter::msgPrefixToolTip()
{
return tr("Type the prefix followed by a space and search term to restrict search to the filter.");
}
/*!
Specifies a label for the include by default input field in configuration
dialogs.
*/
QString ILocatorFilter::msgIncludeByDefault()
{
return tr("Include by default");
}
/*!
Specifies a tooltip for the include by default input field in configuration
dialogs.
*/
QString ILocatorFilter::msgIncludeByDefaultToolTip()
{
return tr("Include the filter when not using a prefix for searches.");
}
/*!
Returns whether a configuration dialog is available for this filter.
The default is \c true.
\sa setConfigurable()
*/
bool ILocatorFilter::isConfigurable() const
{
return m_isConfigurable;
}
/*!
Returns whether using the shortcut string is required to use this filter.
The default is \c false.
\sa shortcutString()
\sa setIncludedByDefault()
*/
bool ILocatorFilter::isIncludedByDefault() const
{
return m_includedByDefault;
}
/*!
Sets whether using the shortcut string is required to use this filter.
Call from the constructor of subclasses to change the default.
\sa isIncludedByDefault()
*/
void ILocatorFilter::setIncludedByDefault(bool includedByDefault)
{
m_includedByDefault = includedByDefault;
}
/*!
Returns whether the filter should be hidden in the
\uicontrol {Locator filters} filter, menus, and locator settings.
The default is \c false.
\sa setHidden()
*/
bool ILocatorFilter::isHidden() const
{
return m_hidden;
}
/*!
Hides the filter in the \uicontrol {Locator filters} filter,
menus, and locator settings. Call in the constructor of subclasses.
*/
void ILocatorFilter::setHidden(bool hidden)
{
m_hidden = hidden;
}
/*!
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 \c true.
\sa setEnabled()
*/
bool ILocatorFilter::isEnabled() const
{
return m_enabled;
}
/*!
Returns the filter's unique ID.
\sa setId()
*/
Id ILocatorFilter::id() const
{
return m_id;
}
/*!
Returns the filter's translated display name.
\sa setDisplayName()
*/
QString ILocatorFilter::displayName() const
{
return m_displayName;
}
/*!
Returns the priority that is used for ordering the results when multiple
filters are used.
The default is ILocatorFilter::Medium.
\sa setPriority()
*/
ILocatorFilter::Priority ILocatorFilter::priority() const
{
return m_priority;
}
/*!
Sets whether the filter is currently available.
\sa isEnabled()
*/
void ILocatorFilter::setEnabled(bool enabled)
{
m_enabled = enabled;
}
/*!
Sets the filter's unique ID.
Subclasses must set the ID in their constructor.
\sa id()
*/
void ILocatorFilter::setId(Id id)
{
m_id = id;
}
/*!
Sets the priority of results of this filter in the result list.
\sa priority()
*/
void ILocatorFilter::setPriority(Priority priority)
{
m_priority = priority;
}
/*!
Sets the translated display name of this filter.
Subclasses must set the display name in their constructor.
\sa displayName()
*/
void ILocatorFilter::setDisplayName(const QString &displayString)
{
m_displayName = displayString;
}
/*!
Sets whether the filter provides a configuration dialog.
Most filters should at least provide the default dialog.
\sa isConfigurable()
*/
void ILocatorFilter::setConfigurable(bool configurable)
{
m_isConfigurable = configurable;
}
/*!
\fn QList<LocatorFilterEntry> ILocatorFilter::matchesFor(QFutureInterface<LocatorFilterEntry> &future, const QString &entry)
Returns the list of results of this filter for the search term \a 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 \a future is \c canceled, the search
should be aborted.
\sa prepareSearch()
\sa caseSensitivity()
\sa containsWildcard()
*/
/*!
\fn void ILocatorFilter::accept(LocatorFilterEntry selection) const
Called with the entry specified by \a selection when the user activates it
in the result list.
*/
/*!
\fn void ILocatorFilter::refresh(QFutureInterface<void> &future)
Refreshes cached data asynchronously.
If \a future is \c canceled, the refresh should be aborted.
*/
/*!
\enum ILocatorFilter::Priority
This enum value holds the priority that is used for ordering the results
when multiple filters are used.
\value Highest
The results for this filter are placed above the results for filters
that have other priorities.
\value High
\value Medium
The default value.
\value Low
The results for this filter are placed below the results for filters
that have other priorities.
*/
......@@ -104,59 +104,34 @@ public:
ILocatorFilter(QObject *parent = 0);
virtual ~ILocatorFilter() {}
/* Internal Id. */
Id id() const;
/* Visible name. */
QString displayName() const;
/* Selection list order in case of multiple active filters (high goes on top). */
Priority priority() const;
/* String to type to use this filter exclusively. */
QString shortcutString() const;
void setShortcutString(const QString &shortcut);
/* Called on the main thread before matchesFor is called in a separate thread.
Can be used to perform actions that need to be done in the main thread before actually
running the search. */
virtual void prepareSearch(const QString &entry);
/* List of matches for the given user entry. This runs in a separate thread, but only
a single thread at a time. */
virtual QList<LocatorFilterEntry> matchesFor(QFutureInterface<LocatorFilterEntry> &future, const QString &entry) = 0;
/* User has selected the given entry that belongs to this filter. */
virtual void accept(LocatorFilterEntry selection) const = 0;
/* Implement to update caches on user request, if that's a long operation. */
virtual void refresh(QFutureInterface<void> &future) = 0;
/* Saved state is used to restore the filter at start up. */
virtual QByteArray saveState() const;
/* Used to restore the filter at start up. */
virtual void restoreState(const QByteArray &state);
/* User wants to configure this filter (if supported). Use it to pop up a dialog.
* needsRefresh is used as a hint to indicate that refresh should be called.
* The default implementation allows changing the shortcut and whether the filter
* is enabled by default.
*/
virtual bool openConfigDialog(QWidget *parent, bool &needsRefresh);
/* If there is a configure dialog available for this filter. The default
* implementation returns true. */
bool isConfigurable() const;
/* Is this filter used also when the shortcutString is not used? */
bool isIncludedByDefault() const;
void setIncludedByDefault(bool includedByDefault);
/* Returns whether the filter should be hidden from configuration and menus. */
bool isHidden() const;
/* Returns whether the filter should be enabled and used in menus. */
bool isEnabled() const;
static Qt::CaseSensitivity caseSensitivity(const QString &str);
......@@ -169,7 +144,6 @@ public:
static QString msgIncludeByDefaultToolTip();
public slots:
/* Enable or disable the filter. */
void setEnabled(bool enabled);
protected:
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment