wx.richtext.RichTextObject

This is the base for drawable rich text objects.

See also

wx.richtext.RichTextBuffer, wx.richtext.RichTextCtrl

Class Hierarchy

Inheritance diagram for class RichTextObject:

Known Subclasses

wx.richtext.RichTextCompositeObject, wx.richtext.RichTextImage, wx.richtext.RichTextPlainText

Methods Summary

__init__	Constructor, taking an optional parent pointer.
AcceptsFocus	Returns True if objects of this class can accept the focus, i.e. a call to SetFocusObject is possible.
AdjustAttributes	Adjusts the attributes for virtual attribute provision, collapsed borders, etc.
AdjustAvailableSpace	Returns the rectangle which the child has available to it given restrictions specified in the child attribute, e.g.
CalculateRange	Calculates the range of the object.
CanEditProperties	Returns True if we can edit the object’s properties via a GUI.
CanMerge	Returns True if this object can merge itself with the given one.
CanSplit	Returns True if this object can potentially be split, by virtue of having different virtual attributes for individual sub-objects.
Clone	Clones the object.
ConvertPixelsToTenthsMM	Convert units in pixels to tenths of a millimetre.
ConvertTenthsMMToPixels	Converts units in tenths of a millimetre to device units.
Copy	Copies the object.
DeleteRange	Deletes the given range.
Dereference	Reference-counting allows us to use the same object in multiple lists (not yet used).
DoSplit	Do a split from pos, returning an object containing the second part, and setting the first part in ‘this’.
Draw	Draw the item, within the given range.
DrawBorder	Draws a border.
DrawBoxAttributes	Draws the borders and background for the given rectangle and attributes.
EditProperties	Edits the object’s properties via a GUI.
FindPosition	Finds the absolute position and row height for the given character position.
GetAbsolutePosition	Returns the absolute object position, by traversing up the child/parent hierarchy.
GetAttributes	Returns the object’s attributes.
GetAvailableContentArea	Calculates the available content space in the given rectangle, given the margins, border and padding specified in the object’s attributes.
GetBestSize	Returns the best size, i.e. the ideal starting size for this object irrespective of available space.
GetBottomMargin	Returns the bottom margin of the object, in pixels.
GetBoxRects	Returns the various rectangles of the box model in pixels.
GetBuffer	Returns the containing buffer.
GetCachedSize	Gets the cached object size as calculated by Layout.
GetContainer	Returns the top-level container of this object.
GetDescent	Returns the stored descent value.
GetFloatDirection	Returns the floating direction.
GetLeftMargin	Returns the left margin of the object, in pixels.
GetMaxSize	Gets the maximum object size as calculated by Layout.
GetMinSize	Gets the minimum object size as calculated by Layout.
GetName	Returns the identifying name for this object from the properties, using the “name” key.
GetNaturalSize	Gets the ‘natural’ size for an object.
GetOwnRange	Returns the object’s own range (valid if top-level).
GetOwnRangeIfTopLevel	Returns the object’s own range only if a top-level object.
GetParent	Returns a pointer to the parent object.
GetParentContainer	Returns the top-level container of this object.
GetPosition	Returns the object position in pixels.
GetProperties	Returns the object’s properties.
GetPropertiesMenuLabel	Returns the label to be used for the properties context menu item.
GetRange	Returns the object’s range.
GetRangeSize	Returns the object size for the given range.
GetRect	Returns the rectangle enclosing the object.
GetRightMargin	Returns the right margin of the object, in pixels.
GetSelection	Returns a selection object specifying the selections between start and end character positions.
GetTextForRange	Returns any text in this object for the given range.
GetTopMargin	Returns the top margin of the object, in pixels.
GetTotalMargin	Returns the total margin for the object in pixels, taking into account margin, padding and border size.
GetXMLNodeName	Returns the XML node name of this object.
HandlesChildSelections	Returns True if this object can handle the selections of its children, fOr example a table.
HitTest	Hit-testing: returns a flag indicating hit test details, plus information about position.
ImportFromXML	Imports this object from XML.
Invalidate	Invalidates the object at the given range.
IsAtomic	Returns True if no user editing can be done inside the object.
IsComposite	Returns True if this object is composite.
IsEmpty	Returns True if the object is empty.
IsFloatable	Returns True if this class of object is floatable.
IsFloating	Returns True if this object is currently floating.
IsShown	Returns True if the object will be shown, False otherwise.
IsTopLevel	Returns True if this object is top-level, i.e. contains its own paragraphs, such as a text box.
Layout	Lay the item out at the specified position with the given size constraint.
LayoutToBestSize	Lays out the object first with a given amount of space, and then if no width was specified in attr, lays out the object again using the minimum size.
Merge	Returns True if this object merged itself with the given one.
Move	Moves the object recursively, by adding the offset from old to new.
Reference	Reference-counting allows us to use the same object in multiple lists (not yet used).
SetAttributes	Sets the object’s attributes.
SetCachedSize	Sets the cached object size as calculated by Layout.
SetDescent	Sets the stored descent value.
SetMargins	Set the margin around the object, in pixels.
SetMaxSize	Sets the maximum object size as calculated by Layout.
SetMinSize	Sets the minimum object size as calculated by Layout.
SetName	Sets the identifying name for this object as a property using the “name” key.
SetOwnRange	Set the object’s own range, for a top-level object with its own position space.
SetParent	Sets the pointer to the parent object.
SetPosition	Sets the object position in pixels.
SetProperties	Sets the object’s properties.
SetRange	Sets the object’s range within its container.
Show	Call to show or hide this object.
Split	Returns the final object in the split objects if this object was split due to differences between sub-object virtual attributes.
UsesParagraphAttributes	Returns True if this object takes note of paragraph attributes (text and image objects don’t).

