interface/richtext/richtextstyles.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        richtext/richtextstyles.h
   3 // Purpose:     documentation for wxRichTextStyleListCtrl class
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxRichTextStyleListCtrl
  11     @headerfile richtextstyles.h wx/richtext/richtextstyles.h
  12
  13     This class incorporates a wxRichTextStyleListBox and
  14     a choice control that allows the user to select the category of style to view.
  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
  19     one of 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     Associate the control with a style sheet and rich text control with
  24     SetStyleSheet and SetRichTextCtrl,
  25     so that when a style is double-clicked, 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{FIXME}
  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();
  62
  63     /**
  64         Returns the wxChoice control used for selecting the style category.
  65     */
  66     wxChoice* GetStyleChoice();
  67
  68     /**
  69         Returns the wxListBox control used to view the style list.
  70     */
  71     wxRichTextStyleListBox* GetStyleListBox();
  72
  73     /**
  74         Returns the associated style sheet, if any.
  75     */
  76     wxRichTextStyleSheet* GetStyleSheet();
  77
  78     /**
  79         Returns the type of style to show in the list box.
  80     */
  81     wxRichTextStyleListBox::wxRichTextStyleType GetStyleType();
  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. One of
  95         wxRichTextStyleListBox::wxRICHTEXT_STYLE_ALL, wxRichTextStyleListBox::wxRICHTEXT_STYLE_PARAGRAPH,
  96         wxRichTextStyleListBox::wxRICHTEXT_STYLE_CHARACTER and
  97         wxRichTextStyleListBox::wxRICHTEXT_STYLE_LIST.
  98     */
  99     void SetStyleType(wxRichTextStyleListBox::wxRichTextStyleType styleType);
 100
 101     /**
 102         Updates the style list box.
 103     */
 104     void UpdateStyles();
 105 };
 106
 107
 108 /**
 109     @class wxRichTextStyleDefinition
 110     @headerfile richtextstyles.h wx/richtext/richtextstyles.h
 111
 112     This is a base class for paragraph and character styles.
 113
 114     @library{wxrichtext}
 115     @category{FIXME}
 116 */
 117 class wxRichTextStyleDefinition : public wxObject
 118 {
 119 public:
 120     /**
 121         Constructor.
 122     */
 123     wxRichTextStyleDefinition(const wxString& name = wxEmptyString);
 124
 125     /**
 126         Destructor.
 127     */
 128     ~wxRichTextStyleDefinition();
 129
 130     /**
 131         Returns the style on which this style is based.
 132     */
 133     const wxString GetBaseStyle();
 134
 135     /**
 136         Returns the style's description.
 137     */
 138     const wxString GetDescription();
 139
 140     /**
 141         Returns the style name.
 142     */
 143     const wxString GetName();
 144
 145     //@{
 146     /**
 147         Returns the attributes associated with this style.
 148     */
 149     wxTextAttr GetStyle();
 150     const wxTextAttr GetStyle();
 151     //@}
 152
 153     /**
 154         Returns the style attributes combined with the attributes of the specified base
 155         style, if any. This function works recursively.
 156     */
 157     wxTextAttr GetStyleMergedWithBase(wxRichTextStyleSheet* sheet);
 158
 159     /**
 160         Sets the name of the style that this style is based on.
 161     */
 162     void SetBaseStyle(const wxString& name);
 163
 164     /**
 165         Sets the style description.
 166     */
 167     void SetDescription(const wxString& descr);
 168
 169     /**
 170         Sets the name of the style.
 171     */
 172     void SetName(const wxString& name);
 173
 174     /**
 175         Sets the attributes for this style.
 176     */
 177     void SetStyle(const wxTextAttr& style);
 178 };
 179
 180
 181 /**
 182     @class wxRichTextParagraphStyleDefinition
 183     @headerfile richtextstyles.h wx/richtext/richtextstyles.h
 184
 185     This class represents a paragraph style definition, usually added to a
 186     wxRichTextStyleSheet.
 187
 188     @library{wxrichtext}
 189     @category{FIXME}
 190 */
 191 class wxRichTextParagraphStyleDefinition : public wxRichTextStyleDefinition
 192 {
 193 public:
 194     /**
 195         Constructor.
 196     */
 197     wxRichTextParagraphStyleDefinition(const wxString& name = wxEmptyString);
 198
 199     /**
 200         Destructor.
 201     */
 202     ~wxRichTextParagraphStyleDefinition();
 203
 204     /**
 205         Returns the style that should normally follow this style.
 206     */
 207     const wxString GetNextStyle();
 208
 209     /**
 210         Sets the style that should normally follow this style.
 211     */
 212     void SetNextStyle(const wxString& name);
 213 };
 214
 215
 216 /**
 217     @class wxRichTextStyleListBox
 218     @headerfile richtextstyles.h wx/richtext/richtextstyles.h
 219
 220     This is a listbox that can display the styles in a wxRichTextStyleSheet,
 221     and apply the selection to an associated wxRichTextCtrl.
 222
 223     See @c samples/richtext for an example of how to use it.
 224
 225     @library{wxrichtext}
 226     @category{FIXME}
 227
 228     @seealso
 229     wxRichTextStyleComboCtrl, @ref overview_wxrichtextctrloverview "wxRichTextCtrl
 230     overview"
 231 */
 232 class wxRichTextStyleListBox : public wxHtmlListBox
 233 {
 234 public:
 235     /**
 236         Constructor.
 237     */
 238     wxRichTextStyleListBox(wxWindow* parent,
 239                            wxWindowID id = wxID_ANY,
 240                            const wxPoint& pos = wxDefaultPosition,
 241                            const wxSize& size = wxDefaultSize,
 242                            long style = 0);
 243
 244     /**
 245         Destructor.
 246     */
 247     ~wxRichTextStyleListBox();
 248
 249     /**
 250         Applies the @e ith style to the associated rich text control.
 251     */
 252     void ApplyStyle(int i);
 253
 254     /**
 255         Converts units in tenths of a millimetre to device units.
 256     */
 257     int ConvertTenthsMMToPixels(wxDC& dc, int units);
 258
 259     /**
 260         Creates a suitable HTML fragment for a definition.
 261     */
 262     wxString CreateHTML(wxRichTextStyleDefinition* def);
 263
 264     /**
 265         If the return value is @true, clicking on a style name in the list will
 266         immediately
 267         apply the style to the associated rich text control.
 268     */
 269     bool GetApplyOnSelection();
 270
 271     /**
 272         Returns the wxRichTextCtrl associated with this listbox.
 273     */
 274     wxRichTextCtrl* GetRichTextCtrl();
 275
 276     /**
 277         Gets a style for a listbox index.
 278     */
 279     wxRichTextStyleDefinition* GetStyle(size_t i);
 280
 281     /**
 282         Returns the style sheet associated with this listbox.
 283     */
 284     wxRichTextStyleSheet* GetStyleSheet();
 285
 286     /**
 287         Returns the type of style to show in the list box.
 288     */
 289     wxRichTextStyleListBox::wxRichTextStyleType GetStyleType();
 290
 291     /**
 292         Returns the HTML for this item.
 293     */
 294     wxString OnGetItem(size_t n);
 295
 296     /**
 297         Implements left click behaviour, applying the clicked style to the
 298         wxRichTextCtrl.
 299     */
 300     void OnLeftDown(wxMouseEvent& event);
 301
 302     /**
 303         Reacts to selection.
 304     */
 305     void OnSelect(wxCommandEvent& event);
 306
 307     /**
 308         If @a applyOnSelection is @true, clicking on a style name in the list will
 309         immediately
 310         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, wxRichTextStyleListBox::wxRICHTEXT_STYLE_PARAGRAPH,
 327         wxRichTextStyleListBox::wxRICHTEXT_STYLE_CHARACTER and
 328         wxRichTextStyleListBox::wxRICHTEXT_STYLE_LIST.
 329     */
 330     void SetStyleType(wxRichTextStyleListBox::wxRichTextStyleType styleType);
 331
 332     /**
 333         Updates the list from the associated style sheet.
 334     */
 335     void UpdateStyles();
 336 };
 337
 338
 339 /**
 340     @class wxRichTextStyleComboCtrl
 341     @headerfile richtextstyles.h wx/richtext/richtextstyles.h
 342
 343     This is a combo control that can display the styles in a wxRichTextStyleSheet,
 344     and apply the selection to an associated wxRichTextCtrl.
 345
 346     See @c samples/richtext for an example of how to use it.
 347
 348     @library{wxrichtext}
 349     @category{FIXME}
 350
 351     @seealso
 352     wxRichTextStyleListBox, @ref overview_wxrichtextctrloverview "wxRichTextCtrl
 353     overview"
 354 */
 355 class wxRichTextStyleComboCtrl : public wxComboCtrl
 356 {
 357 public:
 358     /**
 359         Constructor.
 360     */
 361     wxRichTextStyleComboCtrl(wxWindow* parent,
 362                              wxWindowID id = wxID_ANY,
 363                              const wxPoint& pos = wxDefaultPosition,
 364                              const wxSize& size = wxDefaultSize,
 365                              long style = 0);
 366
 367     /**
 368         Destructor.
 369     */
 370     ~wxRichTextStyleComboCtrl();
 371
 372     /**
 373         Returns the wxRichTextCtrl associated with this control.
 374     */
 375     wxRichTextCtrl* GetRichTextCtrl();
 376
 377     /**
 378         Returns the style sheet associated with this control.
 379     */
 380     wxRichTextStyleSheet* GetStyleSheet();
 381
 382     /**
 383         Associates the control with a wxRichTextCtrl.
 384     */
 385     void SetRichTextCtrl(wxRichTextCtrl* ctrl);
 386
 387     /**
 388         Associates the control with a style sheet.
 389     */
 390     void SetStyleSheet(wxRichTextStyleSheet* styleSheet);
 391
 392     /**
 393         Updates the combo control from the associated style sheet.
 394     */
 395     void UpdateStyles();
 396 };
 397
 398
 399 /**
 400     @class wxRichTextCharacterStyleDefinition
 401     @headerfile richtextstyles.h wx/richtext/richtextstyles.h
 402
 403     This class represents a character style definition, usually added to a
 404     wxRichTextStyleSheet.
 405
 406     @library{wxrichtext}
 407     @category{FIXME}
 408 */
 409 class wxRichTextCharacterStyleDefinition : public wxRichTextStyleDefinition
 410 {
 411 public:
 412     /**
 413         Constructor.
 414     */
 415     wxRichTextCharacterStyleDefinition(const wxString& name = wxEmptyString);
 416
 417     /**
 418         Destructor.
 419     */
 420     ~wxRichTextCharacterStyleDefinition();
 421 };
 422
 423
 424 /**
 425     @class wxRichTextListStyleDefinition
 426     @headerfile richtextstyles.h wx/richtext/richtextstyles.h
 427
 428     This class represents a list style definition, usually added to a
 429     wxRichTextStyleSheet.
 430
 431     The class inherits paragraph attributes from
 432     wxRichTextStyleParagraphDefinition, and adds 10 further attribute objects, one for each level of a list.
 433     When applying a list style to a paragraph, the list style's base and
 434     appropriate level attributes are merged with the
 435     paragraph's existing attributes.
 436
 437     You can apply a list style to one or more paragraphs using
 438     wxRichTextCtrl::SetListStyle. You
 439     can also use the functions wxRichTextCtrl::NumberList,
 440     wxRichTextCtrl::PromoteList and
 441     wxRichTextCtrl::ClearListStyle. As usual, there are wxRichTextBuffer versions
 442     of these functions
 443     so that you can apply them directly to a buffer without requiring a control.
 444
 445     @library{wxrichtext}
 446     @category{FIXME}
 447 */
 448 class wxRichTextListStyleDefinition : public wxRichTextParagraphStyleDefinition
 449 {
 450 public:
 451     /**
 452         Constructor.
 453     */
 454     wxRichTextListStyleDefinition(const wxString& name = wxEmptyString);
 455
 456     /**
 457         Destructor.
 458     */
 459     ~wxRichTextListStyleDefinition();
 460
 461     /**
 462         This function combines the given paragraph style with the list style's base
 463         attributes and level style matching the given indent, returning the combined attributes.
 464         If @a styleSheet is specified, the base style for this definition will also be
 465         included in the result.
 466     */
 467     wxTextAttr CombineWithParagraphStyle(int indent,
 468                                          const wxTextAttr& paraStyle,
 469                                          wxRichTextStyleSheet* styleSheet = NULL);
 470
 471     /**
 472         This function finds the level (from 0 to 9) whose indentation attribute mostly
 473         closely matches @a indent (expressed in tenths of a millimetre).
 474     */
 475     int FindLevelForIndent(int indent);
 476
 477     /**
 478         This function combines the list style's base attributes and the level style
 479         matching the given indent, returning the combined attributes.
 480         If @a styleSheet is specified, the base style for this definition will also be
 481         included in the result.
 482     */
 483     wxTextAttr GetCombinedStyle(int indent,
 484                                 wxRichTextStyleSheet* styleSheet = NULL);
 485
 486     /**
 487         This function combines the list style's base attributes and the style for the
 488         specified level, returning the combined attributes.
 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);
 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);
 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();
 505
 506     /**
 507         Returns @true if the given level has numbered list attributes.
 508     */
 509     int IsNumbered(int level);
 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     @class wxRichTextStyleSheet
 528     @headerfile richtextstyles.h wx/richtext/richtextstyles.h
 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
 534     user interface to show available styles to the user, and allow application
 535     of styles to the control.
 536
 537     @library{wxrichtext}
 538     @category{FIXME}
 539 */
 540 class wxRichTextStyleSheet : public wxObject
 541 {
 542 public:
 543     /**
 544         Constructor.
 545     */
 546     wxRichTextStyleSheet();
 547
 548     /**
 549         Destructor.
 550     */
 551     ~wxRichTextStyleSheet();
 552
 553     /**
 554         Adds a definition to the character style list.
 555     */
 556     bool AddCharacterStyle(wxRichTextCharacterStyleDefinition* def);
 557
 558     /**
 559         Adds a definition to the list style list.
 560     */
 561     bool AddListStyle(wxRichTextListStyleDefinition* def);
 562
 563     /**
 564         Adds a definition to the paragraph style list.
 565     */
 566     bool AddParagraphStyle(wxRichTextParagraphStyleDefinition* def);
 567
 568     /**
 569         Adds a definition to the appropriate style list.
 570     */
 571     bool AddStyle(wxRichTextStyleDefinition* def);
 572
 573     /**
 574         Deletes all styles.
 575     */
 576     void DeleteStyles();
 577
 578     /**
 579         Finds a character definition by name.
 580     */
 581     wxRichTextCharacterStyleDefinition* FindCharacterStyle(const wxString& name);
 582
 583     /**
 584         Finds a list definition by name.
 585     */
 586     wxRichTextListStyleDefinition* FindListStyle(const wxString& name);
 587
 588     /**
 589         Finds a paragraph definition by name.
 590     */
 591     wxRichTextParagraphStyleDefinition* FindParagraphStyle(const wxString& name);
 592
 593     /**
 594         Finds a style definition by name.
 595     */
 596     wxRichTextStyleDefinition* FindStyle(const wxString& name);
 597
 598     /**
 599         Returns the @e nth character style.
 600     */
 601     wxRichTextCharacterStyleDefinition* GetCharacterStyle(size_t n);
 602
 603     /**
 604         Returns the number of character styles.
 605     */
 606     size_t GetCharacterStyleCount();
 607
 608     /**
 609         Returns the style sheet's description.
 610     */
 611     const wxString GetDescription();
 612
 613     /**
 614         Returns the @e nth list style.
 615     */
 616     wxRichTextListStyleDefinition* GetListStyle(size_t n);
 617
 618     /**
 619         Returns the number of list styles.
 620     */
 621     size_t GetListStyleCount();
 622
 623     /**
 624         Returns the style sheet's name.
 625     */
 626     const wxString GetName();
 627
 628     /**
 629         Returns the @e nth paragraph style.
 630     */
 631     wxRichTextParagraphStyleDefinition* GetParagraphStyle(size_t n);
 632
 633     /**
 634         Returns the number of paragraph styles.
 635     */
 636     size_t GetParagraphStyleCount();
 637
 638     /**
 639         Removes a character style.
 640     */
 641     bool RemoveCharacterStyle(wxRichTextStyleDefinition* def,
 642                               bool deleteStyle = false);
 643
 644     /**
 645         Removes a list style.
 646     */
 647     bool RemoveListStyle(wxRichTextStyleDefinition* def,
 648                          bool deleteStyle = false);
 649
 650     /**
 651         Removes a paragraph style.
 652     */
 653     bool RemoveParagraphStyle(wxRichTextStyleDefinition* def,
 654                               bool deleteStyle = false);
 655
 656     /**
 657         Removes a style.
 658     */
 659     bool RemoveStyle(wxRichTextStyleDefinition* def,
 660                      bool deleteStyle = false);
 661
 662     /**
 663         Sets the style sheet's description.
 664     */
 665     void SetDescription(const wxString& descr);
 666
 667     /**
 668         Sets the style sheet's name.
 669     */
 670     void SetName(const wxString& name);
 671 };