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         @param parent
 126             The dialog's parent.
 127         @param id
 128             The dialog's identifier.
 129         @param title
 130             The dialog's caption.
 131         @param pos
 132             The dialog's position.
 133         @param size
 134             The dialog's size.
 135         @param style
 136             The dialog's window style.
 137     */
 138     wxRichTextFormattingDialog(long flags, wxWindow* parent);
 139     const wxPoint& pos = wxDefaultPosition, const wxSize& sz = wxDefaultSize, long style = wxDEFAULT_DIALOG_STYLE)
 140     wxRichTextFormattingDialog();
 141     //@}
 142
 143     /**
 144         Destructor.
 145     */
 146     ~wxRichTextFormattingDialog();
 147
 148     /**
 149         Apply attributes to the given range, only changing attributes that need to be
 150         changed.
 151     */
 152     bool ApplyStyle(wxRichTextCtrl* ctrl,
 153                     const wxRichTextRange& range,
 154                     int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO|wxRICHTEXT_SETSTYLE_OPTIMIZE);
 155
 156     /**
 157         Creation: see @ref overview_wxrichtextformattingdialog "the constructor" for
 158         details about the parameters.
 159     */
 160     bool Create(long flags, wxWindow* parent, const wxString& title,
 161                 wxWindowID id,
 162                 const wxPoint& pos = wxDefaultPosition,
 163                                      const wxSize& sz = wxDefaultSize,
 164                                                         long style = wxDEFAULT_DIALOG_STYLE);
 165
 166     //@{
 167     /**
 168         Gets the attributes being edited.
 169     */
 170     const wxTextAttr GetAttributes();
 171     wxTextAttr GetAttributes();
 172     //@}
 173
 174     /**
 175         Helper for pages to get the top-level dialog.
 176     */
 177     wxRichTextFormattingDialog* GetDialog(wxWindow* win);
 178
 179     /**
 180         Helper for pages to get the attributes.
 181     */
 182     wxTextAttr* GetDialogAttributes(wxWindow* win);
 183
 184     /**
 185         Helper for pages to get the style.
 186     */
 187     wxRichTextStyleDefinition* GetDialogStyleDefinition(wxWindow* win);
 188
 189     /**
 190         Returns the object to be used to customize the dialog and provide pages.
 191     */
 192     wxRichTextFormattingDialogFactory* GetFormattingDialogFactory();
 193
 194     /**
 195         Returns the image list associated with the dialog, used for example if showing
 196         the dialog as a toolbook.
 197     */
 198     wxImageList* GetImageList();
 199
 200     /**
 201         Gets common attributes from the given range and calls SetAttributes. Attributes
 202         that do not have common values in the given range
 203         will be omitted from the style's flags.
 204     */
 205     bool GetStyle(wxRichTextCtrl* ctrl, const wxRichTextRange& range);
 206
 207     /**
 208         Gets the associated style definition, if any.
 209     */
 210     wxRichTextStyleDefinition* GetStyleDefinition();
 211
 212     /**
 213         Gets the associated style sheet, if any.
 214     */
 215     wxRichTextStyleSheet* GetStyleSheet();
 216
 217     /**
 218         Sets the attributes to be edited.
 219     */
 220     void SetAttributes(const wxTextAttr& attr);
 221
 222     /**
 223         Sets the formatting factory object to be used for customization and page
 224         creation.
 225         It deletes the existing factory object.
 226     */
 227     void SetFormattingDialogFactory(wxRichTextFormattingDialogFactory* factory);
 228
 229     /**
 230         Sets the image list associated with the dialog's property sheet.
 231     */
 232     void SetImageList(wxImageList* imageList);
 233
 234     /**
 235         Sets the attributes and optionally updates the display, if @a update is @true.
 236     */
 237     bool SetStyle(const wxTextAttr& style, bool update = true);
 238
 239     /**
 240         Sets the style definition and optionally update the display, if @a update is @c
 241         @true.
 242     */
 243     bool SetStyleDefinition(const wxRichTextStyleDefinition& styleDef,
 244                             wxRichTextStyleSheet* sheet,
 245                             bool update = true);
 246
 247     /**
 248         Updates the display.
 249     */
 250     bool UpdateDisplay();
 251 };