Properties Summary

AbsolutePosition	See GetAbsolutePosition
Attributes	See GetAttributes and SetAttributes
BestSize	See GetBestSize
BottomMargin	See GetBottomMargin
Buffer	See GetBuffer
CachedSize	See GetCachedSize and SetCachedSize
Container	See GetContainer
Descent	See GetDescent and SetDescent
FloatDirection	See GetFloatDirection
LeftMargin	See GetLeftMargin
MaxSize	See GetMaxSize and SetMaxSize
MinSize	See GetMinSize and SetMinSize
Name	See GetName and SetName
NaturalSize	See GetNaturalSize
OwnRange	See GetOwnRange and SetOwnRange
OwnRangeIfTopLevel	See GetOwnRangeIfTopLevel
Parent	See GetParent and SetParent
ParentContainer	See GetParentContainer
Position	See GetPosition and SetPosition
Properties	See GetProperties and SetProperties
PropertiesMenuLabel	See GetPropertiesMenuLabel
Range	See GetRange and SetRange
Rect	See GetRect
RightMargin	See GetRightMargin
TopMargin	See GetTopMargin
XMLNodeName	See GetXMLNodeName

Class API

---

class wx.richtext.RichTextObject(Object)

Possible constructors:

RichTextObject(parent=None)

This is the base for drawable rich text objects.

Methods

---

__init__(self, parent=None)

Constructor, taking an optional parent pointer.

Parameters:parent (wx.richtext.RichTextObject) –

---

AcceptsFocus(self)

Returns True if objects of this class can accept the focus, i.e. a call to SetFocusObject is possible.

For example, containers supporting text, such as a text box object, can accept the focus, but a table can’t (set the focus to individual cells instead).

Return type:bool

---

AdjustAttributes(self, attr, context)

Adjusts the attributes for virtual attribute provision, collapsed borders, etc.

Parameters:

• attr (wx.richtext.RichTextAttr) –
• context (wx.richtext.RichTextDrawingContext) –

Return type:

bool

---

static AdjustAvailableSpace(dc, buffer, parentAttr, childAttr, availableParentSpace, availableContainerSpace)

Returns the rectangle which the child has available to it given restrictions specified in the child attribute, e.g.

50% width of the parent, 400 pixels, x position 20% of the parent, etc. availableContainerSpace might be a parent that the cell has to compute its width relative to. E.g. a cell that’s 50% of its parent.

Parameters:

• dc (wx.DC) –
• buffer (wx.richtext.RichTextBuffer) –
• parentAttr (wx.richtext.RichTextAttr) –
• childAttr (wx.richtext.RichTextAttr) –
• availableParentSpace (wx.Rect) –
• availableContainerSpace (wx.Rect) –

Return type:

Rect

---

CalculateRange(self, start)

