wxrichtextbuffer

this class represents the whole buffer associated with a wxrichtextctrl.

derived from

wxrichtextparagraphlayoutbox

include files

data structures

members

wxrichtextbuffer::wxrichtextbuffer

wxrichtextbuffer(const wxrichtextbuffer& obj)

copy constructor.

wxrichtextbuffer()

default constructors.

wxrichtextbuffer::~wxrichtextbuffer

~wxrichtextbuffer()

destructor.

wxrichtextbuffer::addeventhandler

bool addeventhandler(wxevthandler* handler)

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 wxrichtextbuffer::removeeventhandler is called with true as the second argument.

wxrichtextbuffer::addhandler

void addhandler(wxrichtextfilehandler* handler)

adds a file handler.

wxrichtextbuffer::addparagraph

wxrichtextrange addparagraph(const wxstring& text)

adds a paragraph of text.

wxrichtextbuffer::batchingundo

bool batchingundo() const

returns true if the buffer is currently collapsing commands into a single notional command.

wxrichtextbuffer::beginalignment

bool beginalignment(wxtextattralignment alignment)

begins using alignment.

wxrichtextbuffer::beginbatchundo

bool beginbatchundo(const wxstring& cmdname)

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.

cmdname should be the name of the combined command that will appear next to undo and redo in the edit menu.

wxrichtextbuffer::beginbold

bool beginbold()

begin applying bold.

wxrichtextbuffer::begincharacterstyle

bool begincharacterstyle(const wxstring& characterstyle)

begins applying the named character style.

wxrichtextbuffer::beginfont

bool beginfont(const wxfont& font)

begins using this font.

wxrichtextbuffer::beginfontsize

bool beginfontsize(int pointsize)

begins using the given point size.

wxrichtextbuffer::beginitalic

bool beginitalic()

begins using italic.

wxrichtextbuffer::beginleftindent

bool beginleftindent(int leftindent, int leftsubindent = 0)

begin using leftindent for the left indent, and optionally 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.

wxrichtextbuffer::beginlinespacing

bool beginlinespacing(int linespacing)

begins line spacing using the specified value. 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:

#define wxtext_attr_line_spacing_normal         10
#define wxtext_attr_line_spacing_half           15
#define wxtext_attr_line_spacing_twice          20

wxrichtextbuffer::beginliststyle

bool beginliststyle(const wxstring& liststyle, int level=1, int number=1)

begins using a specified list style. optionally, you can also pass a level and a number.

wxrichtextbuffer::beginnumberedbullet

bool beginnumberedbullet(int bulletnumber, int leftindent, int leftsubindent, int bulletstyle = wxtext_attr_bullet_style_arabic|wxtext_attr_bullet_style_period)

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.

bulletnumber is a number, usually starting with 1.

leftindent and leftsubindent are values in tenths of a millimetre.

bulletstyle is a bitlist of the following values:

#define wxtext_attr_bullet_style_none               0x00000000
#define wxtext_attr_bullet_style_arabic             0x00000001
#define wxtext_attr_bullet_style_letters_upper      0x00000002
#define wxtext_attr_bullet_style_letters_lower      0x00000004
#define wxtext_attr_bullet_style_roman_upper        0x00000008
#define wxtext_attr_bullet_style_roman_lower        0x00000010
#define wxtext_attr_bullet_style_symbol             0x00000020
#define wxtext_attr_bullet_style_bitmap             0x00000040
#define wxtext_attr_bullet_style_parentheses        0x00000080
#define wxtext_attr_bullet_style_period             0x00000100
#define wxtext_attr_bullet_style_standard           0x00000200
#define wxtext_attr_bullet_style_right_parenthesis  0x00000400
#define wxtext_attr_bullet_style_outline            0x00000800
#define wxtext_attr_bullet_style_align_left         0x00000000
#define wxtext_attr_bullet_style_align_right        0x00001000
#define wxtext_attr_bullet_style_align_centre       0x00002000

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.

wxrichtextbuffer::beginparagraphspacing

bool beginparagraphspacing(int before, int after)

begins paragraph spacing; pass the before-paragraph and after-paragraph spacing in tenths of a millimetre.

wxrichtextbuffer::beginparagraphstyle

bool beginparagraphstyle(const wxstring& paragraphstyle)

begins applying the named paragraph style.

wxrichtextbuffer::beginrightindent

bool beginrightindent(int rightindent)

