interface/richtext/richtextformatdlg.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        richtext/richtextformatdlg.h
   3 // Purpose:     interface of wxRichTextFormattingDialogFactory
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxRichTextFormattingDialogFactory
  11     @headerfile richtextformatdlg.h wx/richtext/richtextformatdlg.h
  12
  13     This class provides pages for wxRichTextFormattingDialog, and allows other
  14     customization of the dialog.
  15     A default instance of this class is provided automatically. If you wish to
  16     change the behaviour of the
  17     formatting dialog (for example add or replace a page), you may derive from this
  18     class,
  19     override one or more functions, and call the static function
  20     wxRichTextFormattingDialog::SetFormattingDialogFactory.
  21
  22     @library{wxrichtext}
  23     @category{FIXME}
  24 */
  25 class wxRichTextFormattingDialogFactory : public wxObject
  26 {
  27 public:
  28     /**
  29         Constructor.
  30     */
  31     wxRichTextFormattingDialogFactory();
  32
  33     /**
  34         Destructor.
  35     */
  36     ~wxRichTextFormattingDialogFactory();
  37
  38     /**
  39         Creates the main dialog buttons.
  40     */
  41     virtual bool CreateButtons(wxRichTextFormattingDialog* dialog);
  42
  43     /**
  44         Creates a page, given a page identifier.
  45     */
  46     virtual wxPanel* CreatePage(int page, wxString& title,
  47                                 wxRichTextFormattingDialog* dialog);
  48
  49     /**
  50         Creates all pages under the dialog's book control, also calling AddPage.
  51     */
  52     virtual bool CreatePages(long pages,
  53                              wxRichTextFormattingDialog* dialog);
  54
  55     /**
  56         Enumerate all available page identifiers.
  57     */
  58     virtual int GetPageId(int i) const;
  59
  60     /**
  61         Gets the number of available page identifiers.
  62     */
  63     virtual int GetPageIdCount() const;
  64
  65     /**
  66         Gets the image index for the given page identifier.
  67     */
  68     virtual int GetPageImage(int id) const;
  69
  70     /**
  71         Set the property sheet style, called at the start of
  72         wxRichTextFormattingDialog::Create.
  73     */
  74     virtual bool SetSheetStyle(wxRichTextFormattingDialog* dialog);
  75
  76     /**
  77         Invokes help for the dialog.
  78     */
  79     virtual bool ShowHelp(int page,
  80                           wxRichTextFormattingDialog* dialog);
  81 };
  82
  83
  84
  85 /**
  86     @class wxRichTextFormattingDialog
  87     @headerfile richtextformatdlg.h wx/richtext/richtextformatdlg.h
  88
  89     This dialog allows the user to edit a character and/or paragraph style.
  90
  91     In the constructor, specify the pages that will be created. Use GetStyle
  92     to retrieve the common style for a given range, and then use ApplyStyle
  93     to apply the user-selected formatting to a control. For example:
  94
  95     @code
  96     wxRichTextRange range;
  97         if (m_richTextCtrl-HasSelection())
  98             range = m_richTextCtrl-GetSelectionRange();
  99         else
 100             range = wxRichTextRange(0, m_richTextCtrl-GetLastPosition()+1);
 101
 102         int pages =
 103     wxRICHTEXT_FORMAT_FONT|wxRICHTEXT_FORMAT_INDENTS_SPACING|wxRICHTEXT_FORMAT_TABS|wxRICHTEXT_FORMAT_BULLETS;
 104
 105         wxRichTextFormattingDialog formatDlg(pages, this);
 106         formatDlg.GetStyle(m_richTextCtrl, range);
 107
 108         if (formatDlg.ShowModal() == wxID_OK)
 109         {
 110             formatDlg.ApplyStyle(m_richTextCtrl, range);
 111         }
 112     @endcode
 113
 114     @library{wxrichtext}
 115     @category{richtext}
 116 */
 117 class wxRichTextFormattingDialog : public wxPropertySheetDialog
 118 {
 119 public:
 120     //@{
 121     /**
 122         Constructors.
 123
 124         @param flags
 125             The pages to show.
 126         @param parent
 127             The dialog's parent.
 128         @param id
 129             The dialog's identifier.
 130         @param title
 131             The dialog's caption.
 132         @param pos
 133             The dialog's position.
 134         @param size
 135             The dialog's size.
 136         @param style
 137             The dialog's window style.
 138     */
 139     wxRichTextFormattingDialog(long flags, wxWindow* parent);
 140     const wxPoint& pos = wxDefaultPosition, const wxSize& sz = wxDefaultSize, long style = wxDEFAULT_DIALOG_STYLE)
 141     wxRichTextFormattingDialog();
 142     //@}
 143
 144     /**
 145         Destructor.
 146     */
 147     ~wxRichTextFormattingDialog();
 148
 149     /**
 150         Apply attributes to the given range, only changing attributes that need to be
 151         changed.
 152     */
 153     bool ApplyStyle(wxRichTextCtrl* ctrl,
 154                     const wxRichTextRange& range,
 155                     int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO|wxRICHTEXT_SETSTYLE_OPTIMIZE);
 156
 157     /**
 158         Creation: see @ref overview_wxrichtextformattingdialog "the constructor" for
 159         details about the parameters.
 160     */
 161     bool Create(long flags, wxWindow* parent, const wxString& title,
 162                 wxWindowID id,
 163                 const wxPoint& pos = wxDefaultPosition,
 164                                      const wxSize& sz = wxDefaultSize,
 165                                                         long style = wxDEFAULT_DIALOG_STYLE);
 166
 167     //@{
 168     /**
 169         Gets the attributes being edited.
 170     */
 171     const wxTextAttr GetAttributes();
 172     const wxTextAttr&  GetAttributes();
 173     //@}
 174
 175     /**
 176         Helper for pages to get the top-level dialog.
 177     */
 178     wxRichTextFormattingDialog* GetDialog(wxWindow* win);
 179
 180     /**
 181         Helper for pages to get the attributes.
 182     */
 183     wxTextAttr* GetDialogAttributes(wxWindow* win);
 184
 185     /**
 186         Helper for pages to get the style.
 187     */
 188     wxRichTextStyleDefinition* GetDialogStyleDefinition(wxWindow* win);
 189
 190     /**
 191         Returns the object to be used to customize the dialog and provide pages.
 192     */
 193     wxRichTextFormattingDialogFactory* GetFormattingDialogFactory();
 194
 195     /**
 196         Returns the image list associated with the dialog, used for example if showing
 197         the dialog as a toolbook.
 198     */
 199     wxImageList* GetImageList() const;
 200
 201     /**
 202         Gets common attributes from the given range and calls SetAttributes. Attributes
 203         that do not have common values in the given range
 204         will be omitted from the style's flags.
 205     */
 206     bool GetStyle(wxRichTextCtrl* ctrl, const wxRichTextRange& range);
 207
 208     /**
 209         Gets the associated style definition, if any.
 210     */
 211     wxRichTextStyleDefinition* GetStyleDefinition() const;
 212
 213     /**
 214         Gets the associated style sheet, if any.
 215     */
 216     wxRichTextStyleSheet* GetStyleSheet() const;
 217
 218     /**
 219         Sets the attributes to be edited.
 220     */
 221     void SetAttributes(const wxTextAttr& attr);
 222
 223     /**
 224         Sets the formatting factory object to be used for customization and page
 225         creation.
 226         It deletes the existing factory object.
 227     */
 228     void SetFormattingDialogFactory(wxRichTextFormattingDialogFactory* factory);
 229
 230     /**
 231         Sets the image list associated with the dialog's property sheet.
 232     */
 233     void SetImageList(wxImageList* imageList);
 234
 235     /**
 236         Sets the attributes and optionally updates the display, if @a update is @true.
 237     */
 238     bool SetStyle(const wxTextAttr& style, bool update = true);
 239
 240     /**
 241         Sets the style definition and optionally update the display, if @a update is @c
 242         @true.
 243     */
 244     bool SetStyleDefinition(const wxRichTextStyleDefinition& styleDef,
 245                             wxRichTextStyleSheet* sheet,
 246                             bool update = true);
 247
 248     /**
 249         Updates the display.
 250     */
 251     bool UpdateDisplay();
 252 };
 253