Calculates the range of the object.

By default, guess that the object is 1 unit long.

Parameters:start (long) – Return type:end

---

CanEditProperties(self)

Returns True if we can edit the object’s properties via a GUI.

Return type:bool

---

CanMerge(self, object, context)

Returns True if this object can merge itself with the given one.

Parameters:

• object (wx.richtext.RichTextObject) –
• context (wx.richtext.RichTextDrawingContext) –

Return type:

bool

---

CanSplit(self, context)

Returns True if this object can potentially be split, by virtue of having different virtual attributes for individual sub-objects.

Parameters:context (wx.richtext.RichTextDrawingContext) – Return type:bool

---

Clone(self)

Clones the object.

Return type: wx.richtext.RichTextObject

---

ConvertPixelsToTenthsMM(self, *args, **kw)

Convert units in pixels to tenths of a millimetre.

Overloaded Implementations:

---

ConvertPixelsToTenthsMM (self, dc, pixels)

Parameters:

• dc (wx.DC) –
• pixels (int) –

Return type:

int

---

ConvertPixelsToTenthsMM (ppi, pixels, scale=1.0)

Parameters:

• ppi (int) –
• pixels (int) –
• scale (float) –

Return type:

int

---

---

ConvertTenthsMMToPixels(self, *args, **kw)

Converts units in tenths of a millimetre to device units.

Overloaded Implementations:

---

ConvertTenthsMMToPixels (self, dc, units)

Parameters:

• dc (wx.DC) –
• units (int) –

Return type:

int

---

ConvertTenthsMMToPixels (ppi, units, scale=1.0)

Parameters:

• ppi (int) –
• units (int) –
• scale (float) –

Return type:

int

---

---

Copy(self, obj)

Copies the object.

Parameters:obj (wx.richtext.RichTextObject) –

---

DeleteRange(self, range)

Deletes the given range.

Parameters:range (wx.richtext.RichTextRange) – Return type:bool

---

Dereference(self)

Reference-counting allows us to use the same object in multiple lists (not yet used).

---

DoSplit(self, pos)

Do a split from pos, returning an object containing the second part, and setting the first part in ‘this’.

Parameters:pos (long) – Return type: wx.richtext.RichTextObject

---

Draw(self, dc, context, range, selection, rect, descent, style)

Draw the item, within the given range.

Some objects may ignore the range (for example paragraphs) while others must obey it (lines, to implement wrapping)

Parameters:

• dc (wx.DC) –
• context (wx.richtext.RichTextDrawingContext) –
• range (wx.richtext.RichTextRange) –
• selection (wx.richtext.RichTextSelection) –
• rect (wx.Rect) –
• descent (int) –
• style (int) –

Return type:

bool

---

static DrawBorder(dc, buffer, attr, rect, flags=0)

Draws a border.

Parameters:

• dc (wx.DC) –
• buffer (wx.richtext.RichTextBuffer) –
• attr (wx.richtext.TextAttrBorders) –
• rect (wx.Rect) –
• flags (int) –

Return type:

bool

---

static DrawBoxAttributes(dc, buffer, attr, boxRect, flags=0, obj=None)

Draws the borders and background for the given rectangle and attributes.

boxRect is taken to be the outer margin box, not the box around the content.

Parameters:

• dc (wx.DC) –
• buffer (wx.richtext.RichTextBuffer) –
• attr (wx.richtext.RichTextAttr) –
• boxRect (wx.Rect) –
• flags (int) –
• obj (wx.richtext.RichTextObject) –

Return type:

bool

---

EditProperties(self, parent, buffer)

Edits the object’s properties via a GUI.

Parameters:

• parent (wx.Window) –
• buffer (wx.richtext.RichTextBuffer) –

Return type:

bool

---

FindPosition(self, dc, context, index, forceLineStart)

Finds the absolute position and row height for the given character position.

Parameters:

• dc (wx.DC) –
• context (wx.richtext.RichTextDrawingContext) –
• index (long) –
• forceLineStart (bool) –

Return type:

tuple

Returns:

( bool, pt, height )

---

GetAbsolutePosition(self)

Returns the absolute object position, by traversing up the child/parent hierarchy.

TODO: may not be needed, if all object positions are in fact relative to the top of the coordinate space.

Return type:Point

---

GetAttributes(self)