begins a right indent, specified in tenths of a millimetre.

wxrichtextbuffer::beginstyle

bool beginstyle(const wxtextattrex& style)

begins using a specified style.

wxrichtextbuffer::beginsuppressundo

bool beginsuppressundo()

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.

wxrichtextbuffer::beginstandardbullet

bool beginstandardbullet(const wxstring& bulletname, int leftindent, int leftsubindent, int bulletstyle = wxtext_attr_bullet_style_standard)

begins applying a standard bullet, using one of the standard bullet names (currently standard/circle or standard/square. see beginnumberedbullet for an explanation of how indentation is used to render the bulleted paragraph.

wxrichtextbuffer::beginsymbolbullet

bool beginsymbolbullet(wxchar symbol, int leftindent, int leftsubindent, int bulletstyle = wxtext_attr_bullet_style_symbol)

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.

wxrichtextbuffer::begintextcolour

bool begintextcolour(const wxcolour& colour)

begins using the specified text foreground colour.

wxrichtextbuffer::beginunderline

bool beginunderline()

begins using underline.

wxrichtextbuffer::beginurl

bool beginurl(const wxstring& url, const wxstring& characterstyle = wxemptystring)

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.

wxrichtextbuffer::canpastefromclipboard

bool canpastefromclipboard() const

returns true if content can be pasted from the clipboard.

wxrichtextbuffer::cleanuphandlers

void cleanuphandlers()

cleans up the file handlers.

wxrichtextbuffer::clear

void clear()

clears the buffer.

wxrichtextbuffer::clearliststyle

bool clearliststyle(const wxrichtextrange& range, int flags = wxrichtext_setstyle_with_undo)

clears the list style from the given range, clearing list-related attributes and applying any named paragraph style associated with each paragraph.

flags is a bit list of the following:

wxrichtext_setstyle_with_undo: specifies that this command will be undoable.

wxrichtextbuffer::clearstylestack

void clearstylestack()

clears the style stack.

wxrichtextbuffer::clone

wxrichtextobject* clone() const

clones the object.

wxrichtextbuffer::copy

void copy(const wxrichtextbuffer& obj)

copies the given buffer.

wxrichtextbuffer::copytoclipboard

bool copytoclipboard(const wxrichtextrange& range)

copy the given range to the clipboard.

wxrichtextbuffer::deleterangewithundo

bool deleterangewithundo(const wxrichtextrange& range, wxrichtextctrl* ctrl)

submits a command to delete the given range.

wxrichtextbuffer::dump

void dump()

void dump(wxtextoutputstream& stream)

dumps the contents of the buffer for debugging purposes.

wxrichtextbuffer::endalignment

bool endalignment()

ends alignment.

wxrichtextbuffer::endallstyles

bool endallstyles()

ends all styles that have been started with a begin... command.

wxrichtextbuffer::endbatchundo

bool endbatchundo()

ends collapsing undo/redo commands, and submits the combined command.

wxrichtextbuffer::endbold

bool endbold()

ends using bold.

wxrichtextbuffer::endcharacterstyle

bool endcharacterstyle()

ends using the named character style.

wxrichtextbuffer::endfont

bool endfont()

ends using a font.

wxrichtextbuffer::endfontsize

bool endfontsize()

ends using a point size.

wxrichtextbuffer::enditalic

bool enditalic()

ends using italic.

wxrichtextbuffer::endleftindent

bool endleftindent()

ends using a left indent.

wxrichtextbuffer::endlinespacing

bool endlinespacing()

ends using a line spacing.

wxrichtextbuffer::endliststyle

bool endliststyle()

ends using a specified list style.

wxrichtextbuffer::endnumberedbullet

bool endnumberedbullet()

ends a numbered bullet.

wxrichtextbuffer::endparagraphspacing

bool endparagraphspacing()

ends paragraph spacing.

wxrichtextbuffer::endparagraphstyle

bool endparagraphstyle()

ends applying a named character style.

wxrichtextbuffer::endrightindent

bool endrightindent()

ends using a right indent.

wxrichtextbuffer::endstyle

bool endstyle()

ends the current style.

wxrichtextbuffer::endsuppressundo

bool endsuppressundo()

ends suppressing undo/redo commands.

wxrichtextbuffer::endsymbolbullet

bool endsymbolbullet()

ends using a symbol bullet.

wxrichtextbuffer::endstandardbullet

bool endstandardbullet()

ends using a standard bullet.

wxrichtextbuffer::endtextcolour

bool endtextcolour()

ends using a text foreground colour.

wxrichtextbuffer::endunderline

bool endunderline()

ends using underline.

wxrichtextbuffer::endurl

bool endurl()

ends applying a url.

wxrichtextbuffer::findhandler

wxrichtextfilehandler* findhandler(int imagetype)

finds a handler by type.

wxrichtextfilehandler* findhandler(const wxstring& extension, int imagetype)

finds a handler by extension and type.

wxrichtextfilehandler* findhandler(const wxstring& name)

finds a handler by name.

wxrichtextbuffer::findhandlerfilenameortype

wxrichtextfilehandler* findhandlerfilenameortype(const wxstring& filename, int imagetype)

finds a handler by filename or, if supplied, type.

wxrichtextbuffer::getbasicstyle

const wxtextattrex& getbasicstyle() const

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).

