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

source code of kwidgetsaddons/src/kfontchooserdialog.h