interface/cmndata.h

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