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 16 class 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 * It normally comes up with all font families present on the system; the 29 * getFont method below does allow some more fine-tuning of the selection of fonts 30 * that will be displayed in the dialog. 31 * <p>Consider the following code snippet; 32 * \code 33 * QStringList list; 34 * KFontChooser::getFontList(list, KFontChooser::SmoothScalableFonts); 35 * KFontChooser *chooseFont = new KFontChooser(nullptr, KFontChooser::NoDisplayFlags, list); 36 * \endcode 37 * <p> 38 * The above creates a font chooser dialog with only SmoothScaleble fonts. 39 * \image html kfontchooser.png "KFontChooser Widget" 40 * 41 * @see KFontRequester 42 * 43 * @author Preston Brown <pbrown@kde.org>, Bernd Wuebben <wuebben@kde.org> 44 */ 45 class KWIDGETSADDONS_EXPORT KFontChooser : public QWidget 46 { 47 Q_OBJECT 48 Q_PROPERTY(QFont font READ font WRITE setFont NOTIFY fontSelected USER true) 49 Q_PROPERTY(QColor color READ color WRITE setColor) 50 Q_PROPERTY(QColor backgroundColor READ backgroundColor WRITE setBackgroundColor) 51 Q_PROPERTY(QString sampleText READ sampleText WRITE setSampleText) 52 53 #if KWIDGETSADDONS_ENABLE_DEPRECATED_SINCE(5, 86) 54 Q_PROPERTY(Qt::CheckState sizeIsRelative READ sizeIsRelative WRITE setSizeIsRelative) 55 #endif 56 57 public: 58 /** 59 * Displayed columns. 60 */ 61 enum FontColumn { 62 FamilyList = 0x01, ///< Identifies the family (leftmost) list. 63 StyleList = 0x02, ///< Identifies the style (center) list. 64 SizeList = 0x04, ///< Identifies the size (rightmost) list. 65 }; 66 67 /** 68 * Flags for selecting which font attributes to change 69 * @see FontDiffFlags 70 */ 71 enum FontDiff { 72 NoFontDiffFlags = 0, ///< No flags set 73 FontDiffFamily = 1, ///< Identifies a requested change in the font family. 74 FontDiffStyle = 2, ///< Identifies a requested change in the font style. 75 FontDiffSize = 4, ///< Identifies a requested change in the font size. 76 AllFontDiffs = FontDiffFamily | FontDiffStyle | FontDiffSize, 77 }; 78 /** 79 * Stores an combination of #FontDiff values. 80 */ 81 Q_DECLARE_FLAGS(FontDiffFlags, FontDiff) 82 83 /** 84 * Flags for selecting what is displayed in the widget. 85 * @see DisplayFlags 86 */ 87 enum DisplayFlag { 88 NoDisplayFlags = 0, ///< No flags set 89 FixedFontsOnly = 1, ///< Only show monospaced/fixed-width fonts, excluding proportional fonts, (the 90 ///< checkbox to toggle showing only monospaced fonts is not shown in this case) 91 DisplayFrame = 2, ///< Show a visual frame around the chooser 92 ShowDifferences = 4, ///< Display the font differences interfaces 93 }; 94 /** 95 * Stores a combination of #DisplayFlag values. 96 */ 97 Q_DECLARE_FLAGS(DisplayFlags, DisplayFlag) 98 99 #if KWIDGETSADDONS_ENABLE_DEPRECATED_SINCE(5, 86) 100 /** 101 * Constructs a font picker widget. 102 * 103 * @param parent The parent widget. 104 * @param flags Defines how the font chooser is displayed. 105 * @param fontList A list of fonts to display, in XLFD format. If 106 * no list is formatted, the internal KDE font list is used. 107 * If that has not been created, X is queried, and all fonts 108 * available on the system are displayed. 109 * @param visibleListSize The minimum number of visible entries in the 110 * fontlists. 111 * @param sizeIsRelativeState If not zero the widget will show a 112 * checkbox where the user may choose whether the font size 113 * is to be interpreted as relative size. 114 * Initial state of this checkbox will be set according to 115 * *sizeIsRelativeState, user choice may be retrieved by 116 * calling sizeIsRelative(). 117 * 118 * @deprecated since 5.86, use the KFontChooser(KFontChooser::DisplayFlags, QWidget*) constructor 119 * and the setFontListItems() and setMinVisibleItems() methods. 120 */ 121 KWIDGETSADDONS_DEPRECATED_VERSION( 122 5, 123 86, 124 "Use the KFontChooser(KFontChooser::DisplayFlags, QWidget*) constructor and the setFontListItems() and setMinVisibleItems() methods.") 125 explicit KFontChooser(QWidget *parent, 126 const DisplayFlags &flags, 127 const QStringList &fontList = QStringList(), 128 int visibleListSize = 8, 129 Qt::CheckState *sizeIsRelativeState = nullptr); 130 #endif 131 132 /** 133 * Constructs a font picker widget. 134 * 135 * @param parent the parent widget 136 * 137 * @since 5.86 138 */ 139 explicit KFontChooser(QWidget *parent = nullptr); 140 141 /** 142 * Create a font picker widget. 143 * 144 * @param flags a combination of OR-ed values from the @c KFontChooser::DisplayFlags enum, 145 * the default is @c DisplayFonts::NoDisplayFlags 146 * @param parent the parent widget, if not nullptr the windowing system will use it to position 147 * the chooser widget relative to it 148 * 149 * @since 5.86 150 */ 151 explicit KFontChooser(DisplayFlags flags, QWidget *parent = nullptr); 152 153 /** 154 * Destructor. 155 */ 156 ~KFontChooser() override; 157 158 /** 159 * Enables or disables a column (family, style, size) in the widget. 160 * 161 * Use this function if your application does not need or support all font properties. 162 * 163 * @param column specify the column(s) to enable/disable, an OR-ed combination of 164 * @c KFontChooser::FontColumn enum values 165 * @param state if @p false the columns are disabled, and vice-versa 166 */ 167 void enableColumn(int column, bool state); 168 169 /** 170 * Sets the currently selected font in the widget. 171 * 172 * @param font the font to select 173 * @param onlyFixed if @c true, the font list will only display fixed-width fonts, 174 * otherwise all fonts are displayed. The default is @c false. 175 */ 176 void setFont(const QFont &font, bool onlyFixed = false); 177 178 /** 179 * Returns the bitmask corresponding to the attributes the user wishes to change. 180 */ 181 FontDiffFlags fontDiffFlags() const; 182 183 /** 184 * Returns the currently selected font in the chooser. 185 */ 186 QFont font() const; 187 188 /** 189 * Sets the color to use for the font in the preview area. 190 */ 191 void setColor(const QColor &col); 192 193 /** 194 * Returns the color currently used for the font in the preview 195 * area (default: the text color of the active color group). 196 */ 197 QColor color() const; 198 199 /** 200 * Sets the background color to use in the preview area. 201 */ 202 void setBackgroundColor(const QColor &col); 203 204 /** 205 * Returns the background color currently used in the preview area 206 * (default: the base color of the active colorgroup) 207 */ 208 QColor backgroundColor() const; 209 210 #if KWIDGETSADDONS_ENABLE_DEPRECATED_SINCE(5, 86) 211 /** 212 * Sets the state of the checkbox indicating whether the font size 213 * is to be interpreted as relative size. 214 * @note If parameter @p sizeIsRelative was not set in the constructor 215 * of the widget this setting will be ignored. 216 * 217 * @deprecated Since 5.86, for lack of usage. 218 */ 219 KWIDGETSADDONS_DEPRECATED_VERSION(5, 86, "For lack of usage.") 220 void setSizeIsRelative(Qt::CheckState relative); 221 #endif 222 223 #if KWIDGETSADDONS_ENABLE_DEPRECATED_SINCE(5, 86) 224 /** 225 * @return whether the font size is to be interpreted as relative size 226 * 227 * @deprecated Since 5.86, for lack of usage. 228 */ 229 KWIDGETSADDONS_DEPRECATED_VERSION(5, 86, "For lack of usage.") 230 Qt::CheckState sizeIsRelative() const; 231 #endif 232 233 /** 234 * @return The current text in the sample text input area. 235 */ 236 QString sampleText() const; 237 238 /** 239 * Sets the sample text in the preview area; this is useful if you 240 * want to use text in your native language. 241 * 242 * @param text the new sample text (it will replace the current text) 243 */ 244 void setSampleText(const QString &text); 245 246 /** 247 * If @p visible is @c true the preview area will be shown, and vice-versa 248 * is it's @c false. 249 */ 250 void setSampleBoxVisible(bool visible); 251 252 /** 253 * The selection criteria for the font families shown in the dialog. 254 */ 255 enum FontListCriteria { 256 /** 257 * If set, only show fixed fixed-width (monospace) fonts. 258 */ 259 FixedWidthFonts = 0x01, 260 /** 261 * If set, only show scalable fonts. 262 * Certain configurations allow bitmap fonts to remain unscaled 263 * and thus these fonts have limited number of sizes. 264 */ 265 ScalableFonts = 0x02, 266 /** 267 * If set, only show smooth scalable fonts. 268 * This will return only non-bitmap fonts which are scalable to any size requested. 269 * Setting this option means the @c ScalableFonts flag is ignored. 270 */ 271 SmoothScalableFonts = 0x04 272 }; 273 274 #if KWIDGETSADDONS_ENABLE_DEPRECATED_SINCE(5, 86) 275 /** 276 * Creates a list of font strings. 277 * 278 * @param list The list is returned here. 279 * @param fontListCriteria should contain all the restrictions for font selection as OR-ed values 280 * from KFontChooser::FontListCriteria 281 * 282 * @deprecated since 5.86, use createFontList(uint) instead. 283 */ 284 KWIDGETSADDONS_DEPRECATED_VERSION(5, 86, "Use KFontChooser::createFontList(uint) instead.") 285 static void getFontList(QStringList &list, uint fontListCriteria); 286 #endif 287 288 /** 289 * Returns a list of font faimly name strings filtered based on @p fontListCriteria. 290 * 291 * @param fontListCriteria specifies the criteria used to select fonts to add to 292 * the list, a combination of OR-ed values from @ref KFontChooser::FontListCriteria 293 * 294 * @since 5.86 295 */ 296 static QStringList createFontList(uint fontListCriteria); 297 298 /** 299 * Uses @p fontList to fill the font family list in the widget. 300 * 301 * You can create a custom list of fonts using the static @c createFontList(uint 302 * criteria) to only include fonts that meet certain criteria (e.g. only 303 * smooth-scalable fonts). 304 * 305 * @see KFontChooser::createFontList(uint), KFontChooser::FontListCriteria 306 * 307 * Note that if @p fontList is empty, the font list in the chooser will show 308 * all the available fonts on the system. 309 * @since 5.86 310 */ 311 void setFontListItems(const QStringList &fontList); 312 313 /** 314 * Sets the minimum number of items that should be visible in the 315 * child list widgets; this number will be used to compute and set 316 * the minimum heights for those widgets. 317 * 318 * @since 5.86 319 */ 320 void setMinVisibleItems(int visibleItems); 321 322 /** 323 * Reimplemented for internal reasons. 324 */ 325 QSize sizeHint(void) const override; 326 327 Q_SIGNALS: 328 /** 329 * Emitted when the selected font changes. 330 */ 331 void fontSelected(const QFont &font); 332 333 private: 334 std::unique_ptr<class KFontChooserPrivate> const d; 335 336 Q_DISABLE_COPY(KFontChooser) 337 }; 338 339 Q_DECLARE_OPERATORS_FOR_FLAGS(KFontChooser::DisplayFlags) 340 341 #endif 342