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