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