Locator: Add longer description to filters

This is shown as tool tips in the location options, and if any platform
supports this also as tool tips on the menu actions of the locator input
field.

Change-Id: I8b439e45e6097a16a5f932d25d4e5d3e9bddb6ad
Reviewed-by: Leena Miettinen <riitta-leena.miettinen@qt.io>
Reviewed-by: David Schulz <david.schulz@qt.io>

src/plugins/bazaar/bazaarplugin.cpp

@@ -319,6 +319,7 @@ BazaarPluginPrivate::BazaarPluginPrivate()
 
     const QString prefix = QLatin1String("bzr");
     m_commandLocator = new CommandLocator("Bazaar", prefix, prefix, this);
+    m_commandLocator->setDescription(tr("Triggers a Bazaar version control operation."));
 
     // Create menu item for Bazaar
     m_bazaarContainer = ActionManager::createMenu("Bazaar.BazaarMenu");

src/plugins/bookmarks/bookmarkfilter.cpp

@@ -39,6 +39,8 @@ BookmarkFilter::BookmarkFilter(BookmarkManager *manager)
 {
     setId("Bookmarks");
     setDisplayName(tr("Bookmarks"));
+    setDescription(tr("Matches all bookmarks. Filter by file name, by the text on the line of the "
+                      "bookmark, or by the bookmark's note text."));
     setPriority(Medium);
     setDefaultShortcutString("b");
 }

src/plugins/clearcase/clearcaseplugin.cpp

@@ -660,6 +660,7 @@ ClearCasePluginPrivate::ClearCasePluginPrivate()
     const QString prefix = QLatin1String("cc");
     // register cc prefix in Locator
     m_commandLocator = new CommandLocator("cc", description, prefix, this);
+    m_commandLocator->setDescription(tr("Triggers a ClearCase version control operation."));
 
     //register actions
     ActionContainer *toolsContainer = ActionManager::actionContainer(M_TOOLS);

src/plugins/cmakeprojectmanager/cmakelocatorfilter.cpp

@@ -116,6 +116,7 @@ BuildCMakeTargetLocatorFilter::BuildCMakeTargetLocatorFilter()
 {
     setId("Build CMake target");
     setDisplayName(tr("Build CMake target"));
+    setDescription(tr("Builds a target of any open CMake project."));
     setDefaultShortcutString("cm");
     setPriority(High);
 }
@@ -165,6 +166,7 @@ OpenCMakeTargetLocatorFilter::OpenCMakeTargetLocatorFilter()
 {
     setId("Open CMake target definition");
     setDisplayName(tr("Open CMake target"));
+    setDescription(tr("Jumps to the definition of a target of any open CMake project."));
     setDefaultShortcutString("cmo");
     setPriority(Medium);
 }

src/plugins/coreplugin/locator/directoryfilter.cpp

@@ -67,6 +67,9 @@ DirectoryFilter::DirectoryFilter(Id id)
     setId(id);
     setDefaultIncludedByDefault(true);
     setDisplayName(defaultDisplayName());
+    setDescription(tr("Matches all files from a custom set of directories. Append \"+<number>\" or "
+                      "\":<number>\" to jump to the given line number. Append another "
+                      "\"+<number>\" or \":<number>\" to jump to the column number as well."));
 }
 
 void DirectoryFilter::saveState(QJsonObject &object) const

src/plugins/coreplugin/locator/executefilter.cpp

@@ -38,6 +38,9 @@ ExecuteFilter::ExecuteFilter()
 {
     setId("Execute custom commands");
     setDisplayName(tr("Execute Custom Commands"));
+    setDescription(tr(
+        "Runs an arbitrary command with arguments. The command is searched for in the PATH "
+        "environment variable if needed. Note that the command is run directly, not in a shell."));
     setDefaultShortcutString("!");
     setPriority(High);
     setDefaultIncludedByDefault(false);

src/plugins/coreplugin/locator/externaltoolsfilter.cpp

@@ -37,6 +37,8 @@ ExternalToolsFilter::ExternalToolsFilter()
 {
     setId("Run external tool");
     setDisplayName(tr("Run External Tool"));
+    setDescription(tr("Runs an external tool that you have set up in the options (Environment > "
+                      "External Tools)."));
     setDefaultShortcutString("x");
     setPriority(Medium);
 }

src/plugins/coreplugin/locator/filesystemfilter.cpp

@@ -66,6 +66,9 @@ FileSystemFilter::FileSystemFilter()
 {
     setId("Files in file system");
     setDisplayName(tr("Files in File System"));
+    setDescription(tr("Opens a file given by a relative path to the current document, or absolute "
+                      "path. \"~\" refers to your home directory. You have the option to create a "
+                      "file if it does not exist yet."));
     setDefaultShortcutString("f");
     setDefaultIncludedByDefault(false);
 }

src/plugins/coreplugin/locator/ilocatorfilter.cpp

@@ -459,6 +459,26 @@ void ILocatorFilter::setDisplayName(const QString &displayString)
     m_displayName = displayString;
 }
 
