Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
Add help text for variables
  • Loading branch information
nyalldawson committed Aug 22, 2015
1 parent 00892ce commit 6487f17
Show file tree
Hide file tree
Showing 8 changed files with 154 additions and 14 deletions.
15 changes: 15 additions & 0 deletions python/core/qgsexpression.sip
Expand Up @@ -575,7 +575,22 @@ class QgsExpression
/** Entry function for the visitor pattern */
void acceptVisitor( QgsExpression::Visitor& v ) const;

/** Returns the help text for a specified function.
* @param name function name
* @see variableHelpText()
*/
static QString helptext( QString name );

/** Returns the help text for a specified variable.
* @param variableName name of variable
* @see helptext()
* @note added in QGIS 2.12
*/
static QString variableHelpText( const QString& variableName );

/** Returns the translated name for a function group.
* @param group untranslated group name
*/
static QString group( QString group );

protected:
Expand Down
3 changes: 3 additions & 0 deletions resources/function_help/Variables
@@ -0,0 +1,3 @@
<h3>Variables Group</h3>
This group contains dynamic variables which can be inserted into your expressions.

12 changes: 12 additions & 0 deletions resources/function_help/var
@@ -0,0 +1,12 @@
<h3>var function</h3>
Returns the value stored within a specified variable.

<h4>Syntax</h4>
<pre>var(variable_name)</pre>

<h4>Arguments</h4>
variable_name &rarr; variable name

<h4>Example</h4>
<pre> var('qgis_version') &rarr; '2.12'</pre>

85 changes: 85 additions & 0 deletions src/core/qgsexpression.cpp
Expand Up @@ -3025,6 +3025,91 @@ QString QgsExpression::helptext( QString name )
return gFunctionHelpTexts.value( name, QObject::tr( "function help for %1 missing" ).arg( name ) );
}

QHash<QString, QString> QgsExpression::gVariableHelpTexts;

void QgsExpression::initVariableHelp()
{
if ( !gVariableHelpTexts.isEmpty() )
return;

//global variables
gVariableHelpTexts.insert( "qgis_version", QCoreApplication::translate( "variable_help", "Current QGIS version string." ) );
gVariableHelpTexts.insert( "qgis_version_no", QCoreApplication::translate( "variable_help", "Current QGIS version number." ) );
gVariableHelpTexts.insert( "qgis_release_name", QCoreApplication::translate( "variable_help", "Current QGIS release name." ) );

//project variables
gVariableHelpTexts.insert( "project_title", QCoreApplication::translate( "variable_help", "Title of current project." ) );
gVariableHelpTexts.insert( "project_path", QCoreApplication::translate( "variable_help", "Full path (including file name) of current project." ) );
gVariableHelpTexts.insert( "project_folder", QCoreApplication::translate( "variable_help", "Folder for current project." ) );
gVariableHelpTexts.insert( "project_filename", QCoreApplication::translate( "variable_help", "Filename of current project." ) );

//layer variables
gVariableHelpTexts.insert( "layer_name", QCoreApplication::translate( "variable_help", "Name of current layer." ) );
gVariableHelpTexts.insert( "layer_id", QCoreApplication::translate( "variable_help", "ID of current project." ) );
gVariableHelpTexts.insert( "layer_title", QCoreApplication::translate( "variable_help", "Title of current layer." ) );
gVariableHelpTexts.insert( "layer_abstract", QCoreApplication::translate( "variable_help", "Metadata abstract for current layer." ) );
gVariableHelpTexts.insert( "layer_keywords", QCoreApplication::translate( "variable_help", "Metadata keywords for current layer." ) );
gVariableHelpTexts.insert( "layer_dataurl", QCoreApplication::translate( "variable_help", "Metadata data URL for current layer." ) );
gVariableHelpTexts.insert( "layer_attribution", QCoreApplication::translate( "variable_help", "Metadata attribution for current layer." ) );
gVariableHelpTexts.insert( "layer_attributionurl", QCoreApplication::translate( "variable_help", "Metadata attribution URL for current layer." ) );
gVariableHelpTexts.insert( "layer_source", QCoreApplication::translate( "variable_help", "Source of current layer." ) );
gVariableHelpTexts.insert( "layer_minscale", QCoreApplication::translate( "variable_help", "Minimum display scale for current layer." ) );
gVariableHelpTexts.insert( "layer_maxscale", QCoreApplication::translate( "variable_help", "Maximum display scale for current layer." ) );
gVariableHelpTexts.insert( "layer_crs", QCoreApplication::translate( "variable_help", "CRS of current layer." ) );
gVariableHelpTexts.insert( "layer_crsdefinition", QCoreApplication::translate( "variable_help", "CRS definition of current layer." ) );
gVariableHelpTexts.insert( "layer_extent", QCoreApplication::translate( "variable_help", "Extent of current layer (as a geometry object)." ) );
gVariableHelpTexts.insert( "layer_type", QCoreApplication::translate( "variable_help", "Type of current layer, eg raster/vector." ) );
gVariableHelpTexts.insert( "layer_storagetype", QCoreApplication::translate( "variable_help", "Storage format of current layer." ) );
gVariableHelpTexts.insert( "layer_geometrytype", QCoreApplication::translate( "variable_help", "Geometry type of current layer." ) );
gVariableHelpTexts.insert( "layer_featurecount", QCoreApplication::translate( "variable_help", "Approximate feature count for current layer." ) );

//composition variables
gVariableHelpTexts.insert( "layout_numpages", QCoreApplication::translate( "variable_help", "Number of pages in composition." ) );
gVariableHelpTexts.insert( "layout_pageheight", QCoreApplication::translate( "variable_help", "Composition page height in mm." ) );
gVariableHelpTexts.insert( "layout_pagewidth", QCoreApplication::translate( "variable_help", "Composition page width in mm." ) );
gVariableHelpTexts.insert( "layout_dpi", QCoreApplication::translate( "variable_help", "Composition resolution (DPI)." ) );

//atlas variables
gVariableHelpTexts.insert( "atlas_totalfeatures", QCoreApplication::translate( "variable_help", "Total number of features in atlas." ) );
gVariableHelpTexts.insert( "atlas_featurenumber", QCoreApplication::translate( "variable_help", "Current atlas feature number." ) );
gVariableHelpTexts.insert( "atlas_filename", QCoreApplication::translate( "variable_help", "Current atlas file name." ) );
gVariableHelpTexts.insert( "atlas_pagename", QCoreApplication::translate( "variable_help", "Current atlas page name." ) );
gVariableHelpTexts.insert( "atlas_feature", QCoreApplication::translate( "variable_help", "Current atlas feature (as feature object)." ) );
gVariableHelpTexts.insert( "atlas_featureid", QCoreApplication::translate( "variable_help", "Current atlas feature ID." ) );

//composer item variables
gVariableHelpTexts.insert( "item_id", QCoreApplication::translate( "variable_help", "Composer item user ID (not necessarily unique)." ) );
gVariableHelpTexts.insert( "item_uuid", QCoreApplication::translate( "variable_help", "Composer item unique ID." ) );
gVariableHelpTexts.insert( "item_left", QCoreApplication::translate( "variable_help", "Left position of composer item (in mm)." ) );
gVariableHelpTexts.insert( "item_top", QCoreApplication::translate( "variable_help", "Top position of composer item (in mm)." ) );
gVariableHelpTexts.insert( "item_width", QCoreApplication::translate( "variable_help", "Width of composer item (in mm)." ) );
gVariableHelpTexts.insert( "item_height", QCoreApplication::translate( "variable_help", "Height of composer item (in mm)." ) );
}

