Add variable manager API documentation

Change-Id: Ia4cb33802bda2b51afc2f194136cd4d74d8bd854 Reviewed-by: Leena Miettinen <riitta-leena.miettinen@digia.com>
2013-03-13 17:06:50 +01:00
parent 9347f08533
commit c85c3d15c6
1 changed files with 220 additions and 5 deletions
--- a/src/plugins/coreplugin/variablemanager.cpp
+++ b/src/plugins/coreplugin/variablemanager.cpp
@@ -68,40 +68,182 @@ public:

 /*!
    \class Core::VariableManager
-    \brief The VaraiableManager class holds a generic map from variable names
-    to string values.
+    \brief The VariableManager class manages \QC wide variables, that a user
+    can enter into many string settings. The variables are replaced by an actual value when the string
+    is used, similar to how environment variables are expanded by a shell.

-    The names of the variables are stored as QByteArray. They are typically
-    7-bit-clean. In cases where this is not possible, Latin-1 encoding is
+    \section1 Variables
+
+    Variable names can be basically any string without dollar sign and braces,
+    though it is recommended to only use 7-bit ASCII without special characters and whitespace.
+
+    If there are several variables that contain different aspects of the same object,
+    it is convention to give them the same prefix, followed by a colon and a postfix
+    that describes the aspect.
+    Examples of this are \c{CurrentDocument:FilePath} and \c{CurrentDocument:Selection}.
+
+    When the variable manager is requested to replace variables in a string, it looks for
+    variable names enclosed in ${ and }, like ${CurrentDocument:FilePath}.
+
+    \note The names of the variables are stored as QByteArray. They are typically
+    7-bit-clean. In cases where this is not possible, UTF-8 encoding is
    assumed.
+
+    \section1 Providing Variable Values
+
+    Plugins can register variables together with a description through registerVariable(),
+    and then need to connect to the variableUpdateRequested() signal to actually give
+    the variable its value when requested. A typical setup is to
+
+    \list 1
+    \o Register the variables in ExtensionSystem::IPlugin::initialize():
+       \code
+       static const char kMyVariable[] = "MyVariable";
+
+       bool MyPlugin::initialize(const QStringList &arguments, QString *errorString)
+       {
+       [...]
+       VariableManager::registerVariable(kMyVariable, tr("The current value of whatever I want."));
+       connect(VariableManager::instance(), SIGNAL(variableUpdateRequested(QByteArray)),
+               this, SLOT(updateVariable(QByteArray)));
+       [...]
+       }
+       \endcode
+
+    \o Set the variable value when requested:
+       \code
+       void MyPlugin::updateVariable(const QByteArray &variable)
+       {
+           if (variable == kMyVariable) {
+               QString value;
+               // do whatever is necessary to retrieve the value
+               [...]
+               VariableManager::insert(variable, value);
+           }
+       }
+       \endcode
+    \endlist
+
+    If there are conditions where your variable is not valid, you should call
+    VariableManager::remove(kMyVariable) in updateVariable().
+
+    For variables that refer to a file, you should use the convenience methods
+    VariableManager::registerFileVariables(), VariableManager::fileVariableValue() and
+    VariableManager::isFileVariable(). The methods take a variable prefix, like \c MyFileVariable,
+    and automatically handle standardized postfixes like \c{:FilePath},
+    \c{:Path} and \c{:FileBaseName}, resulting in the combined variables, such as
+    \c{MyFileVariable:FilePath}.
+
+    \section1 Providing and Expanding Parametrized Strings
+
+    Though it is possible to just ask the variable manager for the value of some variable in your
+    code, the preferred use case is to give the user the possibility to parametrize strings, for
+    example for settings.
+
+    (If you ever think about doing the former, think twice. It is much more efficient
+    to just ask the plugin that provides the variable value directly, without going through
+    string conversions, and through the variable manager which will do a large scale poll. To be
+    more concrete, using the example from the Providing Variable Values section: instead of
+    calling \c{VariableManager::value("MyVariable")}, it is much more efficient to just ask directly
+    with \c{MyPlugin::variableValue()}.)
+
+    \section2 User Interface
+
+    If the string that you want to parametrize is settable by the user, through a QLineEdit or
+    QTextEdit derived class, you should add a variable chooser to your UI, which allows adding
+    variables to the string by browsing through a list. See Core::VariableChooser for more
+    details.
+
+    \section2 Expanding Strings
+
+    Expanding variable values in strings is done by "macro expanders".
+    Utils::AbstractMacroExpander is the base class for these, and the variable manager
+    provides an implementation that expands \QC variables through
+    VariableManager::macroExpander().
+
+    There are several different ways to expand a string, covering the different use cases,
+    listed here sorted by relevance:
+    \list
+    \o Using VariableManager::expandedString(). This is the most comfortable way to get a string
+       with variable values expanded, but also the least flexible one. If this is sufficient for
+       you, use it.
+    \o Using the Utils::expandMacros() methods. These take a string and a macro expander (for which
+       you would use the one provided by the variable manager). Mostly the same as
+       VariableManager::expandedString(), but also has a variant that does the replacement inline
+       instead of returning a new string.
+    \o Using Utils::QtcProcess::expandMacros(). This expands the string while conforming to the
+       quoting rules of the platform it is run on. Use this method with the variable manager's
+       macro expander if your string will be passed as a command line parameter string to an
+       external command.
+    \o Writing your own macro expander that nests the variable manager's macro expander. And then
+       doing one of the above. This allows you to expand additional "local" variables/macros,
+       that do not come from the variable manager.
+    \endlist
+
+*/
+
+/*!
+ * \fn void VariableManager::variableUpdateRequested(const QByteArray &variable)
+ * Signals that the value of the \a variable should be updated because someone requests its value.
+ * Handlers of this signal should call insert() and return as fast as possible.
 */

 static VariableManager *variableManagerInstance = 0;
 static VariableManagerPrivate *d;