+/*!
+    Returns a longer, human-readable description of what the filter does.
+
+    \sa setDescription()
+*/
+QString ILocatorFilter::description() const
+{
+    return m_description;
+}
+
+/*!
+    Sets the longer, human-readable \a description of what the filter does.
+
+    \sa description()
+*/
+void ILocatorFilter::setDescription(const QString &description)
+{
+    m_description = description;
+}
+
 /*!
     Sets whether the filter provides a configuration dialog to \a configurable.
     Most filters should at least provide the default dialog.

src/plugins/coreplugin/locator/ilocatorfilter.h

@@ -132,6 +132,9 @@ public:
     QString displayName() const;
     void setDisplayName(const QString &displayString);
 
+    QString description() const;
+    void setDescription(const QString &description);
+
     Priority priority() const;
 
     QString shortcutString() const;
@@ -193,6 +196,7 @@ private:
     QString m_shortcut;
     Priority m_priority = Medium;
     QString m_displayName;
+    QString m_description;
     QString m_defaultShortcut;
     bool m_defaultIncludedByDefault = false;
     bool m_includedByDefault = m_defaultIncludedByDefault;

src/plugins/coreplugin/locator/javascriptfilter.cpp

@@ -38,6 +38,7 @@ JavaScriptFilter::JavaScriptFilter()
 {
     setId("JavaScriptFilter");
     setDisplayName(tr("Evaluate JavaScript"));
+    setDescription(tr("Evaluates arbitrary JavaScript expressions and copies the result."));
     setDefaultIncludedByDefault(false);
     setDefaultShortcutString("=");
     m_abortTimer.setSingleShot(true);

src/plugins/coreplugin/locator/locator.cpp

@@ -250,6 +250,7 @@ void Locator::updateFilterActions()
             action = actionCopy.take(filterId);
             action->setText(filter->displayName());
         }
+        action->setToolTip(filter->description());
         m_filterActionMap.insert(filterId, action);
     }
 

src/plugins/coreplugin/locator/locatorsettingspage.cpp

@@ -111,6 +111,9 @@ QVariant FilterItem::data(int column, int role) const
     default:
         break;
     }
+
+    if (role == Qt::ToolTipRole)
+        return m_filter->description();
     return QVariant();
 }
 

src/plugins/coreplugin/locator/spotlightlocatorfilter.cpp

@@ -241,6 +241,10 @@ SpotlightLocatorFilter::SpotlightLocatorFilter()
     setDefaultShortcutString("md");
     setDefaultIncludedByDefault(false);
     setDisplayName(tr("File Name Index"));
+    setDescription(
+        tr("Matches files from a global file system index (Spotlight, Locate, Everything). Append "
+           "\"+<number>\" or \":<number>\" to jump to the given line number. Append another "
+           "\"+<number>\" or \":<number>\" to jump to the column number as well."));
     setConfigurable(true);
     reset();
 }

src/plugins/coreplugin/menubarfilter.cpp

@@ -54,6 +54,9 @@ MenuBarFilter::MenuBarFilter()
 {
     setId("Actions from the menu");
     setDisplayName(tr("Actions from the Menu"));
+    setDescription(
+        tr("Triggers an action from the menu. Matches any part of a menu hierarchy, separated by "
+           "\">\". For example \"sess def\" matches \"File > Sessions > Default\"."));
     setDefaultShortcutString("t");
     connect(ICore::instance(), &ICore::contextAboutToChange, this, [this] {
         if (LocatorManager::locatorHasFocus())

src/plugins/cpptools/cppincludesfilter.cpp

@@ -121,6 +121,10 @@ CppIncludesFilter::CppIncludesFilter()
 {
     setId(Constants::INCLUDES_FILTER_ID);
     setDisplayName(Constants::INCLUDES_FILTER_DISPLAY_NAME);
+    setDescription(
+        tr("Matches all files that are included by all C++ files in all projects. Append "
+           "\"+<number>\" or \":<number>\" to jump to the given line number. Append another "
+           "\"+<number>\" or \":<number>\" to jump to the column number as well."));
     setDefaultShortcutString("ai");
     setDefaultIncludedByDefault(true);
     setPriority(ILocatorFilter::Low);

src/plugins/cvs/cvsplugin.cpp

@@ -546,6 +546,7 @@ CvsPluginPrivate::CvsPluginPrivate()
 
     const QString prefix = QLatin1String("cvs");
     m_commandLocator = new CommandLocator("CVS", prefix, prefix, this);
+    m_commandLocator->setDescription(tr("Triggers a CVS version control operation."));
 
     // Register actions
     ActionContainer *toolsContainer = ActionManager::actionContainer(M_TOOLS);

src/plugins/git/gitplugin.cpp

@@ -662,6 +662,7 @@ GitPluginPrivate::GitPluginPrivate()
 
     const QString prefix = "git";
     m_commandLocator = new CommandLocator("Git", prefix, prefix, this);
+    m_commandLocator->setDescription(tr("Triggers a Git version control operation."));
 
     //register actions
     ActionContainer *toolsContainer = ActionManager::actionContainer(Core::Constants::M_TOOLS);

src/plugins/languageclient/locatorfilter.cpp

@@ -47,6 +47,8 @@ DocumentLocatorFilter::DocumentLocatorFilter()
 {
     setId(Constants::LANGUAGECLIENT_DOCUMENT_FILTER_ID);
     setDisplayName(Constants::LANGUAGECLIENT_DOCUMENT_FILTER_DISPLAY_NAME);
+    setDescription(
+        tr("Matches all symbols from the current document, based on a language server."));
     setDefaultShortcutString(".");
     setDefaultIncludedByDefault(false);
     setPriority(ILocatorFilter::Low);

src/plugins/macros/macrolocatorfilter.cpp

@@ -42,6 +42,8 @@ MacroLocatorFilter::MacroLocatorFilter()
 {
     setId("Macros");
     setDisplayName(tr("Text Editing Macros"));
+    setDescription(tr("Runs a text editing macro that was recorded with Tools > Text Editing "
+                      "Macros > Record Macro."));
     setDefaultShortcutString("rm");
 }
 

src/plugins/mercurial/mercurialplugin.cpp

@@ -279,6 +279,7 @@ MercurialPluginPrivate::MercurialPluginPrivate()
 
     const QString prefix = QLatin1String("hg");
     m_commandLocator = new Core::CommandLocator("Mercurial", prefix, prefix, this);
+    m_commandLocator->setDescription(tr("Triggers a Mercurial version control operation."));
 
     createMenu(context);
 }

src/plugins/perforce/perforceplugin.cpp

@@ -400,6 +400,7 @@ PerforcePluginPrivate::PerforcePluginPrivate()
 
     const QString prefix = QLatin1String("p4");
     m_commandLocator = new CommandLocator("Perforce", prefix, prefix, this);
+    m_commandLocator->setDescription(tr("Triggers a Perforce version control operation."));
 
     ActionContainer *mtools = ActionManager::actionContainer(Core::Constants::M_TOOLS);
 

src/plugins/projectexplorer/allprojectsfilter.cpp

@@ -38,6 +38,9 @@ AllProjectsFilter::AllProjectsFilter()
 {
     setId("Files in any project");
     setDisplayName(tr("Files in Any Project"));
+    setDescription(tr("Matches all files of all open projects. Append \"+<number>\" or "
+                      "\":<number>\" to jump to the given line number. Append another "
+                      "\"+<number>\" or \":<number>\" to jump to the column number as well."));
     setDefaultShortcutString("a");
     setDefaultIncludedByDefault(true);
 

src/plugins/projectexplorer/currentprojectfilter.cpp

@@ -38,6 +38,9 @@ CurrentProjectFilter::CurrentProjectFilter()
 {
     setId("Files in current project");
     setDisplayName(tr("Files in Current Project"));
+    setDescription(tr("Matches all files from the current document's project. Append \"+<number>\" "
+                      "or \":<number>\" to jump to the given line number. Append another "
+                      "\"+<number>\" or \":<number>\" to jump to the column number as well."));
     setDefaultShortcutString("p");
     setDefaultIncludedByDefault(false);
 

src/plugins/subversion/subversionplugin.cpp

@@ -402,6 +402,7 @@ SubversionPluginPrivate::SubversionPluginPrivate()
 
     const QString prefix = QLatin1String("svn");
     m_commandLocator = new CommandLocator("Subversion", prefix, prefix, this);
+    m_commandLocator->setDescription(tr("Triggers a Subversion version control operation."));
 
     // Register actions
     ActionContainer *toolsContainer = ActionManager::actionContainer(M_TOOLS);

src/plugins/texteditor/linenumberfilter.cpp

@@ -48,6 +48,7 @@ LineNumberFilter::LineNumberFilter(QObject *parent)
 {
     setId("Line in current document");
     setDisplayName(tr("Line in Current Document"));
+    setDescription(tr("Jumps to the given line in the current document."));
     setPriority(High);
     setDefaultShortcutString("l");
     setDefaultIncludedByDefault(true);