interface/wx/textwrapper.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/textwrapper.h
   3 // Purpose:     documentation of wxTextWrapper interface
   4 // Author:      Vadim Zeitlin
   5 // RCS-ID:      $Id$
   6 // Copyright:   (c) 2009 Vadim Zeitlin <vadim@wxwidgets.org>
   7 // Licence:     wxWindows licence
   8 /////////////////////////////////////////////////////////////////////////////
   9
  10 /**
  11     @class wxTextWrapper
  12
  13     Helps wrap lines of text to given width.
  14
  15     This is a generic purpose class which can be used to wrap lines of text to
  16     the specified width. It doesn't do anything by itself but simply calls its
  17     virtual OnOutputLine() and OnNewLine() methods for each wrapped line of
  18     text, you need to implement them in your derived class to actually do
  19     something useful.
  20
  21     Here is an example function using this class which inserts hard line breaks
  22     into a string of text at the positions where it would be wrapped:
  23
  24     @code
  25     wxString WrapText(wxWindow *win, const wxString& text, int widthMax)
  26     {
  27         class HardBreakWrapper : public wxTextWrapper
  28         {
  29         public:
  30             HardBreakWrapper(wxWindow *win, const wxString& text, int widthMax)
  31             {
  32                 Wrap(win, text, widthMax);
  33             }
  34
  35             wxString const& GetWrapped() const { return m_wrapped; }
  36
  37         protected:
  38             virtual void OnOutputLine(const wxString& line)
  39             {
  40                 m_wrapped += line;
  41             }
  42
  43             virtual void OnNewLine()
  44             {
  45                 m_wrapped += '\n';
  46             }
  47
  48         private:
  49             wxString m_wrapped;
  50         };
  51
  52         HardBreakWrapper wrapper(win, text, widthMax);
  53         return wrapper.GetWrapped();
  54     }
  55     @endcode
  56
  57     @nolibrary
  58     @category{gdi}
  59  */
  60 class wxTextWrapper
  61 {
  62 public:
  63     /**
  64         Trivial default constructor.
  65      */
  66     wxTextWrapper();
  67
  68     /**
  69         Wrap the given text.
  70
  71         This method will call OnOutputLine() for every line of wrapped text and
  72         OnNewLine() before the beginning of every new line after the first one
  73         (so it might be never called at all if the width of entire @a text is
  74         less than @a widthMax).
  75
  76         @param win
  77             A non-@NULL window used for measuring the text extents.
  78         @param text
  79             The text to wrap.
  80         @param widthMax
  81             Maximal width of each line of text or @c -1 to disable wrapping.
  82      */
  83     void Wrap(wxWindow *win, const wxString& text, int widthMax);
  84
  85 protected:
  86     /**
  87         Called by Wrap() for each wrapped line of text.
  88
  89         This method will always be called at least once by Wrap(). Notice that
  90         @a line may be empty if the text passed to Wrap() was empty itself.
  91      */
  92     virtual void OnOutputLine(const wxString& line) = 0;
  93
  94     /**
  95         Called at the start of each subsequent line of text by Wrap().
  96
  97         This method may not be called at all if the entire text passed to
  98         Wrap() fits into the specified width.
  99      */
 100     virtual void OnNewLine();
 101 };