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
30class QFont;
31class 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 */
47class 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
56public:
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
248Q_SIGNALS:
249 /**
250 * Emitted whenever the selected font changes.
251 */
252 void fontSelected( const QFont &font );
253
254private:
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
269Q_DECLARE_OPERATORS_FOR_FLAGS( KFontChooser::DisplayFlags )
270
271#endif
272