1/* This file is part of the KDE libraries
2
3 Copyright (C) 1999 Reginald Stadlbauer <reggie@kde.org>
4
5 This library is free software; you can redistribute it and/or
6 modify it under the terms of the GNU Library General Public
7 License as published by the Free Software Foundation; either
8 version 2 of the License, or (at your option) any later version.
9
10 This library is distributed in the hope that it will be useful,
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 Library General Public License for more details.
14
15 You should have received a copy of the GNU Library General Public License
16 along with this library; see the file COPYING.LIB. If not, write to
17 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
18 Boston, MA 02110-1301, USA.
19*/
20
21#ifndef kcharselect_h
22#define kcharselect_h
23
24#include <QtCore/QString>
25#include <QtCore/QStringList>
26#include <QtGui/QWidget>
27#include <kglobal.h>
28#include <kdeui_export.h>
29
30class KActionCollection;
31
32class QFont;
33class QUrl;
34
35/**
36 * @short Character selection widget
37 *
38 * This widget allows the user to select a character of a
39 * specified font and to browse Unicode information
40 *
41 * \image html kcharselect.png "Character Selection Widget"
42 *
43 * You can specify the font whose characters should be displayed via
44 * setCurrentFont(). Using the Controls argument in the contructor
45 * you can create a compact version of KCharSelect if there is not enough
46 * space and if you don't need all features.
47 *
48 * KCharSelect displays one Unicode block at a time and provides
49 * categorized access to them. Unicode character names and further details,
50 * including cross references, are displayed. Additionally, there is a search
51 * to find characters.
52 *
53 * To get the current selected character, use the currentChar()
54 * method. You can set the character which should be displayed with
55 * setCurrentChar().
56 *
57 * @author Reginald Stadlbauer <reggie@kde.org>
58 * @author Daniel Laidig <d.laidig@gmx.de>
59 */
60
61class KDEUI_EXPORT KCharSelect : public QWidget
62{
63 Q_OBJECT
64 Q_PROPERTY(QFont currentFont READ currentFont WRITE setCurrentFont)
65 Q_PROPERTY(QChar currentChar READ currentChar WRITE setCurrentChar)
66 Q_PROPERTY(QList<QChar> displayedChars READ displayedChars)
67
68public:
69 /**
70 * Flags to set the shown widgets
71 */
72 enum Control {
73 /**
74 * Shows the search widgets
75 */
76 SearchLine = 0x01,
77 /**
78 * Shows the font combo box
79 */
80 FontCombo = 0x02,
81 /**
82 * Shows the font size spin box
83 */
84 FontSize = 0x04,
85 /**
86 * Shows the category/block selection combo boxes
87 */
88 BlockCombos = 0x08,
89 /**
90 * Shows the actual table
91 */
92 CharacterTable = 0x10,
93 /**
94 * Shows the detail browser
95 */
96 DetailBrowser = 0x20,
97 /**
98 * Shows the Back/Forward buttons
99 */
100 HistoryButtons = 0x40,
101 /**
102 * Shows everything
103 */
104 AllGuiElements = 65535
105 };
106 Q_DECLARE_FLAGS(Controls,
107 Control)
108
109 /** @deprecated */
110#ifndef KDE_NO_DEPRECATED
111 KDE_CONSTRUCTOR_DEPRECATED explicit KCharSelect(
112 QWidget *parent,
113 const Controls controls = AllGuiElements);
114#endif
115
116 /**
117 * Constructor. @p controls can be used to show a custom set of widgets.
118 *
119 * The widget uses the following actions:
120 * - KStandardActions::find() (edit_find)
121 * - KStandardActions::back() (go_back)
122 * - KStandardActions::forward() (go_forward)
123 *
124 * If you provide a KActionCollection, this will be populated with the above actions,
125 * which you can then manually trigger or place in menus and toolbars.
126 *
127 * @param parent the parent widget for this KCharSelect (see QWidget documentation)
128 * @param collection if this is not @c null, KCharSelect will place its actions into this
129 * collection
130 * @param controls selects the visible controls on the KCharSelect widget
131 *
132 * @since 4.2
133 */
134 explicit KCharSelect(
135 QWidget *parent,
136 KActionCollection *collection,
137 const Controls controls = AllGuiElements);
138
139 ~KCharSelect();
140
141 /**
142 * Reimplemented.
143 */
144 virtual QSize sizeHint() const;
145
146 /**
147 * Returns the currently selected character.
148 */
149 QChar currentChar() const;
150
151 /**
152 * Returns the currently displayed font.
153 */
154 QFont currentFont() const;
155
156 /**
157 * Returns a list of currently displayed characters.
158 */
159 QList<QChar> displayedChars() const;
160
161public Q_SLOTS:
162 /**
163 * Highlights the character @p c. If the character is not displayed, the block is changed.
164 *
165 * @param c the character to highlight
166 */
167 void setCurrentChar(const QChar &c);
168
169 /**
170 * Sets the font which is displayed to @p font
171 *
172 * @param font the display font for the widget
173 */
174 void setCurrentFont(const QFont &font);
175
176Q_SIGNALS:
177 /**
178 * A new font is selected or the font size changed.
179 *
180 * @param font the new font
181 */
182 void currentFontChanged(const QFont &font);
183 /**
184 * The current character is changed.
185 *
186 * @param c the new character
187 */
188 void currentCharChanged(const QChar &c);
189 /**
190 * The currently displayed characters are changed (search results or block).
191 */
192 void displayedCharsChanged();
193 /**
194 * A character is selected to be inserted somewhere.
195 *
196 * @param c the selected character
197 */
198 void charSelected(const QChar &c);
199
200private:
201 Q_PRIVATE_SLOT(d, void _k_activateSearchLine())
202 Q_PRIVATE_SLOT(d, void _k_back())
203 Q_PRIVATE_SLOT(d, void _k_forward())
204 Q_PRIVATE_SLOT(d, void _k_fontSelected())
205 Q_PRIVATE_SLOT(d, void _k_updateCurrentChar(const QChar &c))
206 Q_PRIVATE_SLOT(d, void _k_slotUpdateUnicode(const QChar &c))
207 Q_PRIVATE_SLOT(d, void _k_sectionSelected(int index))
208 Q_PRIVATE_SLOT(d, void _k_blockSelected(int index))
209 Q_PRIVATE_SLOT(d, void _k_searchEditChanged())
210 Q_PRIVATE_SLOT(d, void _k_search())
211 Q_PRIVATE_SLOT(d, void _k_linkClicked(QUrl))
212
213 class KCharSelectPrivate;
214 KCharSelectPrivate* const d;
215
216 void init(const Controls, KActionCollection *);
217};
218
219Q_DECLARE_OPERATORS_FOR_FLAGS(KCharSelect::Controls)
220
221#endif
222