File indexing completed on 2024-03-24 04:01:22
0001 /* 0002 * SPDX-FileCopyrightText: 2007-2009 Petri Damstén <damu@iki.fi> 0003 * SPDX-FileCopyrightText: 2014 John Layt <jlayt@kde.org> 0004 * 0005 * SPDX-License-Identifier: LGPL-2.0-or-later 0006 */ 0007 0008 #ifndef KUNITCONVERSION_UNITCATEGORY_H 0009 #define KUNITCONVERSION_UNITCATEGORY_H 0010 0011 #include "kunitconversion/kunitconversion_export.h" 0012 #include "unit.h" 0013 #include "value.h" 0014 0015 #include <QExplicitlySharedDataPointer> 0016 #include <QObject> 0017 #include <QString> 0018 #include <QStringList> 0019 0020 #include <chrono> 0021 0022 class QNetworkReply; 0023 0024 namespace KUnitConversion 0025 { 0026 class UnitCategoryPrivate; 0027 class UpdateJob; 0028 0029 /** 0030 * @short Class to define a category of units of measurement 0031 * 0032 * This is a class to define a category of units of measurement. 0033 * 0034 * @see Converter, Unit, Value 0035 * 0036 * @author Petri Damstén <damu@iki.fi> 0037 * @author John Layt <jlayt@kde.org> 0038 */ 0039 0040 class KUNITCONVERSION_EXPORT UnitCategory 0041 { 0042 public: 0043 /** 0044 * Null constructor 0045 **/ 0046 UnitCategory(); 0047 0048 /** 0049 * Copy constructor, copy @p other to this. 0050 **/ 0051 UnitCategory(const UnitCategory &other); 0052 0053 ~UnitCategory(); 0054 0055 /** 0056 * Assignment operator, assign @p other to this. 0057 **/ 0058 UnitCategory &operator=(const UnitCategory &other); 0059 0060 /** 0061 * Move-assigns @p other to this UnitCategory instance, transferring the 0062 * ownership of the managed pointer to this instance. 0063 **/ 0064 UnitCategory &operator=(UnitCategory &&other); 0065 0066 /** 0067 * @return @c true if this UnitCategory is equal to the @p other UnitCategory. 0068 **/ 0069 bool operator==(const UnitCategory &other) const; 0070 0071 /** 0072 * @return @c true if this UnitCategory is not equal to the @p other UnitCategory. 0073 **/ 0074 bool operator!=(const UnitCategory &other) const; 0075 0076 /** 0077 * @return returns true if this UnitCategory is null 0078 **/ 0079 bool isNull() const; 0080 0081 /** 0082 * @return category id. 0083 **/ 0084 CategoryId id() const; 0085 0086 /** 0087 * Returns name for the unit category. 0088 * 0089 * @return Translated name for category. 0090 **/ 0091 QString name() const; 0092 0093 /** 0094 * @return unit category description 0095 **/ 0096 QString description() const; 0097 0098 /** 0099 * Returns default unit. 0100 * 0101 * @return default unit. 0102 **/ 0103 Unit defaultUnit() const; 0104 0105 /** 0106 * Check if unit category has a unit. 0107 * 0108 * @return True if unit is found 0109 **/ 0110 bool hasUnit(const QString &unit) const; 0111 0112 /** 0113 * Return unit for string. 0114 * 0115 * @return Pointer to unit class. 0116 **/ 0117 Unit unit(const QString &s) const; 0118 0119 /** 0120 * Return unit for unit enum. 0121 * 0122 * @return Pointer to unit class. 0123 **/ 0124 Unit unit(UnitId unitId) const; 0125 0126 /** 0127 * Return units in this category. 0128 * 0129 * @return list of units. 0130 **/ 0131 QList<Unit> units() const; 0132 0133 /** 0134 * Return most common units in this category. 0135 * 0136 * @return list of units. 0137 **/ 0138 QList<Unit> mostCommonUnits() const; 0139 0140 /** 0141 * Return all unit names, short names and unit synonyms in this category. 0142 * 0143 * @return list of units. 0144 **/ 0145 QStringList allUnits() const; 0146 0147 /** 0148 * Convert value to another unit selected by string. 0149 * 0150 * @param value value to convert 0151 * @param toUnit unit to convert to. If empty default unit is used. 0152 * @return converted value 0153 **/ 0154 Value convert(const Value &value, const QString &toUnit = QString()) const; 0155 0156 /** 0157 * Convert value to another unit selected by enum. 0158 * 0159 * @param value value to convert 0160 * @param toUnit unit to convert to. 0161 * @return converted value 0162 **/ 0163 Value convert(const Value &value, UnitId toUnit) const; 0164 0165 /** 0166 * Convert value to another unit. 0167 * 0168 * @param value value to convert 0169 * @param toUnit unit to be used for conversion 0170 * @return converted value 0171 **/ 0172 Value convert(const Value &value, const Unit &toUnit) const; 0173 0174 /** 0175 * @return true if category has conversion table that needs to be updated via online access, otherwise false 0176 * @see syncConversionTable() 0177 */ 0178 bool hasOnlineConversionTable() const; 0179 0180 /** 0181 * Request an update of the online conversion table when it is older than @p updateSkipPeriod. 0182 * 0183 * Returned jobs are automatically deleted, ie. it is safe to ignore the return value if you 0184 * do not care about being notified about the completion (or failure) of the update process. 0185 * Calling this method while another update is already in progress will not trigger another update 0186 * but instead allows you to watch the already ongoing update. 0187 * Performing conversions before the update has completed will return results based on the old 0188 * conversion table, if available. 0189 * 0190 * @note This method must be called from the main thread! 0191 * 0192 * @returns an UpdateJob if an update is necessary or already running, @c nullptr otherwise. 0193 * @see UpdateJob 0194 * @since 6.0 0195 */ 0196 UpdateJob* syncConversionTable(std::chrono::seconds updateSkipPeriod = std::chrono::hours(24)); 0197 0198 private: 0199 friend class Unit; 0200 friend class UnitCategoryPrivate; 0201 0202 KUNITCONVERSION_NO_EXPORT explicit UnitCategory(UnitCategoryPrivate *dd); 0203 0204 protected: 0205 QExplicitlySharedDataPointer<UnitCategoryPrivate> d; 0206 }; 0207 0208 0209 /** 0210 * Dynamic conversion data update job. 0211 * Created via the factory methods in KUnitConversion::Updater, useful for 0212 * getting notified about an update having completed. 0213 * Update jobs are automatically deleted on completion, but it is also save to delete 0214 * instances manually. 0215 * 0216 * @see UnitCategory 0217 * @since 6.0 0218 */ 0219 class KUNITCONVERSION_EXPORT UpdateJob : public QObject 0220 { 0221 Q_OBJECT 0222 public: 0223 ~UpdateJob(); 0224 0225 Q_SIGNALS: 0226 void finished(); 0227 0228 private: 0229 friend class UnitCategoryPrivate; 0230 explicit UpdateJob(QNetworkReply *dd); 0231 QNetworkReply *d; 0232 }; 0233 0234 } // KUnitConversion namespace 0235 0236 Q_DECLARE_TYPEINFO(KUnitConversion::UnitCategory, Q_RELOCATABLE_TYPE); 0237 0238 #endif