Returns the object’s attributes.

Return type: wx.richtext.RichTextAttr

---

GetAvailableContentArea(self, dc, context, outerRect)

Calculates the available content space in the given rectangle, given the margins, border and padding specified in the object’s attributes.

Parameters:

• dc (wx.DC) –
• context (wx.richtext.RichTextDrawingContext) –
• outerRect (wx.Rect) –

Return type:

Rect

---

GetBestSize(self)

Returns the best size, i.e. the ideal starting size for this object irrespective of available space.

For a short text string, it will be the size that exactly encloses the text. For a longer string, it might use the parent width for example.

Return type:Size

---

GetBottomMargin(self)

Returns the bottom margin of the object, in pixels.

Return type:int

---

static GetBoxRects(dc, buffer, attr)

Returns the various rectangles of the box model in pixels.

You can either specify contentRect (inner) or marginRect (outer), and the other must be the default rectangle (no width or height). Note that the outline doesn’t affect the position of the rectangle, it’s drawn in whatever space is available.

Parameters:

• dc (wx.DC) –
• buffer (wx.richtext.RichTextBuffer) –
• attr (wx.richtext.RichTextAttr) –

Return type:

tuple

Returns:

( bool, marginRect, borderRect, contentRect, paddingRect, outlineRect )

---

GetBuffer(self)

Returns the containing buffer.

Return type: wx.richtext.RichTextBuffer

---

GetCachedSize(self)

Gets the cached object size as calculated by Layout.

Return type:Size

---

GetContainer(self)

Returns the top-level container of this object.

May return itself if it’s a container; use GetParentContainer to return a different container.

Return type: wx.richtext.RichTextParagraphLayoutBox

---

GetDescent(self)

Returns the stored descent value.

Return type:int

---

GetFloatDirection(self)

Returns the floating direction.

Return type:int

---

GetLeftMargin(self)

Returns the left margin of the object, in pixels.

Return type:int

---

GetMaxSize(self)

Gets the maximum object size as calculated by Layout.

This allows us to fit an object to its contents or allocate extra space if required.

Return type:Size

---

GetMinSize(self)

Gets the minimum object size as calculated by Layout.

This allows us to constrain an object to its absolute minimum size if necessary.

Return type:Size

---

GetName(self)

Returns the identifying name for this object from the properties, using the “name” key.

Return type:string

---

GetNaturalSize(self)

Gets the ‘natural’ size for an object.

For an image, it would be the image size.

Return type: wx.richtext.TextAttrSize

---

GetOwnRange(self)

Returns the object’s own range (valid if top-level).

Return type: wx.richtext.RichTextRange

---

GetOwnRangeIfTopLevel(self)

Returns the object’s own range only if a top-level object.

Return type: wx.richtext.RichTextRange

---

GetParent(self)

Returns a pointer to the parent object.

Return type: wx.richtext.RichTextObject

---

GetParentContainer(self)

Returns the top-level container of this object.

Returns a different container than itself, unless there’s no parent, in which case it will return None.

Return type: wx.richtext.RichTextParagraphLayoutBox

---

GetPosition(self)

Returns the object position in pixels.

Return type:Point

---

GetProperties(self)

Returns the object’s properties.

Return type: wx.richtext.RichTextProperties

---

GetPropertiesMenuLabel(self)

Returns the label to be used for the properties context menu item.

Return type:string

---

GetRange(self)

Returns the object’s range.

Return type: wx.richtext.RichTextRange

---

GetRangeSize(self, range, size, descent, dc, context, flags, position=Point(0, 0), parentSize=DefaultSize, partialExtents=None)

Returns the object size for the given range.

Returns False if the range is invalid for this object.

Parameters:

• range (wx.richtext.RichTextRange) –
• size (wx.Size) –
• descent (int) –
• dc (wx.DC) –
• context (wx.richtext.RichTextDrawingContext) –
• flags (int) –
• position (wx.Point) –
• parentSize (wx.Size) –
• partialExtents (list of integers) –

Return type:

bool

---

GetRect(self)

Returns the rectangle enclosing the object.

Return type:Rect

---

GetRightMargin(self)

Returns the right margin of the object, in pixels.

Return type:int

---

GetSelection(self, start, end)

Returns a selection object specifying the selections between start and end character positions.

