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