From 9e7ad1cab887c2f1cd1a624ec0aec60d20b4d6e2 Mon Sep 17 00:00:00 2001 From: Francesco Montorsi Date: Thu, 9 Oct 2008 16:30:57 +0000 Subject: [PATCH] revised richtext headers git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@56199 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775 --- interface/wx/richtext/richtextbuffer.h | 533 ++++++++++++++-------- interface/wx/richtext/richtextctrl.h | 426 +++++++++-------- interface/wx/richtext/richtextformatdlg.h | 83 ++-- interface/wx/richtext/richtexthtml.h | 79 +++- interface/wx/richtext/richtextprint.h | 115 +++-- interface/wx/richtext/richtextstyledlg.h | 126 +++-- interface/wx/richtext/richtextstyles.h | 76 +-- interface/wx/richtext/richtextsymboldlg.h | 71 +-- interface/wx/richtext/richtextxml.h | 24 +- 9 files changed, 899 insertions(+), 634 deletions(-) diff --git a/interface/wx/richtext/richtextbuffer.h b/interface/wx/richtext/richtextbuffer.h index 6753163ae1..0b63bdfd7d 100644 --- a/interface/wx/richtext/richtextbuffer.h +++ b/interface/wx/richtext/richtextbuffer.h @@ -6,6 +6,130 @@ // Licence: wxWindows license ///////////////////////////////////////////////////////////////////////////// + + +/*! + * File types in wxRichText context. + */ +enum wxRichTextFileType +{ + wxRICHTEXT_TYPE_ANY = 0, + wxRICHTEXT_TYPE_TEXT, + wxRICHTEXT_TYPE_XML, + wxRICHTEXT_TYPE_HTML, + wxRICHTEXT_TYPE_RTF, + wxRICHTEXT_TYPE_PDF +}; + +/*! + * Flags determining the available space, passed to Layout + */ + +#define wxRICHTEXT_FIXED_WIDTH 0x01 +#define wxRICHTEXT_FIXED_HEIGHT 0x02 +#define wxRICHTEXT_VARIABLE_WIDTH 0x04 +#define wxRICHTEXT_VARIABLE_HEIGHT 0x08 + +// Only lay out the part of the buffer that lies within +// the rect passed to Layout. +#define wxRICHTEXT_LAYOUT_SPECIFIED_RECT 0x10 + +/*! + * Flags to pass to Draw + */ + +// Ignore paragraph cache optimization, e.g. for printing purposes +// where one line may be drawn higher (on the next page) compared +// with the previous line +#define wxRICHTEXT_DRAW_IGNORE_CACHE 0x01 + +/*! + * Flags returned from hit-testing + */ +enum wxRichTextHitTestFlags +{ + /// The point was not on this object + wxRICHTEXT_HITTEST_NONE = 0x01, + + /// The point was before the position returned from HitTest + wxRICHTEXT_HITTEST_BEFORE = 0x02, + + /// The point was after the position returned from HitTest + wxRICHTEXT_HITTEST_AFTER = 0x04, + + /// The point was on the position returned from HitTest + wxRICHTEXT_HITTEST_ON = 0x08, + + /// The point was on space outside content + wxRICHTEXT_HITTEST_OUTSIDE = 0x10 +}; + +/*! + * Flags for GetRangeSize + */ + +#define wxRICHTEXT_FORMATTED 0x01 +#define wxRICHTEXT_UNFORMATTED 0x02 +#define wxRICHTEXT_CACHE_SIZE 0x04 +#define wxRICHTEXT_HEIGHT_ONLY 0x08 + +/*! + * Flags for SetStyle/SetListStyle + */ + +#define wxRICHTEXT_SETSTYLE_NONE 0x00 + +// Specifies that this operation should be undoable +#define wxRICHTEXT_SETSTYLE_WITH_UNDO 0x01 + +// Specifies that the style should not be applied if the +// combined style at this point is already the style in question. +#define wxRICHTEXT_SETSTYLE_OPTIMIZE 0x02 + +// Specifies that the style should only be applied to paragraphs, +// and not the content. This allows content styling to be +// preserved independently from that of e.g. a named paragraph style. +#define wxRICHTEXT_SETSTYLE_PARAGRAPHS_ONLY 0x04 + +// Specifies that the style should only be applied to characters, +// and not the paragraph. This allows content styling to be +// preserved independently from that of e.g. a named paragraph style. +#define wxRICHTEXT_SETSTYLE_CHARACTERS_ONLY 0x08 + +// For SetListStyle only: specifies starting from the given number, otherwise +// deduces number from existing attributes +#define wxRICHTEXT_SETSTYLE_RENUMBER 0x10 + +// For SetListStyle only: specifies the list level for all paragraphs, otherwise +// the current indentation will be used +#define wxRICHTEXT_SETSTYLE_SPECIFY_LEVEL 0x20 + +// Resets the existing style before applying the new style +#define wxRICHTEXT_SETSTYLE_RESET 0x40 + +// Removes the given style instead of applying it +#define wxRICHTEXT_SETSTYLE_REMOVE 0x80 + +/*! + * Flags for text insertion + */ + +#define wxRICHTEXT_INSERT_NONE 0x00 +#define wxRICHTEXT_INSERT_WITH_PREVIOUS_PARAGRAPH_STYLE 0x01 +#define wxRICHTEXT_INSERT_INTERACTIVE 0x02 + +// A special flag telling the buffer to keep the first paragraph style +// as-is, when deleting a paragraph marker. In future we might pass a +// flag to InsertFragment and DeleteRange to indicate the appropriate mode. +#define wxTEXT_ATTR_KEEP_FIRST_PARA_STYLE 0x10000000 + +/*! + * Default superscript/subscript font multiplication factor + */ + +#define wxSCRIPT_MUL_FACTOR 1.5 + + /** @class wxRichTextBuffer @@ -16,16 +140,18 @@ @see wxTextAttr, wxRichTextCtrl */ -class wxRichTextBuffer +class wxRichTextBuffer : public wxRichTextParagraphLayoutBox { public: - //@{ /** - Default constructors. + Default constructor. */ - wxRichTextBuffer(const wxRichTextBuffer& obj); wxRichTextBuffer(); - //@} + + /** + Copy ctor. + */ + wxRichTextBuffer(const wxRichTextBuffer& obj); /** Destructor. @@ -33,14 +159,15 @@ public: virtual ~wxRichTextBuffer(); /** - Adds an event handler to the buffer's list of handlers. A buffer associated with - a contol has the control as the only event handler, but the application is free - to add more if further notification is required. All handlers are notified - of an event originating from the buffer, such as the replacement of a style - sheet - during loading. The buffer never deletes any of the event handlers, unless - RemoveEventHandler() is - called with @true as the second argument. + Adds an event handler to the buffer's list of handlers. + + A buffer associated with a control has the control as the only event handler, + but the application is free to add more if further notification is required. + All handlers are notified of an event originating from the buffer, such as + the replacement of a style sheet during loading. + + The buffer never deletes any of the event handlers, unless RemoveEventHandler() + is called with @true as the second argument. */ bool AddEventHandler(wxEvtHandler* handler); @@ -69,6 +196,7 @@ public: Begins collapsing undo/redo commands. Note that this may not work properly if combining commands that delete or insert content, changing ranges for subsequent actions. + @a cmdName should be the name of the combined command that will appear next to Undo and Redo in the edit menu. */ @@ -100,48 +228,46 @@ public: bool BeginItalic(); /** - Begin using @a leftIndent for the left indent, and optionally @a leftSubIndent - for + Begin using @a leftIndent for the left indent, and optionally @a leftSubIndent for the sub-indent. Both are expressed in tenths of a millimetre. + The sub-indent is an offset from the left of the paragraph, and is used for all - but the - first line in a paragraph. A positive value will cause the first line to appear - to the left - of the subsequent lines, and a negative value will cause the first line to be - indented - relative to the subsequent lines. + but the first line in a paragraph. A positive value will cause the first line to appear + to the left of the subsequent lines, and a negative value will cause the first line to be + indented relative to the subsequent lines. */ bool BeginLeftIndent(int leftIndent, int leftSubIndent = 0); /** Begins line spacing using the specified value. @e spacing is a multiple, where - 10 means single-spacing, - 15 means 1.5 spacing, and 20 means double spacing. The following constants are - defined for convenience: + 10 means single-spacing, 15 means 1.5 spacing, and 20 means double spacing. + + The ::wxTextAttrLineSpacing enumeration values are defined for convenience. */ bool BeginLineSpacing(int lineSpacing); /** - Begins using a specified list style. Optionally, you can also pass a level and - a number. + Begins using a specified list style. + Optionally, you can also pass a level and a number. */ bool BeginListStyle(const wxString& listStyle, int level = 1, int number = 1); /** - Begins a numbered bullet. This call will be needed for each item in the list, - and the + Begins a numbered bullet. + + This call will be needed for each item in the list, and the application should take care of incrementing the numbering. + @a bulletNumber is a number, usually starting with 1. @a leftIndent and @a leftSubIndent are values in tenths of a millimetre. @a bulletStyle is a bitlist of the following values: - - wxRichTextBuffer uses indentation to render a bulleted item. The left indent is - the distance between - the margin and the bullet. The content of the paragraph, including the first - line, starts - at leftMargin + leftSubIndent. So the distance between the left edge of the - bullet and the + + wxRichTextBuffer uses indentation to render a bulleted item. + The left indent is the distance between the margin and the bullet. + The content of the paragraph, including the first line, starts + at leftMargin + leftSubIndent. + So the distance between the left edge of the bullet and the left of the actual paragraph is leftSubIndent. */ bool BeginNumberedBullet(int bulletNumber, int leftIndent, @@ -150,8 +276,7 @@ public: /** Begins paragraph spacing; pass the before-paragraph and after-paragraph spacing - in tenths of - a millimetre. + in tenths of a millimetre. */ bool BeginParagraphSpacing(int before, int after); @@ -168,6 +293,7 @@ public: /** Begins applying a standard bullet, using one of the standard bullet names (currently @c standard/circle or @c standard/square. + See BeginNumberedBullet() for an explanation of how indentation is used to render the bulleted paragraph. */ @@ -183,18 +309,18 @@ public: /** Begins suppressing undo/redo commands. The way undo is suppressed may be - implemented - differently by each command. If not dealt with by a command implementation, then - it will be implemented automatically by not storing the command in the undo - history - when the action is submitted to the command processor. + implemented differently by each command. + If not dealt with by a command implementation, then it will be implemented + automatically by not storing the command in the undo history when the + action is submitted to the command processor. */ virtual bool BeginSuppressUndo(); /** - Begins applying a symbol bullet, using a character from the current font. See - BeginNumberedBullet() for - an explanation of how indentation is used to render the bulleted paragraph. + Begins applying a symbol bullet, using a character from the current font. + + See BeginNumberedBullet() for an explanation of how indentation is used + to render the bulleted paragraph. */ bool BeginSymbolBullet(wxChar symbol, int leftIndent, int leftSubIndent, @@ -206,10 +332,10 @@ public: bool BeginTextColour(const wxColour& colour); /** - Begins applying wxTEXT_ATTR_URL to the content. Pass a URL and optionally, a - character style to apply, - since it is common to mark a URL with a familiar style such as blue text with - underlining. + Begins applying wxTEXT_ATTR_URL to the content. + + Pass a URL and optionally, a character style to apply, since it is common + to mark a URL with a familiar style such as blue text with underlining. */ bool BeginURL(const wxString& url, const wxString& characterStyle = wxEmptyString); @@ -238,9 +364,11 @@ public: /** Clears the list style from the given range, clearing list-related attributes and applying any named paragraph style associated with each paragraph. + @a flags is a bit list of the following: - wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable. - See also SetListStyle(), PromoteList(), NumberList(). + - wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable. + + @see SetListStyle(), PromoteList(), NumberList() */ bool ClearListStyle(const wxRichTextRange& range, int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO); @@ -392,27 +520,35 @@ public: */ bool EndUnderline(); - //@{ /** - Finds a handler by name. + Finds a handler by type. */ wxRichTextFileHandler* FindHandler(int imageType); + + /** + Finds a handler by extension and type. + */ wxRichTextFileHandler* FindHandler(const wxString& extension, int imageType); + + /** + Finds a handler by name. + */ wxRichTextFileHandler* FindHandler(const wxString& name); - //@} /** Finds a handler by filename or, if supplied, type. */ wxRichTextFileHandler* FindHandlerFilenameOrType(const wxString& filename, - int imageType); + int imageType); /** - Gets the basic (overall) style. This is the style of the whole - buffer before further styles are applied, unlike the default style, which - only affects the style currently being applied (for example, setting the default - style to bold will cause subsequently inserted text to be bold). + Gets the basic (overall) style. + + This is the style of the whole buffer before further styles are applied, + unlike the default style, which only affects the style currently being + applied (for example, setting the default style to bold will cause + subsequently inserted text to be bold). */ const wxTextAttr GetBasicStyle() const; @@ -422,24 +558,23 @@ public: virtual wxRichTextCommand* GetBatchedCommand() const; /** - Gets the command processor. A text buffer always creates its own command - processor when it is - initialized. + Gets the command processor. + A text buffer always creates its own command processor when it is initialized. */ wxCommandProcessor* GetCommandProcessor() const; /** Returns the current default style, affecting the style currently being applied - (for example, setting the default - style to bold will cause subsequently inserted text to be bold). + (for example, setting the default style to bold will cause subsequently + inserted text to be bold). */ const wxTextAttr GetDefaultStyle() const; /** - Gets a wildcard incorporating all visible handlers. If @a types is present, - it will be filled with the file type corresponding to each filter. This can be - used to determine the type to pass to @ref getextwildcard() LoadFile given a - selected filter. + Gets a wildcard incorporating all visible handlers. + If @a types is present, it will be filled with the file type corresponding + to each filter. This can be used to determine the type to pass to LoadFile() + given a selected filter. */ wxString GetExtWildcard(bool combine = false, bool save = false, wxArrayInt* types = NULL); @@ -457,11 +592,11 @@ public: /** Gets the attributes at the given position. + This function gets the combined style - that is, the style you see on the - screen as a result - of combining base style, paragraph style and character style attributes. To get - the character - or paragraph style alone, use GetUncombinedStyle(). + screen as a result of combining base style, paragraph style and character + style attributes. To get the character or paragraph style alone, + use GetUncombinedStyle(). */ bool GetStyle(long position, wxTextAttr& style); @@ -469,29 +604,24 @@ public: This function gets a style representing the common, combined attributes in the given range. Attributes which have different values within the specified range will not be - included the style - flags. + included the style flags. + The function is used to get the attributes to display in the formatting dialog: - the user - can edit the attributes common to the selection, and optionally specify the - values of further - attributes to be applied uniformly. + the user can edit the attributes common to the selection, and optionally specify the + values of further attributes to be applied uniformly. + To apply the edited attributes, you can use SetStyle() specifying the wxRICHTEXT_SETSTYLE_OPTIMIZE flag, which will only apply attributes that - are different - from the @e combined attributes within the range. So, the user edits the - effective, displayed attributes - for the range, but his choice won't be applied unnecessarily to content. As an - example, + are different from the @e combined attributes within the range. + So, the user edits the effective, displayed attributes for the range, + but his choice won't be applied unnecessarily to content. As an example, say the style for a paragraph specifies bold, but the paragraph text doesn't - specify a weight. The - combined style is bold, and this is what the user will see on-screen and in the - formatting - dialog. The user now specifies red text, in addition to bold. When applying with - SetStyle, the content font weight attributes won't be changed to bold because - this is already specified - by the paragraph. However the text colour attributes @e will be changed to - show red. + specify a weight. + The combined style is bold, and this is what the user will see on-screen and + in the formatting dialog. The user now specifies red text, in addition to bold. + When applying with SetStyle(), the content font weight attributes won't be + changed to bold because this is already specified by the paragraph. + However the text colour attributes @e will be changed to show red. */ bool GetStyleForRange(const wxRichTextRange& range, wxTextAttr& style); @@ -508,23 +638,22 @@ public: /** Gets the attributes at the given position. + This function gets the @e uncombined style - that is, the attributes associated - with the - paragraph or character content, and not necessarily the combined attributes you - see on the - screen. To get the combined attributes, use GetStyle(). + with the paragraph or character content, and not necessarily the combined + attributes you see on the screen. To get the combined attributes, use GetStyle(). If you specify (any) paragraph attribute in @e style's flags, this function - will fetch - the paragraph attributes. Otherwise, it will return the character attributes. + will fetch the paragraph attributes. + Otherwise, it will return the character attributes. */ bool GetUncombinedStyle(long position, wxTextAttr& style); /** - Finds the text position for the given position, putting the position in @a - textPosition if - one is found. @a pt is in logical units (a zero y position is - at the beginning of the buffer). - The function returns one of the following values: + Finds the text position for the given position, putting the position in + @a textPosition if one is found. + @a pt is in logical units (a zero y position is at the beginning of the buffer). + + @return One of the ::wxRichTextHitTestFlags values. */ int HitTest(wxDC& dc, const wxPoint& pt, long& textPosition); @@ -534,9 +663,8 @@ public: void Init(); /** - Initialises the standard handlers. Currently, only the plain text - loading/saving handler - is initialised by default. + Initialises the standard handlers. + Currently, only the plain text loading/saving handler is initialised by default. */ static void InitStandardHandlers(); @@ -568,15 +696,17 @@ public: */ bool IsModified() const; - //@{ /** - Loads content from a file. + Loads content from a stream. */ bool LoadFile(wxInputStream& stream, int type = wxRICHTEXT_TYPE_ANY); + + /** + Loads content from a file. + */ bool LoadFile(const wxString& filename, int type = wxRICHTEXT_TYPE_ANY); - //@} /** Marks the buffer as modified or unmodified. @@ -585,17 +715,20 @@ public: //@{ /** - Numbers the paragraphs in the given range. Pass flags to determine how the - attributes are set. + Numbers the paragraphs in the given range. + + Pass flags to determine how the attributes are set. Either the style definition or the name of the style definition (in the current sheet) can be passed. + @a flags is a bit list of the following: - wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable. - wxRICHTEXT_SETSTYLE_RENUMBER: specifies that numbering should start from @e - startFrom, otherwise existing attributes are used. - wxRICHTEXT_SETSTYLE_SPECIFY_LEVEL: specifies that @a listLevel should be used - as the level for all paragraphs, otherwise the current indentation will be used. - See also SetListStyle(), PromoteList(), ClearListStyle(). + - wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable. + - wxRICHTEXT_SETSTYLE_RENUMBER: specifies that numbering should start from + @a startFrom, otherwise existing attributes are used. + - wxRICHTEXT_SETSTYLE_SPECIFY_LEVEL: specifies that @a listLevel should be used + as the level for all paragraphs, otherwise the current indentation will be used. + + @see SetListStyle(), PromoteList(), ClearListStyle() */ bool NumberList(const wxRichTextRange& range, const wxRichTextListStyleDefinition* style, @@ -616,18 +749,21 @@ public: //@{ /** - Promotes or demotes the paragraphs in the given range. A positive @a promoteBy - produces a smaller indent, and a negative number + Promotes or demotes the paragraphs in the given range. + + A positive @a promoteBy produces a smaller indent, and a negative number produces a larger indent. Pass flags to determine how the attributes are set. Either the style definition or the name of the style definition (in the current sheet) can be passed. + @a flags is a bit list of the following: - wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable. - wxRICHTEXT_SETSTYLE_RENUMBER: specifies that numbering should start from @e - startFrom, otherwise existing attributes are used. - wxRICHTEXT_SETSTYLE_SPECIFY_LEVEL: specifies that @a listLevel should be used - as the level for all paragraphs, otherwise the current indentation will be used. - See also SetListStyle(), See also SetListStyle(), ClearListStyle(). + - wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable. + - wxRICHTEXT_SETSTYLE_RENUMBER: specifies that numbering should start from + @a startFrom, otherwise existing attributes are used. + - wxRICHTEXT_SETSTYLE_SPECIFY_LEVEL: specifies that @a listLevel should be used + as the level for all paragraphs, otherwise the current indentation will be used. + + @see SetListStyle(), SetListStyle(), ClearListStyle() */ bool PromoteList(int promoteBy, const wxRichTextRange& range, const wxRichTextListStyleDefinition* style, @@ -656,15 +792,17 @@ public: */ virtual void ResetAndClearCommands(); - //@{ /** - Saves content to a file. + Saves content to a stream. */ bool SaveFile(wxOutputStream& stream, int type = wxRICHTEXT_TYPE_ANY); + + /** + Saves content to a file. + */ bool SaveFile(const wxString& filename, int type = wxRICHTEXT_TYPE_ANY); - //@} /** Sets the basic (overall) style. This is the style of the whole @@ -675,9 +813,10 @@ public: void SetBasicStyle(const wxTextAttr& style); /** - Sets the default style, affecting the style currently being applied (for - example, setting the default - style to bold will cause subsequently inserted text to be bold). + Sets the default style, affecting the style currently being applied + (for example, setting the default style to bold will cause subsequently + inserted text to be bold). + This is not cumulative - setting the default style will replace the previous default style. */ @@ -689,13 +828,15 @@ public: the attributes are set. Either the style definition or the name of the style definition (in the current sheet) can be passed. + @a flags is a bit list of the following: - wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable. - wxRICHTEXT_SETSTYLE_RENUMBER: specifies that numbering should start from @e - startFrom, otherwise existing attributes are used. - wxRICHTEXT_SETSTYLE_SPECIFY_LEVEL: specifies that @a listLevel should be used - as the level for all paragraphs, otherwise the current indentation will be used. - See also NumberList(), PromoteList(), ClearListStyle(). + - wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable. + - wxRICHTEXT_SETSTYLE_RENUMBER: specifies that numbering should start from + @a startFrom, otherwise existing attributes are used. + - wxRICHTEXT_SETSTYLE_SPECIFY_LEVEL: specifies that @a listLevel should be used + as the level for all paragraphs, otherwise the current indentation will be used. + + @see NumberList(), PromoteList(), ClearListStyle(). */ bool SetListStyle(const wxRichTextRange& range, const wxRichTextListStyleDefinition* style, @@ -712,48 +853,50 @@ public: /** Sets @a renderer as the object to be used to render certain aspects of the content, such as bullets. + You can override default rendering by deriving a new class from - wxRichTextRenderer or wxRichTextStdRenderer, - overriding one or more virtual functions, and setting an instance of the class - using this function. + wxRichTextRenderer or wxRichTextStdRenderer, overriding one or more + virtual functions, and setting an instance of the class using this function. */ static void SetRenderer(wxRichTextRenderer* renderer); /** Sets the attributes for the given range. Pass flags to determine how the attributes are set. + The end point of range is specified as the last character position of the span - of text. - So, for example, to set the style for a character at position 5, use the range - (5,5). + of text. So, for example, to set the style for a character at position 5, + use the range (5,5). This differs from the wxRichTextCtrl API, where you would specify (5,6). + @a flags may contain a bit list of the following values: - wxRICHTEXT_SETSTYLE_NONE: no style flag. - wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this operation should be - undoable. - wxRICHTEXT_SETSTYLE_OPTIMIZE: specifies that the style should not be applied - if the - combined style at this point is already the style in question. - wxRICHTEXT_SETSTYLE_PARAGRAPHS_ONLY: specifies that the style should only be - applied to paragraphs, - and not the content. This allows content styling to be preserved independently - from that of e.g. a named paragraph style. - wxRICHTEXT_SETSTYLE_CHARACTERS_ONLY: specifies that the style should only be - applied to characters, - and not the paragraph. This allows content styling to be preserved - independently from that of e.g. a named paragraph style. - wxRICHTEXT_SETSTYLE_RESET: resets (clears) the existing style before applying - the new style. - wxRICHTEXT_SETSTYLE_REMOVE: removes the specified style. Only the style flags - are used in this operation. + - wxRICHTEXT_SETSTYLE_NONE: no style flag. + - wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this operation should be + undoable. + - wxRICHTEXT_SETSTYLE_OPTIMIZE: specifies that the style should not be applied + if the combined style at this point is already the style in question. + - wxRICHTEXT_SETSTYLE_PARAGRAPHS_ONLY: specifies that the style should only be + applied to paragraphs, and not the content. + This allows content styling to be preserved independently from that + of e.g. a named paragraph style. + - wxRICHTEXT_SETSTYLE_CHARACTERS_ONLY: specifies that the style should only be + applied to characters, and not the paragraph. + This allows content styling to be preserved independently from that + of e.g. a named paragraph style. + - wxRICHTEXT_SETSTYLE_RESET: resets (clears) the existing style before applying + the new style. + - wxRICHTEXT_SETSTYLE_REMOVE: removes the specified style. + Only the style flags are used in this operation. */ bool SetStyle(const wxRichTextRange& range, const wxTextAttr& style, int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO); /** - Sets the current style sheet, if any. This will allow the application to use - named character and paragraph styles found in the style sheet. + Sets the current style sheet, if any. + + This will allow the application to use named character and paragraph + styles found in the style sheet. */ void SetStyleSheet(wxRichTextStyleSheet* styleSheet); @@ -790,9 +933,10 @@ public: int type = 0); /** - Override this function and return @true if this handler can we handle @e - filename. By default, - this function checks the extension. + Override this function and return @true if this handler can we handle + @a filename. + + By default, this function checks the extension. */ virtual bool CanHandle(const wxString& filename) const; @@ -807,12 +951,12 @@ public: virtual bool CanSave() const; /** - Override to load content from @a stream into @e buffer. + Override to load content from @a stream into @a buffer. */ bool DoLoadFile(wxRichTextBuffer* buffer, wxInputStream& stream); /** - Override to save content to @a stream from @e buffer. + Override to save content to @a stream from @a buffer. */ bool DoSaveFile(wxRichTextBuffer* buffer, wxOutputStream& stream); @@ -827,9 +971,10 @@ public: wxString GetExtension() const; /** - Returns flags that change the behaviour of loading or saving. See the - documentation for each - handler class to see what flags are relevant for each handler. + Returns flags that change the behaviour of loading or saving. + + See the documentation for each handler class to see what flags are + relevant for each handler. */ int GetFlags() const; @@ -850,26 +995,25 @@ public: //@{ /** - Loads content from a stream or file. Not all handlers will implement file - loading. + Loads content from a stream or file. + Not all handlers will implement file loading. */ bool LoadFile(wxRichTextBuffer* buffer, wxInputStream& stream); - bool LoadFile(wxRichTextBuffer* buffer, - const wxString& filename); + bool LoadFile(wxRichTextBuffer* buffer, const wxString& filename); //@} //@{ /** - Saves content to a stream or file. Not all handlers will implement file saving. + Saves content to a stream or file. + Not all handlers will implement file saving. */ bool SaveFile(wxRichTextBuffer* buffer, wxOutputStream& stream); - bool SaveFile(wxRichTextBuffer* buffer, - const wxString& filename); + bool SaveFile(wxRichTextBuffer* buffer, const wxString& filename); //@} /** - Sets the encoding to use when saving a file. If empty, a suitable encoding is - chosen. + Sets the encoding to use when saving a file. + If empty, a suitable encoding is chosen. */ void SetEncoding(const wxString& encoding); @@ -879,14 +1023,14 @@ public: void SetExtension(const wxString& ext); /** - Sets flags that change the behaviour of loading or saving. See the - documentation for each - handler class to see what flags are relevant for each handler. + Sets flags that change the behaviour of loading or saving. + See the documentation for each handler class to see what flags are relevant + for each handler. + You call this function directly if you are using a file handler explicitly - (without - going through the text control or buffer LoadFile/SaveFile API). Or, you can - call the control or buffer's SetHandlerFlags function to set the flags that will - be used for subsequent load and save operations. + (without going through the text control or buffer LoadFile/SaveFile API). + Or, you can call the control or buffer's SetHandlerFlags function to set + the flags that will be used for subsequent load and save operations. */ void SetFlags(int flags); @@ -902,8 +1046,7 @@ public: /** Sets whether the handler should be visible to the user (via the application's - load and save - dialogs). + load and save dialogs). */ virtual void SetVisible(bool visible); }; @@ -936,16 +1079,15 @@ public: ~wxRichTextRange(); /** - Returns @true if the given position is within this range. Does not - match if the range is empty. + Returns @true if the given position is within this range. + Does not match if the range is empty. */ bool Contains(long pos) const; /** Converts the internal range, which uses the first and last character positions - of the range, - to the API-standard range, whose end is one past the last character in the - range. + of the range, to the API-standard range, whose end is one past the last + character in the range. In other words, one is added to the end position. */ wxRichTextRange FromInternal() const; @@ -1002,9 +1144,8 @@ public: /** Converts the API-standard range, whose end is one past the last character in - the range, - to the internal form, which uses the first and last character positions of the - range. + the range, to the internal form, which uses the first and last character + positions of the range. In other words, one is subtracted from the end position. */ wxRichTextRange ToInternal() const; diff --git a/interface/wx/richtext/richtextctrl.h b/interface/wx/richtext/richtextctrl.h index 690a55d2e1..45d35b9e47 100644 --- a/interface/wx/richtext/richtextctrl.h +++ b/interface/wx/richtext/richtextctrl.h @@ -1,6 +1,6 @@ ///////////////////////////////////////////////////////////////////////////// // Name: richtext/richtextctrl.h -// Purpose: interface of wxRichTextEvent +// Purpose: interface of wxRichTextCtrl and wxRichTextEvent // Author: wxWidgets team // RCS-ID: $Id$ // Licence: wxWindows license @@ -11,8 +11,49 @@ This is the event class for wxRichTextCtrl notifications. + @beginEventTable{wxRichTextEvent} + @event{EVT_RICHTEXT_CHARACTER(id, func)} + Process a wxEVT_COMMAND_RICHTEXT_CHARACTER event, generated when the user + presses a character key. Valid event functions: GetFlags, GetPosition, GetCharacter. + @event{EVT_RICHTEXT_DELETE(id, func)} + Process a wxEVT_COMMAND_RICHTEXT_DELETE event, generated when the user + presses the backspace or delete key. Valid event functions: GetFlags, GetPosition. + @event{EVT_RICHTEXT_RETURN(id, func)} + Process a wxEVT_COMMAND_RICHTEXT_RETURN event, generated when the user + presses the return key. Valid event functions: GetFlags, GetPosition. + @event{EVT_RICHTEXT_STYLE_CHANGED(id, func)} + Process a wxEVT_COMMAND_RICHTEXT_STYLE_CHANGED event, generated when + styling has been applied to the control. Valid event functions: GetPosition, GetRange. + @event{EVT_RICHTEXT_STYLESHEET_CHANGED(id, func)} + Process a wxEVT_COMMAND_RICHTEXT_STYLESHEET_CHANGING event, generated + when the control's stylesheet has changed, for example the user added, + edited or deleted a style. Valid event functions: GetRange, GetPosition. + @event{EVT_RICHTEXT_STYLESHEET_REPLACING(id, func)} + Process a wxEVT_COMMAND_RICHTEXT_STYLESHEET_REPLACING event, generated + when the control's stylesheet is about to be replaced, for example when + a file is loaded into the control. + Valid event functions: Veto, GetOldStyleSheet, GetNewStyleSheet. + @event{EVT_RICHTEXT_STYLESHEET_REPLACED(id, func)} + Process a wxEVT_COMMAND_RICHTEXT_STYLESHEET_REPLACED event, generated + when the control's stylesheet has been replaced, for example when a file + is loaded into the control. + Valid event functions: GetOldStyleSheet, GetNewStyleSheet. + @event{EVT_RICHTEXT_CONTENT_INSERTED(id, func)} + Process a wxEVT_COMMAND_RICHTEXT_CONTENT_INSERTED event, generated when + content has been inserted into the control. + Valid event functions: GetPosition, GetRange. + @event{EVT_RICHTEXT_CONTENT_DELETED(id, func)} + Process a wxEVT_COMMAND_RICHTEXT_CONTENT_DELETED event, generated when + content has been deleted from the control. + Valid event functions: GetPosition, GetRange. + @event{EVT_RICHTEXT_BUFFER_RESET(id, func)} + Process a wxEVT_COMMAND_RICHTEXT_BUFFER_RESET event, generated when the + buffer has been reset by deleting all content. + You can use this to set a default style for the first new paragraph. + @endEventTable + @library{wxrichtext} - @category{richtext} + @category{events,richtext} */ class wxRichTextEvent : public wxNotifyEvent { @@ -25,6 +66,8 @@ public: /** Constructor. + @param commandType + The type of the event. @param id Window identifier. The value @c wxID_ANY indicates a default value. */ @@ -41,22 +84,24 @@ public: wxChar GetCharacter() const; /** - Returns flags indicating modifier keys pressed. Possible values are - wxRICHTEXT_CTRL_DOWN, - wxRICHTEXT_SHIFT_DOWN, and wxRICHTEXT_ALT_DOWN. + Returns flags indicating modifier keys pressed. + + Possible values are wxRICHTEXT_CTRL_DOWN, wxRICHTEXT_SHIFT_DOWN, and wxRICHTEXT_ALT_DOWN. */ int GetFlags() const; /** - Returns the new style sheet. Can be used in a - wxEVT_COMMAND_RICHTEXT_STYLESHEET_CHANGING or + Returns the new style sheet. + + Can be used in a wxEVT_COMMAND_RICHTEXT_STYLESHEET_CHANGING or wxEVT_COMMAND_RICHTEXT_STYLESHEET_CHANGED event handler. */ wxRichTextStyleSheet* GetNewStyleSheet() const; /** - Returns the old style sheet. Can be used in a - wxEVT_COMMAND_RICHTEXT_STYLESHEET_CHANGING or + Returns the old style sheet. + + Can be used in a wxEVT_COMMAND_RICHTEXT_STYLESHEET_CHANGING or wxEVT_COMMAND_RICHTEXT_STYLESHEET_CHANGED event handler. */ wxRichTextStyleSheet* GetOldStyleSheet() const; @@ -77,9 +122,9 @@ public: void SetCharacter(wxChar ch); /** - Sets flags indicating modifier keys pressed. Possible values are - wxRICHTEXT_CTRL_DOWN, - wxRICHTEXT_SHIFT_DOWN, and wxRICHTEXT_ALT_DOWN. + Sets flags indicating modifier keys pressed. + + Possible values are wxRICHTEXT_CTRL_DOWN, wxRICHTEXT_SHIFT_DOWN, and wxRICHTEXT_ALT_DOWN. */ void SetFlags(int flags); @@ -113,9 +158,9 @@ public: capable of showing multiple styles and images. wxRichTextCtrl sends notification events: see wxRichTextEvent. + It also sends the standard wxTextCtrl events wxEVT_COMMAND_TEXT_ENTER and - wxEVT_COMMAND_TEXT_UPDATED, - and wxTextUrlEvent when URL content is clicked. + wxEVT_COMMAND_TEXT_UPDATED, and wxTextUrlEvent when URL content is clicked. For more information, see the @ref overview_richtextctrl. @@ -203,10 +248,10 @@ public: /** Applies the style sheet to the buffer, matching paragraph styles in the sheet - against named styles - in the buffer. This might be useful if the styles have changed. If @a sheet is - @NULL, the - sheet set with SetStyleSheet is used. + against named styles in the buffer. + + This might be useful if the styles have changed. + If @a sheet is @NULL, the sheet set with SetStyleSheet() is used. Currently this applies paragraph styles only. */ bool ApplyStyleSheet(wxRichTextStyleSheet* sheet = NULL); @@ -222,7 +267,7 @@ public: virtual bool BatchingUndo() const; /** - Begins using alignment + Begins using alignment. For alignment values, see wxTextAttr. */ bool BeginAlignment(wxTextAttrAlignment alignment); @@ -259,8 +304,8 @@ public: /** Begins applying a left indent and subindent in tenths of a millimetre. - The subindent is an offset from the left edge of the paragraph, and is - used for all but the first line in a paragraph. A positive value will + The subindent is an offset from the left edge of the paragraph, and is + used for all but the first line in a paragraph. A positive value will cause the first line to appear to the left of the subsequent lines, and a negative value will cause the first line to be indented to the right of the subsequent lines. @@ -279,33 +324,34 @@ public: /** Begins appling line spacing. @e spacing is a multiple, where 10 means - single-spacing, - 15 means 1.5 spacing, and 20 means double spacing. The following constants are - defined for convenience: + single-spacing, 15 means 1.5 spacing, and 20 means double spacing. + + The ::wxTextAttrLineSpacing constants are defined for convenience. */ bool BeginLineSpacing(int lineSpacing); /** - Begins using a specified list style. Optionally, you can also pass a level and - a number. + Begins using a specified list style. + Optionally, you can also pass a level and a number. */ bool BeginListStyle(const wxString& listStyle, int level = 1, int number = 1); /** - Begins a numbered bullet. This call will be needed for each item in the list, - and the + Begins a numbered bullet. + + This call will be needed for each item in the list, and the application should take care of incrementing the numbering. + @a bulletNumber is a number, usually starting with 1. @a leftIndent and @a leftSubIndent are values in tenths of a millimetre. - @a bulletStyle is a bitlist of the following values: - - wxRichTextBuffer uses indentation to render a bulleted item. The left indent is - the distance between - the margin and the bullet. The content of the paragraph, including the first - line, starts - at leftMargin + leftSubIndent. So the distance between the left edge of the - bullet and the + @a bulletStyle is a bitlist of the ::wxTextAttrBulletStyle values. + + wxRichTextBuffer uses indentation to render a bulleted item. + The left indent is the distance between the margin and the bullet. + The content of the paragraph, including the first line, starts + at leftMargin + leftSubIndent. + So the distance between the left edge of the bullet and the left of the actual paragraph is leftSubIndent. */ bool BeginNumberedBullet(int bulletNumber, int leftIndent, @@ -314,8 +360,7 @@ public: /** Begins paragraph spacing; pass the before-paragraph and after-paragraph spacing - in tenths of - a millimetre. + in tenths of a millimetre. */ bool BeginParagraphSpacing(int before, int after); @@ -340,9 +385,9 @@ public: virtual bool BeginSuppressUndo(); /** - Begins applying a symbol bullet, using a character from the current font. See - BeginNumberedBullet() for - an explanation of how indentation is used to render the bulleted paragraph. + Begins applying a symbol bullet, using a character from the current font. + See BeginNumberedBullet() for an explanation of how indentation is used + to render the bulleted paragraph. */ bool BeginSymbolBullet(wxChar symbol, int leftIndent, int leftSubIndent, @@ -354,10 +399,10 @@ public: bool BeginTextColour(const wxColour& colour); /** - Begins applying wxTEXT_ATTR_URL to the content. Pass a URL and optionally, a - character style to apply, - since it is common to mark a URL with a familiar style such as blue text with - underlining. + Begins applying wxTEXT_ATTR_URL to the content. + + Pass a URL and optionally, a character style to apply, since it is common + to mark a URL with a familiar style such as blue text with underlining. */ bool BeginURL(const wxString& url, const wxString& characterStyle = wxEmptyString); @@ -406,9 +451,11 @@ public: /** Clears the list style from the given range, clearing list-related attributes and applying any named paragraph style associated with each paragraph. + @a flags is a bit list of the following: - wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable. - See also SetListStyle(), PromoteList(), NumberList(). + - wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable. + + @see SetListStyle(), PromoteList(), NumberList(). */ bool ClearListStyle(const wxRichTextRange& range, int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO); @@ -578,15 +625,14 @@ public: /** Helper function for extending the selection, returning @true if the selection - was - changed. Selections are in caret positions. + was changed. Selections are in caret positions. */ bool ExtendSelection(long oldPosition, long newPosition, int flags); /** - Helper function for finding the caret position for the next word. Direction - is 1 (forward) or -1 (backwards). + Helper function for finding the caret position for the next word. + Direction is 1 (forward) or -1 (backwards). */ virtual long FindNextWordPosition(int direction = 1) const; @@ -597,10 +643,12 @@ public: void Freeze(); /** - Gets the basic (overall) style. This is the style of the whole - buffer before further styles are applied, unlike the default style, which - only affects the style currently being applied (for example, setting the default - style to bold will cause subsequently inserted text to be bold). + Gets the basic (overall) style. + + This is the style of the whole buffer before further styles are applied, + unlike the default style, which only affects the style currently being + applied (for example, setting the default style to bold will cause + subsequently inserted text to be bold). */ const wxTextAttr GetBasicStyle() const; @@ -618,7 +666,7 @@ public: long GetCaretPosition() const; /** - Returns the caret height and position for the given character position + Returns the caret height and position for the given character position. */ bool GetCaretPositionForIndex(long position, wxRect& rect); @@ -629,8 +677,7 @@ public: /** Returns the current default style, which can be used to change how subsequently - inserted - text is displayed. + inserted text is displayed. */ const wxTextAttr GetDefaultStyle() const; @@ -651,9 +698,9 @@ public: long GetFirstVisiblePosition() const; /** - Returns flags that change the behaviour of loading or saving. See the - documentation for each - handler class to see what flags are relevant for each handler. + Returns flags that change the behaviour of loading or saving. + See the documentation for each handler class to see what flags are + relevant for each handler. */ int GetHandlerFlags() const; @@ -694,8 +741,8 @@ public: /** Gets the text for the given range. - The end point of range is specified as the last character position of the span - of text, plus one. + The end point of range is specified as the last character position of + the span of text, plus one. */ virtual wxString GetRange(long from, long to) const; @@ -720,38 +767,37 @@ public: /** Gets the attributes at the given position. This function gets the combined style - that is, the style you see on the - screen as a result - of combining base style, paragraph style and character style attributes. To get - the character - or paragraph style alone, use GetUncombinedStyle(). + screen as a result of combining base style, paragraph style and character + style attributes. + + To get the character or paragraph style alone, use GetUncombinedStyle(). */ virtual bool GetStyle(long position, wxTextAttr& style); /** - Gets the attributes common to the specified range. Attributes that differ in - value within the range will - not be included in @e style's flags. + Gets the attributes common to the specified range. + Attributes that differ in value within the range will not be included + in @a style flags. */ bool GetStyleForRange(const wxRichTextRange& range, wxTextAttr& style); /** - Returns the style sheet associated with the control, if any. A style sheet - allows named - character and paragraph styles to be applied. + Returns the style sheet associated with the control, if any. + A style sheet allows named character and paragraph styles to be applied. */ wxRichTextStyleSheet* GetStyleSheet() const; /** Gets the attributes at the given position. This function gets the @e uncombined style - that is, the attributes associated - with the - paragraph or character content, and not necessarily the combined attributes you - see on the - screen. To get the combined attributes, use GetStyle(). + with the paragraph or character content, and not necessarily the combined + attributes you see on the screen. + To get the combined attributes, use GetStyle(). + If you specify (any) paragraph attribute in @e style's flags, this function - will fetch - the paragraph attributes. Otherwise, it will return the character attributes. + will fetch the paragraph attributes. + Otherwise, it will return the character attributes. */ virtual bool GetUncombinedStyle(long position, wxTextAttr& style); @@ -761,29 +807,28 @@ public: virtual wxString GetValue() const; /** - Internal helper function returning the line for the visible caret position. If - the caret is - shown at the very end of the line, it means the next character is actually - on the following line. So this function gets the line we're expecting to find - if this is the case. + Internal helper function returning the line for the visible caret position. + If the caret is shown at the very end of the line, it means the next character + is actually on the following line. + So this function gets the line we're expecting to find if this is the case. */ wxRichTextLine* GetVisibleLineForCaretPosition(long caretPosition) const; /** - Test if this whole range has character attributes of the specified kind. If any - of the attributes are different within the range, the test fails. You - can use this to implement, for example, bold button updating. @a style must have - flags indicating which attributes are of interest. + Test if this whole range has character attributes of the specified kind. + If any of the attributes are different within the range, the test fails. + + You can use this to implement, for example, bold button updating. + @a style must have flags indicating which attributes are of interest. */ bool HasCharacterAttributes(const wxRichTextRange& range, const wxTextAttr& style) const; /** - Test if this whole range has paragraph attributes of the specified kind. If any - of the attributes are different within the range, the test fails. You - can use this to implement, for example, centering button updating. @a style - must have - flags indicating which attributes are of interest. + Test if this whole range has paragraph attributes of the specified kind. + If any of the attributes are different within the range, the test fails. + You can use this to implement, for example, centering button updating. + @a style must have flags indicating which attributes are of interest. */ bool HasParagraphAttributes(const wxRichTextRange& range, const wxTextAttr& style) const; @@ -817,13 +862,13 @@ public: /** Returns @true if the user has recently set the default style without moving - the caret, - and therefore the UI needs to reflect the default style and not the style at - the caret. + the caret, and therefore the UI needs to reflect the default style and not + the style at the caret. + Below is an example of code that uses this function to determine whether the UI should show that the current style is bold. - - See also SetAndShowDefaultStyle(). + + @see SetAndShowDefaultStyle(). */ bool IsDefaultStyleShowing() const; @@ -853,8 +898,7 @@ public: bool IsPositionVisible(long pos) const; /** - Returns @true if all of the selection is aligned according to the specified - flag. + Returns @true if all of the selection is aligned according to the specified flag. */ virtual bool IsSelectionAligned(wxTextAttrAlignment alignment); @@ -874,8 +918,8 @@ public: virtual bool IsSelectionUnderlined(); /** - Returns @true if the control is single-line. Currently wxRichTextCtrl does not - support single-line editing. + Returns @true if the control is single-line. + Currently wxRichTextCtrl does not support single-line editing. */ bool IsSingleLine() const; @@ -886,24 +930,26 @@ public: /** Lays out the buffer, which must be done before certain operations, such as - setting the caret position. This function should not normally be required by the - application. + setting the caret position. + This function should not normally be required by the application. */ virtual bool LayoutContent(bool onlyVisibleRect = false); /** - Inserts a line break at the current insertion point. A line break forces - wrapping within a paragraph, and - can be introduced by using this function, by appending the wxChar value @b - wxRichTextLineBreakChar to text content, - or by typing Shift-Return. + Inserts a line break at the current insertion point. + + A line break forces wrapping within a paragraph, and can be introduced by + using this function, by appending the wxChar value @b wxRichTextLineBreakChar + to text content, or by typing Shift-Return. */ virtual bool LineBreak(); /** - Loads content into the control's buffer using the given type. If the specified - type - is wxRICHTEXT_TYPE_ANY, the type is deduced from the filename extension. + Loads content into the control's buffer using the given type. + + If the specified type is wxRICHTEXT_TYPE_ANY, the type is deduced from + the filename extension. + This function looks for a suitable wxRichTextFileHandler object. */ bool LoadFile(const wxString& file, @@ -984,23 +1030,26 @@ public: virtual bool MoveUp(int noLines = 1, int flags = 0); /** - Inserts a new paragraph at the current insertion point. See also LineBreak(). + Inserts a new paragraph at the current insertion point. @see LineBreak(). */ virtual bool Newline(); //@{ /** - Numbers the paragraphs in the given range. Pass flags to determine how the - attributes are set. + Numbers the paragraphs in the given range. + Pass flags to determine how the attributes are set. + Either the style definition or the name of the style definition (in the current sheet) can be passed. + @a flags is a bit list of the following: - wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable. - wxRICHTEXT_SETSTYLE_RENUMBER: specifies that numbering should start from @e - startFrom, otherwise existing attributes are used. - wxRICHTEXT_SETSTYLE_SPECIFY_LEVEL: specifies that @a listLevel should be used - as the level for all paragraphs, otherwise the current indentation will be used. - See also SetListStyle(), PromoteList(), ClearListStyle(). + - wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable. + - wxRICHTEXT_SETSTYLE_RENUMBER: specifies that numbering should start from + @a startFrom, otherwise existing attributes are used. + - wxRICHTEXT_SETSTYLE_SPECIFY_LEVEL: specifies that @a listLevel should be used + as the level for all paragraphs, otherwise the current indentation will be used. + + @see SetListStyle(), PromoteList(), ClearListStyle(). */ bool NumberList(const wxRichTextRange& range, const wxRichTextListStyleDefinition* style, @@ -1128,18 +1177,20 @@ public: //@{ /** - Promotes or demotes the paragraphs in the given range. A positive @a promoteBy - produces a smaller indent, and a negative number + Promotes or demotes the paragraphs in the given range. + A positive @a promoteBy produces a smaller indent, and a negative number produces a larger indent. Pass flags to determine how the attributes are set. Either the style definition or the name of the style definition (in the current sheet) can be passed. + @a flags is a bit list of the following: - wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable. - wxRICHTEXT_SETSTYLE_RENUMBER: specifies that numbering should start from @e - startFrom, otherwise existing attributes are used. - wxRICHTEXT_SETSTYLE_SPECIFY_LEVEL: specifies that @a listLevel should be used + - wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable. + - wxRICHTEXT_SETSTYLE_RENUMBER: specifies that numbering should start from + @a startFrom, otherwise existing attributes are used. + - wxRICHTEXT_SETSTYLE_SPECIFY_LEVEL: specifies that @a listLevel should be used as the level for all paragraphs, otherwise the current indentation will be used. - See also SetListStyle(), See also SetListStyle(), ClearListStyle(). + + @see SetListStyle(), @see SetListStyle(), ClearListStyle(). */ bool PromoteList(int promoteBy, const wxRichTextRange& range, const wxRichTextListStyleDefinition* style, @@ -1162,14 +1213,17 @@ public: virtual void Remove(long from, long to); /** - Replaces the content in the specified range with the string specified by @e - value. + Replaces the content in the specified range with the string specified by + @a value. */ virtual void Replace(long from, long to, const wxString& value); /** - Saves the buffer content using the given type. If the specified type - is wxRICHTEXT_TYPE_ANY, the type is deduced from the filename extension. + Saves the buffer content using the given type. + + If the specified type is wxRICHTEXT_TYPE_ANY, the type is deduced from + the filename extension. + This function looks for a suitable wxRichTextFileHandler object. */ bool SaveFile(const wxString& file = wxEmptyString, @@ -1192,17 +1246,19 @@ public: /** Sets @a attr as the default style and tells the control that the UI should - reflect - this attribute until the user moves the caret. - See also IsDefaultStyleShowing(). + reflect this attribute until the user moves the caret. + + @see IsDefaultStyleShowing(). */ void SetAndShowDefaultStyle(const wxTextAttr& attr); /** - Sets the basic (overall) style. This is the style of the whole - buffer before further styles are applied, unlike the default style, which - only affects the style currently being applied (for example, setting the default - style to bold will cause subsequently inserted text to be bold). + Sets the basic (overall) style. + + This is the style of the whole buffer before further styles are applied, + unlike the default style, which only affects the style currently being + applied (for example, setting the default style to bold will cause + subsequently inserted text to be bold). */ virtual void SetBasicStyle(const wxTextAttr& style); @@ -1215,8 +1271,7 @@ public: /** Sets the current default style, which can be used to change how subsequently - inserted - text is displayed. + inserted text is displayed. */ virtual bool SetDefaultStyle(const wxTextAttr& style); @@ -1242,15 +1297,16 @@ public: void SetFilename(const wxString& filename); /** - Sets the font, and also the basic and default attributes (see - wxRichTextCtrl::SetDefaultStyle). + Sets the font, and also the basic and default attributes + (see wxRichTextCtrl::SetDefaultStyle). */ virtual bool SetFont(const wxFont& font); /** - Sets flags that change the behaviour of loading or saving. See the - documentation for each - handler class to see what flags are relevant for each handler. + Sets flags that change the behaviour of loading or saving. + + See the documentation for each handler class to see what flags are + relevant for each handler. */ void SetHandlerFlags(int flags); @@ -1268,15 +1324,17 @@ public: /** Sets the list attributes for the given range, passing flags to determine how the attributes are set. + Either the style definition or the name of the style definition (in the current sheet) can be passed. @a flags is a bit list of the following: - wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable. - wxRICHTEXT_SETSTYLE_RENUMBER: specifies that numbering should start from @e - startFrom, otherwise existing attributes are used. - wxRICHTEXT_SETSTYLE_SPECIFY_LEVEL: specifies that @a listLevel should be used - as the level for all paragraphs, otherwise the current indentation will be used. - See also NumberList(), PromoteList(), ClearListStyle(). + - wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable. + - wxRICHTEXT_SETSTYLE_RENUMBER: specifies that numbering should start from + @a startFrom, otherwise existing attributes are used. + - wxRICHTEXT_SETSTYLE_SPECIFY_LEVEL: specifies that @a listLevel should be used + as the level for all paragraphs, otherwise the current indentation will be used. + + @see NumberList(), PromoteList(), ClearListStyle(). */ bool SetListStyle(const wxRichTextRange& range, const wxRichTextListStyleDefinition* style, @@ -1294,6 +1352,7 @@ public: Sets the selection to the given range. The end point of range is specified as the last character position of the span of text, plus one. + So, for example, to set the selection for a character at position 5, use the range (5,6). */ @@ -1303,6 +1362,7 @@ public: Sets the selection to the given range. The end point of range is specified as the last character position of the span of text, plus one. + So, for example, to set the selection for a character at position 5, use the range (5,6). */ @@ -1313,6 +1373,7 @@ public: Sets the attributes for the given range. The end point of range is specified as the last character position of the span of text, plus one. + So, for example, to set the style for a character at position 5, use the range (5,6). */ @@ -1325,29 +1386,29 @@ public: /** Sets the attributes for the given range, passing flags to determine how the attributes are set. + The end point of range is specified as the last character position of the span - of text, plus one. - So, for example, to set the style for a character at position 5, use the range - (5,6). + of text, plus one. So, for example, to set the style for a character at + position 5, use the range (5,6). + @a flags may contain a bit list of the following values: - wxRICHTEXT_SETSTYLE_NONE: no style flag. - wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this operation should be - undoable. - wxRICHTEXT_SETSTYLE_OPTIMIZE: specifies that the style should not be applied - if the - combined style at this point is already the style in question. - wxRICHTEXT_SETSTYLE_PARAGRAPHS_ONLY: specifies that the style should only be - applied to paragraphs, - and not the content. This allows content styling to be preserved independently - from that of e.g. a named paragraph style. - wxRICHTEXT_SETSTYLE_CHARACTERS_ONLY: specifies that the style should only be - applied to characters, - and not the paragraph. This allows content styling to be preserved - independently from that of e.g. a named paragraph style. - wxRICHTEXT_SETSTYLE_RESET: resets (clears) the existing style before applying - the new style. - wxRICHTEXT_SETSTYLE_REMOVE: removes the specified style. Only the style flags - are used in this operation. + - wxRICHTEXT_SETSTYLE_NONE: no style flag. + - wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this operation should be + undoable. + - wxRICHTEXT_SETSTYLE_OPTIMIZE: specifies that the style should not be applied + if the combined style at this point is already the style in question. + - wxRICHTEXT_SETSTYLE_PARAGRAPHS_ONLY: specifies that the style should only be + applied to paragraphs, and not the content. + This allows content styling to be preserved independently from that + of e.g. a named paragraph style. + - wxRICHTEXT_SETSTYLE_CHARACTERS_ONLY: specifies that the style should only be + applied to characters, and not the paragraph. + This allows content styling to be preserved independently from that + of e.g. a named paragraph style. + - wxRICHTEXT_SETSTYLE_RESET: resets (clears) the existing style before applying + the new style. + - wxRICHTEXT_SETSTYLE_REMOVE: removes the specified style. Only the style flags + are used in this operation. */ bool SetStyleEx(const wxRichTextRange& range, const wxTextAttr& style, @@ -1358,8 +1419,8 @@ public: //@} /** - Sets the style sheet associated with the control. A style sheet allows named - character and paragraph styles to be applied. + Sets the style sheet associated with the control. + A style sheet allows named character and paragraph styles to be applied. */ void SetStyleSheet(wxRichTextStyleSheet* styleSheet); @@ -1403,14 +1464,21 @@ public: */ virtual bool WordRight(int noWords = 1, int flags = 0); - //@{ /** - Write a bitmap or image at the current insertion point. Supply an optional type - to use - for internal and file storage of the raw data. + Loads an image from a file and writes it at the current insertion point. */ bool WriteImage(const wxString& filename, int bitmapType); + + /** + Writes an image block at the current insertion point. + */ bool WriteImage(const wxRichTextImageBlock& imageBlock); + + //@{ + /** + Write a bitmap or image at the current insertion point. + Supply an optional type to use for internal and file storage of the raw data. + */ bool WriteImage(const wxBitmap& bitmap, int bitmapType = wxBITMAP_TYPE_PNG); bool WriteImage(const wxImage& image, diff --git a/interface/wx/richtext/richtextformatdlg.h b/interface/wx/richtext/richtextformatdlg.h index c0122f329c..fb430cc3ec 100644 --- a/interface/wx/richtext/richtextformatdlg.h +++ b/interface/wx/richtext/richtextformatdlg.h @@ -1,6 +1,6 @@ ///////////////////////////////////////////////////////////////////////////// // Name: richtext/richtextformatdlg.h -// Purpose: interface of wxRichTextFormattingDialogFactory +// Purpose: interface of wxRichTextFormattingDialog* // Author: wxWidgets team // RCS-ID: $Id$ // Licence: wxWindows license @@ -11,15 +11,15 @@ This class provides pages for wxRichTextFormattingDialog, and allows other customization of the dialog. - A default instance of this class is provided automatically. If you wish to - change the behaviour of the - formatting dialog (for example add or replace a page), you may derive from this - class, - override one or more functions, and call the static function + + A default instance of this class is provided automatically. + If you wish to change the behaviour of the formatting dialog (for example add + or replace a page), you may derive from this class, override one or more + functions, and call the static function wxRichTextFormattingDialog::SetFormattingDialogFactory. @library{wxrichtext} - @category{FIXME} + @category{richtext} */ class wxRichTextFormattingDialogFactory : public wxObject { @@ -46,7 +46,7 @@ public: wxRichTextFormattingDialog* dialog); /** - Creates all pages under the dialog's book control, also calling AddPage. + Creates all pages under the dialog's book control, also calling AddPage(). */ virtual bool CreatePages(long pages, wxRichTextFormattingDialog* dialog); @@ -81,24 +81,32 @@ public: +#define wxRICHTEXT_FORMAT_STYLE_EDITOR 0x0001 +#define wxRICHTEXT_FORMAT_FONT 0x0002 +#define wxRICHTEXT_FORMAT_TABS 0x0004 +#define wxRICHTEXT_FORMAT_BULLETS 0x0008 +#define wxRICHTEXT_FORMAT_INDENTS_SPACING 0x0010 + /** @class wxRichTextFormattingDialog This dialog allows the user to edit a character and/or paragraph style. - In the constructor, specify the pages that will be created. Use GetStyle - to retrieve the common style for a given range, and then use ApplyStyle - to apply the user-selected formatting to a control. For example: + In the constructor, specify the pages that will be created. + Use wxRichTextFormattingDialog::GetStyle() to retrieve the common style + for a given range, and then use wxRichTextFormattingDialog::ApplyStyle() + to apply the user-selected formatting to a control. + For example: @code - wxRichTextRange range; + wxRichTextRange range; if (m_richTextCtrl-HasSelection()) range = m_richTextCtrl-GetSelectionRange(); else range = wxRichTextRange(0, m_richTextCtrl-GetLastPosition()+1); - int pages = - wxRICHTEXT_FORMAT_FONT|wxRICHTEXT_FORMAT_INDENTS_SPACING|wxRICHTEXT_FORMAT_TABS|wxRICHTEXT_FORMAT_BULLETS; + int pages = wxRICHTEXT_FORMAT_FONT|wxRICHTEXT_FORMAT_INDENTS_SPACING| \ + wxRICHTEXT_FORMAT_TABS|wxRICHTEXT_FORMAT_BULLETS; wxRichTextFormattingDialog formatDlg(pages, this); formatDlg.GetStyle(m_richTextCtrl, range); @@ -115,29 +123,29 @@ public: class wxRichTextFormattingDialog : public wxPropertySheetDialog { public: - //@{ + /** + Default ctor. + */ + wxRichTextFormattingDialog(); + /** Constructors. - + @param flags The pages to show. @param parent The dialog's parent. - @param id - The dialog's identifier. - @param title - The dialog's caption. @param pos The dialog's position. - @param size + @param sz The dialog's size. @param style The dialog's window style. */ - wxRichTextFormattingDialog(long flags, wxWindow* parent); - const wxPoint& pos = wxDefaultPosition, const wxSize& sz = wxDefaultSize, long style = wxDEFAULT_DIALOG_STYLE) - wxRichTextFormattingDialog(); - //@} + wxRichTextFormattingDialog(long flags, wxWindow* parent, + const wxPoint& pos = wxDefaultPosition, + const wxSize& sz = wxDefaultSize, + long style = wxDEFAULT_DIALOG_STYLE); /** Destructor. @@ -145,29 +153,27 @@ public: virtual ~wxRichTextFormattingDialog(); /** - Apply attributes to the given range, only changing attributes that need to be - changed. + Apply attributes to the given range, only changing attributes that + need to be changed. */ bool ApplyStyle(wxRichTextCtrl* ctrl, const wxRichTextRange& range, int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO|wxRICHTEXT_SETSTYLE_OPTIMIZE); /** - Creation: see @ref overview_wxrichtextformattingdialog "the constructor" for + Creation: see wxRichTextFormattingDialog() "the constructor" for details about the parameters. */ bool Create(long flags, wxWindow* parent, const wxString& title, - wxWindowID id, - const wxPoint& pos = wxDefaultPosition, - const wxSize& sz = wxDefaultSize, - long style = wxDEFAULT_DIALOG_STYLE); + wxWindowID id, const wxPoint& pos = wxDefaultPosition, + const wxSize& sz = wxDefaultSize, long style = wxDEFAULT_DIALOG_STYLE); //@{ /** Gets the attributes being edited. */ - const wxTextAttr GetAttributes(); - const wxTextAttr& GetAttributes(); + const wxTextAttr& GetAttributes() const; + wxTextAttr& GetAttributes(); //@} /** @@ -197,8 +203,8 @@ public: wxImageList* GetImageList() const; /** - Gets common attributes from the given range and calls SetAttributes. Attributes - that do not have common values in the given range + Gets common attributes from the given range and calls SetAttributes(). + Attributes that do not have common values in the given range will be omitted from the style's flags. */ virtual bool GetStyle(wxRichTextCtrl* ctrl, const wxRichTextRange& range); @@ -221,6 +227,7 @@ public: /** Sets the formatting factory object to be used for customization and page creation. + It deletes the existing factory object. */ static void SetFormattingDialogFactory(wxRichTextFormattingDialogFactory* factory); @@ -236,8 +243,8 @@ public: virtual bool SetStyle(const wxTextAttr& style, bool update = true); /** - Sets the style definition and optionally update the display, if @a update is @c - @true. + Sets the style definition and optionally update the display, + if @a update is @true. */ virtual bool SetStyleDefinition(const wxRichTextStyleDefinition& styleDef, wxRichTextStyleSheet* sheet, diff --git a/interface/wx/richtext/richtexthtml.h b/interface/wx/richtext/richtexthtml.h index 12a60ff7ba..89760f1c23 100644 --- a/interface/wx/richtext/richtexthtml.h +++ b/interface/wx/richtext/richtexthtml.h @@ -16,21 +16,41 @@ wxRichTextCtrl::SaveFile. Image handling requires a little extra work from the application, to choose an - appropriate image format for the target HTML viewer and to clean up the - temporary images - later. If you are planning to load the HTML into a standard web browser, you can + appropriate image format for the target HTML viewer and to clean up the temporary + images later. + If you are planning to load the HTML into a standard web browser, you can specify the handler flag wxRICHTEXT_HANDLER_SAVE_IMAGES_TO_BASE64 (the default) and no extra work is required: the images will be written with the HTML. However, if you want wxHTML compatibility, you will need to use - wxRICHTEXT_HANDLER_SAVE_IMAGES_TO_MEMORY - or wxRICHTEXT_HANDLER_SAVE_IMAGES_TO_FILES. In this case, you must either call - wxRichTextHTMLHandler::DeleteTemporaryImages before - the next load operation, or you must store the image - locations and delete them yourself when appropriate. You can call - wxRichTextHTMLHandler::GetTemporaryImageLocations to + @c wxRICHTEXT_HANDLER_SAVE_IMAGES_TO_MEMORY or + @c wxRICHTEXT_HANDLER_SAVE_IMAGES_TO_FILES. + + In this case, you must either call wxRichTextHTMLHandler::DeleteTemporaryImages + before the next load operation, or you must store the image locations and + delete them yourself when appropriate. + + You can call wxRichTextHTMLHandler::GetTemporaryImageLocations to get the array of temporary image names. + + @section richtexthtmlhandler_flags Handler flags + + The following flags can be used with this handler, via the handler's SetFlags() + function or the buffer or control's SetHandlerFlags() function: + + - wxRICHTEXT_HANDLER_SAVE_IMAGES_TO_MEMORY + Images are saved to the memory filesystem: suitable for showing wxHTML windows. + - wxRICHTEXT_HANDLER_SAVE_IMAGES_TO_FILES + Images are saved to temporary files: suitable for showing in wxHTML windows. + - wxRICHTEXT_HANDLER_SAVE_IMAGES_TO_BASE64 + Images are written with the HTML files in Base 64 format: suitable for showing + in web browsers. + - wxRICHTEXT_HANDLER_NO_HEADER_FOOTER + Don't include header and footer tags (HTML, HEAD, BODY), so that the HTML + can be used as part of a larger document. + + @library{wxrichtext} @category{richtext} */ @@ -38,28 +58,29 @@ class wxRichTextHTMLHandler : public wxRichTextFileHandler { public: /** - , wxString&@e ext = wxT("html"), @b int@e type = wxRICHTEXT_TYPE_HTML) Constructor. */ - wxRichTextHTMLHandler() const; + wxRichTextHTMLHandler(const wxString& name = wxT("HTML"), + const wxString& ext = wxT("html"), + int type = wxRICHTEXT_TYPE_HTML); /** Clears the image locations generated by the last operation. */ void ClearTemporaryImageLocations(); - //@{ /** - Delete the in-memory or temporary files generated by the last operation. This - is a static - function that can be used to delete the saved locations from an earlier - operation, - for example after the user has viewed the HTML file. + Deletes the in-memory or temporary files generated by the last operation. */ bool DeleteTemporaryImages(); + + /** + Delete the in-memory or temporary files generated by the last operation. + This is a static function that can be used to delete the saved locations + from an earlier operation, for example after the user has viewed the HTML file. + */ bool DeleteTemporaryImages(int flags, const wxArrayString& imageLocations); - //@} /** Saves the buffer content to the HTML stream. @@ -83,22 +104,34 @@ public: /** Reset the file counter, in case, for example, the same names are required each - time + time. */ static void SetFileCounter(int counter); /** Sets the mapping for converting point sizes to HTML font sizes. + There should be 7 elements, one for each HTML font size, each element - specifying the maximum point size for that - HTML font size. + specifying the maximum point size for that HTML font size. For example: + @code + wxArrayInt fontSizeMapping; + fontSizeMapping.Add(7); + fontSizeMapping.Add(9); + fontSizeMapping.Add(11); + fontSizeMapping.Add(12); + fontSizeMapping.Add(14); + fontSizeMapping.Add(22); + fontSizeMapping.Add(100); + + htmlHandler.SetFontSizeMapping(fontSizeMapping); + @endcode */ void SetFontSizeMapping(const wxArrayInt& fontSizeMapping); /** - Sets the directory for storing temporary files. If empty, the system - temporary directory will be used. + Sets the directory for storing temporary files. + If empty, the system temporary directory will be used. */ void SetTempDir(const wxString& tempDir); diff --git a/interface/wx/richtext/richtextprint.h b/interface/wx/richtext/richtextprint.h index df41065a0e..d3a0208ff7 100644 --- a/interface/wx/richtext/richtextprint.h +++ b/interface/wx/richtext/richtextprint.h @@ -6,28 +6,51 @@ // Licence: wxWindows license ///////////////////////////////////////////////////////////////////////////// + +/** + These are the header and footer page identifiers, passed to functions such + as wxRichTextHeaderFooterData::SetFooterText to specify the odd or even page + for the text. +*/ +enum wxRichTextOddEvenPage { + wxRICHTEXT_PAGE_ODD, + wxRICHTEXT_PAGE_EVEN, + wxRICHTEXT_PAGE_ALL, +}; + + +/** + These are the location identifiers for passing to functions such as + wxRichTextHeaderFooterData::SetFooterText(), to specify whether the text + is on the left, centre or right of the page. +*/ +enum wxRichTextPageLocation { + wxRICHTEXT_PAGE_LEFT, + wxRICHTEXT_PAGE_CENTRE, + wxRICHTEXT_PAGE_RIGHT +}; + + /** @class wxRichTextHeaderFooterData This class represents header and footer data to be passed to the - wxRichTextPrinting and - wxRichTextPrintout classes. + wxRichTextPrinting and wxRichTextPrintout classes. Headers and footers can be specified independently for odd, even or both page - sides. Different text can be specified - for left, centre and right locations on the page, and the font and text colour - can also - be specified. You can specify the following keywords in header and footer text, - which will + sides. Different text can be specified for left, centre and right locations + on the page, and the font and text colour can also be specified. + + You can specify the following keywords in header and footer text, which will be substituted for the actual values during printing and preview. - @@DATE@: the current date. - @@PAGESCNT@: the total number of pages. - @@PAGENUM@: the current page number. - @@TIME@: the current time. - @@TITLE@: the title of the document, as passed to the wxRichTextPrinting or - wxRichTextLayout constructor. + - @@DATE@: the current date. + - @@PAGESCNT@: the total number of pages. + - @@PAGENUM@: the current page number. + - @@TIME@: the current time. + - @@TITLE@: the title of the document, as passed to the wxRichTextPrinting or + wxRichTextLayout constructor. @library{wxrichtext} @category{richtext} @@ -56,7 +79,7 @@ public: /** Returns the font specified for printing the header and footer. */ - const wxFont GetFont() const; + const wxFont& GetFont() const; /** Returns the margin between the text and the footer. @@ -159,9 +182,8 @@ public: /** @class wxRichTextPrintout - This class implements print layout for wxRichTextBuffer. Instead of using it - directly, you - should normally use the wxRichTextPrinting class. + This class implements print layout for wxRichTextBuffer. + Instead of using it directly, you should normally use the wxRichTextPrinting class. @library{wxrichtext} @category{richtext} @@ -170,10 +192,9 @@ class wxRichTextPrintout : public wxPrintout { public: /** - ) Constructor. */ - wxRichTextPrintout(); + wxRichTextPrintout(const wxString& title = wxT("Printout")); /** Calculates scaling and text, header and footer rectangles. @@ -225,9 +246,8 @@ public: int right = 252); /** - Sets the buffer to print. wxRichTextPrintout does not manage this pointer; it - should - be managed by the calling code, such as wxRichTextPrinting. + Sets the buffer to print. wxRichTextPrintout does not manage this pointer; + it should be managed by the calling code, such as wxRichTextPrinting. */ void SetRichTextBuffer(wxRichTextBuffer* buffer); }; @@ -247,16 +267,17 @@ class wxRichTextPrinting : public wxObject { public: /** - , @b wxWindow*@e parentWindow = @NULL) - Constructor. Optionally pass a title to be used in the preview frame and - printing wait dialog, and - also a parent window for these windows. + Constructor. + + Optionally pass a title to be used in the preview frame and printing wait + dialog, and also a parent window for these windows. */ - wxRichTextPrinting(); + wxRichTextPrinting(const wxString& name = wxT("Printing"), + wxWindow* parentWindow = NULL); /** - A convenience function to get the footer text. See wxRichTextHeaderFooterData - for details. + A convenience function to get the footer text. + See wxRichTextHeaderFooterData for details. */ wxString GetFooterText(wxRichTextOddEvenPage page = wxRICHTEXT_PAGE_EVEN, wxRichTextPageLocation location = wxRICHTEXT_PAGE_CENTRE) const; @@ -267,8 +288,8 @@ public: const wxRichTextHeaderFooterData GetHeaderFooterData() const; /** - A convenience function to get the header text. See wxRichTextHeaderFooterData - for details. + A convenience function to get the header text. + See wxRichTextHeaderFooterData for details. */ wxString GetHeaderText(wxRichTextOddEvenPage page = wxRICHTEXT_PAGE_EVEN, wxRichTextPageLocation location = wxRICHTEXT_PAGE_CENTRE) const; @@ -279,8 +300,8 @@ public: wxPageSetupDialogData* GetPageSetupData(); /** - Returns the parent window to be used for the preview window and printing wait - dialog. + Returns the parent window to be used for the preview window and printing + wait dialog. */ wxWindow* GetParentWindow() const; @@ -305,33 +326,33 @@ public: void PageSetup(); /** - Shows a preview window for the given buffer. The function takes its own copy of - @e buffer. + Shows a preview window for the given buffer. + The function takes its own copy of @a buffer. */ bool PreviewBuffer(const wxRichTextBuffer& buffer); /** - Shows a preview window for the given file. @a richTextFile can be a text file - or XML file, or other file + Shows a preview window for the given file. + + @a richTextFile can be a text file or XML file, or other file depending on the available file handlers. */ bool PreviewFile(const wxString& richTextFile); /** - Prints the given buffer. The function takes its own copy of @e buffer. + Prints the given buffer. The function takes its own copy of @a buffer. */ bool PrintBuffer(const wxRichTextBuffer& buffer); /** - Prints the given file. @a richTextFile can be a text file or XML file, or other - file - depending on the available file handlers. + Prints the given file. @a richTextFile can be a text file or XML file, + or other file depending on the available file handlers. */ bool PrintFile(const wxString& richTextFile); /** - A convenience function to set the footer text. See wxRichTextHeaderFooterData - for details. + A convenience function to set the footer text. + See wxRichTextHeaderFooterData for details. */ void SetFooterText(const wxString& text, wxRichTextOddEvenPage page = wxRICHTEXT_PAGE_ALL, @@ -353,8 +374,8 @@ public: void SetHeaderFooterTextColour(const wxColour& colour); /** - A convenience function to set the header text. See wxRichTextHeaderFooterData - for details. + A convenience function to set the header text. + See wxRichTextHeaderFooterData for details. */ void SetHeaderText(const wxString& text, wxRichTextOddEvenPage page = wxRICHTEXT_PAGE_ALL, @@ -366,8 +387,8 @@ public: void SetPageSetupData(const wxPageSetupData& pageSetupData); /** - Sets the parent window to be used for the preview window and printing wait - dialog. + Sets the parent window to be used for the preview window and printing + wait dialog. */ void SetParentWindow(wxWindow* parent); diff --git a/interface/wx/richtext/richtextstyledlg.h b/interface/wx/richtext/richtextstyledlg.h index 30c4e48e7f..fac7c75dbd 100644 --- a/interface/wx/richtext/richtextstyledlg.h +++ b/interface/wx/richtext/richtextstyledlg.h @@ -9,8 +9,8 @@ /** @class wxRichTextStyleOrganiserDialog - This class shows a style sheet and allows the user to edit, add and remove - styles. + This class shows a style sheet and allows the user to edit, add and remove styles. + It can also be used as a style browser, for example if the application is not using a permanent wxRichTextStyleComboCtrl or wxRichTextStyleListCtrl to present styles. @@ -21,85 +21,58 @@ class wxRichTextStyleOrganiserDialog : public wxDialog { public: - //@{ /** - Constructors. + Default ctor. + */ + wxRichTextStyleOrganiserDialog(); + + /** + Constructor. + To create a dialog, pass a bitlist of @a flags (see below), a style sheet, a - text control to apply a selected style to (or @NULL), followed by the usual window parameters. + text control to apply a selected style to (or @NULL), followed by the usual + window parameters. + To specify the operations available to the user, pass a combination of these values to @e flags: - - @b wxRICHTEXT_ORGANISER_DELETE_STYLES - - Provides a button for deleting styles. - - @b wxRICHTEXT_ORGANISER_CREATE_STYLES - - Provides buttons for creating styles. - - @b wxRICHTEXT_ORGANISER_APPLY_STYLES - - Provides a button for applying the currently selected style to the selection. - - @b wxRICHTEXT_ORGANISER_EDIT_STYLES - - Provides a button for editing styles. - - @b wxRICHTEXT_ORGANISER_RENAME_STYLES - - Provides a button for renaming styles. - - @b wxRICHTEXT_ORGANISER_OK_CANCEL - - Provides OK and Cancel buttons. - - @b wxRICHTEXT_ORGANISER_RENUMBER - - Provides a checkbox for specifying that the selection should be renumbered. - + + - @b wxRICHTEXT_ORGANISER_DELETE_STYLES: Provides a button for deleting styles. + - @b wxRICHTEXT_ORGANISER_CREATE_STYLES: Provides buttons for creating styles. + - @b wxRICHTEXT_ORGANISER_APPLY_STYLES: Provides a button for applying the + currently selected style to the selection. + - @b wxRICHTEXT_ORGANISER_EDIT_STYLES: Provides a button for editing styles. + - @b wxRICHTEXT_ORGANISER_RENAME_STYLES: Provides a button for renaming styles. + - @b wxRICHTEXT_ORGANISER_OK_CANCEL: Provides OK and Cancel buttons. + - @b wxRICHTEXT_ORGANISER_RENUMBER: Provides a checkbox for specifying that + the selection should be renumbered. + The following flags determine what will be displayed in the style list: - - @b wxRICHTEXT_ORGANISER_SHOW_CHARACTER - - Displays character styles only. - - @b wxRICHTEXT_ORGANISER_SHOW_PARAGRAPH - - Displays paragraph styles only. - - @b wxRICHTEXT_ORGANISER_SHOW_LIST - - Displays list styles only. - - @b wxRICHTEXT_ORGANISER_SHOW_ALL - - Displays all styles. - + + - @b wxRICHTEXT_ORGANISER_SHOW_CHARACTER: Displays character styles only. + - @b wxRICHTEXT_ORGANISER_SHOW_PARAGRAPH: Displays paragraph styles only. + - @b wxRICHTEXT_ORGANISER_SHOW_LIST: Displays list styles only. + - @b wxRICHTEXT_ORGANISER_SHOW_ALL: Displays all styles. + The following symbols define commonly-used combinations of flags: - - @b wxRICHTEXT_ORGANISER_ORGANISE - - Enable all style editing operations so the dialog behaves as a style organiser. - - @b wxRICHTEXT_ORGANISER_BROWSE - - Show a list of all styles and their previews, but only allow application of a - style or - cancellation of the dialog. This makes the dialog behave as a style browser. - - @b wxRICHTEXT_ORGANISER_BROWSE_NUMBERING - - Enables only list style browsing, plus a control to specify renumbering. This - allows the dialog to be used for applying list styles to the selection. + + - @b wxRICHTEXT_ORGANISER_ORGANISE: + Enable all style editing operations so the dialog behaves as a style organiser. + - @b wxRICHTEXT_ORGANISER_BROWSE: + Show a list of all styles and their previews, but only allow application of a + style or cancellation of the dialog. This makes the dialog behave as a style browser. + - @b wxRICHTEXT_ORGANISER_BROWSE_NUMBERING: + Enables only list style browsing, plus a control to specify renumbering. + This allows the dialog to be used for applying list styles to the selection. */ wxRichTextStyleOrganiserDialog(int flags, wxRichTextStyleSheet* sheet, wxRichTextCtrl* ctrl, wxWindow* parent, - wxWindowID id = wxID_ANY); - const wxSize& size = wxDefaultSize, long style = wxDEFAULT_DIALOG_STYLE|wxRESIZE_BORDER|wxSYSTEM_MENU|wxCLOSE_BOX) - wxRichTextStyleOrganiserDialog(); - //@} + wxWindowID id = wxID_ANY, + const wxString& caption = _("Style Organiser"), + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxDEFAULT_DIALOG_STYLE|wxRESIZE_BORDER|wxSYSTEM_MENU|wxCLOSE_BOX); /** Applies the selected style to selection in the given control or the control @@ -108,14 +81,17 @@ public: bool ApplyStyle(wxRichTextCtrl* ctrl = NULL); /** - , wxPoint&@e pos = wxDefaultPosition, wxSize&@e size = wxDefaultSize, @b - long@e style = wxDEFAULT_DIALOG_STYLE|wxRESIZE_BORDER|wxSYSTEM_MENU|wxCLOSE_BOX) - Creates the dialog. See + Creates the dialog. See the ctor. */ - bool Create(int flags, wxRichTextStyleSheet* sheet, + bool Create(int flags, + wxRichTextStyleSheet* sheet, wxRichTextCtrl* ctrl, wxWindow* parent, - wxWindowID id = wxID_ANY) const; + wxWindowID id = wxID_ANY, + const wxString& caption = _("Style Organiser"), + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxDEFAULT_DIALOG_STYLE|wxRESIZE_BORDER|wxSYSTEM_MENU|wxCLOSE_BOX); /** Returns @true if the user has opted to restart numbering. diff --git a/interface/wx/richtext/richtextstyles.h b/interface/wx/richtext/richtextstyles.h index 4de3688761..3cc9fc99d6 100644 --- a/interface/wx/richtext/richtextstyles.h +++ b/interface/wx/richtext/richtextstyles.h @@ -9,19 +9,21 @@ /** @class wxRichTextStyleListCtrl - This class incorporates a wxRichTextStyleListBox and - a choice control that allows the user to select the category of style to view. + This class incorporates a wxRichTextStyleListBox and a choice control that + allows the user to select the category of style to view. + It is demonstrated in the wxRichTextCtrl sample in @c samples/richtext. To use wxRichTextStyleListCtrl, add the control to your window hierarchy and - call wxRichTextStyleListCtrl::SetStyleType with - one of wxRichTextStyleListBox::wxRICHTEXT_STYLE_ALL, + call wxRichTextStyleListCtrl::SetStyleType with one of + wxRichTextStyleListBox::wxRICHTEXT_STYLE_ALL, wxRichTextStyleListBox::wxRICHTEXT_STYLE_PARAGRAPH, wxRichTextStyleListBox::wxRICHTEXT_STYLE_CHARACTER and wxRichTextStyleListBox::wxRICHTEXT_STYLE_LIST to set the current view. + Associate the control with a style sheet and rich text control with - SetStyleSheet and SetRichTextCtrl, - so that when a style is double-clicked, it is applied to the selection. + SetStyleSheet and SetRichTextCtrl, so that when a style is double-clicked, + it is applied to the selection. @beginStyleTable @style{wxRICHTEXTSTYLELIST_HIDE_TYPE_SELECTOR} @@ -29,7 +31,7 @@ @endStyleTable @library{wxrichtext} - @category{FIXME} + @category{richtext} */ class wxRichTextStyleListCtrl : public wxControl { @@ -90,10 +92,13 @@ public: void SetStyleSheet(wxRichTextStyleSheet* styleSheet); /** - Sets the style type to display. One of - wxRichTextStyleListBox::wxRICHTEXT_STYLE_ALL, wxRichTextStyleListBox::wxRICHTEXT_STYLE_PARAGRAPH, - wxRichTextStyleListBox::wxRICHTEXT_STYLE_CHARACTER and - wxRichTextStyleListBox::wxRICHTEXT_STYLE_LIST. + Sets the style type to display. + + One of + - wxRichTextStyleListBox::wxRICHTEXT_STYLE_ALL, + - wxRichTextStyleListBox::wxRICHTEXT_STYLE_PARAGRAPH, + - wxRichTextStyleListBox::wxRICHTEXT_STYLE_CHARACTER + - wxRichTextStyleListBox::wxRICHTEXT_STYLE_LIST. */ void SetStyleType(wxRichTextStyleListBox::wxRichTextStyleType styleType); @@ -111,7 +116,7 @@ public: This is a base class for paragraph and character styles. @library{wxrichtext} - @category{FIXME} + @category{richtext} */ class wxRichTextStyleDefinition : public wxObject { @@ -224,8 +229,7 @@ public: @library{wxrichtext} @category{richtext} - @see wxRichTextStyleComboCtrl, @ref overview_wxrichtextctrloverview - "wxRichTextCtrl overview" + @see wxRichTextStyleComboCtrl, @ref overview_richtextctrl */ class wxRichTextStyleListBox : public wxHtmlListBox { @@ -261,8 +265,7 @@ public: /** If the return value is @true, clicking on a style name in the list will - immediately - apply the style to the associated rich text control. + immediately apply the style to the associated rich text control. */ bool GetApplyOnSelection() const; @@ -304,8 +307,7 @@ public: /** If @a applyOnSelection is @true, clicking on a style name in the list will - immediately - apply the style to the associated rich text control. + immediately apply the style to the associated rich text control. */ void SetApplyOnSelection(bool applyOnSelection); @@ -321,9 +323,10 @@ public: /** Sets the style type to display. One of - wxRichTextStyleListBox::wxRICHTEXT_STYLE_ALL, wxRichTextStyleListBox::wxRICHTEXT_STYLE_PARAGRAPH, - wxRichTextStyleListBox::wxRICHTEXT_STYLE_CHARACTER and - wxRichTextStyleListBox::wxRICHTEXT_STYLE_LIST. + - wxRichTextStyleListBox::wxRICHTEXT_STYLE_ALL, + - wxRichTextStyleListBox::wxRICHTEXT_STYLE_PARAGRAPH, + - wxRichTextStyleListBox::wxRICHTEXT_STYLE_CHARACTER + - wxRichTextStyleListBox::wxRICHTEXT_STYLE_LIST. */ void SetStyleType(wxRichTextStyleListBox::wxRichTextStyleType styleType); @@ -346,8 +349,7 @@ public: @library{wxrichtext} @category{richtext} - @see wxRichTextStyleListBox, @ref overview_wxrichtextctrloverview - "wxRichTextCtrl overview" + @see wxRichTextStyleListBox, @ref overview_richtextctrl */ class wxRichTextStyleComboCtrl : public wxComboCtrl { @@ -425,18 +427,16 @@ public: This class represents a list style definition, usually added to a wxRichTextStyleSheet. - The class inherits paragraph attributes from - wxRichTextStyleParagraphDefinition, and adds 10 further attribute objects, one for each level of a list. + The class inherits paragraph attributes from wxRichTextStyleParagraphDefinition, + and adds 10 further attribute objects, one for each level of a list. When applying a list style to a paragraph, the list style's base and - appropriate level attributes are merged with the - paragraph's existing attributes. - - You can apply a list style to one or more paragraphs using - wxRichTextCtrl::SetListStyle. You - can also use the functions wxRichTextCtrl::NumberList, - wxRichTextCtrl::PromoteList and - wxRichTextCtrl::ClearListStyle. As usual, there are wxRichTextBuffer versions - of these functions + appropriate level attributes are merged with the paragraph's existing attributes. + + You can apply a list style to one or more paragraphs using wxRichTextCtrl::SetListStyle. + You can also use the functions wxRichTextCtrl::NumberList, wxRichTextCtrl::PromoteList and + wxRichTextCtrl::ClearListStyle. + + As usual, there are wxRichTextBuffer versions of these functions so that you can apply them directly to a buffer without requiring a control. @library{wxrichtext} @@ -458,6 +458,7 @@ public: /** This function combines the given paragraph style with the list style's base attributes and level style matching the given indent, returning the combined attributes. + If @a styleSheet is specified, the base style for this definition will also be included in the result. */ @@ -474,6 +475,7 @@ public: /** This function combines the list style's base attributes and the level style matching the given indent, returning the combined attributes. + If @a styleSheet is specified, the base style for this definition will also be included in the result. */ @@ -483,6 +485,7 @@ public: /** This function combines the list style's base attributes and the style for the specified level, returning the combined attributes. + If @a styleSheet is specified, the base style for this definition will also be included in the result. */ @@ -527,9 +530,8 @@ public: A style sheet contains named paragraph and character styles that make it easy for a user to apply combinations of attributes to a wxRichTextCtrl. - You can use a wxRichTextStyleListBox in your - user interface to show available styles to the user, and allow application - of styles to the control. + You can use a wxRichTextStyleListBox in your user interface to show available + styles to the user, and allow application of styles to the control. @library{wxrichtext} @category{richtext} diff --git a/interface/wx/richtext/richtextsymboldlg.h b/interface/wx/richtext/richtextsymboldlg.h index 5fa4b1d7eb..1095e8c058 100644 --- a/interface/wx/richtext/richtextsymboldlg.h +++ b/interface/wx/richtext/richtextsymboldlg.h @@ -17,30 +17,29 @@ is generic and can be used in other contexts. To use the dialog, pass a default symbol specified as a string, an initial font - name, - and a current font name. The difference between the initial font and + name, and a current font name. The difference between the initial font and current font is that the initial font determines what the font control will be - set to when the dialog shows - an empty string will show the selection @e - normal text. + set to when the dialog shows - an empty string will show the selection + @e normal text. The current font, on the other hand, is used by the dialog to determine what - font - to display the characters in, even when no initial font is selected. + font to display the characters in, even when no initial font is selected. This allows the user (and application) to distinguish between inserting a symbol in the current font, and inserting it with a specified font. When the dialog is dismissed, the application can get the selected symbol - with GetSymbol and test whether a font was specified with UseNormalFont, - fetching the specified font with GetFontName. + with wxSymbolPickerDialog::GetSymbol and test whether a font was specified + with wxSymbolPickerDialog::UseNormalFont,fetching the specified font with + wxSymbolPickerDialog::GetFontName. Here's a realistic example, inserting the supplied symbol into a rich text control in either the current font or specified font. @code - wxRichTextCtrl* ctrl = (wxRichTextCtrl*) FindWindow(ID_RICHTEXT_CTRL); + wxRichTextCtrl* ctrl = (wxRichTextCtrl*) FindWindow(ID_RICHTEXT_CTRL); wxTextAttr attr; attr.SetFlags(wxTEXT_ATTR_FONT); - ctrl-GetStyle(ctrl-GetInsertionPoint(), attr); + ctrl-GetStyle(ctrl->GetInsertionPoint(), attr); wxString currentFontName; if (attr.HasFont() && attr.GetFont().Ok()) @@ -58,7 +57,7 @@ { long insertionPoint = ctrl-GetInsertionPoint(); - ctrl-WriteText(dlg.GetSymbol()); + ctrl->WriteText(dlg.GetSymbol()); if (!dlg.UseNormalFont()) { @@ -77,19 +76,23 @@ class wxSymbolPickerDialog : public wxDialog { public: - //@{ /** - Constructors. - + Default ctor. + */ + wxSymbolPickerDialog(); + + /** + Constructor. + @param symbol - The initial symbol to show. Specify a single character in a string, or an - empty string. + The initial symbol to show. + Specify a single character in a string, or an empty string. @param initialFont - The initial font to be displayed in the font list. If empty, the item - normal text will be selected. + The initial font to be displayed in the font list. + If empty, the item normal text will be selected. @param normalTextFont - The font the dialog will use to display the symbols if the initial font is - empty. + The font the dialog will use to display the symbols if the + initial font is empty. @param parent The dialog's parent. @param id @@ -107,21 +110,25 @@ public: const wxString& initialFont, const wxString& normalTextFont, wxWindow* parent, - wxWindowID id = wxID_ANY); - const wxSize& size = wxDefaultSize, long style = wxDEFAULT_DIALOG_STYLE|wxRESIZE_BORDER|wxCLOSE_BOX) - wxSymbolPickerDialog(); - //@} + wxWindowID id = wxID_ANY, + const wxString& title = _("Symbols"), + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxDEFAULT_DIALOG_STYLE|wxRESIZE_BORDER|wxCLOSE_BOX); /** - , wxPoint&@e pos = wxDefaultPosition, wxSize&@e size = wxDefaultSize, @b - long@e style = wxDEFAULT_DIALOG_STYLE|wxRESIZE_BORDER|wxCLOSE_BOX) - Creation: see @ref wxsymbolpickerdialog() "the constructor" for details about + Creation: see @ref wxSymbolPickerDialog() "the constructor" for details about the parameters. */ - bool Create(const wxString& symbol, const wxString& initialFont, + bool Create(const wxString& symbol, + const wxString& initialFont, const wxString& normalTextFont, wxWindow* parent, - wxWindowID id = wxID_ANY) const; + wxWindowID id = wxID_ANY, + const wxString& title = _("Symbols"), + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxDEFAULT_DIALOG_STYLE|wxRESIZE_BORDER|wxCLOSE_BOX); /** Returns the font name (the font reflected in the font list). @@ -134,8 +141,7 @@ public: bool GetFromUnicode() const; /** - Gets the font name used for displaying symbols in the absence of a selected - font. + Gets the font name used for displaying symbols in the absence of a selected font. */ wxString GetNormalTextFontName() const; @@ -181,8 +187,7 @@ public: void SetUnicodeMode(bool unicodeMode); /** - Returns @true if the has specified normal text - that is, there is no selected - font. + Returns @true if the has specified normal text - that is, there is no selected font. */ bool UseNormalFont() const; }; diff --git a/interface/wx/richtext/richtextxml.h b/interface/wx/richtext/richtextxml.h index 69c812b3b3..9c11dbe355 100644 --- a/interface/wx/richtext/richtextxml.h +++ b/interface/wx/richtext/richtextxml.h @@ -10,10 +10,21 @@ @class wxRichTextXMLHandler A handler for loading and saving content in an XML format specific - to wxRichTextBuffer. You can either add the handler to the buffer - and load and save through the buffer or control API, or you can - create an instance of the handler on the stack and call its - functions directly. + to wxRichTextBuffer. + + You can either add the handler to the buffer and load and save through + the buffer or control API, or you can create an instance of the handler + on the stack and call its functions directly. + + + @section richtextxmlhandler_flags Handler flags + + The following flags can be used with this handler, via the handler's SetFlags() + function or the buffer or control's SetHandlerFlags() function: + + - wxRICHTEXT_HANDLER_INCLUDE_STYLESHEET + Include the style sheet in loading and saving operations. + @library{wxrichtext} @category{richtext} @@ -22,10 +33,11 @@ class wxRichTextXMLHandler : public wxRichTextFileHandler { public: /** - , wxString&@e ext = wxT("xml"), @b int@e type = wxRICHTEXT_TYPE_XML) Constructor. */ - wxRichTextXMLHandler() const; + wxRichTextXMLHandler(const wxString& name = wxT("XML"), + const wxString& ext = wxT("xml"), + int type = wxRICHTEXT_TYPE_XML) const; /** Returns @true. -- 2.47.2