Differential D28122 Diff 78241 src/kfontchooserdialog.h

Changeset View

Standalone View

View Options

src/kfontchooserdialog.h

  • This file was added.
1​/*
2​ Copyright (C) 1997 Bernd Johannes Wuebben <wuebben@kde.org>
3​ Copyright (c) 1999 Preston Brown <pbrown@kde.org>
4​ Copyright (c) 1999 Mario Weilguni <mweilguni@kde.org>
5​
6​ This library is free software; you can redistribute it and/or
7​ modify it under the terms of the GNU Library General Public
8​ License as published by the Free Software Foundation; either
9​ version 2 of the License, or (at your option) any later version.
10​
11​ This library is distributed in the hope that it will be useful,
12​ but WITHOUT ANY WARRANTY; without even the implied warranty of
13​ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14​ Library General Public License for more details.
15​
16​ You should have received a copy of the GNU Library General Public License
17​ along with this library; see the file COPYING.LIB. If not, write to
18​ the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
19​ Boston, MA 02110-1301, USA.
20​*/
21​#ifndef K_FONT_CHOOSER_DIALOG_H
22​#define K_FONT_CHOOSER_DIALOG_H
23​
24​#include <QDialog>
25​
26​#include <kfontchooser.h>
27​
28​class QFont;
29​class QStringList;
30​
31​class KFontChooserDialogPrivate;
32​
33​/**
34​ * @short A font selection dialog.
35​ *
36​ * The KFontChooserDialog provides a dialog for interactive font selection.
37​ * It is basically a thin wrapper around the KFontChooser widget (the latter
38​ * can also be used standalone). In most cases, the simplest use of this
39​ * class is the static method KFontChooserDialog::getFont(), which shows
40​ * the dialog, allows the user to select a font, and returns when the
41​ * dialog is closed.
42​ *
43​ * Features offered by KFontChooserDialog/KFontChooser:
44​ * - The ability to set decimal font sizes (e.g. "12.1")
45​ * - When selecting an initial font, if the styleName property of that font
46​ * isn't set, the dialog will try and select the correct font style from the
47​ * styles list
48​ * - The ability to set multiple fonts at once, for an example of this functionality
49​ * see "Adjust All Fonts" in the Fonts KCM in Systemsettings; and you can change
50​ * the font family, style or size separately
51​ * - Discarding the styleName property when closing the dialog for "Regular" font
52​ * styles, since it doesn't make sense to set that property for such fonts and
53​ * this allows setBold(true) to work correctly for more details see:
54​ * https://bugreports.qt.io/browse/QTBUG-63792
55​ * https://bugs.kde.org/show_bug.cgi?id=378523
56​ *
57​ * Example:
58​ *
59​ * \code
60​ * QFont myFont;
61​ * int result = KFontChooserDialog::getFont(myFont);
62​ * if (result == QDialog::Accepted) {
63​ * ...
64​ * }
65​ * \endcode
66​ *
67​ * \image html kfontchooserdialog.png "KDE Font Dialog"
68​ *
69​ * @author Preston Brown <pbrown@kde.org>, Bernd Wuebben <wuebben@kde.org>
70​ *
71​ * @since 5.69
dfaureUnsubmitted
Done

@since 5.69

dfaure: @since 5.69
72​ */
73​class KWIDGETSADDONS_EXPORT KFontChooserDialog : public QDialog
74​{
75​ Q_OBJECT
76​
77​public:
78​ /**
79​ * Constructs a font selection dialog.
80​ *
81​ * @param parent The parent widget of the dialog, if any.
82​ * @param flags Defines how the font chooser is displayed.
dfaureUnsubmitted
Done

Do @param need to be in order of the arguments? (I'm not sure)

dfaure: Do @param need to be in order of the arguments? (I'm not sure)
ahmadsamirAuthorUnsubmitted
Not Done

They should be, it's more logical.

ahmadsamir: They should be, it's more logical.
83​ * @see KFontChooser::DisplayFlags
84​ *
85​ */
86​ explicit KFontChooserDialog(const KFontChooser::DisplayFlags &flags = KFontChooser::NoDisplayFlags,
87​ QWidget *parent = nullptr);
88​
89​ ~KFontChooserDialog();
90​
dfaureUnsubmitted
Done

The usual way in Qt API is that the parent is the last argument, rather than the first.

But for this to be convenient, the fontlist argument would have to move to a setFontList() method, and I see that KFontChooser itself doesn't support that. So, I won't block for this reason, but if you're aiming for perfection, you know what to do... ;)

Then flags can either be a setter, or a constructor overload:

ctor(QWidget*)
ctor(flags, QWidget*)

like QFontDialog or QLineEdit or many others do, in order to keep the parent pointer as the last argument.

dfaure: The usual way in Qt API is that the parent is the last argument, rather than the first. But…
ahmadsamirAuthorUnsubmitted
Done

Done. And I removed the fontList parameter altogether, it wasn't used, and even QFontDialog doesn't have it. I think the need to set a specific font list to display in a font selection dialog is pretty niche, I couldn't find a single usage of it in lxr (even in stable-qt4 branch).

Since the ctor parameters both have default values, I won't overload the ctor.

ahmadsamir: Done. And I removed the fontList parameter altogether, it wasn't used, and even QFontDialog…
dfaureUnsubmitted
Done

Good call. I can't think of any use case for this.

Maybe choosing an emoji font? But then how to know which of the installed fonts qualify... Yeah let's wait until there's actually a use case, if ever.

dfaure: Good call. I can't think of any use case for this. Maybe choosing an emoji font? But then how…
ahmadsamirAuthorUnsubmitted
Not Done

emoji fonts... that would need a whole rewrite in a lot of places, starting at QFontDatabase, so we'd have isSmoothlyScalable and isEmojiScalable, and maybe isEmojiMonospace, just kidding.

(what's wrong with ":D" ":)" ";)" ":(" "\o/"? all fonts support them, and they look cool :D).

ahmadsamir: emoji fonts... that would need a whole rewrite in a lot of places, starting at QFontDatabase…
91​ /**
92​ * Sets the currently selected font in the dialog.
93​ *
94​ * @param font The font to select
95​ * @param onlyFixed If true, the font list will show only fixed width (monospace)
96​ * fonts, otherwise all available fonts are shown
97​ */
98​ void setFont(const QFont &font, bool onlyFixed = false);
99​
100​ /**
101​ * @return The currently selected font in the dialog.
102​ */
103​ QFont font() const;
104​
105​ /**
106​ * Creates a modal font dialog, lets the user choose a font, and returns when
107​ * the dialog is closed.
108​ *
109​ * @param theFont a reference to the font to write the chosen font into.
110​ * @param flags Defines how the font chooser is displayed.
111​ * @see KFontChooser::DisplayFlags
112​ * @param parent Parent widget of the dialog; the dialog will be centered relative to it.
113​ * @return QDialog::result().
114​ */
115​ static int getFont(QFont &theFont,
116​ const KFontChooser::DisplayFlags &flags = KFontChooser::NoDisplayFlags,
117​ QWidget *parent = nullptr);
118​
119​ /**
120​ * Creates a modal font difference dialog, lets the user choose a selection
121​ * of changes that should be made to a set of fonts, and returns when the
122​ * dialog is closed. Useful for choosing slight adjustments to the font set
123​ * when the user would otherwise have to manually edit a number of fonts.
124​ *
125​ * @param theFont a reference to the font to write the chosen font into.
126​ * @param flags Defines how the font chooser is displayed.
127​ * @see KFontChooser::DisplayFlags
128​ * @param diffFlags a reference to the int into which the chosen
129​ * difference selection bitmask should be written.
130​ * Check the returned bitmask like:
131​ * \code
132​ * if ( diffFlags & KFontChooser::FontDiffFamily ) {
133​ * [...]
134​ * }
135​ * if ( diffFlags & KFontChooser::FontDiffStyle ) {
136​ * [...]
137​ * }
138​ * if ( diffFlags & KFontChooser::FontDiffSize ) {
139​ * [...]
140​ * }
141​ * \endcode
142​ * @param parent Parent widget of the dialog; the dialog will be centered relative to it.
143​ *
144​ * @returns QDialog::result().
145​ */
146​ static int getFontDiff(QFont &theFont,
147​ KFontChooser::FontDiffFlags &diffFlags,
148​ const KFontChooser::DisplayFlags &flags = KFontChooser::NoDisplayFlags,
149​ QWidget *parent = nullptr);
150​
151​Q_SIGNALS:
152​ /**
153​ * Emitted whenever the currently selected font changes.
154​ * Connect to this to monitor the font as it is selected if you are
155​ * not running modal.
156​ */
157​ void fontSelected(const QFont &font);
158​
159​private:
160​ KFontChooserDialogPrivate *const d;
161​
162​ Q_DISABLE_COPY(KFontChooserDialog)
163​};
164​
165​#endif