File indexing completed on 2023-10-01 08:25:21

0001 /* This file is part of the KDE project
0002    Copyright (C) 2018 Jarosław Staniek <staniek@kde.org>
0003    Copyright (C) 2018 Dmitry Baryshev <dmitrymq@gmail.com>
0004 
0005    This library is free software; you can redistribute it and/or
0006    modify it under the terms of the GNU Library General Public
0007    License as published by the Free Software Foundation; either
0008    version 2 of the License, or (at your option) any later version.
0009 
0010    This library is distributed in the hope that it will be useful,
0011    but WITHOUT ANY WARRANTY; without even the implied warranty of
0012    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
0013    Library General Public License for more details.
0014 
0015    You should have received a copy of the GNU Library General Public License
0016    along with this library; see the file COPYING.LIB.  If not, write to
0017    the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
0018  * Boston, MA 02110-1301, USA.
0019 */
0020 
0021 #ifndef KPROPERTYCOMPOSEDURL_H
0022 #define KPROPERTYCOMPOSEDURL_H
0023 
0024 #include "kpropertycore_export.h"
0025 
0026 #include <QDebug>
0027 #include <QMetaType>
0028 #include <QUrl>
0029 
0030 /**
0031  * @brief A data structure that composes absolute and relative URLs.
0032  *
0033  * @since 3.2
0034  */
0035 class KPROPERTYCORE_EXPORT KPropertyComposedUrl
0036 {
0037 public:
0038     /**
0039      * Constructs empty and invalid composed URL
0040      */
0041     KPropertyComposedUrl();
0042 
0043     /**
0044      * Constructs composed URL with specified base URL and path relative to the base URL
0045      *
0046      * @a baseUrl must be a valid absolute URL, otherwise the entire composed URL is invalid.
0047      * @a relativePath must be proper relative path. It is not important if it points to existing
0048      *    filesystem object.
0049      */
0050     KPropertyComposedUrl(const QUrl &baseUrl, const QString &relativePath = QString());
0051 
0052     /**
0053      * Constructs composed URL with specified base URL and independent absolute URL
0054      *
0055      * @a baseUrl must be absolute or empty URL, otherwise the entire composed URL is invalid.
0056      * @a absoluteUrl must be absolute URL. It is not important if it points to existing filesystem
0057      * object.
0058      *
0059      * Because @a absoluteUrl carries all needed information, @a baseUrl is ignored in this variant
0060      * of constructor. However @a baseUrl is still remembered and will be used if this object's
0061      * value will be changed to relative path using setRelativePath().
0062      */
0063     KPropertyComposedUrl(const QUrl &baseUrl, const QUrl &absoluteUrl);
0064 
0065     /**
0066      *  Constructs a copy of @a other
0067      */
0068     KPropertyComposedUrl(const KPropertyComposedUrl &other);
0069 
0070     ~KPropertyComposedUrl();
0071 
0072     /**
0073      *  Assigns @a other to this KPropertyComposedUrl
0074      */
0075     KPropertyComposedUrl &operator=(const KPropertyComposedUrl &other);
0076 
0077     /**
0078      * Return @c true if this KPropertyComposedUrl equals to @a other
0079      *
0080      * Two KPropertyComposedUrl objects are equal if they have the same values.
0081      * @see value()
0082      */
0083     bool operator==(const KPropertyComposedUrl &other) const;
0084 
0085     /**
0086      * Return @c true if this KPropertyComposedUrl does not equal to @a other
0087      */
0088     bool operator!=(const KPropertyComposedUrl &other) const { return !operator==(other); }
0089 
0090     /**
0091      * Returns URL value computed from base URL, absolute URL and relative path, whichever is
0092      * defined.
0093      *
0094      * - If the KPropertyComposedUrl is invalid, empty QUrl is returned
0095      * - If absolute path is present, it is returned
0096      * - If base URL and relative path are present, URL with added relative path is returned
0097      */
0098     QUrl value() const;
0099 
0100     /**
0101      * Returns the base URL (absolute) or empty URL if there is no absolute base URL specified
0102      */
0103     QUrl baseUrl() const;
0104 
0105     /**
0106      * Sets base URL (absolute)
0107      *
0108      * If @a baseUrl is not valid and absolute, base URL is cleared.
0109      * In any case relative path (relativePath()) and absolute URL (absoluteUrl()) are not modified.
0110      */
0111     void setBaseUrl(const QUrl &url);
0112 
0113     /**
0114      * Returns absolute URL that has been set for this object
0115      *
0116      * Empty URL is returned if absolute URL is not specified. In this case relative path can still
0117      * be present. If absolute URL is present, relative path is empty.
0118      */
0119     QUrl absoluteUrl() const;
0120 
0121     /**
0122      * Sets a new absolute URL
0123      *
0124      * If @a absoluteUrl is not valid and absolute, it is cleared.
0125      * If @a absoluteUrl is absolute, relative path (relativePath()) is cleared.
0126      */
0127     void setAbsoluteUrl(const QUrl &absoluteUrl);
0128 
0129     /**
0130      * Returns relative path that has been set for this object
0131      *
0132      * Empty string is returned if there is no path assigned. Non-empty path can be used to
0133      * calculate value by concatenating it with the base URL. If relativePath() is present
0134      * absoluteUrl() is empty .
0135      */
0136     QString relativePath() const;
0137 
0138     /**
0139      * Sets a new relative path for this object
0140      *
0141      * If @a relativePath is not a valid or empty path, it is cleared.
0142      * If @a relativePath is empty or valid, absolute URL is cleared.
0143      */
0144     void setRelativePath(const QString &relativePath);
0145 
0146     /**
0147      * Return @c true if the URL value that can be computed (from base URL, absolute URL and
0148      * relative path) is valid
0149      *
0150      * @see value() for description of how value is computed.
0151      */
0152     bool isValid() const;
0153 
0154 private:
0155     class Private;
0156     Private *const d;
0157 };
0158 
0159 Q_DECLARE_METATYPE(KPropertyComposedUrl)
0160 
0161 //! qDebug() stream operator. Writes KPropertyComposedUrl to the debug output.
0162 KPROPERTYCORE_EXPORT QDebug operator<<(QDebug dbg, const KPropertyComposedUrl &p);
0163 
0164 #endif // KPROPERTYCOMPOSEDURL_H