[FEATURE][needs-docs] Show data defined expected format in expression builder (#6839)

Author: NathanW2

python/gui/qgsexpressionbuilderdialog.sip.in

@@ -35,6 +35,26 @@ The builder widget that is used by the dialog
 
     QString expressionText();
 
+    QString expectedOutputFormat();
+%Docstring
+The set expected format string. This is pure text format and no expression validation
+is done against it.
+
+:return: The expected value format.
+%End
+
+    void setExpectedOutputFormat( const QString &expected );
+%Docstring
+The set expected format string. This is pure text format and no expression validation
+is done against it.
+
+:param expected: The expected value format for the expression.
+
+.. note::
+
+   Only a UI hint and not used for expression validation.
+%End
+
     QgsExpressionContext expressionContext() const;
 %Docstring
 Returns the expression context for the dialog. The context is used for the expression

python/gui/qgsexpressionbuilderwidget.sip.in

@@ -153,6 +153,26 @@ Gets the expression string that has been set in the expression area.
 Sets the expression string for the widget
 %End
 
+    QString expectedOutputFormat();
+%Docstring
+The set expected format string. This is pure text format and no expression validation
+is done against it.
+
+:return: The expected value format.
+%End
+
+    void setExpectedOutputFormat( const QString &expected );
+%Docstring
+The set expected format string. This is pure text format and no expression validation
+is done against it.
+
+:param expected: The expected value format for the expression.
+
+.. note::
+
+   Only a UI hint and not used for expression validation.
+%End
+
     QgsExpressionContext expressionContext() const;
 %Docstring
 Returns the expression context for the widget. The context is used for the expression

src/gui/qgsexpressionbuilderdialog.cpp

@@ -52,6 +52,16 @@ QString QgsExpressionBuilderDialog::expressionText()
   return builder->expressionText();
 }
 
+QString QgsExpressionBuilderDialog::expectedOutputFormat()
+{
+  return builder->expectedOutputFormat();
+}
+
+void QgsExpressionBuilderDialog::setExpectedOutputFormat( const QString &expected )
+{
+  builder->setExpectedOutputFormat( expected );
+}
+
 QgsExpressionContext QgsExpressionBuilderDialog::expressionContext() const
 {
   return builder->expressionContext();

src/gui/qgsexpressionbuilderdialog.h

@@ -47,6 +47,21 @@ class GUI_EXPORT QgsExpressionBuilderDialog : public QDialog, private Ui::QgsExp
 
     QString expressionText();
 
+    /**
+     * The set expected format string. This is pure text format and no expression validation
+     * is done against it.
+     * \returns The expected value format.
+     */
+    QString expectedOutputFormat();
+
+    /**
+     * The set expected format string. This is pure text format and no expression validation
+     * is done against it.
+     * \param expected The expected value format for the expression.
+     * \note Only a UI hint and not used for expression validation.
+     */
+    void setExpectedOutputFormat( const QString &expected );
+
     /**
      * Returns the expression context for the dialog. The context is used for the expression
      * preview result and for populating the list of available functions and variables.

src/gui/qgsexpressionbuilderwidget.cpp

@@ -143,6 +143,8 @@ QgsExpressionBuilderWidget::QgsExpressionBuilderWidget( QWidget *parent )
   txtExpressionString->setIndicatorHoverStyle( QgsCodeEditor::DotsIndicator, FUNCTION_MARKER_ID );
 
   connect( txtExpressionString, &QgsCodeEditorSQL::indicatorClicked, this, &QgsExpressionBuilderWidget::indicatorClicked );
+
+  setExpectedOutputFormat( QString() );
 }
 
 
@@ -597,6 +599,17 @@ void QgsExpressionBuilderWidget::setExpressionText( const QString &expression )
   txtExpressionString->setText( expression );
 }
 
+QString QgsExpressionBuilderWidget::expectedOutputFormat()
+{
+  return lblExpected->text();
+}
+
+void QgsExpressionBuilderWidget::setExpectedOutputFormat( const QString &expected )
+{
+  lblExpected->setText( expected );
+  mExpectedOutputFrame->setVisible( !expected.isNull() );
+}
+
 void QgsExpressionBuilderWidget::setExpressionContext( const QgsExpressionContext &context )
 {
   mExpressionContext = context;

src/gui/qgsexpressionbuilderwidget.h

@@ -173,6 +173,21 @@ class GUI_EXPORT QgsExpressionBuilderWidget : public QWidget, private Ui::QgsExp
     //! Sets the expression string for the widget
     void setExpressionText( const QString &expression );
 
+    /**
+     * The set expected format string. This is pure text format and no expression validation
+     * is done against it.
+     * \returns The expected value format.
+     */
+    QString expectedOutputFormat();
+
+    /**
+     * The set expected format string. This is pure text format and no expression validation
+     * is done against it.
+     * \param expected The expected value format for the expression.
+     * \note Only a UI hint and not used for expression validation.
+     */
+    void setExpectedOutputFormat( const QString &expected );
+
     /**
      * Returns the expression context for the widget. The context is used for the expression
      * preview result and for populating the list of available functions and variables.

src/gui/qgspropertyoverridebutton.cpp

@@ -596,6 +596,7 @@ void QgsPropertyOverrideButton::showExpressionDialog()
                               : mProperty.asExpression();
 
   QgsExpressionBuilderDialog d( const_cast<QgsVectorLayer *>( mVectorLayer ), currentExpression, this, QStringLiteral( "generic" ), context );
+  d.setExpectedOutputFormat( mInputDescription );
   if ( d.exec() == QDialog::Accepted )
   {
     mExpressionString = d.expressionText().trimmed();