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_DIALOG_H
25#define K_FONT_DIALOG_H
26
27#include <kdialog.h>
28#include <kfontchooser.h>
29
30class QFont;
31class QStringList;
32
33/**
34 * @short A font selection dialog.
35 *
36 * The KFontDialog provides a dialog for interactive font selection.
37 * It is basically a thin wrapper around the KFontChooser widget,
38 * which can also be used standalone. In most cases, the simplest
39 * use of this class is the static method KFontDialog::getFont(),
40 * which pops up the dialog, allows the user to select a font, and
41 * returns when the dialog is closed.
42 *
43 * Example:
44 *
45 * \code
46 * QFont myFont;
47 * int result = KFontDialog::getFont( myFont );
48 * if ( result == KFontDialog::Accepted )
49 * ...
50 * \endcode
51 *
52 * \image html kfontdialog.png "KDE Font Dialog"
53 *
54 * @author Preston Brown <pbrown@kde.org>, Bernd Wuebben <wuebben@kde.org>
55 */
56class KDEUI_EXPORT KFontDialog : public KDialog {
57 Q_OBJECT
58
59public:
60 /**
61 * Constructs a font selection dialog.
62 *
63 * @param parent The parent widget of the dialog, if any.
64 * @param flags Defines how the font chooser is displayed.
65 * @see KFontChooser::DisplayFlags
66 * @param fontlist a list of fonts to display, in XLFD format. If
67 * no list is formatted, the internal KDE font list is used.
68 * If that has not been created, X is queried, and all fonts
69 * available on the system are displayed.
70 * @param sizeIsRelativeState If not zero the widget will show a
71 * checkbox where the user may choose whether the font size
72 * is to be interpreted as relative size.
73 * Initial state of this checkbox will be set according to
74 * *sizeIsRelativeState, user choice may be retrieved by
75 * calling sizeIsRelative().
76 *
77 */
78 explicit KFontDialog( QWidget *parent = 0,
79 const KFontChooser::DisplayFlags& flags =
80 KFontChooser::NoDisplayFlags,
81 const QStringList &fontlist = QStringList(),
82 Qt::CheckState *sizeIsRelativeState = 0 );
83
84 ~KFontDialog();
85 /**
86 * Sets the currently selected font in the dialog.
87 *
88 * @param font The font to select.
89 * @param onlyFixed readjust the font list to display only fixed
90 * width fonts if true, or vice-versa
91 */
92 void setFont( const QFont &font, bool onlyFixed = false );
93
94 /**
95 * @return The currently selected font in the dialog.
96 */
97 QFont font() const;
98
99 /**
100 * Sets the state of the checkbox indicating whether the font size
101 * is to be interpreted as relative size.
102 * NOTE: If parameter sizeIsRelative was not set in the constructor
103 * of the dialog this setting will be ignored.
104 */
105 void setSizeIsRelative( Qt::CheckState relative );
106
107 /**
108 * @return Whether the font size is to be interpreted as relative size
109 * (default: false)
110 */
111 Qt::CheckState sizeIsRelative() const;
112
113 /**
114 * Creates a modal font dialog, lets the user choose a font,
115 * and returns when the dialog is closed.
116 *
117 * @param theFont a reference to the font to write the chosen font
118 * into.
119 * @param flags Defines how the font chooser is displayed.
120 * @see KFontChooser::DisplayFlags
121 * @param parent Parent widget of the dialog. Specifying a widget different
122 * from 0 (Null) improves centering (looks better).
123 * @param makeFrame Draws a frame with titles around the contents.
124 * @param sizeIsRelativeState If not zero the widget will show a
125 * checkbox where the user may choose whether the font size
126 * is to be interpreted as relative size.
127 * Initial state of this checkbox will be set according to
128 * *sizeIsRelativeState and user choice will be returned
129 * therein.
130 *
131 * @return QDialog::result().
132 */
133 static int getFont( QFont &theFont,
134 const KFontChooser::DisplayFlags& flags =
135 KFontChooser::NoDisplayFlags,
136 QWidget *parent = 0L,
137 Qt::CheckState *sizeIsRelativeState = 0L );
138
139 /**
140 * Creates a modal font difference dialog, lets the user choose a selection
141 * of changes that should be made to a set of fonts, and returns when the
142 * dialog is closed. Useful for choosing slight adjustments to the font set
143 * when the user would otherwise have to manually edit a number of fonts.
144 *
145 * @param theFont a reference to the font to write the chosen font
146 * into.
147 * @param flags Defines how the font chooser is displayed.
148 * @see KFontChooser::DisplayFlags
149 * @param diffFlags a reference to the int into which the chosen
150 * difference selection bitmask should be written.
151 * Check the returned bitmask like:
152 * \code
153 * if ( diffFlags & KFontChooser::FontDiffFamily )
154 * [...]
155 * if ( diffFlags & KFontChooser::FontDiffStyle )
156 * [...]
157 * if ( diffFlags & KFontChooser::FontDiffSize )
158 * [...]
159 * \endcode
160 * @param parent Parent widget of the dialog. Specifying a widget different
161 * from 0 (Null) improves centering (looks better).
162 * @param sizeIsRelativeState If not zero the widget will show a
163 * checkbox where the user may choose whether the font size
164 * is to be interpreted as relative size.
165 * Initial state of this checkbox will be set according to
166 * *sizeIsRelativeState and user choice will be returned
167 * therein.
168 *
169 * @returns QDialog::result().
170 */
171 static int getFontDiff( QFont &theFont,
172 KFontChooser::FontDiffFlags& diffFlags,
173 const KFontChooser::DisplayFlags& flags =
174 KFontChooser::NoDisplayFlags,
175 QWidget *parent = 0L,
176 Qt::CheckState *sizeIsRelativeState = 0L );
177
178 /**
179 * When you are not only interested in the font selected, but also
180 * in the example string typed in, you can call this method.
181 *
182 * @param theFont a reference to the font to write the chosen font
183 * into.
184 * @param theString a reference to the example text that was typed.
185 * @param flags Defines how the font chooser is displayed.
186 * @see KFontChooser::DisplayFlags
187 * @param parent Parent widget of the dialog. Specifying a widget different
188 * from 0 (Null) improves centering (looks better).
189 * @param sizeIsRelativeState If not zero the widget will show a
190 * checkbox where the user may choose whether the font size
191 * is to be interpreted as relative size.
192 * Initial state of this checkbox will be set according to
193 * *sizeIsRelativeState and user choice will be returned
194 * therein.
195 * @return The result of the dialog.
196 */
197 static int getFontAndText( QFont &theFont, QString &theString,
198 const KFontChooser::DisplayFlags& flags =
199 KFontChooser::NoDisplayFlags,
200 QWidget *parent = 0L,
201 Qt::CheckState *sizeIsRelativeState = 0L );
202
203Q_SIGNALS:
204 /**
205 * Emitted whenever the currently selected font changes.
206 * Connect to this to monitor the font as it is selected if you are
207 * not running modal.
208 */
209 void fontSelected( const QFont &font );
210
211private:
212 class Private;
213 Private * const d;
214
215 Q_DISABLE_COPY(KFontDialog)
216};
217
218#endif
219