1 | /* This file is part of the KDE libraries |
2 | Copyright (C) 2001 David Faure <faure@kde.org> |
3 | |
4 | This library is free software; you can redistribute it and/or |
5 | modify it under the terms of the GNU Library General Public |
6 | License version 2 as published by the Free Software Foundation. |
7 | |
8 | This library is distributed in the hope that it will be useful, |
9 | but WITHOUT ANY WARRANTY; without even the implied warranty of |
10 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
11 | Library General Public License for more details. |
12 | |
13 | You should have received a copy of the GNU Library General Public License |
14 | along with this library; see the file COPYING.LIB. If not, write to |
15 | the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, |
16 | Boston, MA 02110-1301, USA. |
17 | */ |
18 | |
19 | #ifndef kwordwrap_h |
20 | #define kwordwrap_h |
21 | |
22 | #include <kdeui_export.h> |
23 | #include <QtCore/Qt> |
24 | |
25 | class QFontMetrics; |
26 | class QRect; |
27 | class QString; |
28 | class QPainter; |
29 | |
30 | /** |
31 | * Word-wrap algorithm that takes into account beautifulness ;) |
32 | * |
33 | * That means: |
34 | * @li not letting a letter alone on the last line, |
35 | * @li breaking at punctuation signs (not only at spaces) |
36 | * @li improved handling of (), [] and {} |
37 | * @li improved handling of '/' (e.g. for paths) |
38 | * |
39 | * Usage: call the static method, formatText, with the text to |
40 | * wrap and the constraining rectangle etc., it will return an instance of KWordWrap |
41 | * containing internal data, result of the word-wrapping. |
42 | * From that instance you can retrieve the boundingRect, and invoke drawing. |
43 | * |
44 | * This design allows to call the word-wrap algorithm only when the text changes |
45 | * and not every time we want to know the bounding rect or draw the text. |
46 | * |
47 | * @author David Faure <faure@kde.org> |
48 | */ |
49 | class KDEUI_EXPORT KWordWrap |
50 | { |
51 | public: |
52 | /** |
53 | * Use this flag in drawText() if you want to fade out the text if it does |
54 | * not fit into the constraining rectangle. |
55 | */ |
56 | enum { FadeOut = 0x10000000, Truncate = 0x20000000 }; |
57 | |
58 | /** |
59 | * Main method for wrapping text. |
60 | * |
61 | * @param fm Font metrics, for the chosen font. Better cache it, creating a QFontMetrics is expensive. |
62 | * @param r Constraining rectangle. Only the width and height matter. With |
63 | * negative height the complete text will be rendered |
64 | * @param flags currently unused |
65 | * @param str The text to be wrapped. |
66 | * @param len Length of text to wrap (default is -1 for all). |
67 | * @return a KWordWrap instance. The caller is responsible for storing and deleting the result. |
68 | */ |
69 | static KWordWrap* formatText( QFontMetrics &fm, const QRect & r, int flags, const QString & str, int len = -1 ); // KDE5 TODO: return a value, not a pointer, and use QSharedDataPointer. |
70 | |
71 | /** |
72 | * @return the bounding rect, calculated by formatText. The width is the |
73 | * width of the widest text line, and never wider than |
74 | * the rectangle given to formatText. The height is the |
75 | * text block. X and Y are always 0. |
76 | */ |
77 | QRect boundingRect() const; |
78 | |
79 | /** |
80 | * @return the original string, with '\n' inserted where |
81 | * the text is broken by the wordwrap algorithm. |
82 | */ |
83 | QString wrappedString() const; // gift for Dirk :) |
84 | |
85 | /** |
86 | * @return the original string, truncated to the first line. |
87 | * If @p dots was set, '...' is appended in case the string was truncated. |
88 | * Bug: Note that the '...' come out of the bounding rect. |
89 | */ |
90 | QString truncatedString( bool dots = true ) const; |
91 | |
92 | /** |
93 | * Draw the text that has been previously wrapped, at position x,y. |
94 | * Flags are for alignment, e.g. Qt::AlignHCenter. Default is |
95 | * Qt::AlignAuto. |
96 | * @param painter the QPainter to use. |
97 | * @param x the horizontal position of the text |
98 | * @param y the vertical position of the text |
99 | * @param flags the ORed text alignment flags from the Qt namespace, |
100 | * ORed with FadeOut if you want the text to fade out if it |
101 | * does not fit (the @p painter's background must be set |
102 | * accordingly) |
103 | */ |
104 | void drawText( QPainter *painter, int x, int y, int flags = Qt::AlignLeft ) const; |
105 | |
106 | /** |
107 | * Destructor. |
108 | */ |
109 | ~KWordWrap(); |
110 | |
111 | /** |
112 | * Draws the string @p t at the given coordinates, if it does not |
113 | * @p fit into @p maxW the text will be faded out. |
114 | * @param p the painter to use. Must have set the pen for the text |
115 | * color and the background for the color to fade out |
116 | * @param x the horizontal position of the text |
117 | * @param y the vertical position of the text |
118 | * @param maxW the maximum width of the text (including the fade-out |
119 | * effect) |
120 | * @param t the text to draw |
121 | */ |
122 | static void drawFadeoutText( QPainter *p, int x, int y, int maxW, |
123 | const QString &t ); |
124 | |
125 | /** |
126 | * Draws the string @p t at the given coordinates, if it does not |
127 | * @p fit into @p maxW the text will be truncated. |
128 | * @param p the painter to use |
129 | * @param x the horizontal position of the text |
130 | * @param y the vertical position of the text |
131 | * @param maxW the maximum width of the text (including the '...') |
132 | * @param t the text to draw |
133 | */ |
134 | static void drawTruncateText( QPainter *p, int x, int y, int maxW, |
135 | const QString &t ); |
136 | |
137 | private: |
138 | Q_DISABLE_COPY( KWordWrap ) |
139 | KWordWrap( const QRect & r ); |
140 | class KWordWrapPrivate* const d; |
141 | }; |
142 | |
143 | #endif |
144 | |