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

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