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     wxColour& GetColour();
  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     void 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(wxPageSetupDialogData& data);
 156
 157     /**
 158         Construct an object from a print data object.
 159     */
 160     wxPageSetupDialogData(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
 270     /**
 271         Returns @true if the print data associated with the dialog data is
 272         valid. This can return @false on Windows if the current printer is not
 273         set, for example. On all other platforms, it returns @true.
 274     */
 275     bool IsOk() const;
 276
 277     /**
 278         Pass @true if the dialog will simply return default printer information
 279         (such as orientation) instead of showing a dialog (Windows only).
 280     */
 281     void SetDefaultInfo(bool flag);
 282
 283     /**
 284         Pass @true if the page setup dialog will take its minimum margin values
 285         from the currently selected printer properties (Windows only). Units
 286         are in millimetres.
 287     */
 288     void SetDefaultMinMargins(bool flag);
 289
 290     /**
 291         Sets the right (x) and bottom (y) margins in millimetres.
 292     */
 293     void SetMarginBottomRight(const wxPoint& pt);
 294
 295     /**
 296         Sets the left (x) and top (y) margins in millimetres.
 297     */
 298     void SetMarginTopLeft(const wxPoint& pt);
 299
 300     /**
 301         Sets the right (x) and bottom (y) minimum margins the user can enter
 302         (Windows only). Units are in millimetres.
 303     */
 304     void SetMinMarginBottomRight(const wxPoint& pt);
 305
 306     /**
 307         Sets the left (x) and top (y) minimum margins the user can enter
 308         (Windows only). Units are in millimetres.
 309     */
 310     void SetMinMarginTopLeft(const wxPoint& pt);
 311
 312     /**
 313         Sets the paper size id. Calling this function overrides the explicit
 314         paper dimensions passed in SetPaperSize().
 315
 316         @see wxPrintData::SetPaperId()
 317     */
 318     void SetPaperId(wxPaperSize& id);
 319
 320     /**
 321         Sets the paper size in millimetres. If a corresponding paper id is
 322         found, it will be set in the internal wxPrintData object, otherwise the
 323         paper size overrides the paper id.
 324     */
 325     void SetPaperSize(const wxSize& size);
 326
 327     /**
 328         Sets the print data associated with this object.
 329     */
 330     void SetPrintData(const wxPrintData& printData);
 331
 332     /**
 333         Assigns print data to this object.
 334     */
 335     void operator =(const wxPrintData& data);
 336
 337     /**
 338         Assigns page setup data to this object.
 339     */
 340     void operator =(const wxPageSetupDialogData& data);
 341 };
 342
 343
 344
 345 /**
 346     @class wxColourData
 347
 348     This class holds a variety of information related to colour dialogs.
 349
 350     @library{wxcore}
 351     @category{cmndlg}
 352
 353     @see wxColour, wxColourDialog, @ref overview_cmndlg_colour
 354 */
 355 class wxColourData : public wxObject
 356 {
 357 public:
 358     /**
 359         Constructor. Initializes the custom colours to @c wxNullColour, the
 360         @e data colour setting to black, and the @e choose full setting to
 361         @true.
 362     */
 363     wxColourData();
 364
 365     /**
 366         Destructor.
 367     */
 368     virtual ~wxColourData();
 369
 370     /**
 371         Under Windows, determines whether the Windows colour dialog will
 372         display the full dialog with custom colour selection controls. Under
 373         PalmOS, determines whether colour dialog will display full rgb colour
 374         picker or only available palette indexer. Has no meaning under other
 375         platforms.
 376
 377         The default value is @true.
 378     */
 379     bool GetChooseFull() const;
 380
 381     /**
 382         Gets the current colour associated with the colour dialog.
 383
 384         The default colour is black.
 385     */
 386     wxColour& GetColour();
 387
 388     /**
 389         Returns custom colours associated with the colour dialog.
 390
 391         @param i
 392             An integer between 0 and 15, being any of the 15 custom colours
 393             that the user has saved. The default custom colours are invalid
 394             colours.
 395     */
 396     wxColour& GetCustomColour(int i) const;
 397
 398     /**
 399         Under Windows, tells the Windows colour dialog to display the full
 400         dialog with custom colour selection controls. Under other platforms,
 401         has no effect.
 402
 403         The default value is @true.
 404     */
 405     void SetChooseFull(const bool flag);
 406
 407     /**
 408         Sets the default colour for the colour dialog.
 409
 410         The default colour is black.
 411     */
 412     void SetColour(const wxColour& colour);
 413
 414     /**
 415         Sets custom colours for the colour dialog.
 416
 417         @param i
 418             An integer between 0 and 15 for whatever custom colour you want to
 419             set. The default custom colours are invalid colours.
 420     */
 421     void SetCustomColour(int i, const wxColour& colour);
 422
 423     /**
 424         Assignment operator for the colour data.
 425     */
 426     void operator =(const wxColourData& data);
 427 };
 428
 429
 430
 431 /**
 432     Enumeration of various printer bin sources.
 433
 434     @see wxPrintData::SetBin()
 435 */
 436 enum wxPrintBin
 437 {
 438     wxPRINTBIN_DEFAULT,
 439
 440     wxPRINTBIN_ONLYONE,
 441     wxPRINTBIN_LOWER,
 442     wxPRINTBIN_MIDDLE,
 443     wxPRINTBIN_MANUAL,
 444     wxPRINTBIN_ENVELOPE,
 445     wxPRINTBIN_ENVMANUAL,
 446     wxPRINTBIN_AUTO,
 447     wxPRINTBIN_TRACTOR,
 448     wxPRINTBIN_SMALLFMT,
 449     wxPRINTBIN_LARGEFMT,
 450     wxPRINTBIN_LARGECAPACITY,
 451     wxPRINTBIN_CASSETTE,
 452     wxPRINTBIN_FORMSOURCE,
 453
 454     wxPRINTBIN_USER,
 455 };
 456
 457 /**
 458     @class wxPrintData
 459
 460     This class holds a variety of information related to printers and printer
 461     device contexts. This class is used to create a wxPrinterDC and a
 462     wxPostScriptDC. It is also used as a data member of wxPrintDialogData and
 463     wxPageSetupDialogData, as part of the mechanism for transferring data
 464     between the print dialogs and the application.
 465
 466     @remarks
 467
 468     The following functions are specific to PostScript printing and have not
 469     yet been documented:
 470
 471     @code
 472     const wxString& GetPrinterCommand() const ;
 473     const wxString& GetPrinterOptions() const ;
 474     const wxString& GetPreviewCommand() const ;
 475     const wxString& GetFilename() const ;
 476     const wxString& GetFontMetricPath() const ;
 477     double GetPrinterScaleX() const ;
 478     double GetPrinterScaleY() const ;
 479     long GetPrinterTranslateX() const ;
 480     long GetPrinterTranslateY() const ;
 481     // wxPRINT_MODE_PREVIEW, wxPRINT_MODE_FILE, wxPRINT_MODE_PRINTER
 482     wxPrintMode GetPrintMode() const ;
 483
 484     void SetPrinterCommand(const wxString& command) ;
 485     void SetPrinterOptions(const wxString& options) ;
 486     void SetPreviewCommand(const wxString& command) ;
 487     void SetFilename(const wxString& filename) ;
 488     void SetFontMetricPath(const wxString& path) ;
 489     void SetPrinterScaleX(double x) ;
 490     void SetPrinterScaleY(double y) ;
 491     void SetPrinterScaling(double x, double y) ;
 492     void SetPrinterTranslateX(long x) ;
 493     void SetPrinterTranslateY(long y) ;
 494     void SetPrinterTranslation(long x, long y) ;
 495     void SetPrintMode(wxPrintMode printMode) ;
 496     @endcode
 497
 498     @library{wxcore}
 499     @category{printing}
 500
 501     @see @ref overview_printing, wxPrintDialog, wxPageSetupDialog,
 502          wxPrintDialogData, wxPageSetupDialogData, @ref overview_cmndlg_print,
 503          wxPrinterDC, wxPostScriptDC
 504 */
 505 class wxPrintData : public wxObject
 506 {
 507 public:
 508     /**
 509         Default constructor.
 510     */
 511     wxPrintData();
 512
 513     /**
 514         Copy constructor.
 515     */
 516     wxPrintData(const wxPrintData& data);
 517
 518     /**
 519         Destructor.
 520     */
 521     virtual ~wxPrintData();
 522
 523     /**
 524         Returns the current bin (papersource). By default, the system is left
 525         to select the bin (@c wxPRINTBIN_DEFAULT is returned).
 526
 527         See SetBin() for the full list of bin values.
 528     */
 529     wxPrintBin GetBin() const;
 530
 531     /**
 532         Returns @true if collation is on.
 533     */
 534     bool GetCollate() const;
 535
 536     /**
 537         Returns @true if colour printing is on.
 538     */
 539     bool GetColour() const;
 540
 541     /**
 542         Returns the duplex mode. One of wxDUPLEX_SIMPLEX, wxDUPLEX_HORIZONTAL,
 543         wxDUPLEX_VERTICAL.
 544     */
 545     wxDuplexMode GetDuplex() const;
 546
 547     /**
 548         Returns the number of copies requested by the user.
 549     */
 550     int GetNoCopies() const;
 551
 552     /**
 553         Gets the orientation. This can be wxLANDSCAPE or wxPORTRAIT.
 554     */
 555     int GetOrientation() const;
 556
 557     /**
 558         Returns the paper size id.
 559
 560         @see SetPaperId()
 561     */
 562     wxPaperSize GetPaperId() const;
 563
 564     /**
 565         Returns the printer name. If the printer name is the empty string, it
 566         indicates that the default printer should be used.
 567     */
 568     const wxString GetPrinterName() const;
 569
 570     /**
 571         Returns the current print quality. This can be a positive integer,
 572         denoting the number of dots per inch, or  one of the following
 573         identifiers:
 574
 575         - wxPRINT_QUALITY_HIGH
 576         - wxPRINT_QUALITY_MEDIUM
 577         - wxPRINT_QUALITY_LOW
 578         - wxPRINT_QUALITY_DRAFT
 579
 580         On input you should pass one of these identifiers, but on return you
 581         may get back a positive integer indicating the current resolution
 582         setting.
 583     */
 584     wxPrintQuality GetQuality() const;
 585
 586     /**
 587         Returns @true if the print data is valid for using in print dialogs.
 588         This can return @false on Windows if the current printer is not set,
 589         for example. On all other platforms, it returns @true.
 590     */
 591     bool IsOk() const;
 592
 593     /**
 594         Sets the current bin.
 595     */
 596     void SetBin(wxPrintBin flag);
 597
 598     /**
 599         Sets collation to on or off.
 600     */
 601     void SetCollate(bool flag);
 602
 603     /**
 604         Sets colour printing on or off.
 605     */
 606     void SetColour(bool flag);
 607
 608     /**
 609         Returns the duplex mode. One of wxDUPLEX_SIMPLEX, wxDUPLEX_HORIZONTAL,
 610         wxDUPLEX_VERTICAL.
 611     */
 612     void SetDuplex(wxDuplexMode mode);
 613
 614     /**
 615         Sets the default number of copies to be printed out.
 616     */
 617     void SetNoCopies(int n);
 618
 619     /**
 620         Sets the orientation. This can be wxLANDSCAPE or wxPORTRAIT.
 621     */
 622     void SetOrientation(int orientation);
 623
 624     /**
 625         Sets the paper id. This indicates the type of paper to be used. For a
 626         mapping between paper id, paper size and string name, see
 627         wxPrintPaperDatabase in @c "paper.h" (not yet documented).
 628     */
 629     void SetPaperId(wxPaperSize paperId);
 630
 631     /**
 632         Sets the printer name. This can be the empty string to indicate that
 633         the default printer should be used.
 634     */
 635     void SetPrinterName(const wxString& printerName);
 636
 637     /**
 638         Sets the desired print quality. This can be a positive integer,
 639         denoting the number of dots per inch, or one of the following
 640         identifiers:
 641
 642         - wxPRINT_QUALITY_HIGH
 643         - wxPRINT_QUALITY_MEDIUM
 644         - wxPRINT_QUALITY_LOW
 645         - wxPRINT_QUALITY_DRAFT
 646
 647         On input you should pass one of these identifiers, but on return you
 648         may get back a positive integer indicating the current resolution
 649         setting.
 650     */
 651     void SetQuality(wxPrintQuality quality);
 652
 653     /**
 654         Assigns print data to this object.
 655     */
 656     void operator =(const wxPrintData& data);
 657 };
 658
 659
 660
 661 /**
 662     @class wxPrintDialogData
 663
 664     This class holds information related to the visual characteristics of
 665     wxPrintDialog. It contains a wxPrintData object with underlying printing
 666     settings.
 667
 668     @library{wxcore}
 669     @category{printing}
 670
 671     @see @ref overview_printing, wxPrintDialog, @ref overview_cmndlg_print
 672 */
 673 class wxPrintDialogData : public wxObject
 674 {
 675 public:
 676     /**
 677         Default constructor.
 678     */
 679     wxPrintDialogData();
 680
 681     /**
 682         Copy constructor.
 683     */
 684     wxPrintDialogData(wxPrintDialogData& dialogData);
 685
 686     /**
 687         Construct an object from a print dialog data object.
 688     */
 689     wxPrintDialogData(wxPrintData& printData);
 690
 691     /**
 692         Destructor.
 693     */
 694     virtual ~wxPrintDialogData();
 695
 696     /**
 697         Enables or disables the "Help" button.
 698     */
 699     void EnableHelp(bool flag);
 700
 701     /**
 702         Enables or disables the "Page numbers" controls.
 703     */
 704     void EnablePageNumbers(bool flag);
 705
 706     /**
 707         Enables or disables the "Print to file" checkbox.
 708     */
 709     void EnablePrintToFile(bool flag);
 710
 711     /**
 712         Enables or disables the "Selection" radio button.
 713     */
 714     void EnableSelection(bool flag);
 715
 716     /**
 717         Returns @true if the user requested that all pages be printed.
 718     */
 719     bool GetAllPages() const;
 720
 721     /**
 722         Returns @true if the user requested that the document(s) be collated.
 723     */
 724     bool GetCollate() const;
 725
 726     /**
 727         Returns the @e from page number, as entered by the user.
 728     */
 729     int GetFromPage() const;
 730
 731     /**
 732         Returns the @e maximum page number.
 733     */
 734     int GetMaxPage() const;
 735
 736     /**
 737         Returns the @e minimum page number.
 738     */
 739     int GetMinPage() const;
 740
 741     /**
 742         Returns the number of copies requested by the user.
 743     */
 744     int GetNoCopies() const;
 745
 746     /**
 747         Returns a reference to the internal wxPrintData object.
 748     */
 749     wxPrintData& GetPrintData();
 750
 751     /**
 752         Returns @true if the user has selected printing to a file.
 753     */
 754     bool GetPrintToFile() const;
 755
 756     /**
 757         Returns @true if the user requested that the selection be printed
 758         (where "selection" is a concept specific to the application).
 759     */
 760     bool GetSelection() const;
 761
 762     /**
 763         Returns the @e "print to" page number, as entered by the user.
 764     */
 765     int GetToPage() const;
 766
 767     /**
 768         Returns @true if the print data is valid for using in print dialogs.
 769         This can return @false on Windows if the current printer is not set,
 770         for example. On all other platforms, it returns @true.
 771     */
 772     bool IsOk() const;
 773
 774     /**
 775         Sets the "Collate" checkbox to @true or @false.
 776     */
 777     void SetCollate(bool flag);
 778
 779     /**
 780         Sets the @e from page number.
 781     */
 782     void SetFromPage(int page);
 783
 784     /**
 785         Sets the @e maximum page number.
 786     */
 787     void SetMaxPage(int page);
 788
 789     /**
 790         Sets the @e minimum page number.
 791     */
 792     void SetMinPage(int page);
 793
 794     /**
 795         Sets the default number of copies the user has requested to be printed
 796         out.
 797     */
 798     void SetNoCopies(int n);
 799
 800     /**
 801         Sets the internal wxPrintData.
 802     */
 803     void SetPrintData(const wxPrintData& printData);
 804
 805     /**
 806         Sets the "Print to file" checkbox to @true or @false.
 807     */
 808     void SetPrintToFile(bool flag);
 809
 810     /**
 811         Selects the "Selection" radio button. The effect of printing the
 812         selection depends on how the application implements this command, if at
 813         all.
 814     */
 815     void SetSelection(bool flag);
 816
 817     /**
 818         @deprecated This function has been deprecated since version 2.5.4.
 819
 820         Determines whether the dialog to be shown will be the Print dialog
 821         (pass @false) or Print Setup dialog (pass @true).
 822
 823     */
 824     void SetSetupDialog(bool flag);
 825
 826     /**
 827         Sets the @e "print to" page number.
 828     */
 829     void SetToPage(int page);
 830
 831     /**
 832         Assigns print data to this object.
 833     */
 834     void operator =(const wxPrintData& data);
 835
 836     /**
 837         Assigns another print dialog data object to this object.
 838     */
 839     void operator =(const wxPrintDialogData& data);
 840 };
 841