/************************************************************************
 * This file has been generated automatically from                      *
 *                                                                      *
 * src/gui/qgsexpressionbuilderwidget.h                                 *
 *                                                                      *
 * Do not edit manually ! Edit header and run scripts/sipify.py again   *
 ************************************************************************/








class QgsExpressionBuilderWidget : QWidget
{
%Docstring(signature="appended")
A reusable widget that can be used to build a expression string. See
:py:class:`QgsExpressionBuilderDialog` for example of usage.
%End

%TypeHeaderCode
#include "qgsexpressionbuilderwidget.h"
%End
  public:
    enum Flag /BaseType=IntEnum/
    {
      LoadNothing,
      LoadRecent,
      LoadUserExpressions,
      LoadAll,
    };
    typedef QFlags<QgsExpressionBuilderWidget::Flag> Flags;



    QgsExpressionBuilderWidget( QWidget *parent /TransferThis/ = 0 );
%Docstring
Create a new expression builder widget with an optional parent.
%End
    ~QgsExpressionBuilderWidget();

    void init( const QgsExpressionContext &context = QgsExpressionContext(), const QString &recentCollection = QStringLiteral( "generic" ), QgsExpressionBuilderWidget::Flags flags = LoadAll );
%Docstring
Initialize without any layer

.. versionadded:: 3.14
%End

    void initWithLayer( QgsVectorLayer *layer, const QgsExpressionContext &context = QgsExpressionContext(), const QString &recentCollection = QStringLiteral( "generic" ), QgsExpressionBuilderWidget::Flags flags = LoadAll );
%Docstring
Initialize with a layer

.. versionadded:: 3.14
%End

    void initWithFields( const QgsFields &fields, const QgsExpressionContext &context = QgsExpressionContext(), const QString &recentCollection = QStringLiteral( "generic" ), QgsExpressionBuilderWidget::Flags flags = LoadAll );
%Docstring
Initialize with given fields without any layer

.. versionadded:: 3.14
%End

    void setLayer( QgsVectorLayer *layer );
%Docstring
Sets layer in order to get the fields and values

.. note::

   this needs to be called before calling :py:func:`~QgsExpressionBuilderWidget.loadFieldNames`.
%End

    QgsVectorLayer *layer() const;
%Docstring
Returns the current layer or a None.
%End

 void loadFieldNames() /Deprecated/;
%Docstring
.. deprecated:: 3.14

   This is now done automatically.
%End

 void loadFieldNames( const QgsFields &fields ) /Deprecated/;
%Docstring
.. deprecated:: 3.14

   Use :py:func:`~QgsExpressionBuilderWidget.expressionTree`->:py:func:`~QgsExpressionBuilderWidget.loadFieldNames` instead.
%End

 void loadFieldsAndValues( const QMap<QString, QStringList> &fieldValues ) /Deprecated/;
%Docstring
Loads field names and values from the specified map.

.. deprecated:: 3.14

   This will not do anything, use :py:func:`~QgsExpressionBuilderWidget.setLayer` instead.
%End

    void setGeomCalculator( const QgsDistanceArea &da );
%Docstring
Sets geometry calculator used in distance/area calculations.
%End

    QString expressionText();
%Docstring
Gets the expression string that has been set in the expression area.

:return: The expression as a string.
%End

    void setExpressionText( const QString &expression );
%Docstring
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 preview result and for populating the list of available
functions and variables.

.. seealso:: :py:func:`setExpressionContext`
%End

    void setExpressionContext( const QgsExpressionContext &context );
%Docstring
Sets the expression context for the widget. The context is used for the
expression preview result and to populate the list of available
functions and variables.

:param context: expression context

.. seealso:: :py:func:`expressionContext`
%End

    bool isExpressionValid();
%Docstring
Returns if the expression is valid
%End


