interface/wx/cmndata.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        cmndata.h
   3 // Purpose:     interface of common wx*Data classes (font, colour, print)
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxFontData
  11
  12     This class holds a variety of information related to font dialogs.
  13
  14     @library{wxcore}
  15     @category{cmndlg}
  16
  17     @see @ref overview_cmndlg_font, wxFont, wxFontDialog
  18 */
  19 class wxFontData : public wxObject
  20 {
  21 public:
  22     /**
  23         Constructor. Initializes @e fontColour to black, @e showHelp to @false,
  24         @e allowSymbols to @true, @e enableEffects to @true, @e minSize to 0
  25         and @e maxSize to 0.
  26     */
  27     wxFontData();
  28
  29     /**
  30         Enables or disables "effects" under Windows or generic only. This
  31         refers to the controls for manipulating colour, strikeout and underline
  32         properties.
  33
  34         The default value is @true.
  35     */
  36     void EnableEffects(bool enable);
  37
  38     /**
  39         Under Windows, returns a flag determining whether symbol fonts can be
  40         selected. Has no effect on other platforms.
  41
  42         The default value is @true.
  43     */
  44     bool GetAllowSymbols() const;
  45
  46     /**
  47         Gets the font chosen by the user if the user pressed OK
  48         (wxFontDialog::ShowModal() returned wxID_OK).
  49     */
  50     wxFont GetChosenFont() const;
  51
  52     /**
  53         Gets the colour associated with the font dialog.
  54
  55         The default value is black.
  56     */
  57     const wxColour& GetColour() const;
  58
  59     /**
  60         Determines whether "effects" are enabled under Windows. This refers to
  61         the controls for manipulating colour, strikeout and underline
  62         properties.
  63
  64         The default value is @true.
  65     */
  66     bool GetEnableEffects() const;
  67
  68     /**
  69         Gets the font that will be initially used by the font dialog. This
  70         should have previously been set by the application.
  71     */
  72     wxFont GetInitialFont() const;
  73
  74     /**
  75         Returns @true if the Help button will be shown (Windows only).
  76
  77         The default value is @false.
  78     */
  79     bool GetShowHelp() const;
  80
  81     /**
  82         Under Windows, determines whether symbol fonts can be selected. Has no
  83         effect on other platforms.
  84
  85         The default value is @true.
  86     */
  87     void SetAllowSymbols(bool allowSymbols);
  88
  89     /**
  90         Sets the font that will be returned to the user (for internal use
  91         only).
  92     */
  93     void SetChosenFont(const wxFont& font);
  94
  95     /**
  96         Sets the colour that will be used for the font foreground colour.
  97
  98         The default colour is black.
  99     */
 100     void SetColour(const wxColour& colour);
 101
 102     /**
 103         Sets the font that will be initially used by the font dialog.
 104     */
 105     void SetInitialFont(const wxFont& font);
 106
 107     /**
 108         Sets the valid range for the font point size (Windows only).
 109
 110         The default is 0, 0 (unrestricted range).
 111     */
 112     void SetRange(int min, int max);
 113
 114     /**
 115         Determines whether the Help button will be displayed in the font dialog
 116         (Windows only).
 117
 118         The default value is @false.
 119     */
 120     void SetShowHelp(bool showHelp);
 121
 122     /**
 123         Assignment operator for the font data.
 124     */
 125     wxFontData& operator =(const wxFontData& data);
 126 };
 127
 128
 129
 130 /**
 131     @class wxPageSetupDialogData
 132
 133     This class holds a variety of information related to wxPageSetupDialog.
 134
 135     It contains a wxPrintData member which is used to hold basic printer
 136     configuration data (as opposed to the user-interface configuration settings
 137     stored by wxPageSetupDialogData).
 138
 139     @library{wxcore}
 140     @category{printing}
 141
 142     @see @ref overview_printing, wxPageSetupDialog
 143 */
 144 class wxPageSetupDialogData : public wxObject
 145 {
 146 public:
 147     /**
 148         Default constructor.
 149     */
 150     wxPageSetupDialogData();
 151
 152     /**
 153         Copy constructor.
 154     */
 155     wxPageSetupDialogData(const wxPageSetupDialogData& data);
 156
 157     /**
 158         Construct an object from a print data object.
 159     */
 160     wxPageSetupDialogData(const wxPrintData& printData);
 161
 162     /**
 163         Destructor.
 164     */
 165     virtual ~wxPageSetupDialogData();
 166
 167     /**
 168         Enables or disables the "Help" button (Windows only).
 169     */
 170     void EnableHelp(bool flag);
 171
 172     /**
 173         Enables or disables the margin controls (Windows only).
 174     */
 175     void EnableMargins(bool flag);
 176
 177     /**
 178         Enables or disables the orientation control (Windows only).
 179     */
 180     void EnableOrientation(bool flag);
 181
 182     /**
 183         Enables or disables the paper size control (Windows only).
 184     */
 185     void EnablePaper(bool flag);
 186
 187     /**
 188         Enables or disables the "Printer" button, which invokes a printer setup
 189         dialog.
 190     */
 191     void EnablePrinter(bool flag);
 192
 193     /**
 194         Returns @true if the dialog will simply return default printer
 195         information (such as orientation) instead of showing a dialog (Windows
 196         only).
 197     */
 198     bool GetDefaultInfo() const;
 199
 200     /**
 201         Returns @true if the page setup dialog will take its minimum margin
 202         values from the currently selected printer properties (Windows only).
 203     */
 204     bool GetDefaultMinMargins() const;
 205
 206     /**
 207         Returns @true if the printer setup button is enabled.
 208     */
 209     bool GetEnableHelp() const;
 210
 211     /**
 212         Returns @true if the margin controls are enabled (Windows only).
 213     */
 214     bool GetEnableMargins() const;
 215
 216     /**
 217         Returns @true if the orientation control is enabled (Windows only).
 218     */
 219     bool GetEnableOrientation() const;
 220
 221     /**
 222         Returns @true if the paper size control is enabled (Windows only).
 223     */
 224     bool GetEnablePaper() const;
 225
 226     /**
 227         Returns @true if the printer setup button is enabled.
 228     */
 229     bool GetEnablePrinter() const;
 230
 231     /**
 232         Returns the right (x) and bottom (y) margins in millimetres.
 233     */
 234     wxPoint GetMarginBottomRight() const;
 235
 236     /**
 237         Returns the left (x) and top (y) margins in millimetres.
 238     */
 239     wxPoint GetMarginTopLeft() const;
 240
 241     /**
 242         Returns the right (x) and bottom (y) minimum margins the user can enter
 243         (Windows only). Units are in millimetres.
 244     */
 245     wxPoint GetMinMarginBottomRight() const;
 246
 247     /**
 248         Returns the left (x) and top (y) minimum margins the user can enter
 249         (Windows only). Units are in millimetres.
 250     */
 251     wxPoint GetMinMarginTopLeft() const;
 252
 253     /**
 254         Returns the paper id (stored in the internal wxPrintData object).
 255
 256         @see wxPrintData::SetPaperId()
 257     */
 258     wxPaperSize GetPaperId() const;
 259
 260     /**
 261         Returns the paper size in millimetres.
 262     */
 263     wxSize GetPaperSize() const;
 264
 265     /**
 266         Returns a reference to the print data associated with this object.
 267     */
 268     wxPrintData& GetPrintData();
 269     const wxPrintData& GetPrintData() const;
 270
 271     /**
 272         Returns @true if the print data associated with the dialog data is
 273         valid. This can return @false on Windows if the current printer is not
 274         set, for example. On all other platforms, it returns @true.
 275     */
 276     bool IsOk() const;
 277
 278     /**
 279         Pass @true if the dialog will simply return default printer information
 280         (such as orientation) instead of showing a dialog (Windows only).
 281     */
 282     void SetDefaultInfo(bool flag);
 283
 284     /**
 285         Pass @true if the page setup dialog will take its minimum margin values
 286         from the currently selected printer properties (Windows only). Units
 287         are in millimetres.
 288     */
 289     void SetDefaultMinMargins(bool flag);
 290
 291     /**
 292         Sets the right (x) and bottom (y) margins in millimetres.
 293     */
 294     void SetMarginBottomRight(const wxPoint& pt);
 295
 296     /**
 297         Sets the left (x) and top (y) margins in millimetres.
 298     */
 299     void SetMarginTopLeft(const wxPoint& pt);
 300
 301     /**
 302         Sets the right (x) and bottom (y) minimum margins the user can enter
 303         (Windows only). Units are in millimetres.
 304     */
 305     void SetMinMarginBottomRight(const wxPoint& pt);
 306
 307     /**
 308         Sets the left (x) and top (y) minimum margins the user can enter
 309         (Windows only). Units are in millimetres.
 310     */
 311     void SetMinMarginTopLeft(const wxPoint& pt);
 312
 313     /**
 314         Sets the paper size id. Calling this function overrides the explicit
 315         paper dimensions passed in SetPaperSize().
 316
 317         @see wxPrintData::SetPaperId()
 318     */
 319     void SetPaperId(wxPaperSize id);
 320
 321     /**
 322         Sets the paper size in millimetres. If a corresponding paper id is
 323         found, it will be set in the internal wxPrintData object, otherwise the
 324         paper size overrides the paper id.
 325     */
 326     void SetPaperSize(const wxSize& size);
 327
 328     /**
 329         Sets the print data associated with this object.
 330     */
 331     void SetPrintData(const wxPrintData& printData);
 332
 333     /**
 334         Assigns print data to this object.
 335     */
 336     wxPageSetupDialogData& operator =(const wxPrintData& data);
 337
 338     /**
 339         Assigns page setup data to this object.
 340     */
 341     wxPageSetupDialogData& operator =(const wxPageSetupDialogData& data);
 342 };
 343
 344
 345
 346 /**
 347     @class wxColourData
 348
 349     This class holds a variety of information related to colour dialogs.
 350
 351     @library{wxcore}
 352     @category{cmndlg}
 353
 354     @see wxColour, wxColourDialog, @ref overview_cmndlg_colour
 355 */
 356 class wxColourData : public wxObject
 357 {
 358 public:
 359     /**
 360         Constructor. Initializes the custom colours to @c wxNullColour, the
 361         @e data colour setting to black, and the @e choose full setting to
 362         @true.
 363     */
 364     wxColourData();
 365
 366     /**
 367         Destructor.
 368     */
 369     virtual ~wxColourData();
 370
 371     /**
 372         Under Windows, determines whether the Windows colour dialog will
 373         display the full dialog with custom colour selection controls. Under
 374         PalmOS, determines whether colour dialog will display full rgb colour
 375         picker or only available palette indexer. Has no meaning under other
 376         platforms.
 377
 378         The default value is @true.
 379     */
 380     bool GetChooseFull() const;
 381
 382     /**
 383         Gets the current colour associated with the colour dialog.
 384
 385         The default colour is black.
 386     */
 387     wxColour& GetColour();
 388
 389     /**
 390         Returns custom colours associated with the colour dialog.
 391
 392         @param i
 393             An integer between 0 and 15, being any of the 15 custom colours
 394             that the user has saved. The default custom colours are invalid
 395             colours.
 396     */
 397     wxColour GetCustomColour(int i) const;
 398
 399     /**
 400         Under Windows, tells the Windows colour dialog to display the full
 401         dialog with custom colour selection controls. Under other platforms,
 402         has no effect.
 403
 404         The default value is @true.
 405     */
 406     void SetChooseFull(bool flag);
 407
 408     /**
 409         Sets the default colour for the colour dialog.
 410
 411         The default colour is black.
 412     */
 413     void SetColour(const wxColour& colour);
 414
 415     /**
 416         Sets custom colours for the colour dialog.
 417
 418         @param i
 419             An integer between 0 and 15 for whatever custom colour you want to
 420             set. The default custom colours are invalid colours.
 421     */
 422     void SetCustomColour(int i, const wxColour& colour);
 423
 424     /**
 425         Assignment operator for the colour data.
 426     */
 427     wxColourData& operator =(const wxColourData& data);
 428
 429
 430     /** @todo document these */
 431     wxString wxColourData::ToString() const;
 432     bool wxColourData::FromString(const wxString& str);
 433 };
 434
 435
 436
 437 /**
 438     Enumeration of various printer bin sources.
 439
 440     @see wxPrintData::SetBin()
 441 */
 442 enum wxPrintBin
 443 {
 444     wxPRINTBIN_DEFAULT,
 445
 446     wxPRINTBIN_ONLYONE,
 447     wxPRINTBIN_LOWER,
 448     wxPRINTBIN_MIDDLE,
 449     wxPRINTBIN_MANUAL,
 450     wxPRINTBIN_ENVELOPE,
 451     wxPRINTBIN_ENVMANUAL,
 452     wxPRINTBIN_AUTO,
 453     wxPRINTBIN_TRACTOR,
 454     wxPRINTBIN_SMALLFMT,
 455     wxPRINTBIN_LARGEFMT,
 456     wxPRINTBIN_LARGECAPACITY,
 457     wxPRINTBIN_CASSETTE,
 458     wxPRINTBIN_FORMSOURCE,
 459
 460     wxPRINTBIN_USER,
 461 };
 462
 463 /**
 464     @class wxPrintData
 465
 466     This class holds a variety of information related to printers and printer
 467     device contexts. This class is used to create a wxPrinterDC and a
 468     wxPostScriptDC. It is also used as a data member of wxPrintDialogData and
 469     wxPageSetupDialogData, as part of the mechanism for transferring data
 470     between the print dialogs and the application.
 471
 472     @remarks
 473
 474     The following functions are specific to PostScript printing and have not
 475     yet been documented:
 476
 477     @code
 478     const wxString& GetPrinterCommand() const ;
 479     const wxString& GetPrinterOptions() const ;
 480     const wxString& GetPreviewCommand() const ;
 481     const wxString& GetFilename() const ;
 482     const wxString& GetFontMetricPath() const ;
 483     double GetPrinterScaleX() const ;
 484     double GetPrinterScaleY() const ;
 485     long GetPrinterTranslateX() const ;
 486     long GetPrinterTranslateY() const ;
 487     // wxPRINT_MODE_PREVIEW, wxPRINT_MODE_FILE, wxPRINT_MODE_PRINTER
 488     wxPrintMode GetPrintMode() const ;
 489
 490     void SetPrinterCommand(const wxString& command) ;
 491     void SetPrinterOptions(const wxString& options) ;
 492     void SetPreviewCommand(const wxString& command) ;
 493     void SetFilename(const wxString& filename) ;
 494     void SetFontMetricPath(const wxString& path) ;
 495     void SetPrinterScaleX(double x) ;
 496     void SetPrinterScaleY(double y) ;
 497     void SetPrinterScaling(double x, double y) ;
 498     void SetPrinterTranslateX(long x) ;
 499     void SetPrinterTranslateY(long y) ;
 500     void SetPrinterTranslation(long x, long y) ;
 501     void SetPrintMode(wxPrintMode printMode) ;
 502     @endcode
 503
 504     @library{wxcore}
 505     @category{printing}
 506
 507     @see @ref overview_printing, wxPrintDialog, wxPageSetupDialog,
 508          wxPrintDialogData, wxPageSetupDialogData, @ref overview_cmndlg_print,
 509          wxPrinterDC, wxPostScriptDC
 510 */
 511 class wxPrintData : public wxObject
 512 {
 513 public:
 514     /**
 515         Default constructor.
 516     */
 517     wxPrintData();
 518
 519     /**
 520         Copy constructor.
 521     */
 522     wxPrintData(const wxPrintData& data);
 523
 524     /**
 525         Destructor.
 526     */
 527     virtual ~wxPrintData();
 528
 529     /**
 530         Returns the current bin (papersource). By default, the system is left
 531         to select the bin (@c wxPRINTBIN_DEFAULT is returned).
 532
 533         See SetBin() for the full list of bin values.
 534     */
 535     wxPrintBin GetBin() const;
 536
 537     /**
 538         Returns @true if collation is on.
 539     */
 540     bool GetCollate() const;
 541
 542     /**
 543         Returns @true if colour printing is on.
 544     */
 545     bool GetColour() const;
 546
 547     /**
 548         Returns the duplex mode. One of wxDUPLEX_SIMPLEX, wxDUPLEX_HORIZONTAL,
 549         wxDUPLEX_VERTICAL.
 550     */
 551     wxDuplexMode GetDuplex() const;
 552
 553     /**
 554         Returns the number of copies requested by the user.
 555     */
 556     int GetNoCopies() const;
 557
 558     /**
 559         Gets the orientation. This can be wxLANDSCAPE or wxPORTRAIT.
 560     */
 561     int GetOrientation() const;
 562
 563     /**
 564         Returns the paper size id.
 565
 566         @see SetPaperId()
 567     */
 568     wxPaperSize GetPaperId() const;
 569
 570     /**
 571         Returns the printer name. If the printer name is the empty string, it
 572         indicates that the default printer should be used.
 573     */
 574     const wxString& GetPrinterName() const;
 575
 576     /**
 577         Returns the current print quality. This can be a positive integer,
 578         denoting the number of dots per inch, or  one of the following
 579         identifiers:
 580
 581         - wxPRINT_QUALITY_HIGH
 582         - wxPRINT_QUALITY_MEDIUM
 583         - wxPRINT_QUALITY_LOW
 584         - wxPRINT_QUALITY_DRAFT
 585
 586         On input you should pass one of these identifiers, but on return you
 587         may get back a positive integer indicating the current resolution
 588         setting.
 589     */
 590     wxPrintQuality GetQuality() const;
 591
 592     /**
 593         Returns @true if the print data is valid for using in print dialogs.
 594         This can return @false on Windows if the current printer is not set,
 595         for example. On all other platforms, it returns @true.
 596     */
 597     bool IsOk() const;
 598
 599     /**
 600         Sets the current bin.
 601     */
 602     void SetBin(wxPrintBin flag);
 603
 604     /**
 605         Sets collation to on or off.
 606     */
 607     void SetCollate(bool flag);
 608
 609     /**
 610         Sets colour printing on or off.
 611     */
 612     void SetColour(bool flag);
 613
 614     /**
 615         Returns the duplex mode. One of wxDUPLEX_SIMPLEX, wxDUPLEX_HORIZONTAL,
 616         wxDUPLEX_VERTICAL.
 617     */
 618     void SetDuplex(wxDuplexMode mode);
 619
 620     /**
 621         Sets the default number of copies to be printed out.
 622     */
 623     void SetNoCopies(int n);
 624
 625     /**
 626         Sets the orientation. This can be wxLANDSCAPE or wxPORTRAIT.
 627     */
 628     void SetOrientation(int orientation);
 629
 630     /**
 631         Sets the paper id. This indicates the type of paper to be used. For a
 632         mapping between paper id, paper size and string name, see
 633         wxPrintPaperDatabase in @c "paper.h" (not yet documented).
 634     */
 635     void SetPaperId(wxPaperSize paperId);
 636
 637     /**
 638         Sets the printer name. This can be the empty string to indicate that
 639         the default printer should be used.
 640     */
 641     void SetPrinterName(const wxString& printerName);
 642
 643     /**
 644         Sets the desired print quality. This can be a positive integer,
 645         denoting the number of dots per inch, or one of the following
 646         identifiers:
 647
 648         - wxPRINT_QUALITY_HIGH
 649         - wxPRINT_QUALITY_MEDIUM
 650         - wxPRINT_QUALITY_LOW
 651         - wxPRINT_QUALITY_DRAFT
 652
 653         On input you should pass one of these identifiers, but on return you
 654         may get back a positive integer indicating the current resolution
 655         setting.
 656     */
 657     void SetQuality(wxPrintQuality quality);
 658
 659     /**
 660         Assigns print data to this object.
 661     */
 662     void operator =(const wxPrintData& data);
 663 };
 664
 665
 666
 667 /**
 668     @class wxPrintDialogData
 669
 670     This class holds information related to the visual characteristics of
 671     wxPrintDialog. It contains a wxPrintData object with underlying printing
 672     settings.
 673
 674     @library{wxcore}
 675     @category{printing}
 676
 677     @see @ref overview_printing, wxPrintDialog, @ref overview_cmndlg_print
 678 */
 679 class wxPrintDialogData : public wxObject
 680 {
 681 public:
 682     /**
 683         Default constructor.
 684     */
 685     wxPrintDialogData();
 686
 687     /**
 688         Copy constructor.
 689     */
 690     wxPrintDialogData(const wxPrintDialogData& dialogData);
 691
 692     /**
 693         Construct an object from a print dialog data object.
 694     */
 695     wxPrintDialogData(const wxPrintData& printData);
 696
 697     /**
 698         Destructor.
 699     */
 700     virtual ~wxPrintDialogData();
 701
 702     /**
 703         Enables or disables the "Help" button.
 704     */
 705     void EnableHelp(bool flag);
 706
 707     /**
 708         Enables or disables the "Page numbers" controls.
 709     */
 710     void EnablePageNumbers(bool flag);
 711
 712     /**
 713         Enables or disables the "Print to file" checkbox.
 714     */
 715     void EnablePrintToFile(bool flag);
 716
 717     /**
 718         Enables or disables the "Selection" radio button.
 719     */
 720     void EnableSelection(bool flag);
 721
 722     /**
 723         Returns @true if the user requested that all pages be printed.
 724     */
 725     bool GetAllPages() const;
 726
 727     /**
 728         Returns @true if the user requested that the document(s) be collated.
 729     */
 730     bool GetCollate() const;
 731
 732     /**
 733         Returns the @e from page number, as entered by the user.
 734     */
 735     int GetFromPage() const;
 736
 737     /**
 738         Returns the @e maximum page number.
 739     */
 740     int GetMaxPage() const;
 741
 742     /**
 743         Returns the @e minimum page number.
 744     */
 745     int GetMinPage() const;
 746
 747     /**
 748         Returns the number of copies requested by the user.
 749     */
 750     int GetNoCopies() const;
 751
 752     /**
 753         Returns a reference to the internal wxPrintData object.
 754     */
 755     wxPrintData& GetPrintData();
 756
 757     /**
 758         Returns @true if the user has selected printing to a file.
 759     */
 760     bool GetPrintToFile() const;
 761
 762     /**
 763         Returns @true if the user requested that the selection be printed
 764         (where "selection" is a concept specific to the application).
 765     */
 766     bool GetSelection() const;
 767
 768     /**
 769         Returns the @e "print to" page number, as entered by the user.
 770     */
 771     int GetToPage() const;
 772
 773     /**
 774         Returns @true if the print data is valid for using in print dialogs.
 775         This can return @false on Windows if the current printer is not set,
 776         for example. On all other platforms, it returns @true.
 777     */
 778     bool IsOk() const;
 779
 780     /**
 781         Sets the "Collate" checkbox to @true or @false.
 782     */
 783     void SetCollate(bool flag);
 784
 785     /**
 786         Sets the @e from page number.
 787     */
 788     void SetFromPage(int page);
 789
 790     /**
 791         Sets the @e maximum page number.
 792     */
 793     void SetMaxPage(int page);
 794
 795     /**
 796         Sets the @e minimum page number.
 797     */
 798     void SetMinPage(int page);
 799
 800     /**
 801         Sets the default number of copies the user has requested to be printed
 802         out.
 803     */
 804     void SetNoCopies(int n);
 805
 806     /**
 807         Sets the internal wxPrintData.
 808     */
 809     void SetPrintData(const wxPrintData& printData);
 810
 811     /**
 812         Sets the "Print to file" checkbox to @true or @false.
 813     */
 814     void SetPrintToFile(bool flag);
 815
 816     /**
 817         Selects the "Selection" radio button. The effect of printing the
 818         selection depends on how the application implements this command, if at
 819         all.
 820     */
 821     void SetSelection(bool flag);
 822
 823     /**
 824         @deprecated This function has been deprecated since version 2.5.4.
 825
 826         Determines whether the dialog to be shown will be the Print dialog
 827         (pass @false) or Print Setup dialog (pass @true).
 828
 829     */
 830     void SetSetupDialog(bool flag);
 831
 832     /**
 833         Sets the @e "print to" page number.
 834     */
 835     void SetToPage(int page);
 836
 837     /**
 838         Assigns print data to this object.
 839     */
 840     void operator =(const wxPrintData& data);
 841
 842     /**
 843         Assigns another print dialog data object to this object.
 844     */
 845     void operator =(const wxPrintDialogData& data);
 846 };
 847