QString QgsExpression::variableHelpText( const QString &variableName, bool showValue, const QVariant &value )
{
QgsExpression::initVariableHelp();
QString text = gVariableHelpTexts.contains( variableName ) ? QString( "<p>%1</p>" ).arg( gVariableHelpTexts.value( variableName ) ) : QString();
if ( showValue )
{
QString valueString;
if ( !value.isValid() )
{
valueString = QCoreApplication::translate( "variable_help", "not set" );
}
else if ( value.type() == QVariant::String )
{
valueString = QString( "'<b>%1</b>'" ).arg( value.toString() );
}
else
{
valueString = QString( "<b>%1</b>" ).arg( value.toString() );
}
text.append( QCoreApplication::translate( "variable_help", "<p>Current value: %1</p>" ).arg( valueString ) );
}
return text;
}

QHash<QString, QString> QgsExpression::gGroups;

QString QgsExpression::group( QString name )
Expand Down
29 changes: 24 additions & 5 deletions src/core/qgsexpression.h
Expand Up @@ -529,11 +529,11 @@ class CORE_EXPORT QgsExpression
* @return The type of this node
*/
virtual NodeType nodeType() const = 0;
/**
* Abstract virtual eval method
* Errors are reported to the parent
*/

/**
* Abstract virtual eval method
* Errors are reported to the parent
*/
Q_DECL_DEPRECATED virtual QVariant eval( QgsExpression* parent, const QgsFeature* f );

/**
Expand Down Expand Up @@ -853,7 +853,24 @@ class CORE_EXPORT QgsExpression
/** Entry function for the visitor pattern */
void acceptVisitor( Visitor& v ) const;

/** Returns the help text for a specified function.
* @param name function name
* @see variableHelpText()
*/
static QString helptext( QString name );

/** Returns the help text for a specified variable.
* @param variableName name of variable
* @param showValue set to true to include current value of variable in help text
* @param value current value of variable to show in help text
* @see helptext()
* @note added in QGIS 2.12
*/
static QString variableHelpText( const QString& variableName, bool showValue = true, const QVariant& value = QVariant() );

/** Returns the translated name for a function group.
* @param group untranslated group name
*/
static QString group( QString group );

protected:
Expand All @@ -879,9 +896,11 @@ class CORE_EXPORT QgsExpression
static QMap<QString, QString> gmSpecialColumnGroups;

static QHash<QString, QString> gFunctionHelpTexts;
static QHash<QString, QString> gVariableHelpTexts;
static QHash<QString, QString> gGroups;

static void initFunctionHelp();
static void initVariableHelp();

friend class QgsOgcUtils;