    void setCustomPreviewGenerator( const QString &label, const QList<QPair<QString, QVariant>> &choices, SIP_PYCALLABLE );
%Docstring
Sets the widget to run using a custom preview generator.

In this mode, the widget will call a callback function to generate a new
:py:class:`QgsExpressionContext` as the previewed object changes. This
can be used to provide custom preview values for different objects (i.e.
for objects which aren't vector layer features).

:param label: The label to display for the combo box presenting choices
              of objects. This should be a representative name, eg
              "Band" if the widget is showing choices of raster layer
              bands
:param choices: A list of choices to present to the user. Each choice is
                a pair of a human-readable label and a QVariant
                representing the object to preview.
:param previewContextGenerator: A function which takes a QVariant
                                representing the object to preview, and
                                returns a
                                :py:class:`QgsExpressionContext` to use
                                for previewing the object.

.. versionadded:: 3.38
%End
%MethodCode
    Py_XINCREF( a2 );
    Py_BEGIN_ALLOW_THREADS
      sipCpp->setCustomPreviewGenerator( *a0, *a1, [a2]( const QVariant &value ) -> QgsExpressionContext {
        QgsExpressionContext res;
        SIP_BLOCK_THREADS
        PyObject *s = sipCallMethod( NULL, a2, "D", &value, sipType_QVariant, NULL );
        int state;
        int sipIsError = 0;
        QgsExpressionContext *t1 = reinterpret_cast<QgsExpressionContext *>( sipConvertToType( s, sipType_QgsExpressionContext, 0, SIP_NOT_NONE, &state, &sipIsError ) );
        if ( sipIsError == 0 )
        {
          res = QgsExpressionContext( *t1 );
        }
        sipReleaseType( t1, sipType_QgsExpressionContext, state );
        SIP_UNBLOCK_THREADS
        return res;
      } );

    Py_END_ALLOW_THREADS
%End


 void saveToRecent( const QString &collection = "generic" ) /Deprecated/;
%Docstring
Adds the current expression to the given ``collection``. By default it
is saved to the collection "generic".

.. deprecated:: 3.14

   Use :py:func:`~QgsExpressionBuilderWidget.expressionTree`->:py:func:`~QgsExpressionBuilderWidget.saveRecent` instead.
%End

 void loadRecent( const QString &collection = QStringLiteral( "generic" ) ) /Deprecated/;
%Docstring
Loads the recent expressions from the given ``collection``. By default
it is loaded from the collection "generic".

.. deprecated:: 3.14

   Use :py:func:`~QgsExpressionBuilderWidget.expressionTree`->:py:func:`~QgsExpressionBuilderWidget.loadRecent` instead.
%End

    QgsExpressionTreeView *expressionTree() const;
%Docstring
Returns the expression tree

.. versionadded:: 3.14
%End

 void loadUserExpressions() /Deprecated/;
%Docstring
Loads the user expressions.

.. deprecated:: 3.14

   Use :py:func:`~QgsExpressionBuilderWidget.expressionTree`->:py:func:`~QgsExpressionBuilderWidget.loadUserExpressions` instead.
.. versionadded:: 3.12
%End

 void saveToUserExpressions( const QString &label, const QString &expression, const QString &helpText ) /Deprecated/;
%Docstring
Stores the user ``expression`` with given ``label`` and ``helpText``.

.. deprecated:: 3.14

   Use :py:func:`~QgsExpressionBuilderWidget.expressionTree`->:py:func:`~QgsExpressionBuilderWidget.saveToUserExpressions` instead.
.. versionadded:: 3.12
%End

 void removeFromUserExpressions( const QString &label ) /Deprecated/;
%Docstring
Removes the expression ``label`` from the user stored expressions.

.. deprecated:: 3.14

   Use :py:func:`~QgsExpressionBuilderWidget.expressionTree`->:py:func:`~QgsExpressionBuilderWidget.removeFromUserExpressions` instead.
.. versionadded:: 3.12
%End

    void newFunctionFile( const QString &fileName = "scratch" );
%Docstring
Creates a new file in the function editor
%End

    void saveFunctionFile( QString fileName );
%Docstring
Saves the current function editor text to the given file.
%End

    void loadCodeFromFile( QString path );
%Docstring
Loads code from the given file into the function editor
%End

    void loadCodeFromProjectFunctions();
%Docstring
Loads code from the project into the function editor

.. versionadded:: 3.40
%End

    void loadFunctionCode( const QString &code );
%Docstring
Loads code into the function editor
%End

    void updateFunctionFileList( const QString &path );
%Docstring
Updates the list of function files found at the given path
%End

    void saveProjectFunctionsEntry();
%Docstring
Saves the current function editor text to a project entry.

.. versionadded:: 3.40
%End

 QStandardItemModel *model() /Deprecated/;
%Docstring
Returns a pointer to the dialog's function item model. This method is
exposed for testing purposes only - it should not be used to modify the
model.

.. deprecated:: 3.14
%End

    QgsProject *project();
%Docstring
Returns the project currently associated with the widget.

.. seealso:: :py:func:`setProject`
%End

    void setProject( QgsProject *project );
%Docstring
Sets the ``project`` currently associated with the widget. This controls
which layers and relations and other project-specific items are shown in
the widget.

.. seealso:: :py:func:`project`
%End

    bool evalError() const;
%Docstring
Will be set to ``True`` if the current expression text reported an eval
error with the context.
%End

    bool parserError() const;
%Docstring
Will be set to ``True`` if the current expression text reports a parser
error with the context.
%End

    void setExpressionPreviewVisible( bool isVisible );
%Docstring
Sets whether the expression preview is visible.

.. versionadded:: 3.22
%End

  public slots:

    void loadSampleValues();
%Docstring
Load sample values into the sample value area. Including available
values, in case the formatter can provide them (eg. RelationReference).
%End

    void loadAllValues();
%Docstring
Load all unique values from the set layer into the sample area.
Including all available values, in case the formatter can provide them
(eg. RelationReference).
%End

    void loadSampleUsedValues();
%Docstring
Load used sample values into the sample value area. Only the used ones.
Without available values, even if the formatter can provide them (eg.
RelationReference).

.. versionadded:: 3.12
%End

    void loadAllUsedValues();
%Docstring
Load all unique values from the set layer into the sample area. Only the
used ones. Without available values, even if the formatter can provide
them (eg. RelationReference).

.. versionadded:: 3.12
%End

    void autosave();
%Docstring
Auto save the current Python function code.
%End

    void setAutoSave( bool enabled );
%Docstring
Enabled or disable auto saving. When enabled Python scripts will be auto
saved when text changes.

:param enabled: ``True`` to enable auto saving.
%End

    void storeCurrentUserExpression();
%Docstring
Adds the current expressions to the stored user expressions.

.. versionadded:: 3.12
%End

    void removeSelectedUserExpression();
%Docstring
Removes the selected expression from the stored user expressions, the
selected expression must be a user stored expression.

.. versionadded:: 3.12
%End

    void editSelectedUserExpression();
%Docstring
Edits the selected expression from the stored user expressions, the
selected expression must be a user stored expression.

.. versionadded:: 3.14
%End

    const QList<QgsExpressionItem *> findExpressions( const QString &label );
%Docstring
Returns the list of expression items matching a ``label``.

.. versionadded:: 3.12

.. deprecated:: 3.14

   Use :py:func:`~QgsExpressionBuilderWidget.expressionTree`->findExpressions instead.
%End


  signals:

    void expressionParsed( bool isValid );
%Docstring
Emitted when the user changes the expression in the widget. Users of
this widget should connect to this signal to decide if to let the user
continue.

:param isValid: Is ``True`` if the expression the user has typed is
                valid.
%End

    void evalErrorChanged();
%Docstring
Will be set to ``True`` if the current expression text reported an eval
error with the context.
%End

    void parserErrorChanged();
%Docstring
Will be set to ``True`` if the current expression text reported a parser
error with the context.
%End

  protected:
    virtual void showEvent( QShowEvent *e );


      public:
};


/************************************************************************
 * This file has been generated automatically from                      *
 *                                                                      *
 * src/gui/qgsexpressionbuilderwidget.h                                 *
 *                                                                      *
 * Do not edit manually ! Edit header and run scripts/sipify.py again   *
 ************************************************************************/