KWidgetsAddons

kcharselect.h
1 /*
2  This file is part of the KDE libraries
3  SPDX-FileCopyrightText: 1999 Reginald Stadlbauer <[email protected]>
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 
16 class 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 <[email protected]>
58  * @author Daniel Laidig <[email protected]>
59  */
60 class 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(QVector<uint> displayedCodePoints READ displayedCodePoints)
68  Q_PROPERTY(bool allPlanesEnabled READ allPlanesEnabled WRITE setAllPlanesEnabled DESIGNABLE true)
69 
70 public:
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  QVector<uint> displayedCodePoints() const;
208 
209 public 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 
236 Q_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 
274 private:
275  void initWidget(const Controls, QObject *);
276 
277 private:
278  std::unique_ptr<class KCharSelectPrivate> const d;
279 };
280 
281 Q_DECLARE_OPERATORS_FOR_FLAGS(KCharSelect::Controls)
282 
283 #endif
Control
Flags to set the shown widgets.
Definition: kcharselect.h:75
Q_PROPERTY(...)
Character selection widget.
Definition: kcharselect.h:60
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Thu Jul 29 2021 22:44:32 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.