home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / kwordwrap.h < prev    next >
Encoding:
C/C++ Source or Header  |  2005-10-10  |  5.5 KB  |  150 lines
  1. /* This file is part of the KDE libraries
  2.    Copyright (C) 2001 David Faure <david@mandrakesoft.com>
  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 <qfontmetrics.h>
  23. #include <qvaluelist.h>
  24. #include <qrect.h>
  25. #include <qstring.h>
  26.  
  27. #include <kdelibs_export.h>
  28.  
  29. /**
  30.  * Word-wrap algorithm that takes into account beautifulness ;)
  31.  *
  32.  * That means:
  33.  * @li not letting a letter alone on the last line,
  34.  * @li breaking at punctuation signs (not only at spaces)
  35.  * @li improved handling of (), [] and {}
  36.  * @li improved handling of '/' (e.g. for paths)
  37.  *
  38.  * Usage: call the static method, formatText, with the text to
  39.  * wrap and the constraining rectangle etc., it will return an instance of KWordWrap
  40.  * containing internal data, result of the word-wrapping.
  41.  * From that instance you can retrieve the boundingRect, and invoke drawing.
  42.  *
  43.  * This design allows to call the word-wrap algorithm only when the text changes
  44.  * and not every time we want to know the bounding rect or draw the text.
  45.  *
  46.  * @author David Faure <faure@kde.org>
  47.  */
  48. class KDEUI_EXPORT KWordWrap
  49. {
  50. public:
  51.     /**
  52.      * Use this flag in drawText() if you want to fade out the text if it does
  53.      * not fit into the constraining rectangle.
  54.      * @since 3.2
  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 );
  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 { return m_boundingRect; }
  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::AlignAuto ) 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.      * @since 3.2
  122.      */
  123.     static void drawFadeoutText( QPainter *p, int x, int y, int maxW,
  124.                                  const QString &t );
  125.  
  126.     /**
  127.      * Draws the string @p t at the given coordinates, if it does not
  128.      * @p fit into @p maxW the text will be truncated.
  129.      * @param p the painter to use
  130.      * @param x the horizontal position of the text
  131.      * @param y the vertical position of the text
  132.      * @param maxW the maximum width of the text (including the '...')
  133.      * @param t the text to draw
  134.      * @since 3.3
  135.      */
  136.     static void drawTruncateText( QPainter *p, int x, int y, int maxW,
  137.                                   const QString &t );
  138.  
  139. private:
  140.     KWordWrap( const QRect & r );
  141.     QValueList<int> m_breakPositions;
  142.     QValueList<int> m_lineWidths;
  143.     QRect m_boundingRect;
  144.     QString m_text;
  145. private:
  146.     class KWordWrapPrivate* d;
  147. };
  148.  
  149. #endif
  150.