interface/wx/richtext/richtextformatdlg.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        richtext/richtextformatdlg.h
   3 // Purpose:     interface of wxRichTextFormattingDialog*
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows licence
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxRichTextFormattingDialogFactory
  11
  12     This class provides pages for wxRichTextFormattingDialog, and allows other
  13     customization of the dialog.
  14
  15     A default instance of this class is provided automatically.
  16     If you wish to change the behaviour of the formatting dialog (for example add
  17     or replace a page), you may derive from this class, override one or more
  18     functions, and call the static function
  19     wxRichTextFormattingDialog::SetFormattingDialogFactory.
  20
  21     @library{wxrichtext}
  22     @category{richtext}
  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 #define wxRICHTEXT_FORMAT_STYLE_EDITOR      0x0001
  85 #define wxRICHTEXT_FORMAT_FONT              0x0002
  86 #define wxRICHTEXT_FORMAT_TABS              0x0004
  87 #define wxRICHTEXT_FORMAT_BULLETS           0x0008
  88 #define wxRICHTEXT_FORMAT_INDENTS_SPACING   0x0010
  89
  90 /**
  91     @class wxRichTextFormattingDialog
  92
  93     This dialog allows the user to edit a character and/or paragraph style.
  94
  95     In the constructor, specify the pages that will be created.
  96     Use wxRichTextFormattingDialog::GetStyle() to retrieve the common style
  97     for a given range, and then use wxRichTextFormattingDialog::ApplyStyle()
  98     to apply the user-selected formatting to a control.
  99
 100     For example:
 101     @code
 102         wxRichTextRange range;
 103         if (m_richTextCtrl-HasSelection())
 104             range = m_richTextCtrl-GetSelectionRange();
 105         else
 106             range = wxRichTextRange(0, m_richTextCtrl-GetLastPosition()+1);
 107
 108         int pages = wxRICHTEXT_FORMAT_FONT|wxRICHTEXT_FORMAT_INDENTS_SPACING| \
 109                     wxRICHTEXT_FORMAT_TABS|wxRICHTEXT_FORMAT_BULLETS;
 110
 111         wxRichTextFormattingDialog formatDlg(pages, this);
 112         formatDlg.GetStyle(m_richTextCtrl, range);
 113
 114         if (formatDlg.ShowModal() == wxID_OK)
 115         {
 116             formatDlg.ApplyStyle(m_richTextCtrl, range);
 117         }
 118     @endcode
 119
 120     @library{wxrichtext}
 121     @category{richtext}
 122 */
 123 class wxRichTextFormattingDialog : public wxPropertySheetDialog
 124 {
 125 public:
 126     enum { Option_AllowPixelFontSize = 0x0001 };
 127
 128     /**
 129         Default ctor.
 130     */
 131     wxRichTextFormattingDialog();
 132
 133     /**
 134         Constructors.
 135
 136         @param flags
 137             The pages to show.
 138         @param parent
 139             The dialog's parent.
 140         @param title
 141             The dialog's title.
 142         @param id
 143             The dialog's ID.
 144         @param pos
 145             The dialog's position.
 146         @param sz
 147             The dialog's size.
 148         @param style
 149             The dialog's window style.
 150     */
 151     wxRichTextFormattingDialog(long flags, wxWindow* parent, const wxString& title = "Formatting",
 152                                wxWindowID id = wxID_ANY, const wxPoint& pos = wxDefaultPosition,
 153                                const wxSize& sz = wxDefaultSize, long style = wxDEFAULT_DIALOG_STYLE);
 154
 155     /**
 156         Destructor.
 157     */
 158     virtual ~wxRichTextFormattingDialog();
 159
 160     /**
 161         Apply attributes to the given range, only changing attributes that
 162         need to be changed.
 163     */
 164     virtual bool ApplyStyle(wxRichTextCtrl* ctrl, const wxRichTextRange& range,
 165                             int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO|wxRICHTEXT_SETSTYLE_OPTIMIZE);
 166
 167     /**
 168         Creation: see wxRichTextFormattingDialog() "the constructor" for
 169         details about the parameters.
 170     */
 171     bool Create(long flags, wxWindow* parent,
 172                 const wxString& title = wxGetTranslation("Formatting"), wxWindowID id = wxID_ANY,
 173                 const wxPoint& pos = wxDefaultPosition, const wxSize& sz = wxDefaultSize,
 174                 long style = wxDEFAULT_DIALOG_STYLE);
 175
 176     //@{
 177     /**
 178         Gets the attributes being edited.
 179     */
 180     const wxTextAttr& GetAttributes() const;
 181     wxTextAttr& GetAttributes();
 182     //@}
 183
 184     /**
 185         Helper for pages to get the top-level dialog.
 186     */
 187     static wxRichTextFormattingDialog* GetDialog(wxWindow* win);
 188
 189     /**
 190         Helper for pages to get the attributes.
 191     */
 192     static wxTextAttr* GetDialogAttributes(wxWindow* win);
 193
 194     /**
 195         Helper for pages to get the style.
 196     */
 197     static wxRichTextStyleDefinition* GetDialogStyleDefinition(wxWindow* win);
 198
 199     /**
 200         Returns the object to be used to customize the dialog and provide pages.
 201     */
 202     static wxRichTextFormattingDialogFactory* GetFormattingDialogFactory();
 203
 204     /**
 205         Returns the image list associated with the dialog, used for example if showing
 206         the dialog as a toolbook.
 207     */
 208     wxImageList* GetImageList() const;
 209
 210     /**
 211         Gets common attributes from the given range and calls SetAttributes().
 212         Attributes that do not have common values in the given range
 213         will be omitted from the style's flags.
 214     */
 215     virtual bool GetStyle(wxRichTextCtrl* ctrl, const wxRichTextRange& range);
 216
 217     /**
 218         Gets the associated style definition, if any.
 219     */
 220     virtual wxRichTextStyleDefinition* GetStyleDefinition() const;
 221
 222     /**
 223         Gets the associated style sheet, if any.
 224     */
 225     virtual wxRichTextStyleSheet* GetStyleSheet() const;
 226
 227     /**
 228         Sets the attributes to be edited.
 229     */
 230     void SetAttributes(const wxTextAttr& attr);
 231
 232     /**
 233         Sets the dialog options, determining what the interface presents to the user.
 234         Currently the only option is Option_AllowPixelFontSize.
 235     */
 236     void SetOptions(int options) { m_options = options; }
 237
 238     /**
 239         Gets the dialog options, determining what the interface presents to the user.
 240         Currently the only option is Option_AllowPixelFontSize.
 241     */
 242     int GetOptions() const { return m_options; }
 243
 244     /**
 245         Returns @true if the given option is present.
 246     */
 247     bool HasOption(int option) const { return (m_options & option) != 0; }
 248
 249     /**
 250         Sets the formatting factory object to be used for customization and page
 251         creation.
 252
 253         It deletes the existing factory object.
 254     */
 255     static void SetFormattingDialogFactory(wxRichTextFormattingDialogFactory* factory);
 256
 257     /**
 258         Sets the image list associated with the dialog's property sheet.
 259     */
 260     void SetImageList(wxImageList* imageList);
 261
 262     /**
 263         Sets the attributes and optionally updates the display, if @a update is @true.
 264     */
 265     virtual bool SetStyle(const wxTextAttr& style, bool update = true);
 266
 267     /**
 268         Sets the style definition and optionally update the display,
 269         if @a update is @true.
 270     */
 271     virtual bool SetStyleDefinition(const wxRichTextStyleDefinition& styleDef,
 272                                     wxRichTextStyleSheet* sheet,
 273                                     bool update = true);
 274
 275     /**
 276         Updates the display.
 277     */
 278     virtual bool UpdateDisplay();
 279 };
 280