interface/richtext/richtextformatdlg.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        richtext/richtextformatdlg.h
   3 // Purpose:     documentation for wxRichTextFormattingDialogFactory class
   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);
  59
  60     /**
  61         Gets the number of available page identifiers.
  62     */
  63     virtual int GetPageIdCount();
  64
  65     /**
  66         Gets the image index for the given page identifier.
  67     */
  68     virtual int GetPageImage(int id);
  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     @class wxRichTextFormattingDialog
  86     @headerfile richtextformatdlg.h wx/richtext/richtextformatdlg.h
  87
  88     This dialog allows the user to edit a character and/or paragraph style.
  89
  90     In the constructor, specify the pages that will be created. Use GetStyle
  91     to retrieve the common style for a given range, and then use ApplyStyle
  92     to apply the user-selected formatting to a control. For example:
  93
  94     @code
  95     wxRichTextRange range;
  96         if (m_richTextCtrl-HasSelection())
  97             range = m_richTextCtrl-GetSelectionRange();
  98         else
  99             range = wxRichTextRange(0, m_richTextCtrl-GetLastPosition()+1);
 100
 101         int pages =
 102     wxRICHTEXT_FORMAT_FONT|wxRICHTEXT_FORMAT_INDENTS_SPACING|wxRICHTEXT_FORMAT_TABS|wxRICHTEXT_FORMAT_BULLETS;
 103
 104         wxRichTextFormattingDialog formatDlg(pages, this);
 105         formatDlg.GetStyle(m_richTextCtrl, range);
 106
 107         if (formatDlg.ShowModal() == wxID_OK)
 108         {
 109             formatDlg.ApplyStyle(m_richTextCtrl, range);
 110         }
 111     @endcode
 112
 113     @library{wxrichtext}
 114     @category{cmndlg}
 115 */
 116 class wxRichTextFormattingDialog : public wxPropertySheetDialog
 117 {
 118 public:
 119     //@{
 120     /**
 121         Constructors.
 122
 123         @param flags
 124         The pages to show.
 125
 126         @param parent
 127         The dialog's parent.
 128
 129         @param id
 130         The dialog's identifier.
 131
 132         @param title
 133         The dialog's caption.
 134
 135         @param pos
 136         The dialog's position.
 137
 138         @param size
 139         The dialog's size.
 140
 141         @param style
 142         The dialog's window style.
 143     */
 144     wxRichTextFormattingDialog(long flags, wxWindow* parent);
 145         const wxPoint& pos = wxDefaultPosition, const wxSize& sz = wxDefaultSize, long style = wxDEFAULT_DIALOG_STYLE)
 146  wxRichTextFormattingDialog();
 147     //@}
 148
 149     /**
 150         Destructor.
 151     */
 152     ~wxRichTextFormattingDialog();
 153
 154     /**
 155         Apply attributes to the given range, only changing attributes that need to be
 156         changed.
 157     */
 158     bool ApplyStyle(wxRichTextCtrl* ctrl,
 159                     const wxRichTextRange& range,
 160                     int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO|wxRICHTEXT_SETSTYLE_OPTIMIZE);
 161
 162     /**
 163         Creation: see @ref overview_wxrichtextformattingdialog "the constructor" for
 164         details about the parameters.
 165     */
 166     bool Create(long flags, wxWindow* parent, const wxString& title,
 167                 wxWindowID id,
 168                 const wxPoint& pos = wxDefaultPosition,
 169                 const wxSize& sz = wxDefaultSize,
 170                 long style = wxDEFAULT_DIALOG_STYLE);
 171
 172     //@{
 173     /**
 174         Gets the attributes being edited.
 175     */
 176     const wxTextAttr GetAttributes();
 177         wxTextAttr GetAttributes();
 178     //@}
 179
 180     /**
 181         Helper for pages to get the top-level dialog.
 182     */
 183     wxRichTextFormattingDialog* GetDialog(wxWindow* win);
 184
 185     /**
 186         Helper for pages to get the attributes.
 187     */
 188     wxTextAttr* GetDialogAttributes(wxWindow* win);
 189
 190     /**
 191         Helper for pages to get the style.
 192     */
 193     wxRichTextStyleDefinition* GetDialogStyleDefinition(wxWindow* win);
 194
 195     /**
 196         Returns the object to be used to customize the dialog and provide pages.
 197     */
 198     wxRichTextFormattingDialogFactory* GetFormattingDialogFactory();
 199
 200     /**
 201         Returns the image list associated with the dialog, used for example if showing
 202         the dialog as a toolbook.
 203     */
 204     wxImageList* GetImageList();
 205
 206     /**
 207         Gets common attributes from the given range and calls SetAttributes. Attributes
 208         that do not have common values in the given range
 209         will be omitted from the style's flags.
 210     */
 211     bool GetStyle(wxRichTextCtrl* ctrl, const wxRichTextRange& range);
 212
 213     /**
 214         Gets the associated style definition, if any.
 215     */
 216     wxRichTextStyleDefinition* GetStyleDefinition();
 217
 218     /**
 219         Gets the associated style sheet, if any.
 220     */
 221     wxRichTextStyleSheet* GetStyleSheet();
 222
 223     /**
 224         Sets the attributes to be edited.
 225     */
 226     void SetAttributes(const wxTextAttr& attr);
 227
 228     /**
 229         Sets the formatting factory object to be used for customization and page
 230         creation.
 231         It deletes the existing factory object.
 232     */
 233     void SetFormattingDialogFactory(wxRichTextFormattingDialogFactory* factory);
 234
 235     /**
 236         Sets the image list associated with the dialog's property sheet.
 237     */
 238     void SetImageList(wxImageList* imageList);
 239
 240     /**
 241         Sets the attributes and optionally updates the display, if @e update is @true.
 242     */
 243     bool SetStyle(const wxTextAttr& style, bool update = @true);
 244
 245     /**
 246         Sets the style definition and optionally update the display, if @e update is @c
 247         @true.
 248     */
 249     bool SetStyleDefinition(const wxRichTextStyleDefinition& styleDef,
 250                             wxRichTextStyleSheet* sheet,
 251                             bool update = @true);
 252
 253     /**
 254         Updates the display.
 255     */
 256     bool UpdateDisplay();
 257 };