.. wxPython Phoenix documentation
This file was generated by Phoenix's sphinx generator and associated
tools, do not edit by hand.
Copyright: (c) 2011-2018 by Total Control Software
License: wxWindows License
.. include:: headings.inc
.. _wx.richtext.RichTextField:
==========================================================================================================================================
|phoenix_title| **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 :ref:`wx.richtext.RichTextFieldType`, such as instances of :ref:`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.
:ref:`wx.richtext.RichTextField` is derived from :ref:`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 :ref:`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 :ref:`wx.richtext.RichTextFieldTypeStandard` or :ref:`wx.richtext.RichTextFieldType`, if only to implement UpdateField to refresh the field content appropriately. :ref:`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 :meth:`wx.richtext.RichTextBuffer.AddFieldType` . They will be deleted automatically on application exit.
An application can write a field to a control with :meth:`wx.richtext.RichTextCtrl.WriteField` , taking a field type, the properties for the field, and optional attributes.
.. seealso:: :ref:`wx.richtext.RichTextFieldTypeStandard`, :ref:`wx.richtext.RichTextFieldType`, :ref:`wx.richtext.RichTextParagraphLayoutBox`, :ref:`wx.richtext.RichTextProperties`, :ref:`wx.richtext.RichTextCtrl`
|
|class_hierarchy| Class Hierarchy
=================================
.. raw:: html
<div id="toggleBlock" onclick="return toggleVisibility(this)" class="closed" style="cursor:pointer;">
<img id="toggleBlock-trigger" src="_static/images/closed.png"/>
Inheritance diagram for class <strong>RichTextField</strong>:
</div>
<div id="toggleBlock-summary" style="display:block;"></div>
<div id="toggleBlock-content" style="display:none;">
<p class="graphviz">
<center><img src="_static/images/inheritance/wx.richtext.RichTextField_inheritance.png" alt="Inheritance diagram of RichTextField" usemap="#dummy" class="inheritance"/></center>
<script type="text/javascript">toggleVisibilityOnLoad(document.getElementById('toggleBlock'))</script>
<map id="dummy" name="dummy"> <area shape="rect" id="node1" href="wx.richtext.RichTextField.html" title="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." alt="" coords="59,315,250,344"/> <area shape="rect" id="node2" href="wx.richtext.RichTextParagraphLayoutBox.html" title="This class knows how to lay out paragraphs." alt="" coords="5,237,304,267"/> <area shape="rect" id="node3" href="wx.richtext.RichTextCompositeObject.html" title="Objects of this class can contain other objects." alt="" coords="18,160,291,189"/> <area shape="rect" id="node4" href="wx.richtext.RichTextObject.html" title="This is the base for drawable rich text objects." alt="" coords="53,83,256,112"/> <area shape="rect" id="node5" href="wx.Object.html" title="This is the root class of many of the wxWidgets classes." alt="" coords="111,5,199,35"/> </map>
</p>
</div>
|
|method_summary| Methods Summary
================================
================================================================================ ================================================================================
:meth:`~wx.richtext.RichTextField.__init__` Default constructor; optionally pass the parent object.
:meth:`~wx.richtext.RichTextField.AcceptsFocus` Returns ``True`` if objects of this class can accept the focus, i.e. a call to SetFocusObject is possible.
:meth:`~wx.richtext.RichTextField.CalculateRange` Calculates the range of the object.
:meth:`~wx.richtext.RichTextField.CanEditProperties` Returns ``True`` if we can edit the object's properties via a GUI.
:meth:`~wx.richtext.RichTextField.Clone` Clones the object.
:meth:`~wx.richtext.RichTextField.Copy`
:meth:`~wx.richtext.RichTextField.Draw` Draw the item, within the given range.
:meth:`~wx.richtext.RichTextField.EditProperties` Edits the object's properties via a GUI.
:meth:`~wx.richtext.RichTextField.GetFieldType`
:meth:`~wx.richtext.RichTextField.GetPropertiesMenuLabel` Returns the label to be used for the properties context menu item.
:meth:`~wx.richtext.RichTextField.GetRangeSize` Returns the object size for the given range.
:meth:`~wx.richtext.RichTextField.GetXMLNodeName` Returns the ``XML`` node name of this object.
:meth:`~wx.richtext.RichTextField.IsAtomic` If a field has children, we don't want the user to be able to edit it.
:meth:`~wx.richtext.RichTextField.IsEmpty` Returns ``True`` if the buffer is empty.
:meth:`~wx.richtext.RichTextField.IsTopLevel` Returns ``True`` if this object is top-level, i.e. contains its own paragraphs, such as a text box.
:meth:`~wx.richtext.RichTextField.Layout` Lay the item out at the specified position with the given size constraint.
:meth:`~wx.richtext.RichTextField.SetFieldType`
:meth:`~wx.richtext.RichTextField.UpdateField` Update the field; delegated to the associated field type.
================================================================================ ================================================================================
|
|property_summary| Properties Summary
=====================================
================================================================================ ================================================================================
:attr:`~wx.richtext.RichTextField.FieldType` See :meth:`~wx.richtext.RichTextField.GetFieldType` and :meth:`~wx.richtext.RichTextField.SetFieldType`
:attr:`~wx.richtext.RichTextField.PropertiesMenuLabel` See :meth:`~wx.richtext.RichTextField.GetPropertiesMenuLabel`
:attr:`~wx.richtext.RichTextField.XMLNodeName` See :meth:`~wx.richtext.RichTextField.GetXMLNodeName`
================================================================================ ================================================================================
|
|api| 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.
.. method:: __init__(self, *args, **kw)
|overload| Overloaded Implementations:
:html:`<hr class="overloadsep" /><br />`
**__init__** `(self, fieldType="", parent=None)`
Default constructor; optionally pass the parent object.
:param `fieldType`:
:type `fieldType`: string
:param `parent`:
:type `parent`: wx.richtext.RichTextObject
:html:`<hr class="overloadsep" /><br />`
**__init__** `(self, obj)`
Copy constructor.
:param `obj`:
:type `obj`: wx.richtext.RichTextField
:html:`<hr class="overloadsep" /><br />`
.. method:: 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).
:rtype: `bool`
.. method:: CalculateRange(self, start)
Calculates the range of the object.
By default, guess that the object is 1 unit long.
:param `start`:
:type `start`: long
:rtype: `end`
.. method:: CanEditProperties(self)
Returns ``True`` if we can edit the object's properties via a GUI.
:rtype: `bool`
.. method:: Clone(self)
Clones the object.
:rtype: :ref:`wx.richtext.RichTextObject`
.. method:: Copy(self, obj)
:param `obj`:
:type `obj`: wx.richtext.RichTextField
.. method:: 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)
:param `dc`:
:type `dc`: wx.DC
:param `context`:
:type `context`: wx.richtext.RichTextDrawingContext
:param `range`:
:type `range`: wx.richtext.RichTextRange
:param `selection`:
:type `selection`: wx.richtext.RichTextSelection
:param `rect`:
:type `rect`: wx.Rect
:param `descent`:
:type `descent`: int
:param `style`:
:type `style`: int
:rtype: `bool`
.. method:: EditProperties(self, parent, buffer)
Edits the object's properties via a GUI.
:param `parent`:
:type `parent`: wx.Window
:param `buffer`:
:type `buffer`: wx.richtext.RichTextBuffer
:rtype: `bool`
.. method:: GetFieldType(self)
:rtype: `string`
.. method:: GetPropertiesMenuLabel(self)
Returns the label to be used for the properties context menu item.
:rtype: `string`
.. method:: 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.
:param `range`:
:type `range`: wx.richtext.RichTextRange
:param `size`:
:type `size`: wx.Size
:param `descent`:
:type `descent`: int
:param `dc`:
:type `dc`: wx.DC
:param `context`:
:type `context`: wx.richtext.RichTextDrawingContext
:param `flags`:
:type `flags`: int
:param `position`:
:type `position`: wx.Point
:param `parentSize`:
:type `parentSize`: wx.Size
:param `partialExtents`:
:type `partialExtents`: list of integers
:rtype: `bool`
.. method:: GetXMLNodeName(self)
Returns the ``XML`` node name of this object.
This must be overridden for XmlNode-base ``XML`` export to work.
:rtype: `string`
.. method:: IsAtomic(self)
If a field has children, we don't want the user to be able to edit it.
:rtype: `bool`
.. method:: IsEmpty(self)
Returns ``True`` if the buffer is empty.
:rtype: `bool`
.. method:: IsTopLevel(self)
Returns ``True`` if this object is top-level, i.e. contains its own paragraphs, such as a text box.
:rtype: `bool`
.. method:: 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).
:param `dc`:
:type `dc`: wx.DC
:param `context`:
:type `context`: wx.richtext.RichTextDrawingContext
:param `rect`:
:type `rect`: wx.Rect
:param `parentRect`:
:type `parentRect`: wx.Rect
:param `style`:
:type `style`: int
:rtype: `bool`
.. method:: SetFieldType(self, fieldType)
:param `fieldType`:
:type `fieldType`: string
.. method:: 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.
:param `buffer`:
:type `buffer`: wx.richtext.RichTextBuffer
:rtype: `bool`
.. attribute:: FieldType
See :meth:`~wx.richtext.RichTextField.GetFieldType` and :meth:`~wx.richtext.RichTextField.SetFieldType`
.. attribute:: PropertiesMenuLabel
See :meth:`~wx.richtext.RichTextField.GetPropertiesMenuLabel`
.. attribute:: XMLNodeName
See :meth:`~wx.richtext.RichTextField.GetXMLNodeName`