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

source code of kwidgetsaddons/src/kfontchooser.h