interface/wx/richtext/richtextprint.h

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