wxrichtextbuffer::getbatchedcommand

wxrichtextcommand* getbatchedcommand() const

gets the collapsed command.

wxrichtextbuffer::getcommandprocessor

wxcommandprocessor* getcommandprocessor() const

gets the command processor. a text buffer always creates its own command processor when it is initialized.

wxrichtextbuffer::getdefaultstyle

const wxtextattrex& getdefaultstyle() 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).

wxrichtextbuffer::getextwildcard

wxstring getextwildcard(bool combine = false, bool save = false, wxarrayint* types = null)

gets a wildcard incorporating all visible handlers. if 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.

wxrichtextbuffer::gethandlers

wxlist& gethandlers()

returns the list of file handlers.

wxrichtextbuffer::getrenderer

static wxrichtextrenderer* getrenderer()

returns the object to be used to render certain aspects of the content, such as bullets.

wxrichtextbuffer::getstyle

bool getstyle(long position, wxrichtextattr& style)

bool getstyle(long position, wxtextattrex& style)

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.

wxrichtextbuffer::getstyleforrange

bool getstyleforrange(const wxrichtextrange& range, wxtextattrex& 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.

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.

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 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 will be changed to show red.

wxrichtextbuffer::getstylesheet

wxrichtextstylesheet* getstylesheet() const

returns the current style sheet associated with the buffer, if any.

wxrichtextbuffer::getstylestacksize

size_t getstylestacksize() const

get the size of the style stack, for example to check correct nesting.

wxrichtextbuffer::getuncombinedstyle

bool getuncombinedstyle(long position, wxrichtextattr& style)

bool getuncombinedstyle(long position, wxtextattrex& style)

gets the attributes at the given position.

this function gets the 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.

if you specify (any) paragraph attribute in style's flags, this function will fetch the paragraph attributes. otherwise, it will return the character attributes.

wxrichtextbuffer::hittest

int hittest(wxdc& dc, const wxpoint& pt, long& textposition)

finds the text position for the given position, putting the position in textposition if one is found. pt is in logical units (a zero y position is at the beginning of the buffer).

the function returns one of the following values:

// the point was not on this object
#define wxrichtext_hittest_none     0x01
// the point was before the position returned from hittest
#define wxrichtext_hittest_before   0x02
// the point was after the position returned from hittest
#define wxrichtext_hittest_after    0x04
// the point was on the position returned from hittest
#define wxrichtext_hittest_on       0x08
// the point was on space outside content
#define wxrichtext_hittest_outside  0x10

wxrichtextbuffer::init

void init()

initialisation.

wxrichtextbuffer::initstandardhandlers

void initstandardhandlers()

initialises the standard handlers. currently, only the plain text loading/saving handler is initialised by default.

wxrichtextbuffer::inserthandler

void inserthandler(wxrichtextfilehandler* handler)

inserts a handler at the front of the list.

wxrichtextbuffer::insertimagewithundo

bool insertimagewithundo(long pos, const wxrichtextimageblock& imageblock, wxrichtextctrl* ctrl)

submits a command to insert the given image.

wxrichtextbuffer::insertnewlinewithundo

bool insertnewlinewithundo(long pos, wxrichtextctrl* ctrl)

submits a command to insert a newline.

wxrichtextbuffer::inserttextwithundo

bool inserttextwithundo(long pos, const wxstring& text, wxrichtextctrl* ctrl)

submits a command to insert the given text.

wxrichtextbuffer::ismodified

bool ismodified() const

returns true if the buffer has been modified.

wxrichtextbuffer::loadfile

bool loadfile(wxinputstream& stream, int type = wxrichtext_type_any)

loads content from a stream.

bool loadfile(const wxstring& filename, int type = wxrichtext_type_any)

loads content from a file.

wxrichtextbuffer::modify

void modify(bool modify = true)

marks the buffer as modified or unmodified.

wxrichtextbuffer::numberlist

bool numberlist(const wxrichtextrange& range, const wxrichtextliststyledefinition* style, int flags = wxrichtext_setstyle_with_undo, int startfrom = -1, int listlevel = -1)

bool number(const wxrichtextrange& range, const wxstring& stylename, int flags = wxrichtext_setstyle_with_undo, int startfrom = -1, int listlevel = -1)

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.

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 startfrom, otherwise existing attributes are used.
wxrichtext_setstyle_specify_level: specifies that listlevel should be used as the level for all paragraphs, otherwise the current indentation will be used.

wxrichtextbuffer::pastefromclipboard

bool pastefromclipboard(long position)

pastes the clipboard content to the buffer at the given position.

wxrichtextbuffer::promotelist

bool promotelist(int promoteby, const wxrichtextrange& range, const wxrichtextliststyledefinition* style, int flags = wxrichtext_setstyle_with_undo, int listlevel = -1)

bool promotelist(int promoteby, const wxrichtextrange& range, const wxstring& stylename, int flags = wxrichtext_setstyle_with_undo, int listlevel = -1)

promotes or demotes the paragraphs in the given range. a positive 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.

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 startfrom, otherwise existing attributes are used.
wxrichtext_setstyle_specify_level: specifies that listlevel should be used as the level for all paragraphs, otherwise the current indentation will be used.

wxrichtextbuffer::removeeventhandler

bool removeeventhandler(wxevthandler* handler, bool deletehandler = false)

removes an event handler from the buffer's list of handlers, deleting the object if deletehandler is true.

wxrichtextbuffer::removehandler

bool removehandler(const wxstring& name)

removes a handler.

wxrichtextbuffer::resetandclearcommands

void resetandclearcommands()

clears the buffer, adds a new blank paragraph, and clears the command history.

wxrichtextbuffer::savefile

bool savefile(wxoutputstream& stream, int type = wxrichtext_type_any)

saves content to a stream.

bool savefile(const wxstring& filename, int type = wxrichtext_type_any)

saves content to a file.

wxrichtextbuffer::setbasicstyle

void setbasicstyle(const wxrichtextattr& style)

void setbasicstyle(const wxtextattrex& style)

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).

