KI18n

kuitmarkup.h
1 /* This file is part of the KDE libraries
2  SPDX-FileCopyrightText: 2013 Chusslove Illich <[email protected]>
3 
4  SPDX-License-Identifier: LGPL-2.0-or-later
5 */
6 
7 #ifndef KUITMARKUP_H
8 #define KUITMARKUP_H
9 
10 #include <ki18n_export.h>
11 
12 #include <QHash>
13 #include <QString>
14 #include <QStringList>
15 #include <memory>
16 
17 class KuitSetup;
18 
19 /**
20  * Global constants and functions related to KUIT markup.
21  */
22 namespace Kuit
23 {
24 /**
25  * Visual formats into which KUIT markup can be resolved.
26  */
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  */
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  */
53 enum 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  */
75 typedef 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  */
88 KI18N_EXPORT KuitSetup &setupForDomain(const char *domain); // KF6 TODO: remove, the QByteArray overload is enough
89 
90 KI18N_EXPORT KuitSetup &setupForDomain(const QByteArray &domain);
91 }
92 
93 class KLocalizedString;
94 class KuitSetupPrivate;
95 class KuitFormatterPrivate;
96 
97 /**
98  * @class KuitSetup kuitmarkup.h <KuitSetup>
99  *
100  * Class for modifying KUIT markup in a given domain.
101  *
102  * Not directly constructed, but obtained through \c Kuit::setupForDomain.
103  */
104 class KI18N_EXPORT KuitSetup
105 {
106  friend KuitSetup &Kuit::setupForDomain(const QByteArray &domain);
107  friend class KuitFormatterPrivate;
108 
109 public:
110  /**
111  * Destructor.
112  */
113  ~KuitSetup();
114 
115  /**
116  * Set the formatting string for a tag with attributes combination.
117  *
118  * If a new tag name is given, this effectively defines a new tag.
119  * The same holds for attribute names.
120  *
121  * The pattern string \p pattern should contain placeholders
122  * for inserting the text and the attribute values.
123  * %1 will be replaced with the wrapped text, and %2 and upwards
124  * with attribute values in the order given by \p attrNames.
125  * Non markup-aware translation call with context (\c ki18nc)
126  * should be used to create the pattern string.
127  *
128  * In addition to the pattern, a formatting function
129  * of the type \c TagFormatter can be given.
130  * This function receives the full markup parsing context,
131  * so that it can do whatever is necessary with the wrapped text.
132  * The result of this function is then substituted into the pattern.
133  * You can also give an empty pattern (as <tt>KLocalizedString()</tt>)
134  * together with the formatting function, in which case the function
135  * is assumed to do everything and no substitution is performed.
136  *
137  * \param tagName the name of the tag
138  * \param attribNames the names of the attributes (empty names are ignored)
139  * \param format the target visual format
140  * \param pattern the pattern string
141  * \param leadingNewlines the number of new lines (\\n) to be maintained
142  * between any preceding text and the text wrapped
143  * with this tag (for formats where it matters)
144  */
145  void setTagPattern(const QString &tagName,
146  const QStringList &attribNames,
147  Kuit::VisualFormat format,
148  const KLocalizedString &pattern,
149  Kuit::TagFormatter formatter = nullptr,
150  int leadingNewlines = 0);
151 
152  /**
153  * Set the KUIT class of the tag.
154  *
155  * \param tagName the name of the tag
156  * \param aClass the KUIT tag class
157  */
158  void setTagClass(const QString &tagName, Kuit::TagClass aClass);
159 
160  /**
161  * Set the default visual format for a given UI marker.
162  *
163  * Giving <tt>"@<major>"</tt> for \p marker means to set the format
164  * only for standalone <tt>\@<major></tt> marker,
165  * while <tt>"@<major>:"</tt> (with trailing colon) means to set
166  * the same format for all <tt>\@<major>:<minor></tt> combinations.
167  *
168  * Defined UI marker major/minor combinations are listed in the section
169  * \ref uimark_ctxt. If an UI marker combination outside of the defined
170  * is given as \p marker, it will be ignored.
171  *
172  * Setting \c Kuit::UndefinedFormat as \p format
173  * means to fall back to default format for the given UI marker.
174  *
175  * \param marker the UI marker
176  * \param format the visual format
177  */
178  void setFormatForMarker(const QString &marker, Kuit::VisualFormat format);
179 
180 private:
181  KuitSetup(const QByteArray &domain);
182  Q_DISABLE_COPY(KuitSetup)
183 
184  std::unique_ptr<KuitSetupPrivate> const d;
185 };
186 
187 #endif // KUITMARKUP_H
@ RichText
Qt rich text (HTML subset).
Definition: kuitmarkup.h:43
Class for producing and handling localized messages.
KI18N_EXPORT KuitSetup & setupForDomain(const char *domain)
Get hold of the KUIT setup object for a given domain.
Definition: kuitmarkup.cpp:518
@ UndefinedFormat
Visual format not defined.
Definition: kuitmarkup.h:35
QString(* TagFormatter)(const QStringList &languages, const QString &tagName, const QHash< QString, QString > &attributes, const QString &text, const QStringList &tagPath, Kuit::VisualFormat format)
Functions accepted by tag formatting functions.
Definition: kuitmarkup.h:75
VisualFormat
Visual formats into which KUIT markup can be resolved.
Definition: kuitmarkup.h:27
Global constants and functions related to KUIT markup.
Definition: kuitmarkup.cpp:113
@ PhraseTag
Tags wrapping text inserted into running text.
Definition: kuitmarkup.h:57
@ StructTag
Tags splitting text into paragraph-level blocks.
Definition: kuitmarkup.h:61
@ TermText
Terminal escape sequences.
Definition: kuitmarkup.h:47
@ PlainText
Plain text.
Definition: kuitmarkup.h:39
TagClass
Classification of KUIT tags.
Definition: kuitmarkup.h:53
This file is part of the KDE documentation.
Documentation copyright © 1996-2022 The KDE developers.
Generated on Tue Aug 16 2022 04:07:13 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.