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     /** @todo document these */
 430     wxString wxColourData::ToString() const;
 431     bool wxColourData::FromString(const wxString& str);
 432 };
 433
 434
 435
 436 /**
 437     Enumeration of various printer bin sources.
 438
 439     @see wxPrintData::SetBin()
 440 */
 441 enum wxPrintBin
 442 {
 443     wxPRINTBIN_DEFAULT,
 444
 445     wxPRINTBIN_ONLYONE,
 446     wxPRINTBIN_LOWER,
 447     wxPRINTBIN_MIDDLE,
 448     wxPRINTBIN_MANUAL,
 449     wxPRINTBIN_ENVELOPE,
 450     wxPRINTBIN_ENVMANUAL,
 451     wxPRINTBIN_AUTO,
 452     wxPRINTBIN_TRACTOR,
 453     wxPRINTBIN_SMALLFMT,
 454     wxPRINTBIN_LARGEFMT,
 455     wxPRINTBIN_LARGECAPACITY,
 456     wxPRINTBIN_CASSETTE,
 457     wxPRINTBIN_FORMSOURCE,
 458
 459     wxPRINTBIN_USER,
 460 };
 461
 462 /**
 463     @class wxPrintData
 464
 465     This class holds a variety of information related to printers and printer
 466     device contexts. This class is used to create a wxPrinterDC and a
 467     wxPostScriptDC. It is also used as a data member of wxPrintDialogData and
 468     wxPageSetupDialogData, as part of the mechanism for transferring data
 469     between the print dialogs and the application.
 470
 471     @remarks
 472
 473     The following functions are specific to PostScript printing and have not
 474     yet been documented:
 475
 476     @code
 477     const wxString& GetPrinterCommand() const ;
 478     const wxString& GetPrinterOptions() const ;
 479     const wxString& GetPreviewCommand() const ;
 480     const wxString& GetFilename() const ;
 481     const wxString& GetFontMetricPath() const ;
 482     double GetPrinterScaleX() const ;
 483     double GetPrinterScaleY() const ;
 484     long GetPrinterTranslateX() const ;
 485     long GetPrinterTranslateY() const ;
 486     // wxPRINT_MODE_PREVIEW, wxPRINT_MODE_FILE, wxPRINT_MODE_PRINTER
 487     wxPrintMode GetPrintMode() const ;
 488
 489     void SetPrinterCommand(const wxString& command) ;
 490     void SetPrinterOptions(const wxString& options) ;
 491     void SetPreviewCommand(const wxString& command) ;
 492     void SetFilename(const wxString& filename) ;
 493     void SetFontMetricPath(const wxString& path) ;
 494     void SetPrinterScaleX(double x) ;
 495     void SetPrinterScaleY(double y) ;
 496     void SetPrinterScaling(double x, double y) ;
 497     void SetPrinterTranslateX(long x) ;
 498     void SetPrinterTranslateY(long y) ;
 499     void SetPrinterTranslation(long x, long y) ;
 500     void SetPrintMode(wxPrintMode printMode) ;
 501     @endcode
 502
 503     @library{wxcore}
 504     @category{printing}
 505
 506     @see @ref overview_printing, wxPrintDialog, wxPageSetupDialog,
 507          wxPrintDialogData, wxPageSetupDialogData, @ref overview_cmndlg_print,
 508          wxPrinterDC, wxPostScriptDC
 509 */
 510 class wxPrintData : public wxObject
 511 {
 512 public:
 513     /**
 514         Default constructor.
 515     */
 516     wxPrintData();
 517
 518     /**
 519         Copy constructor.
 520     */
 521     wxPrintData(const wxPrintData& data);
 522
 523     /**
 524         Destructor.
 525     */
 526     virtual ~wxPrintData();
 527
 528     /**
 529         Returns the current bin (papersource). By default, the system is left
 530         to select the bin (@c wxPRINTBIN_DEFAULT is returned).
 531
 532         See SetBin() for the full list of bin values.
 533     */
 534     wxPrintBin GetBin() const;
 535
 536     /**
 537         Returns @true if collation is on.
 538     */
 539     bool GetCollate() const;
 540
 541     /**
 542         Returns @true if colour printing is on.
 543     */
 544     bool GetColour() const;
 545
 546     /**
 547         Returns the duplex mode. One of wxDUPLEX_SIMPLEX, wxDUPLEX_HORIZONTAL,
 548         wxDUPLEX_VERTICAL.
 549     */
 550     wxDuplexMode GetDuplex() const;
 551
 552     /**
 553         Returns the number of copies requested by the user.
 554     */
 555     int GetNoCopies() const;
 556
 557     /**
 558         Gets the orientation. This can be wxLANDSCAPE or wxPORTRAIT.
 559     */
 560     int GetOrientation() const;
 561
 562     /**
 563         Returns the paper size id.
 564
 565         @see SetPaperId()
 566     */
 567     wxPaperSize GetPaperId() const;
 568
 569     /**
 570         Returns the printer name. If the printer name is the empty string, it
 571         indicates that the default printer should be used.
 572     */
 573     const wxString GetPrinterName() const;
 574
 575     /**
 576         Returns the current print quality. This can be a positive integer,
 577         denoting the number of dots per inch, or  one of the following
 578         identifiers:
 579
 580         - wxPRINT_QUALITY_HIGH
 581         - wxPRINT_QUALITY_MEDIUM
 582         - wxPRINT_QUALITY_LOW
 583         - wxPRINT_QUALITY_DRAFT
 584
 585         On input you should pass one of these identifiers, but on return you
 586         may get back a positive integer indicating the current resolution
 587         setting.
 588     */
 589     wxPrintQuality GetQuality() const;
 590
 591     /**
 592         Returns @true if the print data is valid for using in print dialogs.
 593         This can return @false on Windows if the current printer is not set,
 594         for example. On all other platforms, it returns @true.
 595     */
 596     bool IsOk() const;
 597
 598     /**
 599         Sets the current bin.
 600     */
 601     void SetBin(wxPrintBin flag);
 602
 603     /**
 604         Sets collation to on or off.
 605     */
 606     void SetCollate(bool flag);
 607
 608     /**
 609         Sets colour printing on or off.
 610     */
 611     void SetColour(bool flag);
 612
 613     /**
 614         Returns the duplex mode. One of wxDUPLEX_SIMPLEX, wxDUPLEX_HORIZONTAL,
 615         wxDUPLEX_VERTICAL.
 616     */
 617     void SetDuplex(wxDuplexMode mode);
 618
 619     /**
 620         Sets the default number of copies to be printed out.
 621     */
 622     void SetNoCopies(int n);
 623
 624     /**
 625         Sets the orientation. This can be wxLANDSCAPE or wxPORTRAIT.
 626     */
 627     void SetOrientation(int orientation);
 628
 629     /**
 630         Sets the paper id. This indicates the type of paper to be used. For a
 631         mapping between paper id, paper size and string name, see
 632         wxPrintPaperDatabase in @c "paper.h" (not yet documented).
 633     */
 634     void SetPaperId(wxPaperSize paperId);
 635
 636     /**
 637         Sets the printer name. This can be the empty string to indicate that
 638         the default printer should be used.
 639     */
 640     void SetPrinterName(const wxString& printerName);
 641
 642     /**
 643         Sets the desired print quality. This can be a positive integer,
 644         denoting the number of dots per inch, or one of the following
 645         identifiers:
 646
 647         - wxPRINT_QUALITY_HIGH
 648         - wxPRINT_QUALITY_MEDIUM
 649         - wxPRINT_QUALITY_LOW
 650         - wxPRINT_QUALITY_DRAFT
 651
 652         On input you should pass one of these identifiers, but on return you
 653         may get back a positive integer indicating the current resolution
 654         setting.
 655     */
 656     void SetQuality(wxPrintQuality quality);
 657
 658     /**
 659         Assigns print data to this object.
 660     */
 661     void operator =(const wxPrintData& data);
 662 };
 663
 664
 665
 666 /**
 667     @class wxPrintDialogData
 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     virtual ~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