.. wxPython Phoenix documentation

   This file was generated by Phoenix's sphinx generator and associated
   tools, do not edit by hand.

   Copyright: (c) 2011-2020 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.svg" 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="63,313,269,341"/> <area shape="rect" id="node2" href="wx.richtext.RichTextParagraphLayoutBox.html" title="This class knows how to lay out paragraphs." alt="" coords="5,236,326,265"/> <area shape="rect" id="node3" href="wx.richtext.RichTextCompositeObject.html" title="Objects of this class can contain other objects." alt="" coords="19,159,312,188"/> <area shape="rect" id="node4" href="wx.richtext.RichTextObject.html" title="This is the base for drawable rich text objects." alt="" coords="58,82,274,111"/> <area shape="rect" id="node5" href="wx.Object.html" title="This is the root class of many of the wxWidgets classes." alt="" coords="116,5,215,34"/> </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: str='', parent: Optional[RichTextObject]=None)
                     -> None
       
       RichTextField(obj : RichTextField) -> None
       
   
   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: str='', parent: Optional[RichTextObject]=None)`
      
      Default constructor; optionally pass the parent object. 
                       
      
      
      :param `fieldType`: 
      :type `fieldType`: string
      :param `parent`: 
      :type `parent`: wx.richtext.RichTextObject
      
      
      
      
      :rtype: `None`     
      
      
      
      
      
      
      
      :html:`<hr class="overloadsep" /><br />`

      
      **__init__** `(self, obj : RichTextField)`
      
      Copy constructor. 
                       
      
      
      :param `obj`: 
      :type `obj`: wx.richtext.RichTextField
      
      
      
      
      :rtype: `None`     
      
      
      
      
      
      
      
      :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 : int)

      Calculates the range of the object. 
                 

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


      :param `start`: 
      :type `start`: long




      :rtype: `int`








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




      :param `obj`: 
      :type `obj`: wx.richtext.RichTextField




      :rtype: `None`     








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


      :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 : Window, buffer : RichTextBuffer)

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








   .. method:: GetPropertiesMenuLabel(self)

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

      :rtype: `str`








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








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


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




      :param `fieldType`: 
      :type `fieldType`: string




      :rtype: `None`     








   .. method:: UpdateField(self, buffer : RichTextBuffer)

      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`