1/*
2 SPDX-FileCopyrightText: 1997 Bernd Johannes Wuebben <wuebben@kde.org>
3 SPDX-FileCopyrightText: 1999 Preston Brown <pbrown@kde.org>
4 SPDX-FileCopyrightText: 1999 Mario Weilguni <mweilguni@kde.org>
5
6 SPDX-License-Identifier: LGPL-2.0-or-later
7*/
8#ifndef K_FONT_CHOOSER_DIALOG_H
9#define K_FONT_CHOOSER_DIALOG_H
10
11#include <QDialog>
12#include <QStringList>
13
14#include <kfontchooser.h>
15
16#include <memory>
17
18class QFont;
19
20class KFontChooserDialogPrivate;
21
22/*!
23 * \class KFontChooserDialog
24 * \inmodule KWidgetsAddons
25 *
26 * \brief A font selection dialog.
27 *
28 * The KFontChooserDialog provides a dialog for interactive font selection.
29 * It is basically a thin wrapper around the KFontChooser widget (the latter
30 * can also be used standalone). In most cases, the simplest use of this
31 * class is the static method KFontChooserDialog::getFont(), which shows
32 * the dialog, allows the user to select a font, and returns when the
33 * dialog is closed.
34 *
35 * Features offered by KFontChooserDialog/KFontChooser:
36 * \list
37 * \li The ability to set decimal font sizes (e.g. "12.1")
38 * \li When selecting an initial font, if the styleName property of that font
39 * isn't set, the dialog will try and select the correct font style from the
40 * styles list
41 * \li The ability to set multiple fonts at once, for an example of this functionality
42 * see "Adjust All Fonts" in the Fonts KCM in Systemsettings; and you can change
43 * the font family, style or size separately
44 * \li Discarding the styleName property when closing the dialog for "Regular" font
45 * styles, since it doesn't make sense to set that property for such fonts and
46 * this allows setBold(true) to work correctly for more details see:
47 * https://bugreports.qt.io/browse/QTBUG-63792
48 * https://bugs.kde.org/show_bug.cgi?id=378523
49 * \endlist
50 *
51 * Example, using the static getFont() method:
52 *
53 * \code
54 * QFont myFont;
55 * int result = KFontChooserDialog::getFont(myFont);
56 * if (result == QDialog::Accepted) {
57 * ...
58 * }
59 * \endcode
60 *
61 * Another example, this time showing the dialog with show() (or open()):
62 * \code
63 * KFontChooserDialog *fontDlg = new KFontChooserDialog(KFontChooser::NoDisplayFlags, this);
64 * // Delete the dialog when it's closed
65 * fontDlg->setAttribute(Qt::WA_DeleteOnClose);
66 *
67 * connect(fontDlg, &QDialog::accepted, this, [fontDlg]() {
68 * // Get the selected font via fontDlg->font() and apply it, save it to
69 * // the settings... etc.
70 * });
71 *
72 * fontDlg->show();
73 * \endcode
74 *
75 * \image kfontchooserdialog.png "KFontChooserDialog"
76 *
77 * \since 5.69
78 */
79class KWIDGETSADDONS_EXPORT KFontChooserDialog : public QDialog
80{
81 Q_OBJECT
82
83public:
84 /*!
85 * Constructs a font selection dialog.
86 *
87 * \a flags flags to define how the font chooser is displayed
88 *
89 * \a parent parent widget of the dialog, if any, the dialog will be centered relative to it
90 */
91 explicit KFontChooserDialog(const KFontChooser::DisplayFlags &flags = KFontChooser::NoDisplayFlags, QWidget *parent = nullptr);
92
93 ~KFontChooserDialog() override;
94
95 /*!
96 * Sets the currently selected font in the dialog.
97 *
98 * \a font the font to select
99 *
100 * \a onlyFixed if \c true, the font list will show only fixed width (monospace)
101 * fonts, otherwise all available fonts are shown
102 */
103 void setFont(const QFont &font, bool onlyFixed = false);
104
105 /*!
106 * Returns the currently selected font in the dialog
107 */
108 QFont font() const;
109
110 /*!
111 * Creates a modal font dialog, lets the user choose a font, and returns when
112 * the dialog is closed.
113 *
114 * \a theFont a reference to the font to write the chosen font into
115 *
116 * \a flags flags to define how the font chooser is displayed
117 *
118 * \a parent parent widget of the dialog, if any, the dialog will be centered relative to it
119 *
120 * Returns QDialog::result()
121 */
122 static int getFont(QFont &theFont, const KFontChooser::DisplayFlags &flags = KFontChooser::NoDisplayFlags, QWidget *parent = nullptr);
123
124 /*!
125 * Creates a modal font difference dialog, lets the user choose a selection
126 * of changes that should be made to a set of fonts, and returns when the
127 * dialog is closed. Useful for choosing slight adjustments to the font set
128 * when the user would otherwise have to manually edit a number of fonts.
129 *
130 * \a theFont a reference to the font to write the chosen font into
131 *
132 * \a flags flags to define how the font chooser is displayed
133 *
134 * \a diffFlags a reference to the integer bitmask into which the chosen
135 * difference selection bitmask should be written.
136 * Check the bitmask afterwards like:
137 * \code
138 * if ( diffFlags & KFontChooser::FontDiffFamily ) {
139 * [...]
140 * }
141 * if ( diffFlags & KFontChooser::FontDiffStyle ) {
142 * [...]
143 * }
144 * if ( diffFlags & KFontChooser::FontDiffSize ) {
145 * [...]
146 * }
147 * \endcode
148 *
149 * \a parent parent widget of the dialog, if any, the dialog will be centered relative to it
150 *
151 * Returns QDialog::result()
152 */
153 static int getFontDiff(QFont &theFont,
154 KFontChooser::FontDiffFlags &diffFlags,
155 const KFontChooser::DisplayFlags &flags = KFontChooser::NoDisplayFlags,
156 QWidget *parent = nullptr);
157
158Q_SIGNALS:
159 /*!
160 * Emitted whenever the currently selected font changes.
161 * Connect to this to monitor the font as it is selected if you are
162 * not running modal.
163 */
164 void fontSelected(const QFont &font);
165
166private:
167 std::unique_ptr<KFontChooserDialogPrivate> const d;
168
169 Q_DISABLE_COPY(KFontChooserDialog)
170};
171
172#endif
173

source code of kwidgetsaddons/src/kfontchooserdialog.h