File indexing completed on 2024-04-28 07:43:05
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 QByteArray &domain); 0089 } 0090 0091 class KLocalizedString; 0092 class KuitSetupPrivate; 0093 class KuitFormatterPrivate; 0094 0095 /** 0096 * @class KuitSetup kuitsetup.h <KuitSetup> 0097 * 0098 * Class for modifying KUIT markup in a given domain. 0099 * 0100 * Not directly constructed, but obtained through \c Kuit::setupForDomain. 0101 */ 0102 class KI18N_EXPORT KuitSetup 0103 { 0104 friend KuitSetup &Kuit::setupForDomain(const QByteArray &domain); 0105 friend class KuitFormatterPrivate; 0106 0107 public: 0108 /** 0109 * Destructor. 0110 */ 0111 ~KuitSetup(); 0112 0113 /** 0114 * Set the formatting string for a tag with attributes combination. 0115 * 0116 * If a new tag name is given, this effectively defines a new tag. 0117 * The same holds for attribute names. 0118 * 0119 * The pattern string \p pattern should contain placeholders 0120 * for inserting the text and the attribute values. 0121 * %1 will be replaced with the wrapped text, and %2 and upwards 0122 * with attribute values in the order given by \p attrNames. 0123 * Non markup-aware translation call with context (\c ki18nc) 0124 * should be used to create the pattern string. 0125 * 0126 * In addition to the pattern, a formatting function 0127 * of the type \c TagFormatter can be given. 0128 * This function receives the full markup parsing context, 0129 * so that it can do whatever is necessary with the wrapped text. 0130 * The result of this function is then substituted into the pattern. 0131 * You can also give an empty pattern (as <tt>KLocalizedString()</tt>) 0132 * together with the formatting function, in which case the function 0133 * is assumed to do everything and no substitution is performed. 0134 * 0135 * \param tagName the name of the tag 0136 * \param attribNames the names of the attributes (empty names are ignored) 0137 * \param format the target visual format 0138 * \param pattern the pattern string 0139 * \param leadingNewlines the number of new lines (\\n) to be maintained 0140 * between any preceding text and the text wrapped 0141 * with this tag (for formats where it matters) 0142 */ 0143 void setTagPattern(const QString &tagName, 0144 const QStringList &attribNames, 0145 Kuit::VisualFormat format, 0146 const KLocalizedString &pattern, 0147 Kuit::TagFormatter formatter = nullptr, 0148 int leadingNewlines = 0); 0149 0150 /** 0151 * Set the KUIT class of the tag. 0152 * 0153 * \param tagName the name of the tag 0154 * \param aClass the KUIT tag class 0155 */ 0156 void setTagClass(const QString &tagName, Kuit::TagClass aClass); 0157 0158 /** 0159 * Set the default visual format for a given UI marker. 0160 * 0161 * Giving <tt>"@<major>"</tt> for \p marker means to set the format 0162 * only for standalone <tt>\@\<major\></tt> marker, 0163 * while <tt>"@<major>:"</tt> (with trailing colon) means to set 0164 * the same format for all <tt>\@\<major\>:\<minor\></tt> combinations. 0165 * 0166 * Defined UI marker major/minor combinations are listed in the section 0167 * \ref uimark_ctxt. If an UI marker combination outside of the defined 0168 * is given as \p marker, it will be ignored. 0169 * 0170 * Setting \c Kuit::UndefinedFormat as \p format 0171 * means to fall back to default format for the given UI marker. 0172 * 0173 * \param marker the UI marker 0174 * \param format the visual format 0175 */ 0176 void setFormatForMarker(const QString &marker, Kuit::VisualFormat format); 0177 0178 private: 0179 KI18N_NO_EXPORT explicit KuitSetup(const QByteArray &domain); 0180 Q_DISABLE_COPY(KuitSetup) 0181 0182 std::unique_ptr<KuitSetupPrivate> const d; 0183 }; 0184 0185 #endif // KUITSETUP_H