wxrichtextbuffer::setdefaultstyle

void setdefaultstyle(const wxtextattrex& 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).

this is not cumulative - setting the default style will replace the previous default style.

wxrichtextbuffer::setliststyle

bool setliststyle(const wxrichtextrange& range, const wxrichtextliststyledefinition* style, int flags = wxrichtext_setstyle_with_undo, int startfrom = -1, int listlevel = -1)

bool setliststyle(const wxrichtextrange& range, const wxstring& stylename, int flags = wxrichtext_setstyle_with_undo, int startfrom = -1, int listlevel = -1)

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.

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 startfrom, otherwise existing attributes are used.
wxrichtext_setstyle_specify_level: specifies that listlevel should be used as the level for all paragraphs, otherwise the current indentation will be used.

wxrichtextbuffer::setrenderer

static void setrenderer(wxrichtextrenderer* renderer)

sets 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.

wxrichtextbuffer::setstyle

bool setstyle(const wxrichtextrange& range, const wxrichtextattr& style, int flags = wxrichtext_setstyle_with_undo)

bool setstyle(const wxrichtextrange& range, const wxtextattrex& style, int flags = wxrichtext_setstyle_with_undo)

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). this differs from the wxrichtextctrl api, where you would specify (5,6).

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.

wxrichtextbuffer::setstylesheet

void setstylesheet(wxrichtextstylesheet* stylesheet)

sets the current style sheet, if any. this will allow the application to use named character and paragraph styles found in the style sheet.

wxrichtextbuffer::submitaction

bool submitaction(wxrichtextaction* action)

submit an action immediately, or delay it according to whether collapsing is on.

wxrichtextbuffer::suppressingundo

bool suppressingundo() const

returns true if undo suppression is currently on.