Expand Down
16 changes: 8 additions & 8 deletions src/core/qgsexpressioncontext.cpp
Expand Up @@ -416,7 +416,7 @@ class GetNamedProjectColor : public QgsScopedExpressionFunction
{
public:
GetNamedProjectColor()
: QgsScopedExpressionFunction( "project_color", 1, "Colors" )
: QgsScopedExpressionFunction( "project_color", 1, "Color" )
{
//build up color list from project. Do this in advance for speed
QStringList colorStrings = QgsProject::instance()->readListEntry( "Palette", "/Colors" );
Expand Down Expand Up @@ -575,7 +575,7 @@ QgsExpressionContextScope* QgsExpressionContextUtils::layerScope( const QgsMapLa
QgsVectorLayer* vLayer = dynamic_cast< QgsVectorLayer* >( nonConstLayer );
if ( vLayer )
{
scope->addVariable( QgsExpressionContextScope::StaticVariable( "layer_geometrytype", vLayer->type(), true ) );
scope->addVariable( QgsExpressionContextScope::StaticVariable( "layer_type", vLayer->type(), true ) );
scope->addVariable( QgsExpressionContextScope::StaticVariable( "layer_storagetype", vLayer->storageType(), true ) );
QString typeString( QGis::vectorGeometryType( vLayer->geometryType() ) );
scope->addVariable( QgsExpressionContextScope::StaticVariable( "layer_geometrytype", typeString, true ) );
Expand Down Expand Up @@ -648,10 +648,10 @@ QgsExpressionContextScope *QgsExpressionContextUtils::compositionScope( const Qg
}

//add known composition context variables
scope->addVariable( QgsExpressionContextScope::StaticVariable( "composer_numpages", composition->numPages(), true ) );
scope->addVariable( QgsExpressionContextScope::StaticVariable( "composer_page_height", composition->paperHeight(), true ) );
scope->addVariable( QgsExpressionContextScope::StaticVariable( "composer_page_width", composition->paperWidth(), true ) );
scope->addVariable( QgsExpressionContextScope::StaticVariable( "composer_dpi", composition->printResolution(), true ) );
scope->addVariable( QgsExpressionContextScope::StaticVariable( "layout_numpages", composition->numPages(), true ) );
scope->addVariable( QgsExpressionContextScope::StaticVariable( "layout_pageheight", composition->paperHeight(), true ) );
scope->addVariable( QgsExpressionContextScope::StaticVariable( "layout_pagewidth", composition->paperWidth(), true ) );
scope->addVariable( QgsExpressionContextScope::StaticVariable( "layout_dpi", composition->printResolution(), true ) );

return scope;
}
Expand Down Expand Up @@ -697,8 +697,8 @@ QgsExpressionContextScope* QgsExpressionContextUtils::atlasScope( const QgsAtlas
return scope;

//add known atlas variables
scope->addVariable( QgsExpressionContextScope::StaticVariable( "atlas_numpages", atlas->numFeatures(), true ) );
scope->addVariable( QgsExpressionContextScope::StaticVariable( "atlas_page", atlas->currentFeatureNumber() + 1, true ) );
scope->addVariable( QgsExpressionContextScope::StaticVariable( "atlas_totalfeatures", atlas->numFeatures(), true ) );
scope->addVariable( QgsExpressionContextScope::StaticVariable( "atlas_featurenumber", atlas->currentFeatureNumber() + 1, true ) );
scope->addVariable( QgsExpressionContextScope::StaticVariable( "atlas_filename", atlas->currentFilename(), true ) );
scope->addVariable( QgsExpressionContextScope::StaticVariable( "atlas_pagename", atlas->currentPageName(), true ) );

Expand Down
2 changes: 1 addition & 1 deletion src/gui/qgsexpressionbuilderwidget.cpp
Expand Up @@ -575,7 +575,7 @@ void QgsExpressionBuilderWidget::loadExpressionContext()
QStringList variableNames = mExpressionContext.filteredVariableNames();
Q_FOREACH ( QString variable, variableNames )
{
registerItem( "Variables", variable, " @" + variable + " " );
registerItem( "Variables", variable, " @" + variable + " ", QgsExpression::variableHelpText( variable, true, mExpressionContext.variable( variable ) ) );
}

// Load the functions from the expression context
Expand Down
6 changes: 6 additions & 0 deletions src/gui/qgsexpressionselectiondialog.cpp
Expand Up @@ -43,6 +43,12 @@ QgsExpressionSelectionDialog::QgsExpressionSelectionDialog( QgsVectorLayer* laye
mExpressionBuilder->loadFieldNames();
mExpressionBuilder->loadRecent( "Selection" );

QgsExpressionContext context;
context << QgsExpressionContextUtils::globalScope()
<< QgsExpressionContextUtils::projectScope()
<< QgsExpressionContextUtils::layerScope( mLayer );
mExpressionBuilder->setExpressionContext( context );

QSettings settings;
restoreGeometry( settings.value( "/Windows/ExpressionSelectionDialog/geometry" ).toByteArray() );
}
Expand Down

0 comments on commit 6487f17

Please sign in to comment.