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