interface/wx/richtext/richtextstyles.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        richtext/richtextstyles.h
   3 // Purpose:     interface of wxRichTextStyleListCtrl
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows licence
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxRichTextStyleListCtrl
  11
  12     This class incorporates a wxRichTextStyleListBox and a choice control that
  13     allows the user to select the category of style to view.
  14
  15     It is demonstrated in the wxRichTextCtrl sample in @c samples/richtext.
  16
  17     To use wxRichTextStyleListCtrl, add the control to your window hierarchy and
  18     call wxRichTextStyleListCtrl::SetStyleType with one of
  19     wxRichTextStyleListBox::wxRICHTEXT_STYLE_ALL,
  20     wxRichTextStyleListBox::wxRICHTEXT_STYLE_PARAGRAPH,
  21     wxRichTextStyleListBox::wxRICHTEXT_STYLE_CHARACTER and
  22     wxRichTextStyleListBox::wxRICHTEXT_STYLE_LIST to set the current view.
  23
  24     Associate the control with a style sheet and rich text control with
  25     SetStyleSheet and SetRichTextCtrl, so that when a style is double-clicked,
  26     it is applied to the selection.
  27
  28     @beginStyleTable
  29     @style{wxRICHTEXTSTYLELIST_HIDE_TYPE_SELECTOR}
  30            This style hides the category selection control.
  31     @endStyleTable
  32
  33     @library{wxrichtext}
  34     @category{richtext}
  35 */
  36 class wxRichTextStyleListCtrl : public wxControl
  37 {
  38 public:
  39     //@{
  40     /**
  41         Constructors.
  42     */
  43     wxRichTextStyleListCtrl(wxWindow* parent,
  44                             wxWindowID id = wxID_ANY,
  45                             const wxPoint& pos = wxDefaultPosition,
  46                             const wxSize& size = wxDefaultSize,
  47                             long style = 0);
  48     wxRichTextStyleListCtrl();
  49     //@}
  50
  51     /**
  52         Creates the windows.
  53     */
  54     bool Create(wxWindow* parent, wxWindowID id = wxID_ANY,
  55                 const wxPoint& pos = wxDefaultPosition,
  56                 const wxSize& size = wxDefaultSize,
  57                 long style = 0);
  58
  59     /**
  60         Returns the associated rich text control, if any.
  61     */
  62     wxRichTextCtrl* GetRichTextCtrl() const;
  63
  64     /**
  65         Returns the wxChoice control used for selecting the style category.
  66     */
  67     wxChoice* GetStyleChoice() const;
  68
  69     /**
  70         Returns the wxListBox control used to view the style list.
  71     */
  72     wxRichTextStyleListBox* GetStyleListBox() const;
  73
  74     /**
  75         Returns the associated style sheet, if any.
  76     */
  77     wxRichTextStyleSheet* GetStyleSheet() const;
  78
  79     /**
  80         Returns the type of style to show in the list box.
  81     */
  82     wxRichTextStyleListBox::wxRichTextStyleType GetStyleType() const;
  83
  84     /**
  85         Associates the control with a wxRichTextCtrl.
  86     */
  87     void SetRichTextCtrl(wxRichTextCtrl* ctrl);
  88
  89     /**
  90         Associates the control with a style sheet.
  91     */
  92     void SetStyleSheet(wxRichTextStyleSheet* styleSheet);
  93
  94     /**
  95         Sets the style type to display.
  96
  97         One of
  98         - wxRichTextStyleListBox::wxRICHTEXT_STYLE_ALL,
  99         - wxRichTextStyleListBox::wxRICHTEXT_STYLE_PARAGRAPH,
 100         - wxRichTextStyleListBox::wxRICHTEXT_STYLE_CHARACTER
 101         - wxRichTextStyleListBox::wxRICHTEXT_STYLE_LIST.
 102     */
 103     void SetStyleType(wxRichTextStyleListBox::wxRichTextStyleType styleType);
 104
 105     /**
 106         Updates the style list box.
 107     */
 108     void UpdateStyles();
 109 };
 110
 111
 112
 113 /**
 114     @class wxRichTextStyleDefinition
 115
 116     This is a base class for paragraph and character styles.
 117
 118     @library{wxrichtext}
 119     @category{richtext}
 120 */
 121 class wxRichTextStyleDefinition : public wxObject
 122 {
 123 public:
 124     /**
 125         Constructor.
 126     */
 127     wxRichTextStyleDefinition(const wxString& name = wxEmptyString);
 128
 129     /**
 130         Destructor.
 131     */
 132     virtual ~wxRichTextStyleDefinition();
 133
 134     /**
 135         Returns the style on which this style is based.
 136     */
 137     const wxString& GetBaseStyle() const;
 138
 139     /**
 140         Returns the style's description.
 141     */
 142     const wxString& GetDescription() const;
 143
 144     /**
 145         Returns the style name.
 146     */
 147     const wxString& GetName() const;
 148
 149     //@{
 150     /**
 151         Returns the attributes associated with this style.
 152     */
 153     wxRichTextAttr GetStyle() const;
 154     const wxRichTextAttr GetStyle() const;
 155     //@}
 156
 157     /**
 158         Returns the style attributes combined with the attributes of the specified base
 159         style, if any. This function works recursively.
 160     */
 161     virtual wxRichTextAttr GetStyleMergedWithBase(const wxRichTextStyleSheet* sheet) const;
 162
 163     /**
 164         Sets the name of the style that this style is based on.
 165     */
 166     void SetBaseStyle(const wxString& name);
 167
 168     /**
 169         Sets the style description.
 170     */
 171     void SetDescription(const wxString& descr);
 172
 173     /**
 174         Sets the name of the style.
 175     */
 176     void SetName(const wxString& name);
 177
 178     /**
 179         Sets the attributes for this style.
 180     */
 181     void SetStyle(const wxRichTextAttr& style);
 182
 183     /**
 184         Returns the definition's properties.
 185     */
 186     wxRichTextProperties& GetProperties();
 187
 188     /**
 189         Returns the definition's properties.
 190     */
 191     const wxRichTextProperties& GetProperties() const;
 192
 193     /**
 194         Sets the definition's properties.
 195     */
 196     void SetProperties(const wxRichTextProperties& props);
 197 };
 198
 199
 200
 201 /**
 202     @class wxRichTextParagraphStyleDefinition
 203
 204     This class represents a paragraph style definition, usually added to a
 205     wxRichTextStyleSheet.
 206
 207     @library{wxrichtext}
 208     @category{richtext}
 209 */
 210 class wxRichTextParagraphStyleDefinition : public wxRichTextStyleDefinition
 211 {
 212 public:
 213     /**
 214         Constructor.
 215     */
 216     wxRichTextParagraphStyleDefinition(const wxString& name = wxEmptyString);
 217
 218     /**
 219         Destructor.
 220     */
 221     virtual ~wxRichTextParagraphStyleDefinition();
 222
 223     /**
 224         Returns the style that should normally follow this style.
 225     */
 226     const wxString& GetNextStyle() const;
 227
 228     /**
 229         Sets the style that should normally follow this style.
 230     */
 231     void SetNextStyle(const wxString& name);
 232 };
 233
 234
 235
 236 /**
 237     @class wxRichTextStyleListBox
 238
 239     This is a listbox that can display the styles in a wxRichTextStyleSheet,
 240     and apply the selection to an associated wxRichTextCtrl.
 241
 242     See @c samples/richtext for an example of how to use it.
 243
 244     @library{wxrichtext}
 245     @category{richtext}
 246
 247     @see wxRichTextStyleComboCtrl, @ref overview_richtextctrl
 248 */
 249 class wxRichTextStyleListBox : public wxHtmlListBox
 250 {
 251 public:
 252
 253     /// Which type of style definition is currently showing?
 254     enum wxRichTextStyleType
 255     {
 256         wxRICHTEXT_STYLE_ALL,
 257         wxRICHTEXT_STYLE_PARAGRAPH,
 258         wxRICHTEXT_STYLE_CHARACTER,
 259         wxRICHTEXT_STYLE_LIST,
 260         wxRICHTEXT_STYLE_BOX
 261     };
 262
 263     /**
 264         Constructor.
 265     */
 266     wxRichTextStyleListBox(wxWindow* parent,
 267                            wxWindowID id = wxID_ANY,
 268                            const wxPoint& pos = wxDefaultPosition,
 269                            const wxSize& size = wxDefaultSize,
 270                            long style = 0);
 271
 272     /**
 273         Destructor.
 274     */
 275     virtual ~wxRichTextStyleListBox();
 276
 277     /**
 278         Applies the @e ith style to the associated rich text control.
 279     */
 280     void ApplyStyle(int i);
 281
 282     /**
 283         Converts units in tenths of a millimetre to device units.
 284     */
 285     int ConvertTenthsMMToPixels(wxDC& dc, int units) const;
 286
 287     /**
 288         Creates a suitable HTML fragment for a definition.
 289     */
 290     wxString CreateHTML(wxRichTextStyleDefinition* def) const;
 291
 292     /**
 293         If the return value is @true, clicking on a style name in the list will
 294         immediately apply the style to the associated rich text control.
 295     */
 296     bool GetApplyOnSelection() const;
 297
 298     /**
 299         Returns the wxRichTextCtrl associated with this listbox.
 300     */
 301     wxRichTextCtrl* GetRichTextCtrl() const;
 302
 303     /**
 304         Gets a style for a listbox index.
 305     */
 306     wxRichTextStyleDefinition* GetStyle(size_t i) const;
 307
 308     /**
 309         Returns the style sheet associated with this listbox.
 310     */
 311     wxRichTextStyleSheet* GetStyleSheet() const;
 312
 313     /**
 314         Returns the type of style to show in the list box.
 315     */
 316     wxRichTextStyleListBox::wxRichTextStyleType GetStyleType() const;
 317
 318     /**
 319         Implements left click behaviour, applying the clicked style to the
 320         wxRichTextCtrl.
 321     */
 322     void OnLeftDown(wxMouseEvent& event);
 323
 324     /**
 325         If @a applyOnSelection is @true, clicking on a style name in the list will
 326         immediately apply the style to the associated rich text control.
 327     */
 328     void SetApplyOnSelection(bool applyOnSelection);
 329
 330     /**
 331         Associates the listbox with a wxRichTextCtrl.
 332     */
 333     void SetRichTextCtrl(wxRichTextCtrl* ctrl);
 334
 335     /**
 336         Associates the control with a style sheet.
 337     */
 338     void SetStyleSheet(wxRichTextStyleSheet* styleSheet);
 339
 340     /**
 341         Sets the style type to display. One of
 342         - wxRichTextStyleListBox::wxRICHTEXT_STYLE_ALL,
 343         - wxRichTextStyleListBox::wxRICHTEXT_STYLE_PARAGRAPH,
 344         - wxRichTextStyleListBox::wxRICHTEXT_STYLE_CHARACTER
 345         - wxRichTextStyleListBox::wxRICHTEXT_STYLE_LIST.
 346     */
 347     void SetStyleType(wxRichTextStyleListBox::wxRichTextStyleType styleType);
 348
 349     /**
 350         Updates the list from the associated style sheet.
 351     */
 352     void UpdateStyles();
 353
 354 protected:
 355
 356     /**
 357         Returns the HTML for this item.
 358     */
 359     virtual wxString OnGetItem(size_t n) const;
 360 };
 361
 362
 363
 364 /**
 365     @class wxRichTextStyleComboCtrl
 366
 367     This is a combo control that can display the styles in a wxRichTextStyleSheet,
 368     and apply the selection to an associated wxRichTextCtrl.
 369
 370     See @c samples/richtext for an example of how to use it.
 371
 372     @library{wxrichtext}
 373     @category{richtext}
 374
 375     @see wxRichTextStyleListBox, @ref overview_richtextctrl
 376 */
 377 class wxRichTextStyleComboCtrl : public wxComboCtrl
 378 {
 379 public:
 380     /**
 381         Constructor.
 382     */
 383     wxRichTextStyleComboCtrl(wxWindow* parent,
 384                              wxWindowID id = wxID_ANY,
 385                              const wxPoint& pos = wxDefaultPosition,
 386                              const wxSize& size = wxDefaultSize,
 387                              long style = 0);
 388
 389     /**
 390         Destructor.
 391     */
 392     virtual ~wxRichTextStyleComboCtrl();
 393
 394     /**
 395         Returns the wxRichTextCtrl associated with this control.
 396     */
 397     wxRichTextCtrl* GetRichTextCtrl() const;
 398
 399     /**
 400         Returns the style sheet associated with this control.
 401     */
 402     wxRichTextStyleSheet* GetStyleSheet() const;
 403
 404     /**
 405         Associates the control with a wxRichTextCtrl.
 406     */
 407     void SetRichTextCtrl(wxRichTextCtrl* ctrl);
 408
 409     /**
 410         Associates the control with a style sheet.
 411     */
 412     void SetStyleSheet(wxRichTextStyleSheet* styleSheet);
 413
 414     /**
 415         Updates the combo control from the associated style sheet.
 416     */
 417     void UpdateStyles();
 418 };
 419
 420
 421
 422 /**
 423     @class wxRichTextCharacterStyleDefinition
 424
 425     This class represents a character style definition, usually added to a
 426     wxRichTextStyleSheet.
 427
 428     @library{wxrichtext}
 429     @category{richtext}
 430 */
 431 class wxRichTextCharacterStyleDefinition : public wxRichTextStyleDefinition
 432 {
 433 public:
 434     /**
 435         Constructor.
 436     */
 437     wxRichTextCharacterStyleDefinition(const wxString& name = wxEmptyString);
 438
 439     /**
 440         Destructor.
 441     */
 442     virtual ~wxRichTextCharacterStyleDefinition();
 443 };
 444
 445
 446
 447 /**
 448     @class wxRichTextListStyleDefinition
 449
 450     This class represents a list style definition, usually added to a
 451     wxRichTextStyleSheet.
 452
 453     The class inherits paragraph attributes from wxRichTextStyleParagraphDefinition,
 454     and adds 10 further attribute objects, one for each level of a list.
 455     When applying a list style to a paragraph, the list style's base and
 456     appropriate level attributes are merged with the paragraph's existing attributes.
 457
 458     You can apply a list style to one or more paragraphs using wxRichTextCtrl::SetListStyle.
 459     You can also use the functions wxRichTextCtrl::NumberList, wxRichTextCtrl::PromoteList and
 460     wxRichTextCtrl::ClearListStyle.
 461
 462     As usual, there are wxRichTextBuffer versions of these functions
 463     so that you can apply them directly to a buffer without requiring a control.
 464
 465     @library{wxrichtext}
 466     @category{richtext}
 467 */
 468 class wxRichTextListStyleDefinition : public wxRichTextParagraphStyleDefinition
 469 {
 470 public:
 471     /**
 472         Constructor.
 473     */
 474     wxRichTextListStyleDefinition(const wxString& name = wxEmptyString);
 475
 476     /**
 477         Destructor.
 478     */
 479     virtual ~wxRichTextListStyleDefinition();
 480
 481     /**
 482         This function combines the given paragraph style with the list style's base
 483         attributes and level style matching the given indent, returning the combined attributes.
 484
 485         If @a styleSheet is specified, the base style for this definition will also be
 486         included in the result.
 487     */
 488     wxRichTextAttr CombineWithParagraphStyle(int indent,
 489                                          const wxRichTextAttr& paraStyle,
 490                                          wxRichTextStyleSheet* styleSheet = NULL);
 491
 492     /**
 493         This function finds the level (from 0 to 9) whose indentation attribute mostly
 494         closely matches @a indent (expressed in tenths of a millimetre).
 495     */
 496     int FindLevelForIndent(int indent) const;
 497
 498     /**
 499         This function combines the list style's base attributes and the level style
 500         matching the given indent, returning the combined attributes.
 501
 502         If @a styleSheet is specified, the base style for this definition will also be
 503         included in the result.
 504     */
 505     wxRichTextAttr GetCombinedStyle(int indent,
 506                                 wxRichTextStyleSheet* styleSheet = NULL);
 507
 508     /**
 509         This function combines the list style's base attributes and the style for the
 510         specified level, returning the combined attributes.
 511
 512         If @a styleSheet is specified, the base style for this definition will also be
 513         included in the result.
 514     */
 515
 516     wxRichTextAttr GetCombinedStyleForLevel(int level,
 517                                      wxRichTextStyleSheet* styleSheet = NULL);
 518
 519     /**
 520         Returns the style for the given level. @a level is a number between 0 and 9.
 521     */
 522     const wxRichTextAttr* GetLevelAttributes(int level) const;
 523
 524     /**
 525         Returns the number of levels. This is hard-wired to 10.
 526         Returns the style for the given level. @e level is a number between 0 and 9.
 527     */
 528     int GetLevelCount() const;
 529
 530     /**
 531         Returns @true if the given level has numbered list attributes.
 532     */
 533     bool IsNumbered(int level) const;
 534
 535     /**
 536         Sets the style for the given level. @a level is a number between 0 and 9.
 537         The first and most flexible form uses a wxTextAttr object, while the second
 538         form is for convenient setting of the most commonly-used attributes.
 539     */
 540     void SetLevelAttributes(int level, const wxRichTextAttr& attr);
 541 };
 542
 543
 544
 545 /**
 546     @class wxRichTextStyleSheet
 547
 548     A style sheet contains named paragraph and character styles that make it
 549     easy for a user to apply combinations of attributes to a wxRichTextCtrl.
 550
 551     You can use a wxRichTextStyleListBox in your user interface to show available
 552     styles to the user, and allow application of styles to the control.
 553
 554     @library{wxrichtext}
 555     @category{richtext}
 556 */
 557 class wxRichTextStyleSheet : public wxObject
 558 {
 559 public:
 560     /**
 561         Constructor.
 562     */
 563     wxRichTextStyleSheet();
 564
 565     /**
 566         Destructor.
 567     */
 568     virtual ~wxRichTextStyleSheet();
 569
 570     /**
 571         Adds a definition to the character style list.
 572     */
 573     bool AddCharacterStyle(wxRichTextCharacterStyleDefinition* def);
 574
 575     /**
 576         Adds a definition to the list style list.
 577     */
 578     bool AddListStyle(wxRichTextListStyleDefinition* def);
 579
 580     /**
 581         Adds a definition to the paragraph style list.
 582     */
 583     bool AddParagraphStyle(wxRichTextParagraphStyleDefinition* def);
 584
 585     /**
 586         Adds a definition to the appropriate style list.
 587     */
 588     bool AddStyle(wxRichTextStyleDefinition* def);
 589
 590     /**
 591         Deletes all styles.
 592     */
 593     void DeleteStyles();
 594
 595     /**
 596         Finds a character definition by name.
 597     */
 598     wxRichTextCharacterStyleDefinition* FindCharacterStyle(const wxString& name,
 599                                                            bool recurse = true) const;
 600
 601     /**
 602         Finds a list definition by name.
 603     */
 604     wxRichTextListStyleDefinition* FindListStyle(const wxString& name,
 605                                                  bool recurse = true) const;
 606
 607     /**
 608         Finds a paragraph definition by name.
 609     */
 610     wxRichTextParagraphStyleDefinition* FindParagraphStyle(const wxString& name,
 611                                                            bool recurse = true) const;
 612
 613     /**
 614         Finds a style definition by name.
 615     */
 616     wxRichTextStyleDefinition* FindStyle(const wxString& name) const;
 617
 618     /**
 619         Returns the @e nth character style.
 620     */
 621     wxRichTextCharacterStyleDefinition* GetCharacterStyle(size_t n) const;
 622
 623     /**
 624         Returns the number of character styles.
 625     */
 626     size_t GetCharacterStyleCount() const;
 627
 628     /**
 629         Returns the style sheet's description.
 630     */
 631     const wxString& GetDescription() const;
 632
 633     /**
 634         Returns the @e nth list style.
 635     */
 636     wxRichTextListStyleDefinition* GetListStyle(size_t n) const;
 637
 638     /**
 639         Returns the number of list styles.
 640     */
 641     size_t GetListStyleCount() const;
 642
 643     /**
 644         Returns the style sheet's name.
 645     */
 646     const wxString& GetName() const;
 647
 648     /**
 649         Returns the @e nth paragraph style.
 650     */
 651     wxRichTextParagraphStyleDefinition* GetParagraphStyle(size_t n) const;
 652
 653     /**
 654         Returns the number of paragraph styles.
 655     */
 656     size_t GetParagraphStyleCount() const;
 657
 658     /**
 659         Removes a character style.
 660     */
 661     bool RemoveCharacterStyle(wxRichTextStyleDefinition* def,
 662                               bool deleteStyle = false);
 663
 664     /**
 665         Removes a list style.
 666     */
 667     bool RemoveListStyle(wxRichTextStyleDefinition* def,
 668                          bool deleteStyle = false);
 669
 670     /**
 671         Removes a paragraph style.
 672     */
 673     bool RemoveParagraphStyle(wxRichTextStyleDefinition* def,
 674                               bool deleteStyle = false);
 675
 676     /**
 677         Removes a style.
 678     */
 679     bool RemoveStyle(wxRichTextStyleDefinition* def,
 680                      bool deleteStyle = false);
 681
 682     /**
 683         Sets the style sheet's description.
 684     */
 685     void SetDescription(const wxString& descr);
 686
 687     /**
 688         Sets the style sheet's name.
 689     */
 690     void SetName(const wxString& name);
 691
 692     /**
 693         Returns the sheet's properties.
 694     */
 695     wxRichTextProperties& GetProperties();
 696
 697     /**
 698         Returns the sheet's properties.
 699     */
 700     const wxRichTextProperties& GetProperties() const;
 701
 702     /**
 703         Sets the sheet's properties.
 704     */
 705     void SetProperties(const wxRichTextProperties& props);
 706 };
 707