wx.richtext.RichTextField

This class implements the general concept of a field, an object that represents additional functionality such as a footnote, a bookmark, a page number, a table of contents, and so on.

Extra information (such as a bookmark name) can be stored in the object properties.

Drawing, layout, and property editing is delegated to classes derived from wx.richtext.RichTextFieldType, such as instances of wx.richtext.RichTextFieldTypeStandard; this makes the use of fields an efficient method of introducing extra functionality, since most of the information required to draw a field (such as a bitmap) is kept centrally in a single field type definition.

The FieldType property, accessed by SetFieldType/GetFieldType, is used to retrieve the field type definition. So be careful not to overwrite this property.

wx.richtext.RichTextField is derived from wx.richtext.RichTextParagraphLayoutBox, which means that it can contain its own read-only content, refreshed when the application calls the UpdateField function. Whether a field is treated as a composite or a single graphic is determined by the field type definition. If using wx.richtext.RichTextFieldTypeStandard, passing the display type RICHTEXT_FIELD_STYLE_COMPOSITE to the field type definition causes the field to behave like a composite; the other display styles display a simple graphic. When implementing a composite field, you will still need to derive from wx.richtext.RichTextFieldTypeStandard or wx.richtext.RichTextFieldType, if only to implement UpdateField to refresh the field content appropriately. wx.richtext.RichTextFieldTypeStandard is only one possible implementation, but covers common needs especially for simple, static fields using text or a bitmap.

Register field types on application initialisation with the static function wx.richtext.RichTextBuffer.AddFieldType . They will be deleted automatically on application exit.

An application can write a field to a control with wx.richtext.RichTextCtrl.WriteField , taking a field type, the properties for the field, and optional attributes.

See also

wx.richtext.RichTextFieldTypeStandard, wx.richtext.RichTextFieldType, wx.richtext.RichTextParagraphLayoutBox, wx.richtext.RichTextProperties, wx.richtext.RichTextCtrl

Class Hierarchy

Inheritance diagram for class RichTextField:

Methods Summary

__init__	Default constructor; optionally pass the parent object.
AcceptsFocus	Returns True if objects of this class can accept the focus, i.e. a call to SetFocusObject is possible.
CalculateRange	Calculates the range of the object.
CanEditProperties	Returns True if we can edit the object’s properties via a GUI.
Clone	Clones the object.
Copy
Draw	Draw the item, within the given range.
EditProperties	Edits the object’s properties via a GUI.
GetFieldType
GetPropertiesMenuLabel	Returns the label to be used for the properties context menu item.
GetRangeSize	Returns the object size for the given range.
GetXMLNodeName	Returns the XML node name of this object.
IsAtomic	If a field has children, we don’t want the user to be able to edit it.
IsEmpty	Returns True if the buffer is empty.
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.
SetFieldType
UpdateField	Update the field; delegated to the associated field type.

Properties Summary

FieldType	See GetFieldType and SetFieldType
PropertiesMenuLabel	See GetPropertiesMenuLabel
XMLNodeName	See GetXMLNodeName

Class API

class wx.richtext.RichTextField(RichTextParagraphLayoutBox)

Possible constructors:

RichTextField(fieldType="", parent=None)

RichTextField(obj)

This class implements the general concept of a field, an object that represents additional functionality such as a footnote, a bookmark, a page number, a table of contents, and so on.

Methods

__init__(self, *args, **kw)

Overloaded Implementations:

---

__init__ (self, fieldType=””, parent=None)

Default constructor; optionally pass the parent object.

Parameters:

• fieldType (string) –

• parent (wx.richtext.RichTextObject) –

---

__init__ (self, obj)

Copy constructor.

Parameters:

obj (wx.richtext.RichTextField) –

---

---

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

---

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

---

Clone(self)

Clones the object.

Return type:

wx.richtext.RichTextObject

---

Copy(self, obj)

Parameters:

obj (wx.richtext.RichTextField) –

---

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

---

EditProperties(self, parent, buffer)

Edits the object’s properties via a GUI.

Parameters:

• parent (wx.Window) –

• buffer (wx.richtext.RichTextBuffer) –

Return type:

bool

---

GetFieldType(self)

Return type:

string

---

GetPropertiesMenuLabel(self)

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

Return type:

string

---

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

---

GetXMLNodeName(self)

Returns the XML node name of this object.

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

Return type:

string

---

IsAtomic(self)

If a field has children, we don’t want the user to be able to edit it.

Return type:

bool

---

IsEmpty(self)

Returns True if the buffer is empty.

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

---

SetFieldType(self, fieldType)

Parameters:

fieldType (string) –

---

UpdateField(self, buffer)

Update the field; delegated to the associated field type.

This would typically expand the field to its value, if this is a dynamically changing and/or composite field.

Parameters:

buffer (wx.richtext.RichTextBuffer) –

Return type:

bool

Properties

FieldType

See GetFieldType and SetFieldType

---

PropertiesMenuLabel

See GetPropertiesMenuLabel

---

XMLNodeName

See GetXMLNodeName