interface/richtext/richtextprint.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        richtext/richtextprint.h
   3 // Purpose:     documentation for wxRichTextHeaderFooterData class
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxRichTextHeaderFooterData
  11     @headerfile richtextprint.h wx/richtext/richtextprint.h
  12
  13
  14     This class represents header and footer data to be passed to the
  15     wxRichTextPrinting and
  16     wxRichTextPrintout classes.
  17
  18     Headers and footers can be specified independently for odd, even or both page
  19     sides. Different text can be specified
  20     for left, centre and right locations on the page, and the font and text colour
  21     can also
  22     be specified. You can specify the following keywords in header and footer text,
  23     which will
  24     be substituted for the actual values during printing and preview.
  25
  26      @DATE@: the current date.
  27      @PAGESCNT@: the total number of pages.
  28      @PAGENUM@: the current page number.
  29      @TIME@: the current time.
  30      @TITLE@: the title of the document, as passed to the wxRichTextPrinting or
  31     wxRichTextLayout constructor.
  32
  33     @library{wxrichtext}
  34     @category{FIXME}
  35 */
  36 class wxRichTextHeaderFooterData : public wxObject
  37 {
  38 public:
  39     //@{
  40     /**
  41         Constructors.
  42     */
  43     wxRichTextHeaderFooterData();
  44     wxRichTextHeaderFooterData(const wxRichTextHeaderFooterData& data);
  45     //@}
  46
  47     /**
  48         Clears all text.
  49     */
  50     void Clear();
  51
  52     /**
  53         Copies the data.
  54     */
  55     void Copy(const wxRichTextHeaderFooterData& data);
  56
  57     /**
  58         Returns the font specified for printing the header and footer.
  59     */
  60     const wxFont GetFont() const;
  61
  62     /**
  63         Returns the margin between the text and the footer.
  64     */
  65     int GetFooterMargin() const;
  66
  67     /**
  68         Returns the footer text on odd or even pages, and at a given position on the
  69         page (left, centre or right).
  70     */
  71     wxString GetFooterText(wxRichTextOddEvenPage page = wxRICHTEXT_PAGE_EVEN,
  72                            wxRichTextPageLocation location = wxRICHTEXT_PAGE_CENTRE) const;
  73
  74     /**
  75         Returns the margin between the text and the header.
  76     */
  77     int GetHeaderMargin() const;
  78
  79     /**
  80         Returns the header text on odd or even pages, and at a given position on the
  81         page (left, centre or right).
  82     */
  83     wxString GetHeaderText(wxRichTextOddEvenPage page = wxRICHTEXT_PAGE_EVEN,
  84                            wxRichTextPageLocation location = wxRICHTEXT_PAGE_CENTRE) const;
  85
  86     /**
  87         Returns @true if the header and footer will be shown on the first page.
  88     */
  89     bool GetShowOnFirstPage() const;
  90
  91     /**
  92         Helper function for getting the header or footer text, odd or even pages, and
  93         at a given position on the page (left, centre or right).
  94     */
  95     wxString GetText(int headerFooter, wxRichTextOddEvenPage page,
  96                      wxRichTextPageLocation location) const;
  97
  98     /**
  99         Returns the text colour for drawing the header and footer.
 100     */
 101     const wxColour GetTextColour() const;
 102
 103     /**
 104         Initialises the object.
 105     */
 106     void Init();
 107
 108     /**
 109         Sets the font for drawing the header and footer.
 110     */
 111     void SetFont(const wxFont& font);
 112
 113     /**
 114         Sets the footer text on odd or even pages, and at a given position on the page
 115         (left, centre or right).
 116     */
 117     void SetFooterText(const wxString& text,
 118                        wxRichTextOddEvenPage page = wxRICHTEXT_PAGE_ALL,
 119                        wxRichTextPageLocation location = wxRICHTEXT_PAGE_CENTRE);
 120
 121     /**
 122         Sets the header text on odd or even pages, and at a given position on the page
 123         (left, centre or right).
 124     */
 125     void SetHeaderText(const wxString& text,
 126                        wxRichTextOddEvenPage page = wxRICHTEXT_PAGE_ALL,
 127                        wxRichTextPageLocation location = wxRICHTEXT_PAGE_CENTRE);
 128
 129     /**
 130         Sets the margins between text and header or footer, in tenths of a millimeter.
 131     */
 132     void SetMargins(int headerMargin, int footerMargin);
 133
 134     /**
 135         Pass @true to show the header or footer on first page (the default).
 136     */
 137     void SetShowOnFirstPage(bool showOnFirstPage);
 138
 139     /**
 140         Helper function for setting the header or footer text, odd or even pages, and
 141         at a given position on the page (left, centre or right).
 142     */
 143     void SetText(const wxString& text, int headerFooter,
 144                  wxRichTextOddEvenPage page,
 145                  wxRichTextPageLocation location);
 146
 147     /**
 148         Sets the text colour for drawing the header and footer.
 149     */
 150     void SetTextColour(const wxColour& col);
 151
 152     /**
 153         Assignment operator.
 154     */
 155     void operator operator=(const wxRichTextHeaderFooterData& data);
 156 };
 157
 158
 159 /**
 160     @class wxRichTextPrintout
 161     @headerfile richtextprint.h wx/richtext/richtextprint.h
 162
 163     This class implements print layout for wxRichTextBuffer. Instead of using it
 164     directly, you
 165     should normally use the wxRichTextPrinting class.
 166
 167     @library{wxrichtext}
 168     @category{FIXME}
 169 */
 170 class wxRichTextPrintout : public wxPrintout
 171 {
 172 public:
 173     /**
 174         )
 175         Constructor.
 176     */
 177     wxRichTextPrintout();
 178
 179     /**
 180         Calculates scaling and text, header and footer rectangles.
 181     */
 182     void CalculateScaling(wxDC* dc, wxRect& textRect,
 183                           wxRect& headerRect,
 184                           wxRect& footerRect);
 185
 186     /**
 187         Returns the header and footer data associated with the printout.
 188     */
 189     const wxRichTextHeaderFooterData GetHeaderFooterData() const;
 190
 191     /**
 192         Gets the page information.
 193     */
 194     void GetPageInfo(int* minPage, int* maxPage, int* selPageFrom,
 195                      int* selPageTo);
 196
 197     /**
 198         Returns a pointer to the buffer being rendered.
 199     */
 200     wxRichTextBuffer* GetRichTextBuffer() const;
 201
 202     /**
 203         Returns @true if the given page exists in the printout.
 204     */
 205     bool HasPage(int page);
 206
 207     /**
 208         Prepares for printing, laying out the buffer and calculating pagination.
 209     */
 210     void OnPreparePrinting();
 211
 212     /**
 213         Does the actual printing for this page.
 214     */
 215     bool OnPrintPage(int page);
 216
 217     /**
 218         Sets the header and footer data associated with the printout.
 219     */
 220     void SetHeaderFooterData(const wxRichTextHeaderFooterData& data);
 221
 222     /**
 223         Sets margins in 10ths of millimetre. Defaults to 1 inch for margins.
 224     */
 225     void SetMargins(int top = 252, int bottom = 252, int left = 252,
 226                     int right = 252);
 227
 228     /**
 229         Sets the buffer to print. wxRichTextPrintout does not manage this pointer; it
 230         should
 231         be managed by the calling code, such as wxRichTextPrinting.
 232     */
 233     void SetRichTextBuffer(wxRichTextBuffer* buffer);
 234 };
 235
 236
 237 /**
 238     @class wxRichTextPrinting
 239     @headerfile richtextprint.h wx/richtext/richtextprint.h
 240
 241     This class provides a simple interface for performing wxRichTextBuffer printing
 242     and previewing. It uses wxRichTextPrintout for layout and rendering.
 243
 244     @library{wxrichtext}
 245     @category{FIXME}
 246 */
 247 class wxRichTextPrinting : public wxObject
 248 {
 249 public:
 250     /**
 251         , @b wxWindow*@e parentWindow = @NULL)
 252         Constructor. Optionally pass a title to be used in the preview frame and
 253         printing wait dialog, and
 254         also a parent window for these windows.
 255     */
 256     wxRichTextPrinting();
 257
 258     /**
 259         A convenience function to get the footer text. See wxRichTextHeaderFooterData
 260         for details.
 261     */
 262     wxString GetFooterText(wxRichTextOddEvenPage page = wxRICHTEXT_PAGE_EVEN,
 263                            wxRichTextPageLocation location = wxRICHTEXT_PAGE_CENTRE) const;
 264
 265     /**
 266         Returns the internal wxRichTextHeaderFooterData object.
 267     */
 268     const wxRichTextHeaderFooterData GetHeaderFooterData() const;
 269
 270     /**
 271         A convenience function to get the header text. See wxRichTextHeaderFooterData
 272         for details.
 273     */
 274     wxString GetHeaderText(wxRichTextOddEvenPage page = wxRICHTEXT_PAGE_EVEN,
 275                            wxRichTextPageLocation location = wxRICHTEXT_PAGE_CENTRE) const;
 276
 277     /**
 278         Returns a pointer to the internal page setup data.
 279     */
 280     wxPageSetupDialogData* GetPageSetupData();
 281
 282     /**
 283         Returns the parent window to be used for the preview window and printing wait
 284         dialog.
 285     */
 286     wxWindow* GetParentWindow() const;
 287
 288     /**
 289         Returns the dimensions to be used for the preview window.
 290     */
 291     const wxRect GetPreviewRect() const;
 292
 293     /**
 294         Returns a pointer to the internal print data.
 295     */
 296     wxPrintData* GetPrintData();
 297
 298     /**
 299         Returns the title of the preview window or printing wait caption.
 300     */
 301     const wxString GetTitle() const;
 302
 303     /**
 304         Shows the page setup dialog.
 305     */
 306     void PageSetup();
 307
 308     /**
 309         Shows a preview window for the given buffer. The function takes its own copy of
 310         @e buffer.
 311     */
 312     bool PreviewBuffer(const wxRichTextBuffer& buffer);
 313
 314     /**
 315         Shows a preview window for the given file. @a richTextFile can be a text file
 316         or XML file, or other file
 317         depending on the available file handlers.
 318     */
 319     bool PreviewFile(const wxString& richTextFile);
 320
 321     /**
 322         Prints the given buffer. The function takes its own copy of @e buffer.
 323     */
 324     bool PrintBuffer(const wxRichTextBuffer& buffer);
 325
 326     /**
 327         Prints the given file. @a richTextFile can be a text file or XML file, or other
 328         file
 329         depending on the available file handlers.
 330     */
 331     bool PrintFile(const wxString& richTextFile);
 332
 333     /**
 334         A convenience function to set the footer text. See wxRichTextHeaderFooterData
 335         for details.
 336     */
 337     void SetFooterText(const wxString& text,
 338                        wxRichTextOddEvenPage page = wxRICHTEXT_PAGE_ALL,
 339                        wxRichTextPageLocation location = wxRICHTEXT_PAGE_CENTRE);
 340
 341     /**
 342         Sets the internal wxRichTextHeaderFooterData object.
 343     */
 344     void SetHeaderFooterData(const wxRichTextHeaderFooterData& data);
 345
 346     /**
 347         Sets the wxRichTextHeaderFooterData font.
 348     */
 349     void SetHeaderFooterFont(const wxFont& font);
 350
 351     /**
 352         Sets the wxRichTextHeaderFooterData text colour.
 353     */
 354     void SetHeaderFooterTextColour(const wxColour& colour);
 355
 356     /**
 357         A convenience function to set the header text. See wxRichTextHeaderFooterData
 358         for details.
 359     */
 360     void SetHeaderText(const wxString& text,
 361                        wxRichTextOddEvenPage page = wxRICHTEXT_PAGE_ALL,
 362                        wxRichTextPageLocation location = wxRICHTEXT_PAGE_CENTRE);
 363
 364     /**
 365         Sets the page setup data.
 366     */
 367     void SetPageSetupData(const wxPageSetupData& pageSetupData);
 368
 369     /**
 370         Sets the parent window to be used for the preview window and printing wait
 371         dialog.
 372     */
 373     void SetParentWindow(wxWindow* parent);
 374
 375     /**
 376         Sets the dimensions to be used for the preview window.
 377     */
 378     void SetPreviewRect(const wxRect& rect);
 379
 380     /**
 381         Sets the print data.
 382     */
 383     void SetPrintData(const wxPrintData& printData);
 384
 385     /**
 386         Pass @true to show the header and footer on the first page.
 387     */
 388     void SetShowOnFirstPage(bool show);
 389
 390     /**
 391         Pass the title of the preview window or printing wait caption.
 392     */
 393     void SetTitle(const wxString& title);
 394 };