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