extracted wxTextWrapper in its own header and made it public

[wxWidgets.git] / interface / wx / textwrapper.h

diff --git a/interface/wx/textwrapper.h b/interface/wx/textwrapper.h
new file mode 100644 (file)
index 0000000..dd830ed
--- /dev/null
+++ b/interface/wx/textwrapper.h
@@ -0,0 +1,100 @@
+/////////////////////////////////////////////////////////////////////////////
+// Name:        wx/textwrapper.h
+// Purpose:     documentation of wxTextWrapper interface
+// Author:      Vadim Zeitlin
+// RCS-ID:      $Id$
+// Copyright:   (c) 2009 Vadim Zeitlin <vadim@wxwidgets.org>
+// Licence:     wxWindows license
+/////////////////////////////////////////////////////////////////////////////
+
+/**
+    @class wxTextWrapper
+
+    Helps wrap lines of text to given width.
+
+    This is a generic purpose class which can be used to wrap lines of text to
+    the specified width. It doesn't do anything by itself but simply calls its
+    virtual OnOutputLine() and OnNewLine() methods for each wrapped line of
+    text, you need to implement them in your derived class to actually do
+    something useful.
+
+    Here is an example function using this class which inserts hard line breaks
+    into a string of text at the positions where it would be wrapped:
+    @code
+wxString WrapText(wxWindow *win, const wxString& text, int widthMax)
+{
+    class HardBreakWrapper : public wxTextWrapper
+    {
+    public:
+        HardBreakWrapper(wxWindow *win, const wxString& text, int widthMax)
+        {
+            Wrap(win, text, widthMax);
+        }
+
+        wxString const& GetWrapped() const { return m_wrapped; }
+
+    protected:
+        virtual void OnOutputLine(const wxString& line)
+        {
+            m_wrapped += line;
+        }
+
+        virtual void OnNewLine()
+        {
+            m_wrapped += '\n';
+        }
+
+    private:
+        wxString m_wrapped;
+    };
+
+    HardBreakWrapper wrapper(win, text, widthMax);
+    return wrapper.GetWrapped();
+}
+    @endcode
+
+    @library{none}
+    @category{gdi}
+ */
+class wxTextWrapper
+{
+public:
+    /**
+        Trivial default constructor.
+     */
+    wxTextWrapper();
+
+    /**
+        Wrap the given text.
+
+        This method will call OnOutputLine() for every line of wrapped text and
+        OnNewLine() before the beginning of every new line after the first one
+        (so it might be never called at all if the width of entire @a text is
+        less than @a widthMax).
+
+        @param win
+            A non-@NULL window used for measuring the text extents.
+        @param text
+            The text to wrap.
+        @param widthMax
+            Maximal width of each line of text or @c -1 to disable wrapping.
+     */
+    void Wrap(wxWindow *win, const wxString& text, int widthMax);
+
+protected:
+    /**
+        Called by Wrap() for each wrapped line of text.
+
+        This method will always be called at least once by Wrap(). Notice that
+        @a line may be empty if the text passed to Wrap() was empty itself.
+     */
+    virtual void OnOutputLine(const wxString& line) = 0;
+
+    /**
+        Called at the start of each subsequent line of text by Wrap().
+
+        This method may not be called at all if the entire text passed to
+        Wrap() fits into the specified width.
+     */
+    virtual void OnNewLine();
+};