// 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
@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.
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);
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.
*/
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,
/**
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);
/**
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.
*/
/**
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,
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);
/**
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);
*/
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;
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);
/**
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);
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);
/**
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);
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();
*/
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.
//@{
/**
- 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,
//@{
/**
- 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,
*/
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
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.
*/
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,
/**
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);
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;
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);
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;
//@{
/**
- 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);
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);
/**
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);
};
~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;
/**
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;
/////////////////////////////////////////////////////////////////////////////
// Name: richtext/richtextctrl.h
-// Purpose: interface of wxRichTextEvent
+// Purpose: interface of wxRichTextCtrl and wxRichTextEvent
// Author: wxWidgets team
// RCS-ID: $Id$
// Licence: wxWindows license
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
{
/**
Constructor.
+ @param commandType
+ The type of the event.
@param id
Window identifier. The value @c wxID_ANY indicates a default value.
*/
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;
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);
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.
/**
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);
virtual bool BatchingUndo() const;
/**
- Begins using alignment
+ Begins using alignment.
For alignment values, see wxTextAttr.
*/
bool BeginAlignment(wxTextAttrAlignment alignment);
/**
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.
/**
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,
/**
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);
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,
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);
/**
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);
/**
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;
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;
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);
/**
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;
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;
/**
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;
/**
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);
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;
/**
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;
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);
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;
/**
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,
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,
//@{
/**
- 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,
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,
/**
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);
/**
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);
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);
/**
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,
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).
*/
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).
*/
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).
*/
/**
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,
//@}
/**
- 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);
*/
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,
/////////////////////////////////////////////////////////////////////////////
// Name: richtext/richtextformatdlg.h
-// Purpose: interface of wxRichTextFormattingDialogFactory
+// Purpose: interface of wxRichTextFormattingDialog*
// Author: wxWidgets team
// RCS-ID: $Id$
// Licence: wxWindows license
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
{
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);
+#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);
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.
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();
//@}
/**
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);
/**
Sets the formatting factory object to be used for customization and page
creation.
+
It deletes the existing factory object.
*/
static void SetFormattingDialogFactory(wxRichTextFormattingDialogFactory* factory);
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,
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}
*/
{
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.
/**
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);
// 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}
/**
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.
/**
@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}
{
public:
/**
- )
Constructor.
*/
- wxRichTextPrintout();
+ wxRichTextPrintout(const wxString& title = wxT("Printout"));
/**
Calculates scaling and text, header and footer rectangles.
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);
};
{
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;
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;
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;
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,
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,
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);
/**
@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.
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
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.
/**
@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}
@endStyleTable
@library{wxrichtext}
- @category{FIXME}
+ @category{richtext}
*/
class wxRichTextStyleListCtrl : public wxControl
{
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);
This is a base class for paragraph and character styles.
@library{wxrichtext}
- @category{FIXME}
+ @category{richtext}
*/
class wxRichTextStyleDefinition : public wxObject
{
@library{wxrichtext}
@category{richtext}
- @see wxRichTextStyleComboCtrl, @ref overview_wxrichtextctrloverview
- "wxRichTextCtrl overview"
+ @see wxRichTextStyleComboCtrl, @ref overview_richtextctrl
*/
class wxRichTextStyleListBox : public wxHtmlListBox
{
/**
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;
/**
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);
/**
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);
@library{wxrichtext}
@category{richtext}
- @see wxRichTextStyleListBox, @ref overview_wxrichtextctrloverview
- "wxRichTextCtrl overview"
+ @see wxRichTextStyleListBox, @ref overview_richtextctrl
*/
class wxRichTextStyleComboCtrl : public wxComboCtrl
{
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}
/**
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.
*/
/**
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.
*/
/**
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.
*/
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}
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())
{
long insertionPoint = ctrl-GetInsertionPoint();
- ctrl-WriteText(dlg.GetSymbol());
+ ctrl->WriteText(dlg.GetSymbol());
if (!dlg.UseNormalFont())
{
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
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).
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;
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;
};
@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}
{
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.
projects / wxWidgets.git / commitdiff