-
+/*!
+ * \internal
+ */
 VariableManager::VariableManager()
 {
    d = new VariableManagerPrivate;
    variableManagerInstance = this;
 }

+/*!
+ * \internal
+ */
 VariableManager::~VariableManager()
 {
    variableManagerInstance = 0;
    delete d;
 }

+/*!
+ * Used to set the \a value of a \a variable. Most of the time this is only done when
+ * requested by VariableManager::variableUpdateRequested(). If the value of the variable
+ * does not change, or changes very seldom, you can also keep the value up to date by calling
+ * this method whenever the value changes.
+ *
+ * As long as insert() was never called for a variable, it will not have a value, not even
+ * an empty string, meaning that the variable will not be expanded when expanding strings.
+ *
+ * \sa remove()
+ */
 void VariableManager::insert(const QByteArray &variable, const QString &value)
 {
    d->m_map.insert(variable, value);
 }

+/*!
+ * Removes any previous value for the given \a variable. This means that the variable
+ * will not be expanded at all when expanding strings, not even to an empty string.
+ *
+ * Returns true if the variable value could be removed, false if the variable value
+ * was not set when remove() was called.
+ *
+ * \sa insert()
+ */
 bool VariableManager::remove(const QByteArray &variable)
 {
    return d->m_map.remove(variable) > 0;
 }

+/*!
+ * Returns the value of the given \a variable. This will request an
+ * update of the variable's value first, by sending the variableUpdateRequested() signal.
+ * If \a found is given, it is set to true if the variable has a value at all, false if not.
+ */
 QString VariableManager::value(const QByteArray &variable, bool *found)
 {
    variableManagerInstance->variableUpdateRequested(variable);
@@ -110,26 +252,63 @@ QString VariableManager::value(const QByteArray &variable, bool *found)
    return d->m_map.value(variable);
 }

+/*!
+ * Returns \a stringWithVariables with all variables replaced by their values.
+ * See the VariableManager overview documentation for other ways to expand variables.
+ *
+ * \sa VariableManager
+ * \sa macroExpander()
+ */
 QString VariableManager::expandedString(const QString &stringWithVariables)
 {
    return Utils::expandMacros(stringWithVariables, macroExpander());
 }

+/*!
+ * Returns a macro expander that is used to expand all variables from the variable manager
+ * in a string.
+ * See the VariableManager overview documentation for other ways to expand variables.
+ *
+ * \sa VariableManager
+ * \sa expandedString()
+ */
 Utils::AbstractMacroExpander *VariableManager::macroExpander()
 {
    return &d->m_macroExpander;
 }