For example, a table would deduce what cells (of range length 1) are selected when dragging across the table.

Parameters:

• start (long) –
• end (long) –

Return type:

wx.richtext.RichTextSelection

---

GetTextForRange(self, range)

Returns any text in this object for the given range.

Parameters:range (wx.richtext.RichTextRange) – Return type:string

---

GetTopMargin(self)

Returns the top margin of the object, in pixels.

Return type:int

---

static GetTotalMargin(dc, buffer, attr)

Returns the total margin for the object in pixels, taking into account margin, padding and border size.

Parameters:

• dc (wx.DC) –
• buffer (wx.richtext.RichTextBuffer) –
• attr (wx.richtext.RichTextAttr) –

Return type:

tuple

Returns:

( bool, leftMargin, rightMargin, topMargin, bottomMargin )

---

GetXMLNodeName(self)

Returns the XML node name of this object.

This must be overridden for XmlNode-base XML export to work.

Return type:string

---

HandlesChildSelections(self)

Returns True if this object can handle the selections of its children, fOr example a table.

Required for composite selection handling to work.

Return type:bool

---

HitTest(self, dc, context, pt, flags=0)

Hit-testing: returns a flag indicating hit test details, plus information about position.

contextObj is returned to specify what object position is relevant to, since otherwise there’s an ambiguity. @ obj might not be a child of contextObj, since we may be referring to the container itself if we have no hit on a child - for example if we click outside an object.

The function puts the position in textPosition if one is found. pt is in logical units (a zero y position is at the beginning of the buffer).

Parameters:

• dc (wx.DC) –
• context (wx.richtext.RichTextDrawingContext) –
• pt (wx.Point) –
• flags (int) –

Return type:

tuple

Returns:

( int, textPosition, obj, contextObj )

---

ImportFromXML(self, buffer, node, handler, recurse)

Imports this object from XML.

Parameters:

• buffer (wx.richtext.RichTextBuffer) –
• node (wx.xml.XmlNode) –
• handler (wx.richtext.RichTextXMLHandler) –
• recurse (bool) –

Return type:

bool

---

Invalidate(self, invalidRange=RICHTEXT_ALL)

Invalidates the object at the given range.

With no argument, invalidates the whole object.

Parameters:invalidRange (wx.richtext.RichTextRange) –

---

IsAtomic(self)

Returns True if no user editing can be done inside the object.

This returns True for simple objects, False for most composite objects, but True for fields, which if composite, should not be user-edited.

Return type:bool

---

IsComposite(self)

Returns True if this object is composite.

Return type:bool

---

IsEmpty(self)

Returns True if the object is empty.

Return type:bool

---

IsFloatable(self)

Returns True if this class of object is floatable.

Return type:bool

---

IsFloating(self)

Returns True if this object is currently floating.

Return type:bool

---

IsShown(self)

Returns True if the object will be shown, False otherwise.

Return type:bool

---

IsTopLevel(self)

Returns True if this object is top-level, i.e. contains its own paragraphs, such as a text box.

Return type:bool

---

Layout(self, dc, context, rect, parentRect, style)

Lay the item out at the specified position with the given size constraint.

Layout must set the cached size. rect is the available space for the object, and parentRect is the container that is used to determine a relative size or position (for example if a text box must be 50% of the parent text box).

Parameters:

• dc (wx.DC) –
• context (wx.richtext.RichTextDrawingContext) –
• rect (wx.Rect) –
• parentRect (wx.Rect) –
• style (int) –

Return type:

bool

---

LayoutToBestSize(self, dc, context, buffer, parentAttr, attr, availableParentSpace, availableContainerSpace, style)

Lays out the object first with a given amount of space, and then if no width was specified in attr, lays out the object again using the minimum size.

availableParentSpace is the maximum space for the object, whereas availableContainerSpace is the container with which relative positions and sizes should be computed. For example, a text box whose space has already been constrained in a previous layout pass to availableParentSpace, but should have a width of 50% of availableContainerSpace. (If these two rects were the same, a 2nd pass could see the object getting too small.)

Parameters:

• dc (wx.DC) –
• context (wx.richtext.RichTextDrawingContext) –
• buffer (wx.richtext.RichTextBuffer) –
• parentAttr (wx.richtext.RichTextAttr) –
• attr (wx.richtext.RichTextAttr) –
• availableParentSpace (wx.Rect) –
• availableContainerSpace (wx.Rect) –
• style (int) –

