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