1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
/* ============================================================
 *
 * This file is a part of digiKam project
 * https://www.digikam.org
 *
 * Date        : 2010-06-02
 * Description : class that holds list of applied filters to image
 *
 * SPDX-FileCopyrightText: 2010 by Marcel Wiesweg <marcel dot wiesweg at gmx dot de>
 * SPDX-FileCopyrightText: 2010 by Martin Klapetek <martin dot klapetek at gmail dot com>
 *
 * SPDX-License-Identifier: GPL-2.0-or-later
 *
 * ============================================================ */

#pragma once

// Qt includes

#include <QFlags>
#include <QHash>
#include <QString>
#include <QVariant>

// Local includes

#include "digikam_export.h"

namespace Digikam
{

class DIGIKAM_EXPORT FilterAction
{
public:

    enum Category
    {
        /**
         * @note Do not change existing values, they are written to XML in files!
         */

        /**
         * When given the set of stored parameters and the original data,
         *  an identical result will be produced.
         */
        ReproducibleFilter = 0,

        /**
         * The operation is documented and a number of parameters may be known,
         * but the identical result cannot be reproduced.
         * It may be possible to produce a sufficiently similar result.
         */
        ComplexFilter      = 1,

        /**
         * The source images are known, a textual description may be added,
         * but there is no way to automatically replay
         */
        DocumentedHistory  = 2,

        CategoryFirst      = ReproducibleFilter,
        CategoryLast       = DocumentedHistory
    };

    enum Flag
    {
        /**
         * The editing step of this filter action explicitly branches from the parent.
         * This is an optional hint that the result is meant as a new version.
         */
        ExplicitBranch     = 1 << 0
    };
    Q_DECLARE_FLAGS(Flags, Flag)

public:

    FilterAction() = default;
    FilterAction(const QString& identifier, int version, Category category = ReproducibleFilter);

    bool isNull()                                                   const;

    bool operator==(const FilterAction& other)                      const;

    Category category()                                             const;

    /**
     * Returns a technical identifier for the filter used to produce this action.
     * Can include a namespace. Example: digikam:charcoal
     */
    QString  identifier()                                           const;<--- Function 'identifier()' should return member 'm_identifier' by const reference.

    /**
     * Returns the version (>= 1) of the filter used to produce this action.
     * When a filter / tool is found by the identifier, it can decide
     * by the version if it supports this action and which parameters it expects.
     */
    int      version()                                              const;

    /**
     * Returns a description / comment for this action.
     * In the case of DocumentedHistory, this may be the most useful value.
     */
    QString  description()                                          const;<--- Function 'description()' should return member 'm_description' by const reference.
    void     setDescription(const QString& description);

    QString  displayableName()                                      const;<--- Function 'displayableName()' should return member 'm_displayableName' by const reference.
    void     setDisplayableName(const QString& displayableName);

    Flags flags()                                                   const;
    void  setFlags(Flags flags);
    void  addFlag(Flags flags);
    void  removeFlag(Flags flags);

    /**
     * Access parameters.
     * A parameters is a key -> value pair.
     * Keys need to be unique.
     */
    bool                           hasParameters()                  const;
    const QHash<QString,QVariant>& parameters()                     const;
    QHash<QString, QVariant>&      parameters();

    bool                           hasParameter(const QString& key) const;
    const QVariant                 parameter(const QString& key)    const;
    QVariant&                      parameter(const QString& key);

    /**
     * Returns parameter converted from QVariant to given type
     */
    template <typename T>
    T parameter(const QString& key)                                 const
    {
        return parameter(key).value<T>();
    }

    /**
     * Read parameter with a default value:
     * If there is a parameter for the given key, return it converted
     *  from QVariant to the template type.
     * If there is no parameter, return the given default value.
     */
    template <typename T>
    T parameter(const QString& key, const T& defaultValue)          const
    {
        QVariant var = parameter(key);
        return (
                (var.isValid()) ? var.value<T>()
                                : defaultValue
               );
    }

    /// Sets parameter, removing all other values for the same key
    void addParameter(const QString& key, const QVariant& value);

    /// Removes all parameters for key
    void removeParameters(const QString& key);

    /// Clear all parameters
    void clearParameters();

    /// Replaces parameters
    void setParameters(const QHash<QString, QVariant>& params);

protected:

    /// @note Value class, do not create a d-pointer
    Category                 m_category         = ReproducibleFilter;
    Flags                    m_flags;
    QString                  m_identifier;
    int                      m_version          = 0;
    QString                  m_description;
    QString                  m_displayableName;
    QHash<QString, QVariant> m_params;
};

} // namespace Digikam

Q_DECLARE_METATYPE(Digikam::FilterAction)
Q_DECLARE_OPERATORS_FOR_FLAGS(Digikam::FilterAction::Flags)