返回 Qt.io
联系我们 博客 下载 Qt

宏展开类

类 Utils::MacroExpander

MacroExpander 类管理 Qt Creator 中的全局变量，用户可以将这些变量输入到许多字符串设置中。当字符串被使用时，变量会被实际值替换，类似于shell展开环境变量。更多...

头文件 #include <MacroExpander>

公共函数

QStringexpand(const QString &stringWithVariables) const
voidregisterFileVariables(const QByteArray &prefix, const QString &heading, const Utils::MacroExpander::FileFunction &base, bool visibleInChooser = true)
voidregisterIntVariable(const QByteArray &variable, const QString &description, const Utils::MacroExpander::IntFunction &value)
voidregisterPrefix(const QByteArray &prefix, const QString &description, const Utils::MacroExpander::PrefixFunction &value, bool visible = true)
voidregisterVariable(const QByteArray &variable, const QString &description, const Utils::MacroExpander::StringFunction &value, bool visibleInChooser = true)
QStringvalue(const QByteArray &variable, bool *found = nullptr) const
QStringvariableDescription(const QByteArray &variable) const
QList<QByteArray>visibleVariables() const

详细描述

变量

变量名可以是基本上任何不带美元符号和大括号的字符串，尽管推荐只使用不带特殊字符和空白的 7 位 ASCII。

如果有几个变量包含相同对象的多个方面，习惯上会给它们相同的词缀，后面跟一个冒号和一个描述方面的后缀。例如，这是 CurrentDocument:FilePath 和 CurrentDocument:Selection。

当变量管理器请求在一个字符串中替换变量时，它会寻找被大括号括起来的变量名，如 %{CurrentDocument:FilePath}。

可以使用 %{Env:...} 表示法访问环境变量。例如，要访问 SHELL 环境变量，请使用 %{Env:SHELL}。

注意：变量的名称存储为 QByteArray。它们通常是 7 位干净的。在不可能做到这一点的情况下，假设 UTF-8 编码。

提供变量值

插件可以通过 registerVariable() 与描述一起注册变量。典型的设置是在 Plugin::initialize() 函数中注册变量。

bool MyPlugin::initialize(const QStringList &arguments, QString *errorString)
{
    [...]
    MacroExpander::registerVariable(
        "MyVariable",
        Tr::tr("The current value of whatever I want."));
        [] {
            QString value;
            // do whatever is necessary to retrieve the value
            [...]
            return value;
        }
    );
    [...]
}

对于指向文件的变量，您应使用便捷函数 MacroExpander::registerFileVariables()。该函数接收一个变量前缀，例如 MyFileVariable，并自动处理标准后缀如 :FilePath、:Path 和 :FileBaseName，得到组合变量，例如 MyFileVariable:FilePath。

提供和扩展参数化字符串

尽管可以在代码中直接请求变量的值，但最佳做法是允许用户对字符串进行参数化，例如用于设置。

(如果您曾考虑过前者，请三思。直接询问提供变量值的插件，不通过字符串转换完成任务，也不通过变量管理器进行大量轮询，会更高效。具体来说，使用“提供变量值”部分中的示例：直接使用 MyPlugin::variableValue() 而不是调用 MacroExpander::value("MyVariable")，会更高效。)

用户界面

如果要参数化的字符串可以通过用户设置，通过一个 QLineEdit 或其衍生类的 QTextEdit，您应该在UI中添加一个变量选择器，允许通过遍历列表将变量添加到字符串中。有关更多信息，请参阅 Utils::VariableChooser。

扩展字符串

在字符串中扩展变量值是通过“宏扩展器”完成的。Utils::AbstractMacroExpander 是这些扩展器的基类，而变量管理器提供了一个由 MacroExpander::macroExpander() 提供的实现，用于扩展 Qt Creator 变量。

