PopupManager Class

  • PopupManager
  • class Esri::ArcGISRuntime::PopupManager

    A popup manager that contains helper properties and methods to allow developers to easily build their own UI for pop-ups. More...

    Header: #include <PopupManager.h>
    Since: Esri::ArcGISRuntime 100.0
    Inherits: Esri::ArcGISRuntime::Object

    Properties

    Public Functions

    PopupManager(Esri::ArcGISRuntime::Popup *popup, QObject *parent = nullptr)
    virtual ~PopupManager() override
    Esri::ArcGISRuntime::PopupAttachmentManager *attachmentManager() const
    void cancelEditing()
    QMap<QString, Esri::ArcGISRuntime::Error> contingencyValidationErrors() const
    QMap<QString, Esri::ArcGISRuntime::Error> contingencyValidationWarnings() const
    Esri::ArcGISRuntime::ContingentValuesResult *contingentValuesForField(Esri::ArcGISRuntime::PopupField *field) const
    QString customHtmlDescription() const
    Esri::ArcGISRuntime::PopupAttributeListModel *displayedFields() const
    bool doesChangeRequireNotification(const Esri::ArcGISRuntime::FeatureTemplate &featureTemplate) const
    Esri::ArcGISRuntime::Domain domain(Esri::ArcGISRuntime::PopupField *popupField) const
    QString editSummary() const
    Esri::ArcGISRuntime::PopupAttributeListModel *editableFields() const
    Esri::ArcGISRuntime::GeometryBuilder *editingGeometryBuilder() const
    QFuture<QList<Esri::ArcGISRuntime::PopupExpressionEvaluation *>> evaluateExpressionsAsync(QObject *parent = nullptr)
    QList<Esri::ArcGISRuntime::PopupElement *> evaluatedElements() const
    QList<Esri::ArcGISRuntime::FeatureType> featureTypes() const
    Esri::ArcGISRuntime::PopupField *fieldByName(const QString &fieldName) const
    QString fieldLabel(Esri::ArcGISRuntime::PopupField *popupField) const
    Esri::ArcGISRuntime::FieldType fieldType(Esri::ArcGISRuntime::PopupField *popupField) const
    QVariant fieldValue(Esri::ArcGISRuntime::PopupField *popupField) const
    QVariant fieldValue(const QString &fieldName, Esri::ArcGISRuntime::PopupElement *popupElement) const
    void finishEditing()
    QString formattedValue(Esri::ArcGISRuntime::PopupField *popupField) const
    bool isDeleteAllowed() const
    bool isEditGeometryAllowed() const
    bool isEditing() const
    bool isEditingAllowed() const
    bool isFeatureType(Esri::ArcGISRuntime::PopupField *popupField) const
    bool isFieldInFieldGroup(Esri::ArcGISRuntime::PopupField *popupField) const
    bool isGeoElementValid() const
    bool isNullable(Esri::ArcGISRuntime::PopupField *popupField) const
    bool isShowAttachments() const
    bool isShowCustomHtmlDescription() const
    bool isShowEditSummary() const
    bool isShowMedia() const
    int maxLength(Esri::ArcGISRuntime::PopupField *popupField) const
    Esri::ArcGISRuntime::Popup *popup() const
    QString rangeDomainValidationText(Esri::ArcGISRuntime::PopupField *popupField) const
    void setEditingGeometryBuilder(Esri::ArcGISRuntime::GeometryBuilder *builder)
    bool startEditing()
    QString substitute(const QString &templateString) const
    Esri::ArcGISRuntime::Symbol *symbol() const
    QString title() const
    Esri::ArcGISRuntime::Error updateValue(const QVariant &newValue, Esri::ArcGISRuntime::PopupField *popupField)
    Esri::ArcGISRuntime::Error updateValue(const Esri::ArcGISRuntime::FeatureTemplate &featureTemplate, Esri::ArcGISRuntime::FeatureTypeChangeMode changeMode)
    Esri::ArcGISRuntime::Error validationError(Esri::ArcGISRuntime::PopupField *popupField) const

    Signals

    void editingCompleted(const Esri::ArcGISRuntime::Error &errors)
    void featureTypeChanged()
    void geoElementContingencyValidationErrorsChanged(const QMap<QString, Esri::ArcGISRuntime::Error> &errors)
    void geoElementContingencyValidationWarningsChanged(const QMap<QString, Esri::ArcGISRuntime::Error> &warnings)
    void geoElementValidChanged()
    void geoElementWarningsChanged(const QMap<QString, Esri::ArcGISRuntime::Error> &warnings)

    Detailed Description

    This class works in conjunction with the PopupView in the ArcGIS Maps SDK Toolkit. The PopupView is used to display information about a GeoElement. For example, a PopupView could be used to display the attributes of an ArcGISFeature that is stored in a Feature Service. PopupManager provides the PopupView with the content to display in the view. It also contains many helper functions and properties to assist the PopupView with displaying and editing information related to the associated GeoElement.

    An example workflow for displaying a PopupView using a PopupManager would be:

    • Declare a PopupView and anchor it to a desired location.
    • Perform an identify operation on a GeoView and select a Feature from the identify result.
    • Create a Popup from the Feature.
    • Optionally obtain the Popup's PopupDefinition and set the title, whether to show attachments, and so on.
    • Create a PopupManager from the Popup.
    • Assign the PopupView's popupManager property the PopupManager created in the previous step.
    • Call the show() method to display the PopupView.
    • Call the dismiss() method to hide the PopupView.

    Note: Each time a change is made to the Popup, PopupDefinition, PopupManager, or any of their properties, the PopupManager must be re-set to the PopupView.

    In order to use the PopupManager with a QML UI, the PopupManager, PopupAttachmentManager, PopupAttachmentListModel, and PopupAttributeListModel classes must be registered as QML Types. For example, the following lines could be added to the main.cpp to register the classes under the Esri.Samples namespace:

    qmlRegisterUncreatableType<PopupManager>("Esri.Samples", 1, 0, "PopupManager", "PopupManager is uncreateable");
    qmlRegisterUncreatableType<PopupAttachmentManager>("Esri.Samples", 1, 0, "PopupAttachmentManager", "PopupAttachmentManager is uncreateable");
    qmlRegisterUncreatableType<PopupAttributeListModel>("Esri.Samples", 1, 0, "PopupAttributeListModel", "PopupAttributeListModel is uncreateable");
    qmlRegisterUncreatableType<PopupAttachmentListModel>("Esri.Samples", 1, 0, "PopupAttachmentListModel", "PopupAttachmentListModel is uncreateable");

    Note: The default PopupView provided with the toolkit is built with Qt Quick for a QML UI. If using Qt Widgets, a custom Widgets UI could be created to consume the information provided by PopupManager.

    Property Documentation

    [read-only] attachmentManager : PopupAttachmentManager* const

    This property holds the Popup's PopupAttachmentManager (read-only).

    Access functions:

    Esri::ArcGISRuntime::PopupAttachmentManager *attachmentManager() const

    [read-only] customHtmlDescription : const QString

    This property holds the Popup's custom HTML description (read-only).

    Access functions:

    QString customHtmlDescription() const

    [read-only] deleteAllowed : const bool

    Returns whether or not the pop-up UI should allow deleting the associated geo-element (read-only).

    Access functions:

    bool isDeleteAllowed() const

    [read-only] displayedFields : PopupAttributeListModel* const

    Returns the list of PopupFields that are visible (read-only).

    Access functions:

    Esri::ArcGISRuntime::PopupAttributeListModel *displayedFields() const

    [read-only] editGeometryAllowed : const bool

    This property holds whether editing a feature's geometry is allowed (read-only).

    Access functions:

    bool isEditGeometryAllowed() const

    [read-only] editSummary : const QString

    Returns the edit summary text (read-only).

    Access functions:

    QString editSummary() const

    [read-only] editableFields : PopupAttributeListModel* const

    Returns the list of PopupFields that are editable (read-only).

    Access functions:

    Esri::ArcGISRuntime::PopupAttributeListModel *editableFields() const

    [read-only] editing : const bool

    This property holds whether the PopupManager is in editing mode (read-only).

    Access functions:

    bool isEditing() const

    [read-only] editingAllowed : const bool

    Returns whether or not the pop-up UI should allow editing the associated geo-element (read-only).

    Access functions:

    bool isEditingAllowed() const

    [read-only] geoElementValid : const bool

    This property holds whether the Popup's GeoElement is valid (read-only).

    Access functions:

    bool isGeoElementValid() const

    [read-only] showAttachments : const bool

    This property holds whether attachments should be shown in the PopupView (read-only).

    Access functions:

    bool isShowAttachments() const

    [read-only] showCustomHtmlDescription : const bool

    This property holds whether a custom HTML description should be shown in the PopupView (read-only).

    Access functions:

    [read-only] showEditSummary : const bool

    This property holds whether the edit summary should be shown in the PopupView (read-only).

    Access functions:

    bool isShowEditSummary() const

    [read-only] showMedia : const bool

    This property holds whether media should be shown in the PopupView (read-only).

    Access functions:

    bool isShowMedia() const

    [read-only] title : const QString

    This property holds the Popup's title (read-only).

    Access functions:

    QString title() const

    Member Function Documentation

    [explicit] PopupManager::PopupManager(Esri::ArcGISRuntime::Popup *popup, QObject *parent = nullptr)

    Creates a PopupManager to manage the specified popup. If the GeoElement associated with the popup implements Loadable it must be loaded for the PopupManager to work properly.

    • popup - The Popup to manage.
    • parent - The optional parent QObject.

    [override virtual] PopupManager::~PopupManager()

    Destructor.

    [since Esri::ArcGISRuntime 100.1] Esri::ArcGISRuntime::PopupAttachmentManager *PopupManager::attachmentManager() const

    Returns the PopupAttachmentManager for this PopupManager.

    Returns null if there is no associated PopupAttachmentManager.

    Note: Getter function for property attachmentManager.

    This function was introduced in Esri::ArcGISRuntime 100.1.

    [invokable] void PopupManager::cancelEditing()

    Cancels the editing of the popup.

    This rolls the GeoElement back to its original state. Any edits that have been made since starting will be discarded.

    Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

    [since Esri::ArcGISRuntime 100.14] QMap<QString, Esri::ArcGISRuntime::Error> PopupManager::contingencyValidationErrors() const

    Returns pairs of field group name and an associated contingent values validation error.

    Errors are reported in validation when editing is defined as restrictive in the FieldGroup.

    This function was introduced in Esri::ArcGISRuntime 100.14.

    [since Esri::ArcGISRuntime 100.14] QMap<QString, Esri::ArcGISRuntime::Error> PopupManager::contingencyValidationWarnings() const

    Returns pairs of field group name and an associated contingent values validation warning.

    Warnings are reported in validation when editing is defined as non-restrictive in the FieldGroup.

    This function was introduced in Esri::ArcGISRuntime 100.14.

    [since Esri::ArcGISRuntime 100.14] Esri::ArcGISRuntime::ContingentValuesResult *PopupManager::contingentValuesForField(Esri::ArcGISRuntime::PopupField *field) const

    Returns the returned result will contain values for each FieldGroup the Field belongs to and all groups if there is more than one field group (the intersection of the values for each field group).

    • field - The PopupField to get the contingent values for.

    This function was introduced in Esri::ArcGISRuntime 100.14.

    QString PopupManager::customHtmlDescription() const

    Returns the text to display as the custom HTML description.

    If PopupDefinition::expressions is not empty, the custom HTML description may be using expressions with Arcade FeatureSet functions. Use PopupManager::evaluateExpressionsAsync() to evaluate the Arcade expressions before trying to get the PopupManager::customHtmlDescription() otherwise it may not return the correct description.

    Note: Getter function for property customHtmlDescription.

    Esri::ArcGISRuntime::PopupAttributeListModel *PopupManager::displayedFields() const

    Returns the fields for display use as a PopupAttributeListModel.

    Note: Getter function for property displayedFields.

    bool PopupManager::doesChangeRequireNotification(const Esri::ArcGISRuntime::FeatureTemplate &featureTemplate) const

    Returns whether changing to the specified FeatureTemplate requires warning the user that some data may be overwritten by the change.

    • featureTemplate - The template that the user wants to change to.

    Esri::ArcGISRuntime::Domain PopupManager::domain(Esri::ArcGISRuntime::PopupField *popupField) const

    Returns the Domain associated with a given PopupField if there is any.

    • popupField - The PopupField to get the Domain for.

    QString PopupManager::editSummary() const

    Returns the current edit summary.

    Note: Getter function for property editSummary.

    Esri::ArcGISRuntime::PopupAttributeListModel *PopupManager::editableFields() const

    Returns the editable fields as a PopupAttributeListModel.

    Note: Getter function for property editableFields.

    [signal] void PopupManager::editingCompleted(const Esri::ArcGISRuntime::Error &errors)

    Signal emitted when editing completes after finishEditing is called.

    • errors - The Error object.

    Esri::ArcGISRuntime::GeometryBuilder *PopupManager::editingGeometryBuilder() const

    Returns the GeometryBuilder used to edit the GeoElement's geometry.

    See also setEditingGeometryBuilder().

    [since Esri::ArcGISRuntime 200.2] QFuture<QList<Esri::ArcGISRuntime::PopupExpressionEvaluation *>> PopupManager::evaluateExpressionsAsync(QObject *parent = nullptr)

    Asynchronously evaluates all expressions, including Arcade FeatureSet functions available at PopupDefinition::expressions.

    • parent - The optional parent QObject

    This method must be called before displaying the popup information in a UI and after finishEditing so you can use the synchronous methods Esri::ArcGISRuntime::Popup::formattedValue, substitute(), and the customHtmlDescription property to get the formatted QString representation. If there are no PopupDefinition::expressions then result array will be empty.

    The PopupExpression may be used in the PopupDefinition::fields, PopupDefinition::media, PopupDefinition::title and PopupDefinition::description.

    This method returns a QFuture for the asynchronous operation. Use future.then() to continue processing when the operation completes. Use future.onFailed() to handle exceptions of type ErrorException.

    See Working with QFuture for further details.

    This function was introduced in Esri::ArcGISRuntime 200.2.

    [since Esri::ArcGISRuntime 100.14] QList<Esri::ArcGISRuntime::PopupElement *> PopupManager::evaluatedElements() const

    Returns a QList of PopupElement objects evaluated asynchronously by evaluateExpressionsAsync.

    During the evaluation, the ExpressionPopupElement are replaced by the PopupElement returned by the Arcade expression. If the Arcade expression returns a list of attributes to use by the pop-up element, these attributes will be used by formattedValue(PopupField) or fieldValue(PopupField).

    The QList is empty while evaluateExpressionsAsync has not been executed and is cleared if evaluateExpressionsAsync is executed more than once. After evaluation, the order of the PopupElement in the QList is the order that elements are in the PopupDefinition::elements and are shown in the pop-up window. If an ExpressionPopupElement is failed to be evaluated, it will be skipped in the QList. The error can be found in the list of PopupExpressionEvaluation returned from evaluateExpressionsAsync.

    This function was introduced in Esri::ArcGISRuntime 100.14.

    See also PopupDefinition::elements and evaluateExpressionsAsync.

    [signal] void PopupManager::featureTypeChanged()

    Signal emitted when isFeatureType changes.

    QList<Esri::ArcGISRuntime::FeatureType> PopupManager::featureTypes() const

    Returns a list of FeatureTypes or an empty list if the GeoElement is not an ArcGISFeature in an ArcGISFeatureTable.

    Esri::ArcGISRuntime::PopupField *PopupManager::fieldByName(const QString &fieldName) const

    Returns the PopupField for a given field name.

    • fieldName - The name of the field.

    This will return nullptr if there is no such field or if the GeoElement is not an ArcGISFeature with fields.

    [since Esri::ArcGISRuntime 100.3] QString PopupManager::fieldLabel(Esri::ArcGISRuntime::PopupField *popupField) const

    Returns a user-friendly display name for a given popup field.

    • popupField - The PopupField to get the label for.

    If the field is based on a PopupExpression, the title of the expression will be returned.

    This function was introduced in Esri::ArcGISRuntime 100.3.

    Esri::ArcGISRuntime::FieldType PopupManager::fieldType(Esri::ArcGISRuntime::PopupField *popupField) const

    Returns the field type for a given PopupField.

    • popupField - The PopupField to get the field type for.

    QVariant PopupManager::fieldValue(Esri::ArcGISRuntime::PopupField *popupField) const

    Returns the attribute value for a given Field.

    • popupField - The PopupField to get the attribute value for.

    If the field is part of a CodedValueDomain, the CodedValue::code is returned (unlike formattedValue(), which returns the CodedValue::name).

    [since Esri::ArcGISRuntime 100.14] QVariant PopupManager::fieldValue(const QString &fieldName, Esri::ArcGISRuntime::PopupElement *popupElement) const

    Returns the attribute value for the field specified by a name.

    • fieldName - The name of the field.
    • popupElement - The pop-up element to look up for the field. This argument is useful only if the pop-up element is coming from an Arcade expression evaluation that can return a list of attributes (see evaluatedElements).

    If any field is using expressions, use evaluateExpressionsAsync to evaluate the Arcade expressions before trying to get the fields' values. Otherwise, the values may not be evaluated properly.

    If any field is using expressions, use evaluateExpressions to evaluate the Arcade expressions before trying to get the fields' values. Otherwise, the values may not be evaluated properly.

    If the field is part of a CodedValueDomain, the CodedValue::code is returned (unlike formattedValue(PopupField), which returns the CodedValue::name).

    This function was introduced in Esri::ArcGISRuntime 100.14.

    [invokable] void PopupManager::finishEditing()

    Finishes the editing session.

    This runs asynchronously, and editingCompleted signal emit once the editing session has ended.

    Note: The PopupManager does not automatically call applyEdits on the associated GeoElement's ArcGISFeatureTable. To commit any edits to the source data, call applyEdits on the associated ArcGISFeatureTable.

    Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

    QString PopupManager::formattedValue(Esri::ArcGISRuntime::PopupField *popupField) const

    Returns a formatted String representation of the current popup field's value.

    • popupField - The popup field object.

    If PopupDefinition::expressions is not empty, the PopupField may be using expressions with Arcade FeatureSet functions. Use PopupManager::evaluateExpressionsAsync() to evaluate the Arcade expressions before trying to get the formatted string representation of the popup field's value, otherwise it may return an empty string.

    If the field is part of a CodedValueDomain, the CodedValue::name is returned.

    [signal, since Esri::ArcGISRuntime 100.14] void PopupManager::geoElementContingencyValidationErrorsChanged(const QMap<QString, Esri::ArcGISRuntime::Error> &errors)

    Signal emitted when the geoelement contingency validation errors change.

    • errors - The Error object.

    This function was introduced in Esri::ArcGISRuntime 100.14.

    [signal, since Esri::ArcGISRuntime 100.14] void PopupManager::geoElementContingencyValidationWarningsChanged(const QMap<QString, Esri::ArcGISRuntime::Error> &warnings)

    Signal emitted when the geoelement contingency validation warnings change.

    • warnings - The Error object.

    This function was introduced in Esri::ArcGISRuntime 100.14.

    [signal] void PopupManager::geoElementValidChanged()

    Signal emitted when isGeoElementValid changes.

    [signal, since Esri::ArcGISRuntime 100.14] void PopupManager::geoElementWarningsChanged(const QMap<QString, Esri::ArcGISRuntime::Error> &warnings)

    Signal emitted when the geoelement validation warnings change.

    • warnings - The Error object.

    This function was introduced in Esri::ArcGISRuntime 100.14.

    bool PopupManager::isDeleteAllowed() const

    Returns whether deleting the GeoElement is allowed.

    Note: Getter function for property deleteAllowed.

    bool PopupManager::isEditGeometryAllowed() const

    Returns whether geometry editing is allowed.

    Note: Getter function for property editGeometryAllowed.

    bool PopupManager::isEditing() const

    Returns whether or not currently in editing mode.

    Note: Getter function for property editing.

    bool PopupManager::isEditingAllowed() const

    Returns whether attribute editing is allowed.

    Note: Getter function for property editingAllowed.

    bool PopupManager::isFeatureType(Esri::ArcGISRuntime::PopupField *popupField) const

    Returns whether the specified popupField is a FeatureType field.

    [since Esri::ArcGISRuntime 100.14] bool PopupManager::isFieldInFieldGroup(Esri::ArcGISRuntime::PopupField *popupField) const

    Returns if the given PopupField is part of a FieldGroup as defined in a ContingentValuesDefinition.

    This function was introduced in Esri::ArcGISRuntime 100.14.

    bool PopupManager::isGeoElementValid() const

    Returns whether or not the GeoElement is in a valid state as far as the values it has set in its attributes and its geometry.

    Note: Getter function for property geoElementValid.

    bool PopupManager::isNullable(Esri::ArcGISRuntime::PopupField *popupField) const

    Returns whether or not a given PopupField allows null values.

    bool PopupManager::isShowAttachments() const

    Returns whether or not the pop-up UI should show the attachments.

    Takes into account the PopupDefinition::isShowAttachments and if the layer has attachments.

    Note: Getter function for property showAttachments.

    bool PopupManager::isShowCustomHtmlDescription() const

    Returns whether or not the pop-up UI should show the custom description HTML.

    Note: Getter function for property showCustomHtmlDescription.

    bool PopupManager::isShowEditSummary() const

    Returns whether or not the pop-up UI should show the edit info summary.

    Note: Getter function for property showEditSummary.

    bool PopupManager::isShowMedia() const

    Returns whether or not the pop-up UI should show the media.

    Note: Getter function for property showMedia.

    int PopupManager::maxLength(Esri::ArcGISRuntime::PopupField *popupField) const

    Returns the maximum allowed length of the specified PopupField.

    Returns the associated Popup object.

    If the geo-element associated with the popup implements Loadable it must be loaded for the PopupManager to work properly.

    QString PopupManager::rangeDomainValidationText(Esri::ArcGISRuntime::PopupField *popupField) const

    Returns a string that you can display in the UI for informing the user of the valid range for numeric input.

    • popupField - The PopupField to get the valid range text for.

    void PopupManager::setEditingGeometryBuilder(Esri::ArcGISRuntime::GeometryBuilder *builder)

    Sets the GeometryBuilder used to edit the GeoElement's geometry.

    See also editingGeometryBuilder().

    [invokable] bool PopupManager::startEditing()

    Initiates an editing session with the Popup.

    Returns true if editing was started successfully and false if editing is already started or not allowed.

    Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

    [invokable] QString PopupManager::substitute(const QString &templateString) const

    Substitutes attribute values for attribute place-holders in a given template string.

    • templateString - The template string containing attribute place-holders.

    If PopupDefinition::expressions is not empty, the input string may be using expressions with Arcade FeatureSet functions. Use PopupManager::evaluateExpressionsAsync() to evaluate the Arcade expressions before trying to get the substitute string, otherwise it may return an empty string.

    Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

    Esri::ArcGISRuntime::Symbol *PopupManager::symbol() const

    Returns symbol used by the popup's geo-element.

    QString PopupManager::title() const

    Returns the text to display as the popup title.

    Note: Getter function for property title.

    Esri::ArcGISRuntime::Error PopupManager::updateValue(const QVariant &newValue, Esri::ArcGISRuntime::PopupField *popupField)

    Updates the value of a field in the geo-element associated with the popup.

    This function expects you to pass at least the correct type of value for the field. The only exception to that is that you can pass a string for numeric fields and this function will do the work of converting it to the appropriate number type for the specified field. Returns an empty Error if the new value passes validation.

    Esri::ArcGISRuntime::Error PopupManager::updateValue(const Esri::ArcGISRuntime::FeatureTemplate &featureTemplate, Esri::ArcGISRuntime::FeatureTypeChangeMode changeMode)

    Updates the feature type of the geo-element associated with the popup to match those in the feature template, dependent on the change mode.

    • featureTemplate - The FeatureTemplate to use in updating the attributes.
    • changeMode - The feature type change mode to apply.

    If changeMode is ResetToDefaults, then all current values will be reset to the defaults specified in the FeatureTemplate. If KeepValues, current values will be kept unless they are not valid for the new feature type (for example, if a CodedValueDomain changes and the current value is not in the new domain).

    Esri::ArcGISRuntime::Error PopupManager::validationError(Esri::ArcGISRuntime::PopupField *popupField) const

    Returns the validation warning, if any, currently associated with a given PopupField.

    • popupField - The PopupField to get the validation warning for.

    When warning conditions occur, PopupManager still allows to update field values and finish edits. And no Error will be returned from validationError(), updateValue() and finishEditing.

    Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.