File indexing completed on 2024-04-28 11:40:06
0001 /* This file is part of the KDE libraries 0002 SPDX-FileCopyrightText: 2013 Chusslove Illich <caslav.ilic@gmx.net> 0003 0004 SPDX-License-Identifier: LGPL-2.0-or-later 0005 */ 0006 0007 #ifndef KUITSETUP_H 0008 #define KUITSETUP_H 0009 0010 #include <ki18n_export.h> 0011 0012 #include <QHash> 0013 #include <QString> 0014 #include <QStringList> 0015 #include <memory> 0016 0017 class KuitSetup; 0018 0019 /** 0020 * Global constants and functions related to KUIT markup. 0021 */ 0022 namespace Kuit 0023 { 0024 /** 0025 * Visual formats into which KUIT markup can be resolved. 0026 */ 0027 enum VisualFormat { 0028 /** 0029 * Visual format not defined. 0030 * This value can be explicitly set 0031 * (e.g. through \c KLocalizedString::withFormat) 0032 * to indicate that the format should be decided 0033 * by another mechanism (e.g. context UI marker). 0034 */ 0035 UndefinedFormat = 0, 0036 /** 0037 * Plain text. 0038 */ 0039 PlainText = 10, 0040 /** 0041 * Qt rich text (HTML subset). 0042 */ 0043 RichText = 20, 0044 /** 0045 * Terminal escape sequences. 0046 */ 0047 TermText = 30, 0048 }; 0049 0050 /** 0051 * Classification of KUIT tags. 0052 */ 0053 enum TagClass { 0054 /** 0055 * Tags wrapping text inserted into running text. 0056 */ 0057 PhraseTag = 0, 0058 /** 0059 * Tags splitting text into paragraph-level blocks. 0060 */ 0061 StructTag = 1, 0062 }; 0063 0064 /** 0065 * Functions accepted by tag formatting functions. 0066 * 0067 * \param languages the target languages (by decreasing priority) 0068 * \param tagName the wrapping tag name 0069 * \param attributes the attribute name-value pairs in the tag 0070 * \param text the wrapped text 0071 * \param tagPath the ordered list of ancestor tag names, parent first 0072 * \param format the target visual format 0073 * \return formatted text 0074 */ 0075 typedef QString (*TagFormatter)(const QStringList &languages, 0076 const QString &tagName, 0077 const QHash<QString, QString> &attributes, 0078 const QString &text, 0079 const QStringList &tagPath, 0080 Kuit::VisualFormat format); 0081 0082 /** 0083 * Get hold of the KUIT setup object for a given domain. 0084 * 0085 * \param domain the translation domain 0086 * \return pointer to KUIT setup object 0087 */ 0088 KI18N_EXPORT KuitSetup &setupForDomain(const char *domain); // KF6 TODO: remove, the QByteArray overload is enough 0089 0090 KI18N_EXPORT KuitSetup &setupForDomain(const QByteArray &domain); 0091 } 0092 0093 class KLocalizedString; 0094 class KuitSetupPrivate; 0095 class KuitFormatterPrivate; 0096 0097 /** 0098 * @class KuitSetup kuitsetup.h <KuitSetup> 0099 * 0100 * Class for modifying KUIT markup in a given domain. 0101 * 0102 * Not directly constructed, but obtained through \c Kuit::setupForDomain. 0103 */ 0104 class KI18N_EXPORT KuitSetup 0105 { 0106 friend KuitSetup &Kuit::setupForDomain(const QByteArray &domain); 0107 friend class KuitFormatterPrivate; 0108 0109 public: 0110 /** 0111 * Destructor. 0112 */ 0113 ~KuitSetup(); 0114 0115 /** 0116 * Set the formatting string for a tag with attributes combination. 0117 * 0118 * If a new tag name is given, this effectively defines a new tag. 0119 * The same holds for attribute names. 0120 * 0121 * The pattern string \p pattern should contain placeholders 0122 * for inserting the text and the attribute values. 0123 * %1 will be replaced with the wrapped text, and %2 and upwards 0124 * with attribute values in the order given by \p attrNames. 0125 * Non markup-aware translation call with context (\c ki18nc) 0126 * should be used to create the pattern string. 0127 * 0128 * In addition to the pattern, a formatting function 0129 * of the type \c TagFormatter can be given. 0130 * This function receives the full markup parsing context, 0131 * so that it can do whatever is necessary with the wrapped text. 0132 * The result of this function is then substituted into the pattern. 0133 * You can also give an empty pattern (as <tt>KLocalizedString()</tt>) 0134 * together with the formatting function, in which case the function 0135 * is assumed to do everything and no substitution is performed. 0136 * 0137 * \param tagName the name of the tag 0138 * \param attribNames the names of the attributes (empty names are ignored) 0139 * \param format the target visual format 0140 * \param pattern the pattern string 0141 * \param leadingNewlines the number of new lines (\\n) to be maintained 0142 * between any preceding text and the text wrapped 0143 * with this tag (for formats where it matters) 0144 */ 0145 void setTagPattern(const QString &tagName, 0146 const QStringList &attribNames, 0147 Kuit::VisualFormat format, 0148 const KLocalizedString &pattern, 0149 Kuit::TagFormatter formatter = nullptr, 0150 int leadingNewlines = 0); 0151 0152 /** 0153 * Set the KUIT class of the tag. 0154 * 0155 * \param tagName the name of the tag 0156 * \param aClass the KUIT tag class 0157 */ 0158 void setTagClass(const QString &tagName, Kuit::TagClass aClass); 0159 0160 /** 0161 * Set the default visual format for a given UI marker. 0162 * 0163 * Giving <tt>"@<major>"</tt> for \p marker means to set the format 0164 * only for standalone <tt>\@\<major\></tt> marker, 0165 * while <tt>"@<major>:"</tt> (with trailing colon) means to set 0166 * the same format for all <tt>\@\<major\>:\<minor\></tt> combinations. 0167 * 0168 * Defined UI marker major/minor combinations are listed in the section 0169 * \ref uimark_ctxt. If an UI marker combination outside of the defined 0170 * is given as \p marker, it will be ignored. 0171 * 0172 * Setting \c Kuit::UndefinedFormat as \p format 0173 * means to fall back to default format for the given UI marker. 0174 * 0175 * \param marker the UI marker 0176 * \param format the visual format 0177 */ 0178 void setFormatForMarker(const QString &marker, Kuit::VisualFormat format); 0179 0180 private: 0181 KI18N_NO_EXPORT explicit KuitSetup(const QByteArray &domain); 0182 Q_DISABLE_COPY(KuitSetup) 0183 0184 std::unique_ptr<KuitSetupPrivate> const d; 0185 }; 0186 0187 #endif // KUITSETUP_H