File: kcharselect.h

package info (click to toggle)
kwidgetsaddons 5.28.0-3
  • links: PTS, VCS
  • area: main
  • in suites: stretch
  • size: 62,388 kB
  • ctags: 3,611
  • sloc: cpp: 26,647; python: 682; sh: 23; makefile: 6
file content (311 lines) | stat: -rw-r--r-- 10,201 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
/* This file is part of the KDE libraries

   Copyright (C) 1999 Reginald Stadlbauer <reggie@kde.org>

   This library is free software; you can redistribute it and/or
   modify it under the terms of the GNU Library General Public
   License as published by the Free Software Foundation; either
   version 2 of the License, or (at your option) any later version.

   This library is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
   Library General Public License for more details.

   You should have received a copy of the GNU Library General Public License
   along with this library; see the file COPYING.LIB.  If not, write to
   the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
   Boston, MA 02110-1301, USA.
*/

#ifndef kcharselect_h
#define kcharselect_h

#include <QtCore/QString>
#include <QtCore/QStringList>
#include <QWidget>
#include <kwidgetsaddons_export.h>

class QFont;
class QUrl;

/**
 * @short Character selection widget
 *
 * This widget allows the user to select a character of a
 * specified font and to browse Unicode information
 *
 * \image html kcharselect.png "Character Selection Widget"
 *
 * You can specify the font whose characters should be displayed via
 * setCurrentFont(). Using the Controls argument in the contructor
 * you can create a compact version of KCharSelect if there is not enough
 * space and if you don't need all features.
 *
 * KCharSelect displays one Unicode block at a time and provides
 * categorized access to them. Unicode character names and further details,
 * including cross references, are displayed. Additionally, there is a search
 * to find characters.
 *
 * By default, KCharSelect is restricted to Basic Multilingual Plane (BMP)
 * characters that QChar supports, i.e. characters with code points that
 * fit into a quint16 (U+0000..U+FFFF). API methods that have a QChar
 * argument can only be used for this default mode:
 *
 * To get the current selected character, use the currentChar()
 * method. You can set the character which should be displayed with
 * setCurrentChar().
 *
 * If you want the user to select and search characters from all planes,
 * i.e. characters U+0000..U+10FFFF, use setAllPlanesEnabled(true)
 * and use the @c uint based methods currentCodePoint() and
 * setCurrentCodePoint() instead.
 *
 * Since QString does not allow @c uint code points, you either must
 * use QString::fromUcs4() and QString::ToUcs4() to convert between
 * strings and code points, or manually do the surrogate pair handling
 * using QChar::requiresSurrogates() and friends.
 *
 * @author Reginald Stadlbauer <reggie@kde.org>
 * @author Daniel Laidig <d.laidig@gmx.de>
 */

class KWIDGETSADDONS_EXPORT KCharSelect : public QWidget
{
    Q_OBJECT
    Q_PROPERTY(QFont currentFont READ currentFont WRITE setCurrentFont)
    Q_PROPERTY(QChar currentChar READ currentChar WRITE setCurrentChar)
    Q_PROPERTY(uint currentCodePoint READ currentCodePoint WRITE setCurrentCodePoint NOTIFY currentCodePointChanged)
    Q_PROPERTY(QList<QChar> displayedChars READ displayedChars)
    Q_PROPERTY(QVector<uint> displayedCodePoints READ displayedCodePoints)
    Q_PROPERTY(bool allPlanesEnabled READ allPlanesEnabled WRITE setAllPlanesEnabled DESIGNABLE true)

public:
    /**
     * Flags to set the shown widgets
     */
    enum Control {
        /**
         * Shows the search widgets
         */
        SearchLine = 0x01,
        /**
         * Shows the font combo box
         */
        FontCombo = 0x02,
        /**
         * Shows the font size spin box
         */
        FontSize = 0x04,
        /**
         * Shows the category/block selection combo boxes
         */
        BlockCombos = 0x08,
        /**
         * Shows the actual table
         */
        CharacterTable = 0x10,
        /**
         * Shows the detail browser
         */
        DetailBrowser = 0x20,
        /**
         * Shows the Back/Forward buttons
         */
        HistoryButtons = 0x40,
        /**
         * Shows everything
         */
        AllGuiElements      = 65535
    };
    Q_DECLARE_FLAGS(Controls,
                    Control)

    /**
     * Constructor. @p controls can be used to show a custom set of widgets.
     *
     * @param parent     the parent widget for this KCharSelect (see QWidget documentation)
     * @param controls   selects the visible controls on the KCharSelect widget
     *
     * @since 4.2
     */
    explicit KCharSelect(
        QWidget *parent,
        const Controls controls = AllGuiElements);

