File indexing completed on 2024-03-24 15:28:42
0001 /* This file is part of the KDE libraries 0002 SPDX-FileCopyrightText: 2001 David Faure <faure@kde.org> 0003 0004 SPDX-License-Identifier: LGPL-2.0-or-later 0005 */ 0006 0007 #ifndef kwordwrap_h 0008 #define kwordwrap_h 0009 0010 #include <kguiaddons_export.h> 0011 0012 #include <QSharedDataPointer> 0013 #include <qnamespace.h> 0014 0015 class QFontMetrics; 0016 class QRect; 0017 class QString; 0018 class QPainter; 0019 class KWordWrapPrivate; 0020 0021 /** 0022 * @class KWordWrap kwordwrap.h KWordWrap 0023 * 0024 * Word-wrap algorithm that takes into account beautifulness ;) 0025 * 0026 * That means: 0027 * @li not letting a letter alone on the last line, 0028 * @li breaking at punctuation signs (not only at spaces) 0029 * @li improved handling of (), [] and {} 0030 * @li improved handling of '/' (e.g. for paths) 0031 * 0032 * Usage: call the static method, formatText, with the text to 0033 * wrap and the constraining rectangle etc., it will return an instance of KWordWrap 0034 * containing internal data, result of the word-wrapping. 0035 * From that instance you can retrieve the boundingRect, and invoke drawing. 0036 * 0037 * This design allows to call the word-wrap algorithm only when the text changes 0038 * and not every time we want to know the bounding rect or draw the text. 0039 * 0040 * @author David Faure <faure@kde.org> 0041 */ 0042 class KGUIADDONS_EXPORT KWordWrap 0043 { 0044 public: 0045 /** 0046 * Use this flag in drawText() if you want to fade out the text if it does 0047 * not fit into the constraining rectangle. 0048 */ 0049 enum { 0050 FadeOut = 0x10000000, 0051 Truncate = 0x20000000, 0052 }; 0053 0054 /** 0055 * Main method for wrapping text. 0056 * 0057 * @param fm Font metrics, for the chosen font. Better cache it, creating a QFontMetrics is expensive. 0058 * @param r Constraining rectangle. Only the width and height matter. With 0059 * negative height the complete text will be rendered 0060 * @param flags currently unused 0061 * @param str The text to be wrapped. 0062 * @param len Length of text to wrap (default is -1 for all). 0063 * @return a KWordWrap instance. The caller is responsible for storing and deleting the result. 0064 */ 0065 static KWordWrap formatText(QFontMetrics &fm, const QRect &r, int flags, const QString &str, int len = -1); 0066 0067 /** 0068 * @return the bounding rect, calculated by formatText. The width is the 0069 * width of the widest text line, and never wider than 0070 * the rectangle given to formatText. The height is the 0071 * text block. X and Y are always 0. 0072 */ 0073 QRect boundingRect() const; 0074 0075 /** 0076 * @return the original string, with '\n' inserted where 0077 * the text is broken by the wordwrap algorithm. 0078 */ 0079 QString wrappedString() const; // gift for Dirk :) 0080 0081 /** 0082 * @return the original string, truncated to the first line. 0083 * If @p dots was set, '...' is appended in case the string was truncated. 0084 * Bug: Note that the '...' come out of the bounding rect. 0085 */ 0086 QString truncatedString(bool dots = true) const; 0087 0088 /** 0089 * Draw the text that has been previously wrapped, at position x,y. 0090 * Flags are for alignment, e.g. Qt::AlignHCenter. Default is 0091 * Qt::AlignAuto. 0092 * @param painter the QPainter to use. 0093 * @param x the horizontal position of the text 0094 * @param y the vertical position of the text 0095 * @param flags the ORed text alignment flags from the Qt namespace, 0096 * ORed with FadeOut if you want the text to fade out if it 0097 * does not fit (the @p painter's background must be set 0098 * accordingly) 0099 */ 0100 void drawText(QPainter *painter, int x, int y, int flags = Qt::AlignLeft) const; 0101 0102 /** 0103 * Destructor. 0104 */ 0105 ~KWordWrap(); 0106 0107 /** 0108 * Copy constructor 0109 */ 0110 KWordWrap(const KWordWrap &other); 0111 /** 0112 * Assignment operator 0113 */ 0114 KWordWrap &operator=(const KWordWrap &other); 0115 0116 /** 0117 * Draws the string @p t at the given coordinates, if it does not 0118 * @p fit into @p maxW the text will be faded out. 0119 * @param p the painter to use. Must have set the pen for the text 0120 * color and the background for the color to fade out 0121 * @param x the horizontal position of the text 0122 * @param y the vertical position of the text 0123 * @param maxW the maximum width of the text (including the fade-out 0124 * effect) 0125 * @param t the text to draw 0126 */ 0127 static void drawFadeoutText(QPainter *p, int x, int y, int maxW, const QString &t); 0128 0129 /** 0130 * Draws the string @p t at the given coordinates, if it does not 0131 * @p fit into @p maxW the text will be truncated. 0132 * @param p the painter to use 0133 * @param x the horizontal position of the text 0134 * @param y the vertical position of the text 0135 * @param maxW the maximum width of the text (including the '...') 0136 * @param t the text to draw 0137 */ 0138 static void drawTruncateText(QPainter *p, int x, int y, int maxW, const QString &t); 0139 0140 private: 0141 KGUIADDONS_NO_EXPORT explicit KWordWrap(const QRect &r); 0142 0143 QExplicitlySharedDataPointer<KWordWrapPrivate> d; 0144 }; 0145 0146 #endif