wx.richtext.RichTextObject¶

This is the base for drawable rich text objects.

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: Optional[RichTextObject]=None) -> None

This is the base for drawable rich text objects.

Methods¶

__init__(self, parent: RichTextObject | None = None)¶

Constructor, taking an optional parent pointer.

Parameters:: parent (wx.richtext.RichTextObject)
Return type:: None

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: RichTextAttr, context: RichTextDrawingContext)¶

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: DC, buffer: RichTextBuffer, parentAttr: RichTextAttr, childAttr: RichTextAttr, availableParentSpace: Rect, availableContainerSpace: Rect)¶

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: int)¶

Calculates the range of the object.

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

Parameters:: start (long)
Return type:: int

CanEditProperties(self)¶

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

Return type:: bool

CanMerge(self, object: RichTextObject, context: RichTextDrawingContext)¶

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: RichTextDrawingContext)¶

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 : DC, pixels : int)

Parameters:

dc (wx.DC)
pixels (int)

Return type:

int

ConvertPixelsToTenthsMM (ppi : int, pixels : int, scale: float=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 : DC, units : int)

Parameters:

dc (wx.DC)
units (int)

Return type:

int

ConvertTenthsMMToPixels (ppi : int, units : int, scale: float=1.0)

Parameters:

ppi (int)
units (int)
scale (float)

Return type:

int

Copy(self, obj: RichTextObject)¶

Copies the object.

Parameters:: obj (wx.richtext.RichTextObject)
Return type:: None

DeleteRange(self, range: RichTextRange)¶

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

Return type:: None

DoSplit(self, pos: int)¶

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: DC, context: RichTextDrawingContext, range: RichTextRange, selection: RichTextSelection, rect: Rect, descent: int, style: int)¶

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: DC, buffer: RichTextBuffer, attr: RichTextAttr, borders: TextAttrBorders, rect: Rect, flags: int = 0)¶

Draws a border.

Parameters:

dc (wx.DC)
buffer (wx.richtext.RichTextBuffer)
attr (wx.richtext.RichTextAttr)
borders (wx.richtext.TextAttrBorders)
rect (wx.Rect)
flags (int)

Return type:

bool

static DrawBoxAttributes(dc: DC, buffer: RichTextBuffer, attr: RichTextAttr, boxRect: Rect, flags: int = 0, obj: RichTextObject | None = 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: Window, buffer: RichTextBuffer)¶

Edits the object’s properties via a GUI.

Parameters:

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

Return type:

bool

FindPosition(self, dc: DC, context: RichTextDrawingContext, index: int, forceLineStart: bool)¶

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:

le[bool, wx.Point, int]

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: DC, context: RichTextDrawingContext, outerRect: Rect)¶

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: DC, buffer: RichTextBuffer, attr: RichTextAttr)¶

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:

le[bool, wx.Rect, wx.Rect, wx.Rect, wx.Rect, wx.Rect]

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:: str

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:: str

GetRange(self)¶

Returns the object’s range.

Return type:: wx.richtext.RichTextRange

GetRangeSize(self, range: RichTextRange, size: Size, descent: int, dc: DC, context: RichTextDrawingContext, flags: int, position: Point = Point(0, 0), parentSize: Size = DefaultSize, partialExtents: List[int] | None = 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: int, end: int)¶

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: RichTextRange)¶

Returns any text in this object for the given range.

Parameters:: range (wx.richtext.RichTextRange)
Return type:: str

GetTopMargin(self)¶

Returns the top margin of the object, in pixels.

Return type:: int

static GetTotalMargin(dc: DC, buffer: RichTextBuffer, attr: RichTextAttr)¶

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[bool, int, int, int, int]

GetXMLNodeName(self)¶

Returns the XML node name of this object.

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

Return type:: str

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: DC, context: RichTextDrawingContext, pt: Point, flags: int = 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[int, int, RichTextObject, RichTextObject]

Returns:

One of the wx.richtext.RichTextHitTestFlags values.

ImportFromXML(self, buffer: RichTextBuffer, node: XmlNode, handler: RichTextXMLHandler, recurse: bool)¶

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: RichTextRange = RICHTEXT_ALL)¶

Invalidates the object at the given range.

With no argument, invalidates the whole object.

Parameters:: invalidRange (wx.richtext.RichTextRange)
Return type:: None

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: DC, context: RichTextDrawingContext, rect: Rect, parentRect: Rect, style: int)¶

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: DC, context: RichTextDrawingContext, buffer: RichTextBuffer, parentAttr: RichTextAttr, attr: RichTextAttr, availableParentSpace: Rect, availableContainerSpace: Rect, style: int)¶

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: