juce/source/src/gui/graphics/fonts/juce_TextLayout.h

   1 /*
   2   ==============================================================================
   3
   4    This file is part of the JUCE library - "Jules' Utility Class Extensions"
   5    Copyright 2004-11 by Raw Material Software Ltd.
   6
   7   ------------------------------------------------------------------------------
   8
   9    JUCE can be redistributed and/or modified under the terms of the GNU General
  10    Public License (Version 2), as published by the Free Software Foundation.
  11    A copy of the license is included in the JUCE distribution, or can be found
  12    online at www.gnu.org/licenses.
  13
  14    JUCE is distributed in the hope that it will be useful, but WITHOUT ANY
  15    WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
  16    A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
  17
  18   ------------------------------------------------------------------------------
  19
  20    To release a closed-source product which uses JUCE, commercial licenses are
  21    available: visit www.rawmaterialsoftware.com/juce for more information.
  22
  23   ==============================================================================
  24 */
  25
  26 #ifndef __JUCE_TEXTLAYOUT_JUCEHEADER__
  27 #define __JUCE_TEXTLAYOUT_JUCEHEADER__
  28
  29 #include "juce_Font.h"
  30 #include "../contexts/juce_Justification.h"
  31 #include "../../../containers/juce_OwnedArray.h"
  32 class Graphics;
  33
  34
  35 //==============================================================================
  36 /**
  37     A laid-out arrangement of text.
  38
  39     You can add text in different fonts to a TextLayout object, then call its
  40     layout() method to word-wrap it into lines. The layout can then be drawn
  41     using a graphics context.
  42
  43     It's handy if you've got a message to display, because you can format it,
  44     measure the extent of the layout, and then create a suitably-sized window
  45     to show it in.
  46
  47     @see Font, Graphics::drawFittedText, GlyphArrangement
  48 */
  49 class JUCE_API  TextLayout
  50 {
  51 public:
  52     //==============================================================================
  53     /** Creates an empty text layout.
  54
  55         Text can then be appended using the appendText() method.
  56     */
  57     TextLayout();
  58
  59     /** Creates a copy of another layout object. */
  60     TextLayout (const TextLayout& other);
  61
  62     /** Creates a text layout from an initial string and font. */
  63     TextLayout (const String& text, const Font& font);
  64
  65     /** Destructor. */
  66     ~TextLayout();
  67
  68     /** Copies another layout onto this one. */
  69     TextLayout& operator= (const TextLayout& layoutToCopy);
  70
  71     //==============================================================================
  72     /** Clears the layout, removing all its text. */
  73     void clear();
  74
  75     /** Adds a string to the end of the arrangement.
  76
  77         The string will be broken onto new lines wherever it contains
  78         carriage-returns or linefeeds. After adding it, you can call layout()
  79         to wrap long lines into a paragraph and justify it.
  80     */
  81     void appendText (const String& textToAppend,
  82                      const Font& fontToUse);
  83
  84     /** Replaces all the text with a new string.
  85
  86         This is equivalent to calling clear() followed by appendText().
  87     */
  88     void setText (const String& newText,
  89                   const Font& fontToUse);
  90
  91     /** Returns true if the layout has not had any text added yet. */
  92     bool isEmpty() const;
  93
  94     //==============================================================================
  95     /** Breaks the text up to form a paragraph with the given width.
  96
  97         @param maximumWidth                 any text wider than this will be split
  98                                             across multiple lines
  99         @param justification                how the lines are to be laid-out horizontally
 100         @param attemptToBalanceLineLengths  if true, it will try to split the lines at a
 101                                             width that keeps all the lines of text at a
 102                                             similar length - this is good when you're displaying
 103                                             a short message and don't want it to get split
 104                                             onto two lines with only a couple of words on
 105                                             the second line, which looks untidy.
 106     */
 107     void layout (int maximumWidth,
 108                  const Justification& justification,
 109                  bool attemptToBalanceLineLengths);
 110
 111
 112     //==============================================================================
 113     /** Returns the overall width of the entire text layout. */
 114     int getWidth() const;
 115
 116     /** Returns the overall height of the entire text layout. */
 117     int getHeight() const;
 118
 119     /** Returns the total number of lines of text. */
 120     int getNumLines() const                     { return totalLines; }
 121
 122     /** Returns the width of a particular line of text.
 123
 124         @param lineNumber   the line, from 0 to (getNumLines() - 1)
 125     */
 126     int getLineWidth (int lineNumber) const;
 127
 128     //==============================================================================
 129     /** Renders the text at a specified position using a graphics context.
 130     */
 131     void draw (Graphics& g, int topLeftX, int topLeftY) const;
 132
 133     /** Renders the text within a specified rectangle using a graphics context.
 134
 135         The justification flags dictate how the block of text should be positioned
 136         within the rectangle.
 137     */
 138     void drawWithin (Graphics& g,
 139                      int x, int y, int w, int h,
 140                      const Justification& layoutFlags) const;
 141
 142
 143 private:
 144     //==============================================================================
 145     class Token;
 146     friend class OwnedArray <Token>;
 147     OwnedArray <Token> tokens;
 148     int totalLines;
 149
 150     JUCE_LEAK_DETECTOR (TextLayout);
 151 };
 152
 153
 154 #endif   // __JUCE_TEXTLAYOUT_JUCEHEADER__