+/*!
+ * Returns the variable manager instance, for connecting to signals. All other methods are static
+ * and should be called as class methods, not through the instance.
+ */
 VariableManager *VariableManager::instance()
 {
    return variableManagerInstance;
 }

+/*!
+ * Makes the given \a variable known to the variable manager, together with a localized
+ * \a description. It is not strictly necessary to register variables, but highly recommended,
+ * because this information is used and presented to the user by the VariableChooser.
+ *
+ * \sa registerFileVariables()
+ */
 void VariableManager::registerVariable(const QByteArray &variable, const QString &description)
 {
    d->m_descriptions.insert(variable, description);
 }

+/*!
+ * Convenience method to register several variables with the same \a prefix, that have a file
+ * as a value. Takes the prefix and registers variables like \c{prefix:FilePath} and
+ * \c{prefix:Path}, with descriptions that start with the given \a heading.
+ * For example \c{registerFileVariables("CurrentDocument", tr("Current Document"))} registers
+ * variables such as \c{CurrentDocument:FilePath} with description
+ * "Current Document: Full path including file name."
+ *
+ * \sa isFileVariable()
+ * \sa fileVariableValue()
+ */
 void VariableManager::registerFileVariables(const QByteArray &prefix, const QString &heading)
 {
    registerVariable(prefix + kFilePathPostfix, tr("%1: Full path including file name.").arg(heading));
@@ -138,6 +317,13 @@ void VariableManager::registerFileVariables(const QByteArray &prefix, const QStr
    registerVariable(prefix + kFileBaseNamePostfix, tr("%1: File base name without path and suffix.").arg(heading));
 }

+/*!
+ * Returns whether the \a variable is a file kind of variable with the given \a prefix. For example
+ * \c{MyVariable:FilePath} is a file variable with prefix \c{MyVariable}.
+ *
+ * \sa registerFileVariables()
+ * \sa fileVariableValue()
+ */
 bool VariableManager::isFileVariable(const QByteArray &variable, const QByteArray &prefix)
 {
    return variable == prefix + kFilePathPostfix
@@ -146,12 +332,32 @@ bool VariableManager::isFileVariable(const QByteArray &variable, const QByteArra
            || variable == prefix + kFileBaseNamePostfix;
 }

+/*!
+ * Checks if the \a variable is a variable of the file type with the given \a prefix, and returns
+ * the value of the variable by extracting the wanted information from the given absolute
+ * \a fileName.
+ * Returns an empty string if the variable does not have the prefix, or does not have a
+ * postfix that is used for file variables, or if the file name is empty.
+ *
+ * \sa registerFileVariables()
+ * \sa isFileVariable()
+ */
 QString VariableManager::fileVariableValue(const QByteArray &variable, const QByteArray &prefix,
                                           const QString &fileName)
 {
    return fileVariableValue(variable, prefix, QFileInfo(fileName));
 }

+/*!
+ * Checks if the \a variable is a variable of the file type with the given \a prefix, and returns
+ * the value of the variable by extracting the wanted information from the given
+ * \a fileInfo.
+ * Returns an empty string if the variable does not have the prefix, or does not have a
+ * postfix that is used for file variables, or if the file name is empty.
+ *
+ * \sa registerFileVariables()
+ * \sa isFileVariable()
+ */
 QString VariableManager::fileVariableValue(const QByteArray &variable, const QByteArray &prefix,
                                           const QFileInfo &fileInfo)
 {
@@ -166,11 +372,20 @@ QString VariableManager::fileVariableValue(const QByteArray &variable, const QBy
    return QString();
 }

+/*!
+ * Returns all registered variable names.
+ *
+ * \sa registerVariable()
+ * \sa registerFileVariables()
+ */
 QList<QByteArray> VariableManager::variables()
 {
    return d->m_descriptions.keys();
 }

+/*!
+ * Returns the description that was registered for the \a variable.
+ */
 QString VariableManager::variableDescription(const QByteArray &variable)
 {
    return d->m_descriptions.value(variable);