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 license
   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     wxTextAttr GetStyle() const;
 154     const wxTextAttr 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     wxTextAttr GetStyleMergedWithBase(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 wxTextAttr& style);
 182 };
 183
 184
 185
 186 /**
 187     @class wxRichTextParagraphStyleDefinition
 188
 189     This class represents a paragraph style definition, usually added to a
 190     wxRichTextStyleSheet.
 191
 192     @library{wxrichtext}
 193     @category{richtext}
 194 */
 195 class wxRichTextParagraphStyleDefinition : public wxRichTextStyleDefinition
 196 {
 197 public:
 198     /**
 199         Constructor.
 200     */
 201     wxRichTextParagraphStyleDefinition(const wxString& name = wxEmptyString);
 202
 203     /**
 204         Destructor.
 205     */
 206     virtual ~wxRichTextParagraphStyleDefinition();
 207
 208     /**
 209         Returns the style that should normally follow this style.
 210     */
 211     const wxString GetNextStyle() const;
 212
 213     /**
 214         Sets the style that should normally follow this style.
 215     */
 216     void SetNextStyle(const wxString& name);
 217 };
 218
 219
 220
 221 /**
 222     @class wxRichTextStyleListBox
 223
 224     This is a listbox that can display the styles in a wxRichTextStyleSheet,
 225     and apply the selection to an associated wxRichTextCtrl.
 226
 227     See @c samples/richtext for an example of how to use it.
 228
 229     @library{wxrichtext}
 230     @category{richtext}
 231
 232     @see wxRichTextStyleComboCtrl, @ref overview_richtextctrl
 233 */
 234 class wxRichTextStyleListBox : public wxHtmlListBox
 235 {
 236 public:
 237     /**
 238         Constructor.
 239     */
 240     wxRichTextStyleListBox(wxWindow* parent,
 241                            wxWindowID id = wxID_ANY,
 242                            const wxPoint& pos = wxDefaultPosition,
 243                            const wxSize& size = wxDefaultSize,
 244                            long style = 0);
 245
 246     /**
 247         Destructor.
 248     */
 249     virtual ~wxRichTextStyleListBox();
 250
 251     /**
 252         Applies the @e ith style to the associated rich text control.
 253     */
 254     void ApplyStyle(int i);
 255
 256     /**
 257         Converts units in tenths of a millimetre to device units.
 258     */
 259     int ConvertTenthsMMToPixels(wxDC& dc, int units) const;
 260
 261     /**
 262         Creates a suitable HTML fragment for a definition.
 263     */
 264     wxString CreateHTML(wxRichTextStyleDefinition* def) const;
 265
 266     /**
 267         If the return value is @true, clicking on a style name in the list will
 268         immediately apply the style to the associated rich text control.
 269     */
 270     bool GetApplyOnSelection() const;
 271
 272     /**
 273         Returns the wxRichTextCtrl associated with this listbox.
 274     */
 275     wxRichTextCtrl* GetRichTextCtrl() const;
 276
 277     /**
 278         Gets a style for a listbox index.
 279     */
 280     wxRichTextStyleDefinition* GetStyle(size_t i) const;
 281
 282     /**
 283         Returns the style sheet associated with this listbox.
 284     */
 285     wxRichTextStyleSheet* GetStyleSheet() const;
 286
 287     /**
 288         Returns the type of style to show in the list box.
 289     */
 290     wxRichTextStyleListBox::wxRichTextStyleType GetStyleType() const;
 291
 292     /**
 293         Returns the HTML for this item.
 294     */
 295     virtual wxString OnGetItem(size_t n) const;
 296
 297     /**
 298         Implements left click behaviour, applying the clicked style to the
 299         wxRichTextCtrl.
 300     */
 301     void OnLeftDown(wxMouseEvent& event);
 302
 303     /**
 304         Reacts to selection.
 305     */
 306     void OnSelect(wxCommandEvent& event);
 307
 308     /**
 309         If @a applyOnSelection is @true, clicking on a style name in the list will
 310         immediately apply the style to the associated rich text control.
 311     */
 312     void SetApplyOnSelection(bool applyOnSelection);
 313
 314     /**
 315         Associates the listbox with a wxRichTextCtrl.
 316     */
 317     void SetRichTextCtrl(wxRichTextCtrl* ctrl);
 318
 319     /**
 320         Associates the control with a style sheet.
 321     */
 322     void SetStyleSheet(wxRichTextStyleSheet* styleSheet);
 323
 324     /**
 325         Sets the style type to display. One of
 326         - wxRichTextStyleListBox::wxRICHTEXT_STYLE_ALL,
 327         - wxRichTextStyleListBox::wxRICHTEXT_STYLE_PARAGRAPH,
 328         - wxRichTextStyleListBox::wxRICHTEXT_STYLE_CHARACTER
 329         - wxRichTextStyleListBox::wxRICHTEXT_STYLE_LIST.
 330     */
 331     void SetStyleType(wxRichTextStyleListBox::wxRichTextStyleType styleType);
 332
 333     /**
 334         Updates the list from the associated style sheet.
 335     */
 336     void UpdateStyles();
 337 };
 338
 339
 340
 341 /**
 342     @class wxRichTextStyleComboCtrl
 343
 344     This is a combo control that can display the styles in a wxRichTextStyleSheet,
 345     and apply the selection to an associated wxRichTextCtrl.
 346
 347     See @c samples/richtext for an example of how to use it.
 348
 349     @library{wxrichtext}
 350     @category{richtext}
 351
 352     @see wxRichTextStyleListBox, @ref overview_richtextctrl
 353 */
 354 class wxRichTextStyleComboCtrl : public wxComboCtrl
 355 {
 356 public:
 357     /**
 358         Constructor.
 359     */
 360     wxRichTextStyleComboCtrl(wxWindow* parent,
 361                              wxWindowID id = wxID_ANY,
 362                              const wxPoint& pos = wxDefaultPosition,
 363                              const wxSize& size = wxDefaultSize,
 364                              long style = 0);
 365
 366     /**
 367         Destructor.
 368     */
 369     virtual ~wxRichTextStyleComboCtrl();
 370
 371     /**
 372         Returns the wxRichTextCtrl associated with this control.
 373     */
 374     wxRichTextCtrl* GetRichTextCtrl() const;
 375
 376     /**
 377         Returns the style sheet associated with this control.
 378     */
 379     wxRichTextStyleSheet* GetStyleSheet() const;
 380
 381     /**
 382         Associates the control with a wxRichTextCtrl.
 383     */
 384     void SetRichTextCtrl(wxRichTextCtrl* ctrl);
 385
 386     /**
 387         Associates the control with a style sheet.
 388     */
 389     void SetStyleSheet(wxRichTextStyleSheet* styleSheet);
 390
 391     /**
 392         Updates the combo control from the associated style sheet.
 393     */
 394     void UpdateStyles();
 395 };
 396
 397
 398
 399 /**
 400     @class wxRichTextCharacterStyleDefinition
 401
 402     This class represents a character style definition, usually added to a
 403     wxRichTextStyleSheet.
 404
 405     @library{wxrichtext}
 406     @category{richtext}
 407 */
 408 class wxRichTextCharacterStyleDefinition : public wxRichTextStyleDefinition
 409 {
 410 public:
 411     /**
 412         Constructor.
 413     */
 414     wxRichTextCharacterStyleDefinition(const wxString& name = wxEmptyString);
 415
 416     /**
 417         Destructor.
 418     */
 419     virtual ~wxRichTextCharacterStyleDefinition();
 420 };
 421
 422
 423
 424 /**
 425     @class wxRichTextListStyleDefinition
 426
 427     This class represents a list style definition, usually added to a
 428     wxRichTextStyleSheet.
 429
 430     The class inherits paragraph attributes from wxRichTextStyleParagraphDefinition,
 431     and adds 10 further attribute objects, one for each level of a list.
 432     When applying a list style to a paragraph, the list style's base and
 433     appropriate level attributes are merged with the paragraph's existing attributes.
 434
 435     You can apply a list style to one or more paragraphs using wxRichTextCtrl::SetListStyle.
 436     You can also use the functions wxRichTextCtrl::NumberList, wxRichTextCtrl::PromoteList and
 437     wxRichTextCtrl::ClearListStyle.
 438
 439     As usual, there are wxRichTextBuffer versions of these functions
 440     so that you can apply them directly to a buffer without requiring a control.
 441
 442     @library{wxrichtext}
 443     @category{richtext}
 444 */
 445 class wxRichTextListStyleDefinition : public wxRichTextParagraphStyleDefinition
 446 {
 447 public:
 448     /**
 449         Constructor.
 450     */
 451     wxRichTextListStyleDefinition(const wxString& name = wxEmptyString);
 452
 453     /**
 454         Destructor.
 455     */
 456     virtual ~wxRichTextListStyleDefinition();
 457
 458     /**
 459         This function combines the given paragraph style with the list style's base
 460         attributes and level style matching the given indent, returning the combined attributes.
 461
 462         If @a styleSheet is specified, the base style for this definition will also be
 463         included in the result.
 464     */
 465     wxTextAttr CombineWithParagraphStyle(int indent,
 466                                          const wxTextAttr& paraStyle,
 467                                          wxRichTextStyleSheet* styleSheet = NULL);
 468
 469     /**
 470         This function finds the level (from 0 to 9) whose indentation attribute mostly
 471         closely matches @a indent (expressed in tenths of a millimetre).
 472     */
 473     int FindLevelForIndent(int indent) const;
 474
 475     /**
 476         This function combines the list style's base attributes and the level style
 477         matching the given indent, returning the combined attributes.
 478
 479         If @a styleSheet is specified, the base style for this definition will also be
 480         included in the result.
 481     */
 482     wxTextAttr GetCombinedStyle(int indent,
 483                                 wxRichTextStyleSheet* styleSheet = NULL) const;
 484
 485     /**
 486         This function combines the list style's base attributes and the style for the
 487         specified level, returning the combined attributes.
 488
 489         If @a styleSheet is specified, the base style for this definition will also be
 490         included in the result.
 491     */
 492     wxTextAttr GetCombinedStyleLevel(int level,
 493                                      wxRichTextStyleSheet* styleSheet = NULL) const;
 494
 495     /**
 496         Returns the style for the given level. @a level is a number between 0 and 9.
 497     */
 498     const wxTextAttr* GetLevelAttributes(int level) const;
 499
 500     /**
 501         Returns the number of levels. This is hard-wired to 10.
 502         Returns the style for the given level. @e level is a number between 0 and 9.
 503     */
 504     int GetLevelCount() const;
 505
 506     /**
 507         Returns @true if the given level has numbered list attributes.
 508     */
 509     int IsNumbered(int level) const;
 510
 511     //@{
 512     /**
 513         Sets the style for the given level. @a level is a number between 0 and 9.
 514         The first and most flexible form uses a wxTextAttr object, while the second
 515         form is for convenient setting of the most commonly-used attributes.
 516     */
 517     void SetLevelAttributes(int level, const wxTextAttr& attr);
 518     void SetLevelAttributes(int level, int leftIndent,
 519                             int leftSubIndent,
 520                             int bulletStyle,
 521                             const wxString& bulletSymbol = wxEmptyString);
 522     //@}
 523 };
 524
 525
 526
 527 /**
 528     @class wxRichTextStyleSheet
 529
 530     A style sheet contains named paragraph and character styles that make it
 531     easy for a user to apply combinations of attributes to a wxRichTextCtrl.
 532
 533     You can use a wxRichTextStyleListBox in your user interface to show available
 534     styles to the user, and allow application of styles to the control.
 535
 536     @library{wxrichtext}
 537     @category{richtext}
 538 */
 539 class wxRichTextStyleSheet : public wxObject
 540 {
 541 public:
 542     /**
 543         Constructor.
 544     */
 545     wxRichTextStyleSheet();
 546
 547     /**
 548         Destructor.
 549     */
 550     virtual ~wxRichTextStyleSheet();
 551
 552     /**
 553         Adds a definition to the character style list.
 554     */
 555     bool AddCharacterStyle(wxRichTextCharacterStyleDefinition* def);
 556
 557     /**
 558         Adds a definition to the list style list.
 559     */
 560     bool AddListStyle(wxRichTextListStyleDefinition* def);
 561
 562     /**
 563         Adds a definition to the paragraph style list.
 564     */
 565     bool AddParagraphStyle(wxRichTextParagraphStyleDefinition* def);
 566
 567     /**
 568         Adds a definition to the appropriate style list.
 569     */
 570     bool AddStyle(wxRichTextStyleDefinition* def);
 571
 572     /**
 573         Deletes all styles.
 574     */
 575     void DeleteStyles();
 576
 577     /**
 578         Finds a character definition by name.
 579     */
 580     wxRichTextCharacterStyleDefinition* FindCharacterStyle(const wxString& name) const;
 581
 582     /**
 583         Finds a list definition by name.
 584     */
 585     wxRichTextListStyleDefinition* FindListStyle(const wxString& name) const;
 586
 587     /**
 588         Finds a paragraph definition by name.
 589     */
 590     wxRichTextParagraphStyleDefinition* FindParagraphStyle(const wxString& name) const;
 591
 592     /**
 593         Finds a style definition by name.
 594     */
 595     wxRichTextStyleDefinition* FindStyle(const wxString& name) const;
 596
 597     /**
 598         Returns the @e nth character style.
 599     */
 600     wxRichTextCharacterStyleDefinition* GetCharacterStyle(size_t n) const;
 601
 602     /**
 603         Returns the number of character styles.
 604     */
 605     size_t GetCharacterStyleCount() const;
 606
 607     /**
 608         Returns the style sheet's description.
 609     */
 610     const wxString GetDescription() const;
 611
 612     /**
 613         Returns the @e nth list style.
 614     */
 615     wxRichTextListStyleDefinition* GetListStyle(size_t n) const;
 616
 617     /**
 618         Returns the number of list styles.
 619     */
 620     size_t GetListStyleCount() const;
 621
 622     /**
 623         Returns the style sheet's name.
 624     */
 625     const wxString GetName() const;
 626
 627     /**
 628         Returns the @e nth paragraph style.
 629     */
 630     wxRichTextParagraphStyleDefinition* GetParagraphStyle(size_t n) const;
 631
 632     /**
 633         Returns the number of paragraph styles.
 634     */
 635     size_t GetParagraphStyleCount() const;
 636
 637     /**
 638         Removes a character style.
 639     */
 640     bool RemoveCharacterStyle(wxRichTextStyleDefinition* def,
 641                               bool deleteStyle = false);
 642
 643     /**
 644         Removes a list style.
 645     */
 646     bool RemoveListStyle(wxRichTextStyleDefinition* def,
 647                          bool deleteStyle = false);
 648
 649     /**
 650         Removes a paragraph style.
 651     */
 652     bool RemoveParagraphStyle(wxRichTextStyleDefinition* def,
 653                               bool deleteStyle = false);
 654
 655     /**
 656         Removes a style.
 657     */
 658     bool RemoveStyle(wxRichTextStyleDefinition* def,
 659                      bool deleteStyle = false);
 660
 661     /**
 662         Sets the style sheet's description.
 663     */
 664     void SetDescription(const wxString& descr);
 665
 666     /**
 667         Sets the style sheet's name.
 668     */
 669     void SetName(const wxString& name);
 670 };
 671