interface/wx/richtext/richtextstyles.h

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