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 @e 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 @e 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 @e 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 @e 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 @e 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. @e 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
 503         Returns the style for the given level. @e level is a number between 0 and 9.
 504     */
 505     int GetLevelCount();
 506
 507     /**
 508         Returns @true if the given level has numbered list attributes.
 509     */
 510     int IsNumbered(int level);
 511
 512     //@{
 513     /**
 514         Sets the style for the given level. @e level is a number between 0 and 9.
 515
 516         The first and most flexible form uses a wxTextAttr object, while the second
 517         form is for convenient setting of the most commonly-used attributes.
 518     */
 519     void SetLevelAttributes(int level, const wxTextAttr& attr);
 520     void SetLevelAttributes(int level, int leftIndent,
 521                             int leftSubIndent,
 522                             int bulletStyle,
 523                             const wxString& bulletSymbol = wxEmptyString);
 524     //@}
 525 };
 526
 527
 528 /**
 529     @class wxRichTextStyleSheet
 530     @headerfile richtextstyles.h wx/richtext/richtextstyles.h
 531
 532     A style sheet contains named paragraph and character styles that make it
 533     easy for a user to apply combinations of attributes to a wxRichTextCtrl.
 534
 535     You can use a wxRichTextStyleListBox in your
 536     user interface to show available styles to the user, and allow application
 537     of styles to the control.
 538
 539     @library{wxrichtext}
 540     @category{FIXME}
 541 */
 542 class wxRichTextStyleSheet : public wxObject
 543 {
 544 public:
 545     /**
 546         Constructor.
 547     */
 548     wxRichTextStyleSheet();
 549
 550     /**
 551         Destructor.
 552     */
 553     ~wxRichTextStyleSheet();
 554
 555     /**
 556         Adds a definition to the character style list.
 557     */
 558     bool AddCharacterStyle(wxRichTextCharacterStyleDefinition* def);
 559
 560     /**
 561         Adds a definition to the list style list.
 562     */
 563     bool AddListStyle(wxRichTextListStyleDefinition* def);
 564
 565     /**
 566         Adds a definition to the paragraph style list.
 567     */
 568     bool AddParagraphStyle(wxRichTextParagraphStyleDefinition* def);
 569
 570     /**
 571         Adds a definition to the appropriate style list.
 572     */
 573     bool AddStyle(wxRichTextStyleDefinition* def);
 574
 575     /**
 576         Deletes all styles.
 577     */
 578     void DeleteStyles();
 579
 580     /**
 581         Finds a character definition by name.
 582     */
 583     wxRichTextCharacterStyleDefinition* FindCharacterStyle(const wxString& name);
 584
 585     /**
 586         Finds a list definition by name.
 587     */
 588     wxRichTextListStyleDefinition* FindListStyle(const wxString& name);
 589
 590     /**
 591         Finds a paragraph definition by name.
 592     */
 593     wxRichTextParagraphStyleDefinition* FindParagraphStyle(const wxString& name);
 594
 595     /**
 596         Finds a style definition by name.
 597     */
 598     wxRichTextStyleDefinition* FindStyle(const wxString& name);
 599
 600     /**
 601         Returns the @e nth character style.
 602     */
 603     wxRichTextCharacterStyleDefinition* GetCharacterStyle(size_t n);
 604
 605     /**
 606         Returns the number of character styles.
 607     */
 608     size_t GetCharacterStyleCount();
 609
 610     /**
 611         Returns the style sheet's description.
 612     */
 613     const wxString GetDescription();
 614
 615     /**
 616         Returns the @e nth list style.
 617     */
 618     wxRichTextListStyleDefinition* GetListStyle(size_t n);
 619
 620     /**
 621         Returns the number of list styles.
 622     */
 623     size_t GetListStyleCount();
 624
 625     /**
 626         Returns the style sheet's name.
 627     */
 628     const wxString GetName();
 629
 630     /**
 631         Returns the @e nth paragraph style.
 632     */
 633     wxRichTextParagraphStyleDefinition* GetParagraphStyle(size_t n);
 634
 635     /**
 636         Returns the number of paragraph styles.
 637     */
 638     size_t GetParagraphStyleCount();
 639
 640     /**
 641         Removes a character style.
 642     */
 643     bool RemoveCharacterStyle(wxRichTextStyleDefinition* def,
 644                               bool deleteStyle = @false);
 645
 646     /**
 647         Removes a list style.
 648     */
 649     bool RemoveListStyle(wxRichTextStyleDefinition* def,
 650                          bool deleteStyle = @false);
 651
 652     /**
 653         Removes a paragraph style.
 654     */
 655     bool RemoveParagraphStyle(wxRichTextStyleDefinition* def,
 656                               bool deleteStyle = @false);
 657
 658     /**
 659         Removes a style.
 660     */
 661     bool RemoveStyle(wxRichTextStyleDefinition* def,
 662                      bool deleteStyle = @false);
 663
 664     /**
 665         Sets the style sheet's description.
 666     */
 667     void SetDescription(const wxString& descr);
 668
 669     /**
 670         Sets the style sheet's name.
 671     */
 672     void SetName(const wxString& name);
 673 };