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_H
9#define K_FONT_CHOOSER_H
10
11#include <QStringList>
12#include <QWidget>
13#include <kwidgetsaddons_export.h>
14#include <memory>
15
16class QFont;
17
18/*!
19 * \class KFontChooser
20 * \inmodule KWidgetsAddons
21 *
22 * \brief A font selection widget.
23 *
24 * While KFontChooser as an ordinary widget can be embedded in
25 * custom dialogs and therefore is very flexible, in most cases
26 * it is preferable to use the convenience functions in
27 * QFontDialog.
28 *
29 * \image kfontchooser.png "KFontChooser Widget"
30 *
31 * \sa KFontRequester
32 */
33class KWIDGETSADDONS_EXPORT KFontChooser : public QWidget
34{
35 Q_OBJECT
36
37 /*!
38 * \property KFontChooser::font
39 */
40 Q_PROPERTY(QFont font READ font WRITE setFont NOTIFY fontSelected USER true)
41
42 /*!
43 * \property KFontChooser::color
44 */
45 Q_PROPERTY(QColor color READ color WRITE setColor)
46
47 /*!
48 * \property KFontChooser::backgroundColor
49 */
50 Q_PROPERTY(QColor backgroundColor READ backgroundColor WRITE setBackgroundColor)
51
52 /*!
53 * \property KFontChooser::sampleText
54 */
55 Q_PROPERTY(QString sampleText READ sampleText WRITE setSampleText)
56
57public:
58 /*!
59 * Displayed columns.
60 *
61 * \value FamilyList Identifies the family (leftmost) list.
62 * \value StyleList Identifies the style (center) list.
63 * \value SizeList Identifies the size (rightmost) list.
64 */
65 enum FontColumn {
66 FamilyList = 0x01,
67 StyleList = 0x02,
68 SizeList = 0x04,
69 };
70
71 /*!
72 * Flags for selecting which font attributes to change
73 *
74 * \value NoFontDiffFlags No flags set
75 * \value FontDiffFamily Identifies a requested change in the font family.
76 * \value FontDiffStyle Identifies a requested change in the font style.
77 * \value FontDiffSize Identifies a requested change in the font size.
78 * \value AllFontDiffs
79 */
80 enum FontDiff {
81 NoFontDiffFlags = 0,
82 FontDiffFamily = 1,
83 FontDiffStyle = 2,
84 FontDiffSize = 4,
85 AllFontDiffs = FontDiffFamily | FontDiffStyle | FontDiffSize,
86 };
87 Q_DECLARE_FLAGS(FontDiffFlags, FontDiff)
88
89 /*!
90 * Flags for selecting what is displayed in the widget.
91 *
92 * \value NoDisplayFlags No flags set
93 * \value FixedFontsOnly Only show monospaced/fixed-width fonts, *excluding proportional fonts, (the checkbox to toggle showing only monospaced fonts is not
94 * shown in this case)
95 * \value DisplayFrame = Show a visual frame around the chooser
96 * \value ShowDifferences Display the font differences interfaces
97 */
98 enum DisplayFlag {
99 NoDisplayFlags = 0,
100 FixedFontsOnly = 1,
101 DisplayFrame = 2,
102 ShowDifferences = 4,
103 };
104 Q_DECLARE_FLAGS(DisplayFlags, DisplayFlag)
105
106 /*!
107 * Constructs a font picker widget.
108 *
109 * \a parent the parent widget
110 *
111 * \since 5.86
112 */
113 explicit KFontChooser(QWidget *parent = nullptr);
114
115 /*!
116 * Create a font picker widget.
117 *
118 * \a flags a combination of OR-ed values from the \c KFontChooser::DisplayFlags enum,
119 * the default is \c DisplayFonts::NoDisplayFlags
120 *
121 * \a parent the parent widget, if not nullptr the windowing system will use it to position
122 * the chooser widget relative to it
123 *
124 * \since 5.86
125 */
126 explicit KFontChooser(DisplayFlags flags, QWidget *parent = nullptr);
127
128 ~KFontChooser() override;
129
130 /*!
131 * Enables or disables a column (family, style, size) in the widget.
132 *
133 * Use this function if your application does not need or support all font properties.
134 *
135 * \a column specify the column(s) to enable/disable, an OR-ed combination of
136 * KFontChooser::FontColumn enum values
137 *
138 * \a state if \a false the columns are disabled, and vice-versa
139 */
140 void enableColumn(int column, bool state);
141
142 /*!
143 * Sets the currently selected font in the widget.
144 *
145 * \a font the font to select
146 *
147 * \a onlyFixed if \c true, the font list will only display fixed-width fonts,
148 * otherwise all fonts are displayed. The default is \c false.
149 */
150 void setFont(const QFont &font, bool onlyFixed = false);
151
152 /*!
153 * Returns the bitmask corresponding to the attributes the user wishes to change.
154 */
155 FontDiffFlags fontDiffFlags() const;
156
157 /*!
158 * Returns the currently selected font in the chooser.
159 */
160 QFont font() const;
161
162 /*!
163 * Sets the color to use for the font in the preview area.
164 */
165 void setColor(const QColor &col);
166
167 /*!
168 * Returns the color currently used for the font in the preview
169 * area (default: the text color of the active color group).
170 */
171 QColor color() const;
172
173 /*!
174 * Sets the background color to use in the preview area.
175 */
176 void setBackgroundColor(const QColor &col);
177
178 /*!
179 * Returns the background color currently used in the preview area
180 * (default: the base color of the active colorgroup)
181 */
182 QColor backgroundColor() const;
183
184 /*!
185 * Returns the current text in the sample text input area.
186 */
187 QString sampleText() const;
188
189 /*!
190 * Sets the sample text in the preview area; this is useful if you
191 * want to use text in your native language.
192 *
193 * \a text the new sample text (it will replace the current text)
194 */
195 void setSampleText(const QString &text);
196
197 /*!
198 * If \a visible is \c true the preview area will be shown, and vice-versa
199 * is it's \c false.
200 */
201 void setSampleBoxVisible(bool visible);
202
203 /*!
204 * The selection criteria for the font families shown in the dialog.
205 *
206 * \value FixedWidthFonts If set, only show fixed fixed-width (monospace) fonts.
207 * \value ScalableFonts If set, only show scalable fonts. Certain configurations allow bitmap fonts to remain unscaled and thus these fonts have limited
208 * number of sizes.
209 * \value SmoothScalableFonts If set, only show smooth scalable fonts. This will return only non-bitmap fonts which are scalable to any size requested.
210 * Setting this option means the \c ScalableFonts flag is ignored.
211 */
212 enum FontListCriteria {
213 FixedWidthFonts = 0x01,
214 ScalableFonts = 0x02,
215 SmoothScalableFonts = 0x04
216 };
217
218 /*!
219 * Returns a list of font faimly name strings filtered based on \a fontListCriteria.
220 *
221 * \a fontListCriteria specifies the criteria used to select fonts to add to
222 * the list, a combination of OR-ed values from KFontChooser::FontListCriteria
223 *
224 * \since 5.86
225 */
226 static QStringList createFontList(uint fontListCriteria);
227
228 /*!
229 * Uses \a fontList to fill the font family list in the widget.
230 *
231 * You can create a custom list of fonts using the static createFontList(uint
232 * criteria) to only include fonts that meet certain criteria (e.g. only
233 * smooth-scalable fonts).
234 *
235 * \sa KFontChooser::createFontList(uint), KFontChooser::FontListCriteria
236 *
237 * Note that if \a fontList is empty, the font list in the chooser will show
238 * all the available fonts on the system.
239 * \since 5.86
240 */
241 void setFontListItems(const QStringList &fontList);
242
243 /*!
244 * Sets the minimum number of items that should be visible in the
245 * child list widgets; this number will be used to compute and set
246 * the minimum heights for those widgets.
247 *
248 * \since 5.86
249 */
250 void setMinVisibleItems(int visibleItems);
251
252 QSize sizeHint(void) const override;
253
254Q_SIGNALS:
255 /*!
256 * Emitted when the selected font changes.
257 */
258 void fontSelected(const QFont &font);
259
260private:
261 std::unique_ptr<class KFontChooserPrivate> const d;
262
263 Q_DISABLE_COPY(KFontChooser)
264};
265
266Q_DECLARE_OPERATORS_FOR_FLAGS(KFontChooser::DisplayFlags)
267
268#endif
269

source code of kwidgetsaddons/src/kfontchooser.h