    /**
     * Constructor. @p controls can be used to show a custom set of widgets.
     *
     * The widget uses the following actions:
     *   - KStandardActions::find() (edit_find)
     *   - KStandardActions::back() (go_back)
     *   - KStandardActions::forward() (go_forward)
     *
     * If you provide a KActionCollection, this will be populated with the above actions,
     * which you can then manually trigger or place in menus and toolbars.
     *
     * @param parent     the parent widget for this KCharSelect (see QWidget documentation)
     * @param actionParent if this is not @c null, KCharSelect will place its actions into this
     *                     collection
     * @param controls   selects the visible controls on the KCharSelect widget
     *
     * @since 4.2
     */
    explicit KCharSelect(
        QWidget *parent,
        QObject *actionParent,
        const Controls controls = AllGuiElements);

    ~KCharSelect();

    /**
     * Reimplemented.
     */
    QSize sizeHint() const Q_DECL_OVERRIDE;

    /**
     * Sets the allowed Unicode code planes. If @p all is @c false, then
     * only characters from the Basic Multilingual Plane (BMP) can be
     * selected, otherwise characters from all planes are allowed.
     *
     * For compatibility reasons, the default is @c false.
     *
     * If you enable support for all planes, you must use the functions
     * handling @c uint code points instead of @c QChar characters.
     * @since 5.25
     */
    void setAllPlanesEnabled(bool all);

    /**
     * @returns @c true, if characters from all Unicode code planes
     * can be selected.
     * @since 5.25
     */
    bool allPlanesEnabled() const;

    /**
     * Returns the currently selected character. If characters outside the
     * Basic Multilingual Plane (BMP) can be selected, use currentCodePoint
     * instead.
     * @sa currentCodePoint
     */
    QChar currentChar() const;

    /**
     * Returns the Unicode code point of the currently selected character.
     * @warning If you enabled support for all Unicode planes, you must use
     * QChar::requiresSurrogates() to check if the code point requires
     * conversion to a UTF-16 surrogate pair before converting it to QString.
     * You cannot convert a code point to a QChar.
     * @since 5.25
     */
    uint currentCodePoint() const;

    /**
     * Returns the currently displayed font.
     */
    QFont currentFont() const;

    /**
     * Returns a list of currently displayed characters. If characters outside the
     * Basic Multilingual Plane (BMP) can be selected, use displayedCodePoints
     * instead.
     * Warning: this method can be a bit slow
     * @sa displayedCodePoints
     */
    QList<QChar> displayedChars() const;

    /**
     * Returns a list of Unicode code points of the currently displayed characters.
     * @since 5.25
     */
    QVector<uint> displayedCodePoints() const;

public Q_SLOTS:
    /**
     * Highlights the character @p c. If the character is not displayed, the block is changed.
     *
     * @param c the character to highlight
     */
    void setCurrentChar(const QChar &c);

    /**
     * Highlights the character with the specified @p codePoint. If the character is
     * outside the Basic Multilingual Plane (BMP), then you must enable support
     * for all planes for this to work.
     *
     * @param codePoint the Unicode code point of the character to highlight
     *
     * @sa allPlanesEnabled
     * @since 5.25
     */
    void setCurrentCodePoint(uint codePoint);

    /**
     * Sets the font which is displayed to @p font
     *
     * @param font the display font for the widget
     */
    void setCurrentFont(const QFont &font);

Q_SIGNALS:
    /**
     * A new font is selected or the font size changed.
     *
     * @param font the new font
     */
    void currentFontChanged(const QFont &font);
    /**
     * The current character is changed.
     *
     * @param c the new character
     */
    void currentCharChanged(const QChar &c);
    /**
     * The current character is changed.
     *
     * @param codePoint the Unicode code point of the new character
     * @since 5.25
     */
    void currentCodePointChanged(uint codePoint);
    /**
     * The currently displayed characters are changed (search results or block).
     */
    void displayedCharsChanged();
    /**
     * A character is selected to be inserted somewhere.
     *
     * @param c the selected character
     */
    void charSelected(const QChar &c);
    /**
     * A character is selected to be inserted somewhere.
     *
     * @param codePoint the Unicode code point of the selected character
     * @since 5.25
     */
    void codePointSelected(uint codePoint);

private:
    Q_PRIVATE_SLOT(d, void _k_activateSearchLine())
    Q_PRIVATE_SLOT(d, void _k_back())
    Q_PRIVATE_SLOT(d, void _k_forward())
    Q_PRIVATE_SLOT(d, void _k_fontSelected())
    Q_PRIVATE_SLOT(d, void _k_charSelected(uint c))
    Q_PRIVATE_SLOT(d, void _k_updateCurrentChar(uint c))
    Q_PRIVATE_SLOT(d, void _k_slotUpdateUnicode(uint c))
    Q_PRIVATE_SLOT(d, void _k_sectionSelected(int index))
    Q_PRIVATE_SLOT(d, void _k_blockSelected(int index))
    Q_PRIVATE_SLOT(d, void _k_searchEditChanged())
    Q_PRIVATE_SLOT(d, void _k_search())
    Q_PRIVATE_SLOT(d, void _k_linkClicked(QUrl))

    class KCharSelectPrivate;
    KCharSelectPrivate *const d;

    void initWidget(const Controls, QObject *);
};

Q_DECLARE_OPERATORS_FOR_FLAGS(KCharSelect::Controls)

#endif