有多种方法可以扩展一个字符串，涵盖了不同的使用场景，按相关性排序如下

  • 使用 MacroExpander::expandedString()。这是获取已扩展变量值字符串的最舒适方式，但也是灵活性最差的方式。如果这对您足够，请使用它。
  • 使用 Utils::expandMacros() 函数。这些函数接收一个字符串和一个宏扩展器（您可以使用变量管理器提供的扩展器）。与 MacroExpander::expandedString() 大致相同，但还有一个变体，它直接替换字符串而不是返回一个新字符串。
  • 使用 Utils::CommandLine::expandMacros()。在符合其运行平台引用规则的同时扩展字符串。将此函数与变量管理器的宏扩展器一起使用，如果要将字符串作为命令行参数传递给外部命令。
  • 编写自己的宏扩展器，嵌套变量管理器的宏扩展器。然后执行上述操作之一。这允许您扩展来自变量管理器之外的“本地”变量/宏。

成员函数文档

QString MacroExpander::expand(const QString &stringWithVariables) const

返回 stringWithVariables，其中所有变量都已替换为其值。有关其他扩展变量的方法，请参阅 MacroExpander 概述文档。

另请参见 MacroExpander

void MacroExpander::registerFileVariables(const QByteArray &prefix, const QString &heading, const Utils::MacroExpander::FileFunction &base, bool visibleInChooser = true)

这是一个方便的功能，用于注册具有相同前缀、以文件作为值的多个变量。它将前缀和变量 registering 如 prefix:FilePath 和 prefix:Path 注册，并且以给定的标题 heading 开头提供描述。例如 registerFileVariables("CurrentDocument", Tr::tr("Current Document")) 将注册类似 CurrentDocument:FilePath 的变量，其描述为 "当前文档：包括文件名的完整路径"。

接受一个返回 FilePath 作为基函数。

如果 visibleInChooser 是 true，则变量将显示给用户。

另请参见 registerVariable（），registerIntVariable（）和registerPrefix（）。

void MacroExpander::registerIntVariable(const QByteArray &variable, const QString &description, const Utils::MacroExpander::IntFunction &value)

将给定的整数值变量知识与变量管理器，以及本地化的描述。

当需要检索变量的当前值时，将调用 value IntFunction。

另请参见 registerVariable（），registerFileVariables（）和registerPrefix（）。

void MacroExpander::registerPrefix(const QByteArray &prefix, const QString &description, const Utils::MacroExpander::PrefixFunction &value, bool visible = true)

将给定的字符串值前缀知识与变量管理器，连同本地化描述一起。

value PrefixFunction 将被调用，并用没有前缀的完整变量名作为输入。如果 visible 是 true，则将显示给用户。

另请参见 registerVariable（），registerIntVariable（）和registerFileVariables（）。

void MacroExpander::registerVariable(const QByteArray &variable, const QString &description, const Utils::MacroExpander::StringFunction &value, bool visibleInChooser = true)

将给定的字符串值变量知识与变量管理器，连同本地化描述一起。

当需要检索变量的当前值时，将调用 value StringFunction。如果 visibleInChooser 是 true，则将显示给用户。

另请参见 registerFileVariables（），registerIntVariable（）和registerPrefix（）。

QString MacroExpander::value(const QByteArray &variable, bool *found = nullptr) const

返回给定变量的值。如果提供了found，则无论变量是否有值，都将其设置为true，如果没有则设置为false。

QString MacroExpander::variableDescription(const QByteArray &variable) const

返回为变量variable注册的描述。

QList<QByteArray> MacroExpander::visibleVariables() const

返回所有已注册的变量名。

另请参阅registerVariable()和registerFileVariables。

©2024 Qt公司有限公司。本文档中包含的贡献归各自版权所有者所有。本文档根据自由软件基金会发布的GNU自由文档许可协议版本1.3的条款授予许可。Qt及其相关标志是Qt公司在芬兰和/或全球其他国家的商标。所有其他商标都是各自所有者的财产。