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

source code of kwidgetsaddons/src/kcharselect.h