interface/wx/richtext/richtextformatdlg.h

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