1/*
2 This file is part of the KDE libraries
3 SPDX-FileCopyrightText: 1999 Reginald Stadlbauer <reggie@kde.org>
4
5 SPDX-License-Identifier: LGPL-2.0-or-later
6*/
7
8#ifndef kcharselect_h
9#define kcharselect_h
10
11#include <QString>
12#include <QWidget>
13#include <kwidgetsaddons_export.h>
14#include <memory>
15
16class QFont;
17
18/*!
19 * \class KCharSelect
20 * \inmodule KWidgetsAddons
21 *
22 * \brief Character selection widget.
23 *
24 * This widget allows the user to select a character of a
25 * specified font and to browse Unicode information
26 *
27 * \image kcharselect.png "KCharSelect Widget"
28 *
29 * You can specify the font whose characters should be displayed via
30 * setCurrentFont(). Using the Controls argument in the constructor
31 * you can create a compact version of KCharSelect if there is not enough
32 * space and if you don't need all features.
33 *
34 * KCharSelect displays one Unicode block at a time and provides
35 * categorized access to them. Unicode character names and further details,
36 * including cross references, are displayed. Additionally, there is a search
37 * to find characters.
38 *
39 * By default, KCharSelect is restricted to Basic Multilingual Plane (BMP)
40 * characters that QChar supports, i.e. characters with code points that
41 * fit into a quint16 (U+0000..U+FFFF). API methods that have a QChar
42 * argument can only be used for this default mode:
43 *
44 * To get the current selected character, use the currentChar()
45 * method. You can set the character which should be displayed with
46 * setCurrentChar().
47 *
48 * If you want the user to select and search characters from all planes,
49 * i.e. characters U+0000..U+10FFFF, use setAllPlanesEnabled(true)
50 * and use the \c uint based methods currentCodePoint() and
51 * setCurrentCodePoint() instead.
52 *
53 * Since QString does not allow \c uint code points, you either must
54 * use QString::fromUcs4() and QString::ToUcs4() to convert between
55 * strings and code points, or manually do the surrogate pair handling
56 * using QChar::requiresSurrogates() and friends.
57 */
58class KWIDGETSADDONS_EXPORT KCharSelect : public QWidget
59{
60 Q_OBJECT
61
62 /*!
63 * \property KCharSelect::currentFont
64 */
65 Q_PROPERTY(QFont currentFont READ currentFont WRITE setCurrentFont)
66
67 /*!
68 * \property KCharSelect::currentChar
69 */
70 Q_PROPERTY(QChar currentChar READ currentChar WRITE setCurrentChar)
71
72 /*!
73 * \property KCharSelect::currentCodePoint
74 */
75 Q_PROPERTY(uint currentCodePoint READ currentCodePoint WRITE setCurrentCodePoint NOTIFY currentCodePointChanged)
76
77 /*!
78 * \property KCharSelect::displayedChars
79 */
80 Q_PROPERTY(QList<QChar> displayedChars READ displayedChars)
81
82 /*!
83 * \property KCharSelect::displayedCodePoints
84 */
85 Q_PROPERTY(QList<uint> displayedCodePoints READ displayedCodePoints)
86
87 /*!
88 * \property KCharSelect::allPlanesEnabled
89 */
90 Q_PROPERTY(bool allPlanesEnabled READ allPlanesEnabled WRITE setAllPlanesEnabled DESIGNABLE true)
91
92public:
93 /*!
94 * Flags to set the shown widgets
95 *
96 * \value SearchLine Shows the search widgets
97 * \value FontCombo Shows the font combo box
98 * \value FontSize Shows the font size spin box
99 * \value BlockCombos Shows the category/block selection combo boxes
100 * \value CharacterTable Shows the actual table
101 * \value DetailBrowser Shows the detail browser
102 * \value HistoryButtons Shows the Back/Forward buttons
103 * \value AllGuiElements Shows everything
104 */
105 enum Control {
106 SearchLine = 0x01,
107 FontCombo = 0x02,
108 FontSize = 0x04,
109 BlockCombos = 0x08,
110 CharacterTable = 0x10,
111 DetailBrowser = 0x20,
112 HistoryButtons = 0x40,
113 AllGuiElements = 65535,
114 };
115 Q_DECLARE_FLAGS(Controls, Control)
116
117 /*!
118 * Constructor. \a controls can be used to show a custom set of widgets.
119 *
120 * \a parent the parent widget for this KCharSelect (see QWidget documentation)
121 *
122 * \a controls selects the visible controls on the KCharSelect widget
123 *
124 * \since 4.2
125 */
126 explicit KCharSelect(QWidget *parent, const Controls controls = AllGuiElements);
127
128 /*!
129 * Constructor. \a controls can be used to show a custom set of widgets.
130 *
131 * The widget uses the following actions:
132 * \list
133 * \li KStandardActions::find() (edit_find)
134 * \li KStandardActions::back() (go_back)
135 * \li KStandardActions::forward() (go_forward)
136 * \endlist
137 *
138 * If you provide a KActionCollection, this will be populated with the above actions,
139 * which you can then manually trigger or place in menus and toolbars.
140 *
141 * \a parent the parent widget for this KCharSelect (see QWidget documentation)
142 *
143 * \a actionParent if this is not \c null, KCharSelect will place its actions into this
144 * collection
145 *
146 * \a controls selects the visible controls on the KCharSelect widget
147 *
148 * \since 4.2
149 */
150 explicit KCharSelect(QWidget *parent, QObject *actionParent, const Controls controls = AllGuiElements);
151
152 ~KCharSelect() override;
153
154 QSize sizeHint() const override;
155
156 /*!
157 * Sets the allowed Unicode code planes. If \a all is \c false, then
158 * only characters from the Basic Multilingual Plane (BMP) can be
159 * selected, otherwise characters from all planes are allowed.
160 *
161 * For compatibility reasons, the default is \c false.
162 *
163 * If you enable support for all planes, you must use the functions
164 * handling \c uint code points instead of QChar characters.
165 *
166 * \since 5.25
167 */
168 void setAllPlanesEnabled(bool all);
169
170 /*!
171 * Returns \c true, if characters from all Unicode code planes
172 * can be selected.
173 *
174 * \since 5.25
175 */
176 bool allPlanesEnabled() const;
177
178 /*!
179 * Returns the currently selected character. If characters outside the
180 * Basic Multilingual Plane (BMP) can be selected, use currentCodePoint
181 * instead.
182 * \sa currentCodePoint
183 */
184 QChar currentChar() const;
185
186 /*!
187 * Returns the Unicode code point of the currently selected character.
188 *
189 * \warning If you enabled support for all Unicode planes, you must use
190 * QChar::requiresSurrogates() to check if the code point requires
191 * conversion to a UTF-16 surrogate pair before converting it to QString.
192 * You cannot convert a code point to a QChar.
193 * \since 5.25
194 */
195 uint currentCodePoint() const;
196
197 /*!
198 * Returns the currently displayed font.
199 */
200 QFont currentFont() const;
201
202 /*!
203 * Returns a list of currently displayed characters. If characters outside the
204 * Basic Multilingual Plane (BMP) can be selected, use displayedCodePoints
205 * instead.
206 *
207 * Warning: this method can be a bit slow
208 * \sa displayedCodePoints
209 */
210 QList<QChar> displayedChars() const;
211
212 /*!
213 * Returns a list of Unicode code points of the currently displayed characters.
214 * \since 5.25
215 */
216 QList<uint> displayedCodePoints() const;
217
218public Q_SLOTS:
219 /*!
220 * Highlights the character \a c. If the character is not displayed, the block is changed.
221 *
222 * \a c the character to highlight
223 */
224 void setCurrentChar(const QChar &c);
225
226 /*!
227 * Highlights the character with the specified \a codePoint. If the character is
228 * outside the Basic Multilingual Plane (BMP), then you must enable support
229 * for all planes for this to work.
230 *
231 * \a codePoint the Unicode code point of the character to highlight
232 *
233 * \sa allPlanesEnabled
234 * \since 5.25
235 */
236 void setCurrentCodePoint(uint codePoint);
237
238 /*!
239 * Sets the font which is displayed to \a font
240 *
241 * \a font the display font for the widget
242 */
243 void setCurrentFont(const QFont &font);
244
245Q_SIGNALS:
246 /*!
247 * A new font is selected or the font size changed.
248 *
249 * \a font the new font
250 */
251 void currentFontChanged(const QFont &font);
252 /*!
253 * The current character is changed.
254 *
255 * \a c the new character
256 */
257 void currentCharChanged(const QChar &c);
258 /*!
259 * The current character is changed.
260 *
261 * \a codePoint the Unicode code point of the new character
262 * \since 5.25
263 */
264 void currentCodePointChanged(uint codePoint);
265 /*!
266 * The currently displayed characters are changed (search results or block).
267 */
268 void displayedCharsChanged();
269 /*!
270 * A character is selected to be inserted somewhere.
271 *
272 * \a c the selected character
273 */
274 void charSelected(const QChar &c);
275 /*!
276 * A character is selected to be inserted somewhere.
277 *
278 * \a codePoint the Unicode code point of the selected character
279 * \since 5.25
280 */
281 void codePointSelected(uint codePoint);
282
283private:
284 KWIDGETSADDONS_NO_EXPORT void initWidget(const Controls, QObject *);
285
286private:
287 std::unique_ptr<class KCharSelectPrivate> const d;
288};
289
290Q_DECLARE_OPERATORS_FOR_FLAGS(KCharSelect::Controls)
291
292#endif
293

source code of kwidgetsaddons/src/kcharselect.h