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         @param colour
 422             The colour to set
 423     */
 424     void SetCustomColour(int i, const wxColour& colour);
 425
 426     /**
 427         Assignment operator for the colour data.
 428     */
 429     wxColourData& operator =(const wxColourData& data);
 430
 431
 432     /** @todo document these */
 433     wxString wxColourData::ToString() const;
 434     bool wxColourData::FromString(const wxString& str);
 435 };
 436
 437
 438
 439 /**
 440     Enumeration of various printer bin sources.
 441
 442     @see wxPrintData::SetBin()
 443 */
 444 enum wxPrintBin
 445 {
 446     wxPRINTBIN_DEFAULT,
 447
 448     wxPRINTBIN_ONLYONE,
 449     wxPRINTBIN_LOWER,
 450     wxPRINTBIN_MIDDLE,
 451     wxPRINTBIN_MANUAL,
 452     wxPRINTBIN_ENVELOPE,
 453     wxPRINTBIN_ENVMANUAL,
 454     wxPRINTBIN_AUTO,
 455     wxPRINTBIN_TRACTOR,
 456     wxPRINTBIN_SMALLFMT,
 457     wxPRINTBIN_LARGEFMT,
 458     wxPRINTBIN_LARGECAPACITY,
 459     wxPRINTBIN_CASSETTE,
 460     wxPRINTBIN_FORMSOURCE,
 461
 462     wxPRINTBIN_USER,
 463 };
 464
 465 /**
 466     @class wxPrintData
 467
 468     This class holds a variety of information related to printers and printer
 469     device contexts. This class is used to create a wxPrinterDC and a
 470     wxPostScriptDC. It is also used as a data member of wxPrintDialogData and
 471     wxPageSetupDialogData, as part of the mechanism for transferring data
 472     between the print dialogs and the application.
 473
 474     @remarks
 475
 476     The following functions are specific to PostScript printing and have not
 477     yet been documented:
 478
 479     @code
 480     const wxString& GetPrinterCommand() const ;
 481     const wxString& GetPrinterOptions() const ;
 482     const wxString& GetPreviewCommand() const ;
 483     const wxString& GetFilename() const ;
 484     const wxString& GetFontMetricPath() const ;
 485     double GetPrinterScaleX() const ;
 486     double GetPrinterScaleY() const ;
 487     long GetPrinterTranslateX() const ;
 488     long GetPrinterTranslateY() const ;
 489     // wxPRINT_MODE_PREVIEW, wxPRINT_MODE_FILE, wxPRINT_MODE_PRINTER
 490     wxPrintMode GetPrintMode() const ;
 491
 492     void SetPrinterCommand(const wxString& command) ;
 493     void SetPrinterOptions(const wxString& options) ;
 494     void SetPreviewCommand(const wxString& command) ;
 495     void SetFilename(const wxString& filename) ;
 496     void SetFontMetricPath(const wxString& path) ;
 497     void SetPrinterScaleX(double x) ;
 498     void SetPrinterScaleY(double y) ;
 499     void SetPrinterScaling(double x, double y) ;
 500     void SetPrinterTranslateX(long x) ;
 501     void SetPrinterTranslateY(long y) ;
 502     void SetPrinterTranslation(long x, long y) ;
 503     void SetPrintMode(wxPrintMode printMode) ;
 504     @endcode
 505
 506     @library{wxcore}
 507     @category{printing}
 508
 509     @see @ref overview_printing, wxPrintDialog, wxPageSetupDialog,
 510          wxPrintDialogData, wxPageSetupDialogData, @ref overview_cmndlg_print,
 511          wxPrinterDC, wxPostScriptDC
 512 */
 513 class wxPrintData : public wxObject
 514 {
 515 public:
 516     /**
 517         Default constructor.
 518     */
 519     wxPrintData();
 520
 521     /**
 522         Copy constructor.
 523     */
 524     wxPrintData(const wxPrintData& data);
 525
 526     /**
 527         Destructor.
 528     */
 529     virtual ~wxPrintData();
 530
 531     /**
 532         Returns the current bin (papersource). By default, the system is left
 533         to select the bin (@c wxPRINTBIN_DEFAULT is returned).
 534
 535         See SetBin() for the full list of bin values.
 536     */
 537     wxPrintBin GetBin() const;
 538
 539     /**
 540         Returns @true if collation is on.
 541     */
 542     bool GetCollate() const;
 543
 544     /**
 545         Returns @true if colour printing is on.
 546     */
 547     bool GetColour() const;
 548
 549     /**
 550         Returns the duplex mode. One of wxDUPLEX_SIMPLEX, wxDUPLEX_HORIZONTAL,
 551         wxDUPLEX_VERTICAL.
 552     */
 553     wxDuplexMode GetDuplex() const;
 554
 555     /**
 556         Returns the number of copies requested by the user.
 557     */
 558     int GetNoCopies() const;
 559
 560     /**
 561         Gets the orientation. This can be wxLANDSCAPE or wxPORTRAIT.
 562     */
 563     int GetOrientation() const;
 564
 565     /**
 566         Returns the paper size id.
 567
 568         @see SetPaperId()
 569     */
 570     wxPaperSize GetPaperId() const;
 571
 572     /**
 573         Returns the printer name. If the printer name is the empty string, it
 574         indicates that the default printer should be used.
 575     */
 576     const wxString& GetPrinterName() const;
 577
 578     /**
 579         Returns the current print quality. This can be a positive integer,
 580         denoting the number of dots per inch, or  one of the following
 581         identifiers:
 582
 583         - wxPRINT_QUALITY_HIGH
 584         - wxPRINT_QUALITY_MEDIUM
 585         - wxPRINT_QUALITY_LOW
 586         - wxPRINT_QUALITY_DRAFT
 587
 588         On input you should pass one of these identifiers, but on return you
 589         may get back a positive integer indicating the current resolution
 590         setting.
 591     */
 592     wxPrintQuality GetQuality() const;
 593
 594     /**
 595         Returns @true if the print data is valid for using in print dialogs.
 596         This can return @false on Windows if the current printer is not set,
 597         for example. On all other platforms, it returns @true.
 598     */
 599     bool IsOk() const;
 600
 601     /**
 602         Sets the current bin.
 603     */
 604     void SetBin(wxPrintBin flag);
 605
 606     /**
 607         Sets collation to on or off.
 608     */
 609     void SetCollate(bool flag);
 610
 611     /**
 612         Sets colour printing on or off.
 613     */
 614     void SetColour(bool flag);
 615
 616     /**
 617         Returns the duplex mode. One of wxDUPLEX_SIMPLEX, wxDUPLEX_HORIZONTAL,
 618         wxDUPLEX_VERTICAL.
 619     */
 620     void SetDuplex(wxDuplexMode mode);
 621
 622     /**
 623         Sets the default number of copies to be printed out.
 624     */
 625     void SetNoCopies(int n);
 626
 627     /**
 628         Sets the orientation. This can be wxLANDSCAPE or wxPORTRAIT.
 629     */
 630     void SetOrientation(int orientation);
 631
 632     /**
 633         Sets the paper id. This indicates the type of paper to be used. For a
 634         mapping between paper id, paper size and string name, see
 635         wxPrintPaperDatabase in @c "paper.h" (not yet documented).
 636     */
 637     void SetPaperId(wxPaperSize paperId);
 638
 639     /**
 640         Sets the printer name. This can be the empty string to indicate that
 641         the default printer should be used.
 642     */
 643     void SetPrinterName(const wxString& printerName);
 644
 645     /**
 646         Sets the desired print quality. This can be a positive integer,
 647         denoting the number of dots per inch, or one of the following
 648         identifiers:
 649
 650         - wxPRINT_QUALITY_HIGH
 651         - wxPRINT_QUALITY_MEDIUM
 652         - wxPRINT_QUALITY_LOW
 653         - wxPRINT_QUALITY_DRAFT
 654
 655         On input you should pass one of these identifiers, but on return you
 656         may get back a positive integer indicating the current resolution
 657         setting.
 658     */
 659     void SetQuality(wxPrintQuality quality);
 660
 661     /**
 662         Assigns print data to this object.
 663     */
 664     void operator =(const wxPrintData& data);
 665 };
 666
 667
 668
 669 /**
 670     @class wxPrintDialogData
 671
 672     This class holds information related to the visual characteristics of
 673     wxPrintDialog. It contains a wxPrintData object with underlying printing
 674     settings.
 675
 676     @library{wxcore}
 677     @category{printing}
 678
 679     @see @ref overview_printing, wxPrintDialog, @ref overview_cmndlg_print
 680 */
 681 class wxPrintDialogData : public wxObject
 682 {
 683 public:
 684     /**
 685         Default constructor.
 686     */
 687     wxPrintDialogData();
 688
 689     /**
 690         Copy constructor.
 691     */
 692     wxPrintDialogData(const wxPrintDialogData& dialogData);
 693
 694     /**
 695         Construct an object from a print dialog data object.
 696     */
 697     wxPrintDialogData(const wxPrintData& printData);
 698
 699     /**
 700         Destructor.
 701     */
 702     virtual ~wxPrintDialogData();
 703
 704     /**
 705         Enables or disables the "Help" button.
 706     */
 707     void EnableHelp(bool flag);
 708
 709     /**
 710         Enables or disables the "Page numbers" controls.
 711     */
 712     void EnablePageNumbers(bool flag);
 713
 714     /**
 715         Enables or disables the "Print to file" checkbox.
 716     */
 717     void EnablePrintToFile(bool flag);
 718
 719     /**
 720         Enables or disables the "Selection" radio button.
 721     */
 722     void EnableSelection(bool flag);
 723
 724     /**
 725         Returns @true if the user requested that all pages be printed.
 726     */
 727     bool GetAllPages() const;
 728
 729     /**
 730         Returns @true if the user requested that the document(s) be collated.
 731     */
 732     bool GetCollate() const;
 733
 734     /**
 735         Returns the @e from page number, as entered by the user.
 736     */
 737     int GetFromPage() const;
 738
 739     /**
 740         Returns the @e maximum page number.
 741     */
 742     int GetMaxPage() const;
 743
 744     /**
 745         Returns the @e minimum page number.
 746     */
 747     int GetMinPage() const;
 748
 749     /**
 750         Returns the number of copies requested by the user.
 751     */
 752     int GetNoCopies() const;
 753
 754     /**
 755         Returns a reference to the internal wxPrintData object.
 756     */
 757     wxPrintData& GetPrintData();
 758
 759     /**
 760         Returns @true if the user has selected printing to a file.
 761     */
 762     bool GetPrintToFile() const;
 763
 764     /**
 765         Returns @true if the user requested that the selection be printed
 766         (where "selection" is a concept specific to the application).
 767     */
 768     bool GetSelection() const;
 769
 770     /**
 771         Returns the @e "print to" page number, as entered by the user.
 772     */
 773     int GetToPage() const;
 774
 775     /**
 776         Returns @true if the print data is valid for using in print dialogs.
 777         This can return @false on Windows if the current printer is not set,
 778         for example. On all other platforms, it returns @true.
 779     */
 780     bool IsOk() const;
 781
 782     /**
 783         Sets the "Collate" checkbox to @true or @false.
 784     */
 785     void SetCollate(bool flag);
 786
 787     /**
 788         Sets the @e from page number.
 789     */
 790     void SetFromPage(int page);
 791
 792     /**
 793         Sets the @e maximum page number.
 794     */
 795     void SetMaxPage(int page);
 796
 797     /**
 798         Sets the @e minimum page number.
 799     */
 800     void SetMinPage(int page);
 801
 802     /**
 803         Sets the default number of copies the user has requested to be printed
 804         out.
 805     */
 806     void SetNoCopies(int n);
 807
 808     /**
 809         Sets the internal wxPrintData.
 810     */
 811     void SetPrintData(const wxPrintData& printData);
 812
 813     /**
 814         Sets the "Print to file" checkbox to @true or @false.
 815     */
 816     void SetPrintToFile(bool flag);
 817
 818     /**
 819         Selects the "Selection" radio button. The effect of printing the
 820         selection depends on how the application implements this command, if at
 821         all.
 822     */
 823     void SetSelection(bool flag);
 824
 825     /**
 826         @deprecated This function has been deprecated since version 2.5.4.
 827
 828         Determines whether the dialog to be shown will be the Print dialog
 829         (pass @false) or Print Setup dialog (pass @true).
 830
 831     */
 832     void SetSetupDialog(bool flag);
 833
 834     /**
 835         Sets the @e "print to" page number.
 836     */
 837     void SetToPage(int page);
 838
 839     /**
 840         Assigns print data to this object.
 841     */
 842     void operator =(const wxPrintData& data);
 843
 844     /**
 845         Assigns another print dialog data object to this object.
 846     */
 847     void operator =(const wxPrintDialogData& data);
 848 };
 849