Return type:

bool

---

Merge(self, object, context)

Returns True if this object merged itself with the given one.

The calling code will then delete the given object.

Parameters:

• object (wx.richtext.RichTextObject) –
• context (wx.richtext.RichTextDrawingContext) –

Return type:

bool

---

Move(self, pt)

Moves the object recursively, by adding the offset from old to new.

Parameters:pt (wx.Point) –

---

Reference(self)

Reference-counting allows us to use the same object in multiple lists (not yet used).

---

SetAttributes(self, attr)

Sets the object’s attributes.

Parameters:attr (wx.richtext.RichTextAttr) –

---

SetCachedSize(self, sz)

Sets the cached object size as calculated by Layout.

Parameters:sz (wx.Size) –

---

SetDescent(self, descent)

Sets the stored descent value.

Parameters:descent (int) –

---

SetMargins(self, *args, **kw)

Set the margin around the object, in pixels.

Overloaded Implementations:

---

SetMargins (self, margin)

Parameters:margin (int) –

---

SetMargins (self, leftMargin, rightMargin, topMargin, bottomMargin)

Parameters:

• leftMargin (int) –
• rightMargin (int) –
• topMargin (int) –
• bottomMargin (int) –

---

---

SetMaxSize(self, sz)

Sets the maximum object size as calculated by Layout.

This allows us to fit an object to its contents or allocate extra space if required.

Parameters:sz (wx.Size) –

---

SetMinSize(self, sz)

Sets the minimum object size as calculated by Layout.

This allows us to constrain an object to its absolute minimum size if necessary.

Parameters:sz (wx.Size) –

---

SetName(self, name)

Sets the identifying name for this object as a property using the “name” key.

Parameters:name (string) –

---

SetOwnRange(self, range)

Set the object’s own range, for a top-level object with its own position space.

Parameters:range (wx.richtext.RichTextRange) –

---

SetParent(self, parent)

Sets the pointer to the parent object.

Parameters:parent (wx.richtext.RichTextObject) –

---

SetPosition(self, pos)

Sets the object position in pixels.

Parameters:pos (wx.Point) –

---

SetProperties(self, props)

Sets the object’s properties.

Parameters:props (wx.richtext.RichTextProperties) –

---

SetRange(self, range)

Sets the object’s range within its container.

Parameters:range (wx.richtext.RichTextRange) –

---

Show(self, show)

Call to show or hide this object.

This function does not cause the content to be laid out or redrawn.

Parameters:show (bool) –

---

Split(self, context)

Returns the final object in the split objects if this object was split due to differences between sub-object virtual attributes.

Returns itself if it was not split.

Parameters:context (wx.richtext.RichTextDrawingContext) – Return type: wx.richtext.RichTextObject

---

UsesParagraphAttributes(self)

Returns True if this object takes note of paragraph attributes (text and image objects don’t).

Return type:bool

Properties

---

AbsolutePosition

See GetAbsolutePosition

---

Attributes

See GetAttributes and SetAttributes

---

BestSize

See GetBestSize

---

BottomMargin

See GetBottomMargin

---

Buffer

See GetBuffer

---

CachedSize

See GetCachedSize and SetCachedSize

---

Container

See GetContainer

---

Descent

See GetDescent and SetDescent

---

FloatDirection

See GetFloatDirection

---

LeftMargin

See GetLeftMargin

---

MaxSize

See GetMaxSize and SetMaxSize

---

MinSize

See GetMinSize and SetMinSize

---

Name

See GetName and SetName

---

NaturalSize

See GetNaturalSize

---

OwnRange

See GetOwnRange and SetOwnRange

---

OwnRangeIfTopLevel

See GetOwnRangeIfTopLevel

---

Parent

See GetParent and SetParent

---

ParentContainer

See GetParentContainer

---

Position

See GetPosition and SetPosition

---

Properties

See GetProperties and SetProperties

---

PropertiesMenuLabel

See GetPropertiesMenuLabel

---

Range

See GetRange and SetRange

---

Rect

See GetRect

---

RightMargin

See GetRightMargin

---

TopMargin

See GetTopMargin

---

XMLNodeName

See GetXMLNodeName