File indexing completed on 2025-02-02 14:19:57
0001 /* 0002 This file is part of the KDE libraries 0003 SPDX-FileCopyrightText: 1999 Reginald Stadlbauer <reggie@kde.org> 0004 0005 SPDX-License-Identifier: LGPL-2.0-or-later 0006 */ 0007 0008 #ifndef kcharselect_h 0009 #define kcharselect_h 0010 0011 #include <QString> 0012 #include <QWidget> 0013 #include <kwidgetsaddons_export.h> 0014 #include <memory> 0015 0016 class QFont; 0017 0018 /** 0019 * @class KCharSelect kcharselect.h KCharSelect 0020 * 0021 * @short Character selection widget 0022 * 0023 * This widget allows the user to select a character of a 0024 * specified font and to browse Unicode information 0025 * 0026 * \image html kcharselect.png "KCharSelect Widget" 0027 * 0028 * You can specify the font whose characters should be displayed via 0029 * setCurrentFont(). Using the Controls argument in the constructor 0030 * you can create a compact version of KCharSelect if there is not enough 0031 * space and if you don't need all features. 0032 * 0033 * KCharSelect displays one Unicode block at a time and provides 0034 * categorized access to them. Unicode character names and further details, 0035 * including cross references, are displayed. Additionally, there is a search 0036 * to find characters. 0037 * 0038 * By default, KCharSelect is restricted to Basic Multilingual Plane (BMP) 0039 * characters that QChar supports, i.e. characters with code points that 0040 * fit into a quint16 (U+0000..U+FFFF). API methods that have a QChar 0041 * argument can only be used for this default mode: 0042 * 0043 * To get the current selected character, use the currentChar() 0044 * method. You can set the character which should be displayed with 0045 * setCurrentChar(). 0046 * 0047 * If you want the user to select and search characters from all planes, 0048 * i.e. characters U+0000..U+10FFFF, use setAllPlanesEnabled(true) 0049 * and use the @c uint based methods currentCodePoint() and 0050 * setCurrentCodePoint() instead. 0051 * 0052 * Since QString does not allow @c uint code points, you either must 0053 * use QString::fromUcs4() and QString::ToUcs4() to convert between 0054 * strings and code points, or manually do the surrogate pair handling 0055 * using QChar::requiresSurrogates() and friends. 0056 * 0057 * @author Reginald Stadlbauer <reggie@kde.org> 0058 * @author Daniel Laidig <d.laidig@gmx.de> 0059 */ 0060 class KWIDGETSADDONS_EXPORT KCharSelect : public QWidget 0061 { 0062 Q_OBJECT 0063 Q_PROPERTY(QFont currentFont READ currentFont WRITE setCurrentFont) 0064 Q_PROPERTY(QChar currentChar READ currentChar WRITE setCurrentChar) 0065 Q_PROPERTY(uint currentCodePoint READ currentCodePoint WRITE setCurrentCodePoint NOTIFY currentCodePointChanged) 0066 Q_PROPERTY(QList<QChar> displayedChars READ displayedChars) 0067 Q_PROPERTY(QVector<uint> displayedCodePoints READ displayedCodePoints) 0068 Q_PROPERTY(bool allPlanesEnabled READ allPlanesEnabled WRITE setAllPlanesEnabled DESIGNABLE true) 0069 0070 public: 0071 /** 0072 * Flags to set the shown widgets 0073 * @see Controls 0074 */ 0075 enum Control { 0076 /** 0077 * Shows the search widgets 0078 */ 0079 SearchLine = 0x01, 0080 /** 0081 * Shows the font combo box 0082 */ 0083 FontCombo = 0x02, 0084 /** 0085 * Shows the font size spin box 0086 */ 0087 FontSize = 0x04, 0088 /** 0089 * Shows the category/block selection combo boxes 0090 */ 0091 BlockCombos = 0x08, 0092 /** 0093 * Shows the actual table 0094 */ 0095 CharacterTable = 0x10, 0096 /** 0097 * Shows the detail browser 0098 */ 0099 DetailBrowser = 0x20, 0100 /** 0101 * Shows the Back/Forward buttons 0102 */ 0103 HistoryButtons = 0x40, 0104 /** 0105 * Shows everything 0106 */ 0107 AllGuiElements = 65535, 0108 }; 0109 /** 0110 * Stores a combination of #Control values. 0111 */ 0112 Q_DECLARE_FLAGS(Controls, Control) 0113 0114 /** 0115 * Constructor. @p controls can be used to show a custom set of widgets. 0116 * 0117 * @param parent the parent widget for this KCharSelect (see QWidget documentation) 0118 * @param controls selects the visible controls on the KCharSelect widget 0119 * 0120 * @since 4.2 0121 */ 0122 explicit KCharSelect(QWidget *parent, const Controls controls = AllGuiElements); 0123 0124 /** 0125 * Constructor. @p controls can be used to show a custom set of widgets. 0126 * 0127 * The widget uses the following actions: 0128 * - KStandardActions::find() (edit_find) 0129 * - KStandardActions::back() (go_back) 0130 * - KStandardActions::forward() (go_forward) 0131 * 0132 * If you provide a KActionCollection, this will be populated with the above actions, 0133 * which you can then manually trigger or place in menus and toolbars. 0134 * 0135 * @param parent the parent widget for this KCharSelect (see QWidget documentation) 0136 * @param actionParent if this is not @c null, KCharSelect will place its actions into this 0137 * collection 0138 * @param controls selects the visible controls on the KCharSelect widget 0139 * 0140 * @since 4.2 0141 */ 0142 explicit KCharSelect(QWidget *parent, QObject *actionParent, const Controls controls = AllGuiElements); 0143 0144 ~KCharSelect() override; 0145 0146 /** 0147 * Reimplemented. 0148 */ 0149 QSize sizeHint() const override; 0150 0151 /** 0152 * Sets the allowed Unicode code planes. If @p all is @c false, then 0153 * only characters from the Basic Multilingual Plane (BMP) can be 0154 * selected, otherwise characters from all planes are allowed. 0155 * 0156 * For compatibility reasons, the default is @c false. 0157 * 0158 * If you enable support for all planes, you must use the functions 0159 * handling @c uint code points instead of @c QChar characters. 0160 * @since 5.25 0161 */ 0162 void setAllPlanesEnabled(bool all); 0163 0164 /** 0165 * @returns @c true, if characters from all Unicode code planes 0166 * can be selected. 0167 * @since 5.25 0168 */ 0169 bool allPlanesEnabled() const; 0170 0171 /** 0172 * Returns the currently selected character. If characters outside the 0173 * Basic Multilingual Plane (BMP) can be selected, use currentCodePoint 0174 * instead. 0175 * @sa currentCodePoint 0176 */ 0177 QChar currentChar() const; 0178 0179 /** 0180 * Returns the Unicode code point of the currently selected character. 0181 * @warning If you enabled support for all Unicode planes, you must use 0182 * QChar::requiresSurrogates() to check if the code point requires 0183 * conversion to a UTF-16 surrogate pair before converting it to QString. 0184 * You cannot convert a code point to a QChar. 0185 * @since 5.25 0186 */ 0187 uint currentCodePoint() const; 0188 0189 /** 0190 * Returns the currently displayed font. 0191 */ 0192 QFont currentFont() const; 0193 0194 /** 0195 * Returns a list of currently displayed characters. If characters outside the 0196 * Basic Multilingual Plane (BMP) can be selected, use displayedCodePoints 0197 * instead. 0198 * Warning: this method can be a bit slow 0199 * @sa displayedCodePoints 0200 */ 0201 QList<QChar> displayedChars() const; 0202 0203 /** 0204 * Returns a list of Unicode code points of the currently displayed characters. 0205 * @since 5.25 0206 */ 0207 QVector<uint> displayedCodePoints() const; 0208 0209 public Q_SLOTS: 0210 /** 0211 * Highlights the character @p c. If the character is not displayed, the block is changed. 0212 * 0213 * @param c the character to highlight 0214 */ 0215 void setCurrentChar(const QChar &c); 0216 0217 /** 0218 * Highlights the character with the specified @p codePoint. If the character is 0219 * outside the Basic Multilingual Plane (BMP), then you must enable support 0220 * for all planes for this to work. 0221 * 0222 * @param codePoint the Unicode code point of the character to highlight 0223 * 0224 * @sa allPlanesEnabled 0225 * @since 5.25 0226 */ 0227 void setCurrentCodePoint(uint codePoint); 0228 0229 /** 0230 * Sets the font which is displayed to @p font 0231 * 0232 * @param font the display font for the widget 0233 */ 0234 void setCurrentFont(const QFont &font); 0235 0236 Q_SIGNALS: 0237 /** 0238 * A new font is selected or the font size changed. 0239 * 0240 * @param font the new font 0241 */ 0242 void currentFontChanged(const QFont &font); 0243 /** 0244 * The current character is changed. 0245 * 0246 * @param c the new character 0247 */ 0248 void currentCharChanged(const QChar &c); 0249 /** 0250 * The current character is changed. 0251 * 0252 * @param codePoint the Unicode code point of the new character 0253 * @since 5.25 0254 */ 0255 void currentCodePointChanged(uint codePoint); 0256 /** 0257 * The currently displayed characters are changed (search results or block). 0258 */ 0259 void displayedCharsChanged(); 0260 /** 0261 * A character is selected to be inserted somewhere. 0262 * 0263 * @param c the selected character 0264 */ 0265 void charSelected(const QChar &c); 0266 /** 0267 * A character is selected to be inserted somewhere. 0268 * 0269 * @param codePoint the Unicode code point of the selected character 0270 * @since 5.25 0271 */ 0272 void codePointSelected(uint codePoint); 0273 0274 private: 0275 KWIDGETSADDONS_NO_EXPORT void initWidget(const Controls, QObject *); 0276 0277 private: 0278 std::unique_ptr<class KCharSelectPrivate> const d; 0279 }; 0280 0281 Q_DECLARE_OPERATORS_FOR_FLAGS(KCharSelect::Controls) 0282 0283 #endif