Commit c85c3d15 authored by Eike Ziller's avatar Eike Ziller
Browse files

Add variable manager API documentation



Change-Id: Ia4cb33802bda2b51afc2f194136cd4d74d8bd854
Reviewed-by: default avatarLeena Miettinen <riitta-leena.miettinen@digia.com>
parent 9347f085
......@@ -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);
......
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