1/* This file is part of the KDE libraries
2 SPDX-FileCopyrightText: 2013 Chusslove Illich <caslav.ilic@gmx.net>
3
4 SPDX-License-Identifier: LGPL-2.0-or-later
5*/
6
7#ifndef KUITSETUP_H
8#define KUITSETUP_H
9
10#include <ki18n_export.h>
11
12#include <QHash>
13#include <QString>
14#include <QStringList>
15#include <memory>
16
17class KuitSetup;
18
19/**
20 * Global constants and functions related to KUIT markup.
21 */
22namespace Kuit
23{
24/**
25 * Visual formats into which KUIT markup can be resolved.
26 */
27enum VisualFormat {
28 /**
29 * Visual format not defined.
30 * This value can be explicitly set
31 * (e.g. through \c KLocalizedString::withFormat)
32 * to indicate that the format should be decided
33 * by another mechanism (e.g. context UI marker).
34 */
35 UndefinedFormat = 0,
36 /**
37 * Plain text.
38 */
39 PlainText = 10,
40 /**
41 * Qt rich text (HTML subset).
42 */
43 RichText = 20,
44 /**
45 * Terminal escape sequences.
46 */
47 TermText = 30,
48};
49
50/**
51 * Classification of KUIT tags.
52 */
53enum TagClass {
54 /**
55 * Tags wrapping text inserted into running text.
56 */
57 PhraseTag = 0,
58 /**
59 * Tags splitting text into paragraph-level blocks.
60 */
61 StructTag = 1,
62};
63
64/**
65 * Functions accepted by tag formatting functions.
66 *
67 * \param languages the target languages (by decreasing priority)
68 * \param tagName the wrapping tag name
69 * \param attributes the attribute name-value pairs in the tag
70 * \param text the wrapped text
71 * \param tagPath the ordered list of ancestor tag names, parent first
72 * \param format the target visual format
73 * \return formatted text
74 */
75typedef QString (*TagFormatter)(const QStringList &languages,
76 const QString &tagName,
77 const QHash<QString, QString> &attributes,
78 const QString &text,
79 const QStringList &tagPath,
80 Kuit::VisualFormat format);
81
82/**
83 * Get hold of the KUIT setup object for a given domain.
84 *
85 * \param domain the translation domain
86 * \return pointer to KUIT setup object
87 */
88KI18N_EXPORT KuitSetup &setupForDomain(const QByteArray &domain);
89}
90
91class KLocalizedString;
92class KuitSetupPrivate;
93class KuitFormatterPrivate;
94
95/**
96 * @class KuitSetup kuitsetup.h <KuitSetup>
97 *
98 * Class for modifying KUIT markup in a given domain.
99 *
100 * Not directly constructed, but obtained through \c Kuit::setupForDomain.
101 */
102class KI18N_EXPORT KuitSetup
103{
104 friend KuitSetup &Kuit::setupForDomain(const QByteArray &domain);
105 friend class KuitFormatterPrivate;
106
107public:
108 /**
109 * Destructor.
110 */
111 ~KuitSetup();
112
113 /**
114 * Set the formatting string for a tag with attributes combination.
115 *
116 * If a new tag name is given, this effectively defines a new tag.
117 * The same holds for attribute names.
118 *
119 * The pattern string \p pattern should contain placeholders
120 * for inserting the text and the attribute values.
121 * %1 will be replaced with the wrapped text, and %2 and upwards
122 * with attribute values in the order given by \p attrNames.
123 * Non markup-aware translation call with context (\c ki18nc)
124 * should be used to create the pattern string.
125 *
126 * In addition to the pattern, a formatting function
127 * of the type \c TagFormatter can be given.
128 * This function receives the full markup parsing context,
129 * so that it can do whatever is necessary with the wrapped text.
130 * The result of this function is then substituted into the pattern.
131 * You can also give an empty pattern (as <tt>KLocalizedString()</tt>)
132 * together with the formatting function, in which case the function
133 * is assumed to do everything and no substitution is performed.
134 *
135 * \param tagName the name of the tag
136 * \param attribNames the names of the attributes (empty names are ignored)
137 * \param format the target visual format
138 * \param pattern the pattern string
139 * \param leadingNewlines the number of new lines (\\n) to be maintained
140 * between any preceding text and the text wrapped
141 * with this tag (for formats where it matters)
142 */
143 void setTagPattern(const QString &tagName,
144 const QStringList &attribNames,
145 Kuit::VisualFormat format,
146 const KLocalizedString &pattern,
147 Kuit::TagFormatter formatter = nullptr,
148 int leadingNewlines = 0);
149
150 /**
151 * Set the KUIT class of the tag.
152 *
153 * \param tagName the name of the tag
154 * \param aClass the KUIT tag class
155 */
156 void setTagClass(const QString &tagName, Kuit::TagClass aClass);
157
158 /**
159 * Set the default visual format for a given UI marker.
160 *
161 * Giving <tt>"@<major>"</tt> for \p marker means to set the format
162 * only for standalone <tt>\@\<major\></tt> marker,
163 * while <tt>"@<major>:"</tt> (with trailing colon) means to set
164 * the same format for all <tt>\@\<major\>:\<minor\></tt> combinations.
165 *
166 * Defined UI marker major/minor combinations are listed in the section
167 * \ref uimark_ctxt. If an UI marker combination outside of the defined
168 * is given as \p marker, it will be ignored.
169 *
170 * Setting \c Kuit::UndefinedFormat as \p format
171 * means to fall back to default format for the given UI marker.
172 *
173 * \param marker the UI marker
174 * \param format the visual format
175 */
176 void setFormatForMarker(const QString &marker, Kuit::VisualFormat format);
177
178private:
179 KI18N_NO_EXPORT explicit KuitSetup(const QByteArray &domain);
180 Q_DISABLE_COPY(KuitSetup)
181
182 std::unique_ptr<KuitSetupPrivate> const d;
183};
184
185#endif // KUITSETUP_H
186

source code of ki18n/src/i18n/kuitsetup.h