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