1 | /* |
2 | Requires the Qt widget libraries, available at no cost at |
3 | http://www.troll.no |
4 | |
5 | Copyright (C) 1997 Bernd Johannes Wuebben <wuebben@kde.org> |
6 | Copyright (c) 1999 Preston Brown <pbrown@kde.org> |
7 | Copyright (c) 1999 Mario Weilguni <mweilguni@kde.org> |
8 | |
9 | This library is free software; you can redistribute it and/or |
10 | modify it under the terms of the GNU Library General Public |
11 | License as published by the Free Software Foundation; either |
12 | version 2 of the License, or (at your option) any later version. |
13 | |
14 | This library is distributed in the hope that it will be useful, |
15 | but WITHOUT ANY WARRANTY; without even the implied warranty of |
16 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
17 | Library General Public License for more details. |
18 | |
19 | You should have received a copy of the GNU Library General Public License |
20 | along with this library; see the file COPYING.LIB. If not, write to |
21 | the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, |
22 | Boston, MA 02110-1301, USA. |
23 | */ |
24 | #ifndef K_FONT_CHOOSER_H |
25 | #define K_FONT_CHOOSER_H |
26 | |
27 | #include <kdeui_export.h> |
28 | #include <QtGui/QWidget> |
29 | |
30 | class QFont; |
31 | class QStringList; |
32 | |
33 | /** |
34 | * @short A font selection widget. |
35 | * |
36 | * While KFontChooser as an ordinary widget can be embedded in |
37 | * custom dialogs and therefore is very flexible, in most cases |
38 | * it is preferable to use the convenience functions in |
39 | * KFontDialog. |
40 | * |
41 | * \image html kfontchooser.png "KDE Font Chooser Widget" |
42 | * |
43 | * @see KFontRequester |
44 | * |
45 | * @author Preston Brown <pbrown@kde.org>, Bernd Wuebben <wuebben@kde.org> |
46 | */ |
47 | class KDEUI_EXPORT KFontChooser : public QWidget |
48 | { |
49 | Q_OBJECT |
50 | Q_PROPERTY( QFont font READ font WRITE setFont NOTIFY fontSelected USER true ) |
51 | Q_PROPERTY( QColor color READ color WRITE setColor ) |
52 | Q_PROPERTY( QColor backgroundColor READ backgroundColor WRITE setBackgroundColor ) |
53 | Q_PROPERTY( Qt::CheckState sizeIsRelative READ sizeIsRelative WRITE setSizeIsRelative ) |
54 | Q_PROPERTY( QString sampleText READ sampleText WRITE setSampleText ) |
55 | |
56 | public: |
57 | /** |
58 | * @li @p FamilyList - Identifies the family (leftmost) list. |
59 | * @li @p StyleList - Identifies the style (center) list. |
60 | * @li @p SizeList - Identifies the size (rightmost) list. |
61 | */ |
62 | enum FontColumn { FamilyList=0x01, StyleList=0x02, SizeList=0x04}; |
63 | |
64 | /** |
65 | * @li @p FontDiffFamily - Identifies a requested change in the font family. |
66 | * @li @p FontDiffStyle - Identifies a requested change in the font style. |
67 | * @li @p FontDiffSize - Identifies a requested change in the font size. |
68 | */ |
69 | enum FontDiff { NoFontDiffFlags = 0, |
70 | FontDiffFamily = 1, |
71 | FontDiffStyle = 2, |
72 | FontDiffSize = 4, |
73 | AllFontDiffs = FontDiffFamily | FontDiffStyle | FontDiffSize }; |
74 | Q_DECLARE_FLAGS( FontDiffFlags, FontDiff ) |
75 | |
76 | /** |
77 | * @li @p FixedFontsOnly only show fixed fonts, excluding proportional fonts |
78 | * @li @p DisplayFrame show a visual frame around the chooser |
79 | * @li @p ShowDifferences display the font differences interfaces |
80 | */ |
81 | enum DisplayFlag { NoDisplayFlags = 0, |
82 | FixedFontsOnly = 1, |
83 | DisplayFrame = 2, |
84 | ShowDifferences = 4 }; |
85 | Q_DECLARE_FLAGS( DisplayFlags, DisplayFlag ) |
86 | |
87 | /** |
88 | * Constructs a font picker widget. |
89 | * It normally comes up with all font families present on the system; the |
90 | * getFont method below does allow some more fine-tuning of the selection of fonts |
91 | * that will be displayed in the dialog. |
92 | * <p>Consider the following code snippet; |
93 | * \code |
94 | * QStringList list; |
95 | * KFontChooser::getFontList(list, KFontChooser::SmoothScalableFonts); |
96 | * KFontChooser *chooseFont = new KFontChooser(0, NoDisplayFlags, list); |
97 | * \endcode |
98 | * <p> |
99 | * The above creates a font chooser dialog with only SmoothScaleble fonts. |
100 | * |
101 | * @param parent The parent widget. |
102 | * @param flags Defines how the font chooser is displayed. @see DisplayFlags |
103 | * @param fontList A list of fonts to display, in XLFD format. If |
104 | * no list is formatted, the internal KDE font list is used. |
105 | * If that has not been created, X is queried, and all fonts |
106 | * available on the system are displayed. |
107 | * @param visibleListSize The minimum number of visible entries in the |
108 | * fontlists. |
109 | * @param sizeIsRelativeState If not zero the widget will show a |
110 | * checkbox where the user may choose whether the font size |
111 | * is to be interpreted as relative size. |
112 | * Initial state of this checkbox will be set according to |
113 | * *sizeIsRelativeState, user choice may be retrieved by |
114 | * calling sizeIsRelative(). |
115 | */ |
116 | explicit KFontChooser( QWidget *parent = 0L, |
117 | const DisplayFlags& flags = DisplayFrame, |
118 | const QStringList &fontList = QStringList(), |
119 | int visibleListSize = 8, |
120 | Qt::CheckState *sizeIsRelativeState = 0L ); |
121 | |
122 | /** |
123 | * Destructs the font chooser. |
124 | */ |
125 | virtual ~KFontChooser(); |
126 | |
127 | /** |
128 | * Enables or disable a font column in the chooser. |
129 | * |
130 | * Use this |
131 | * function if your application does not need or supports all font |
132 | * properties. |
133 | * |
134 | * @param column Specify the columns. An or'ed combination of |
135 | * @p FamilyList, @p StyleList and @p SizeList is possible. |
136 | * @param state If @p false the columns are disabled. |
137 | */ |
138 | void enableColumn( int column, bool state ); |
139 | |
140 | /** |
141 | * Sets the currently selected font in the chooser. |
142 | * |
143 | * @param font The font to select. |
144 | * @param onlyFixed Readjust the font list to display only fixed |
145 | * width fonts if @p true, or vice-versa. |
146 | */ |
147 | void setFont( const QFont &font, bool onlyFixed = false ); |
148 | |
149 | /** |
150 | * @return The bitmask corresponding to the attributes the user |
151 | * wishes to change. |
152 | */ |
153 | FontDiffFlags fontDiffFlags() const; |
154 | |
155 | /** |
156 | * @return The currently selected font in the chooser. |
157 | */ |
158 | QFont font() const; |
159 | |
160 | /** |
161 | * Sets the color to use in the preview. |
162 | */ |
163 | void setColor( const QColor & col ); |
164 | |
165 | /** |
166 | * @return The color currently used in the preview (default: the text |
167 | * color of the active color group) |
168 | */ |
169 | QColor color() const; |
170 | |
171 | /** |
172 | * Sets the background color to use in the preview. |
173 | */ |
174 | void setBackgroundColor( const QColor & col ); |
175 | |
176 | /** |
177 | * @return The background color currently used in the preview (default: |
178 | * the base color of the active colorgroup) |
179 | */ |
180 | QColor backgroundColor() const; |
181 | |
182 | /** |
183 | * Sets the state of the checkbox indicating whether the font size |
184 | * is to be interpreted as relative size. |
185 | * NOTE: If parameter sizeIsRelative was not set in the constructor |
186 | * of the widget this setting will be ignored. |
187 | */ |
188 | void setSizeIsRelative( Qt::CheckState relative ); |
189 | |
190 | /** |
191 | * @return Whether the font size is to be interpreted as relative size |
192 | * (default: QButton:Off) |
193 | */ |
194 | Qt::CheckState sizeIsRelative() const; |
195 | |
196 | |
197 | /** |
198 | * @return The current text in the sample text input area. |
199 | */ |
200 | QString sampleText() const; |
201 | |
202 | /** |
203 | * Sets the sample text. |
204 | * |
205 | * Normally you should not change this |
206 | * text, but it can be better to do this if the default text is |
207 | * too large for the edit area when using the default font of your |
208 | * application. |
209 | * |
210 | * @param text The new sample text. The current will be removed. |
211 | */ |
212 | void setSampleText( const QString &text ); |
213 | |
214 | /** |
215 | * Shows or hides the sample text box. |
216 | * |
217 | * @param visible Set it to true to show the box, to false to hide it. |
218 | */ |
219 | void setSampleBoxVisible( bool visible ); |
220 | |
221 | /** |
222 | * The selection criteria for the font families shown in the dialog. |
223 | * @li @p FixedWidthFont when included only fixed-width fonts are returned. |
224 | * The fonts where the width of every character is equal. |
225 | * @li @p ScalableFont when included only scalable fonts are returned; |
226 | * certain configurations allow bitmap fonts to remain unscaled and |
227 | * thus these fonts have limited number of sizes. |
228 | * @li @p SmoothScalableFont when included only return smooth scalable fonts. |
229 | * this will return only non-bitmap fonts which are scalable to any size requested. |
230 | * Setting this option to true will mean the "scalable" flag is irrelavant. |
231 | */ |
232 | enum FontListCriteria { FixedWidthFonts=0x01, ScalableFonts=0x02, SmoothScalableFonts=0x04 }; |
233 | |
234 | /** |
235 | * Creates a list of font strings. |
236 | * |
237 | * @param list The list is returned here. |
238 | * @param fontListCriteria should contain all the restrictions for font selection as OR-ed values |
239 | * @see KFontChooser::FontListCriteria for the individual values |
240 | */ |
241 | static void getFontList( QStringList &list, uint fontListCriteria); |
242 | |
243 | /** |
244 | * Reimplemented for internal reasons. |
245 | */ |
246 | virtual QSize sizeHint( void ) const; |
247 | |
248 | Q_SIGNALS: |
249 | /** |
250 | * Emitted whenever the selected font changes. |
251 | */ |
252 | void fontSelected( const QFont &font ); |
253 | |
254 | private: |
255 | class Private; |
256 | Private * const d; |
257 | |
258 | Q_DISABLE_COPY(KFontChooser) |
259 | |
260 | Q_PRIVATE_SLOT(d, void _k_toggled_checkbox()) |
261 | Q_PRIVATE_SLOT(d, void _k_family_chosen_slot(const QString&)) |
262 | Q_PRIVATE_SLOT(d, void _k_size_chosen_slot(const QString&)) |
263 | Q_PRIVATE_SLOT(d, void _k_style_chosen_slot(const QString&)) |
264 | Q_PRIVATE_SLOT(d, void _k_displaySample(const QFont &font)) |
265 | Q_PRIVATE_SLOT(d, void _k_showXLFDArea(bool)) |
266 | Q_PRIVATE_SLOT(d, void _k_size_value_slot(double)) |
267 | }; |
268 | |
269 | Q_DECLARE_OPERATORS_FOR_FLAGS( KFontChooser::DisplayFlags ) |
270 | |
271 | #endif |
272 | |