.. wxPython Phoenix documentation

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

   Copyright: (c) 2011-2017 by Total Control Software
   License:   wxWindows License

.. include:: headings.inc



.. _wx.Region:

==========================================================================================================================================
|phoenix_title|  **wx.Region**
==========================================================================================================================================

A :ref:`wx.Region`  represents a simple or complex region on a device context or window.          

This class uses :ref:`reference counting and copy-on-write <reference counting>`  internally so that assignments between two instances of this class are very cheap. You can therefore use actual objects instead of pointers without efficiency problems. If an instance of this class is changed it will create its own data internally so that other instances, which previously shared the data using the reference counting, are not affected. 









         



.. seealso:: :ref:`wx.RegionIterator`    







|

|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>Region</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.Region_inheritance.png" alt="Inheritance diagram of Region" usemap="#dummy" class="inheritance"/></center>
   </div>
   <script type="text/javascript">toggleVisibilityOnLoad(document.getElementById('toggleBlock'))</script>
   <map id="dummy" name="dummy"> <area shape="rect" id="node1" href="wx.Object.html" title="wx.Object" alt="" coords="17,5,99,35"/> <area shape="rect" id="node3" href="wx.GDIObject.html" title="wx.GDIObject" alt="" coords="5,83,112,112"/> <area shape="rect" id="node2" href="wx.Region.html" title="wx.Region" alt="" coords="17,160,100,189"/> </map> 
   </p>

|


|method_summary| Methods Summary
================================

================================================================================ ================================================================================
:meth:`~wx.Region.__init__`                                                      Default constructor.
:meth:`~wx.Region.Clear`                                                         Clears the current region.
:meth:`~wx.Region.Contains`                                                      Returns a value indicating whether the given point is contained within the region.
:meth:`~wx.Region.ConvertToBitmap`                                               Convert the region to a black and white bitmap with the white pixels being inside the region.
:meth:`~wx.Region.GetBox`                                                        Returns the outer bounds of the region.
:meth:`~wx.Region.Intersect`                                                     Finds the intersection of this region and another, rectangular region, specified using position and size.
:meth:`~wx.Region.IsEmpty`                                                       Returns ``True`` if the region is empty, ``False`` otherwise.
:meth:`~wx.Region.IsEqual`                                                       Returns ``True`` if the region is equal to, i.e. covers the same area as, another one.
:meth:`~wx.Region.Offset`                                                        Moves the region by the specified offsets in horizontal and vertical directions.
:meth:`~wx.Region.Subtract`                                                      Subtracts a rectangular region from this region.
:meth:`~wx.Region.Union`                                                         Finds the union of this region and another, rectangular region, specified using position and size.
:meth:`~wx.Region.Xor`                                                           Finds the Xor of this region and another, rectangular region, specified using position and size.
:meth:`~wx.Region.__iter__`                                                      Returns a rectangle interator conforming to the Python iterator
================================================================================ ================================================================================


|


|property_summary| Properties Summary
=====================================

================================================================================ ================================================================================
:attr:`~wx.Region.Box`                                                           See :meth:`~wx.Region.GetBox`
================================================================================ ================================================================================


|


|api| Class API
===============


.. class:: wx.Region(GDIObject)

   **Possible constructors**::

       Region()
       
       Region(x, y, width, height)
       
       Region(topLeft, bottomRight)
       
       Region(rect)
       
       Region(region)
       
       Region(bmp)
       
       Region(bmp, transColour, tolerance=0)
       
       Region(points, fillStyle=ODDEVEN_RULE)
       
   
   A Region represents a simple or complex region on a device context
   or window.



   .. method:: __init__(self, *args, **kw)



      |overload| Overloaded Implementations:

      **~~~**

      
      **__init__** `(self)`
      
      Default constructor.                  
      
      This constructor creates an invalid, or null, object, i.e. calling IsOk() on it returns ``False`` and :meth:`IsEmpty`   returns ``True``.                   
      
      
      
      
      **~~~**

      
      **__init__** `(self, x, y, width, height)`
      
      Constructs a rectangular region with the given position and size.                  
      
      
      :param `x`: 
      :type `x`: int
      :param `y`: 
      :type `y`: int
      :param `width`: 
      :type `width`: int
      :param `height`: 
      :type `height`: int
      
      
      
      
      
      
      **~~~**

      
      **__init__** `(self, topLeft, bottomRight)`
      
      Constructs a rectangular region from the top left point and the bottom right point.                  
      
      
      :param `topLeft`: 
      :type `topLeft`: wx.Point
      :param `bottomRight`: 
      :type `bottomRight`: wx.Point
      
      
      
      
      
      
      **~~~**

      
      **__init__** `(self, rect)`
      
      Constructs a rectangular region a :ref:`wx.Rect`  object.                  
      
      
      :param `rect`: 
      :type `rect`: wx.Rect
      
      
      
      
      
      
      **~~~**

      
      **__init__** `(self, region)`
      
      Copy constructor, uses :ref:`Reference Counting <reference counting>`.                  
      
      
      :param `region`: 
      :type `region`: wx.Region
      
      
      
      
      
      
      **~~~**

      
      **__init__** `(self, bmp)`
      
      Constructs a region using a bitmap.                  
      
      See :meth:`Union`   for more details.                  
      
      
      :param `bmp`: 
      :type `bmp`: wx.Bitmap
      
      
      
      
      
      
      **~~~**

      
      **__init__** `(self, bmp, transColour, tolerance=0)`
      
      Constructs a region using the non-transparent pixels of a bitmap.                  
      
      See :meth:`Union`   for more details.                  
      
      
      :param `bmp`: 
      :type `bmp`: wx.Bitmap
      :param `transColour`: 
      :type `transColour`: wx.Colour
      :param `tolerance`: 
      :type `tolerance`: int
      
      
      
      
      
      
      **~~~**

      
      **__init__** `(self, points, fillStyle=ODDEVEN_RULE)`
      
                      Constructs a region corresponding to the polygon made from the points
                      in the provided sequence.  
      
      
      
      
      **~~~**






   .. method:: Clear(self)

      Clears the current region.                  

      The object becomes invalid, or null, after being cleared.                   





   .. method:: Contains(self, *args, **kw)



      |overload| Overloaded Implementations:

      **~~~**

      
      **Contains** `(self, x, y)`
      
      Returns a value indicating whether the given point is contained within the region.                  
      
      This method always returns  ``OutRegion``   for an invalid region but may, nevertheless, be safely called in this case. 
      
                      
      
      
      :param `x`: 
      :type `x`: int
      :param `y`: 
      :type `y`: int
      
      
      
      
      :rtype: :ref:`wx.RegionContain`
      
      
      
      
      
      
      
      :returns: 
      
         The return value is one of  ``OutRegion``   and   ``InRegion`` .    
      
      
      
      
      
      
      
      **~~~**

      
      **Contains** `(self, pt)`
      
      Returns a value indicating whether the given point is contained within the region.                  
      
      This method always returns  ``OutRegion``   for an invalid region but may, nevertheless, be safely called in this case. 
      
                      
      
      
      :param `pt`: 
      :type `pt`: wx.Point
      
      
      
      
      :rtype: :ref:`wx.RegionContain`
      
      
      
      
      
      
      
      :returns: 
      
         The return value is one of  ``OutRegion``   and   ``InRegion`` .    
      
      
      
      
      
      
      
      **~~~**

      
      **Contains** `(self, x, y, width, height)`
      
      Returns a value indicating whether the given rectangle is contained within the region.                  
      
      This method always returns  ``OutRegion``   for an invalid region but may, nevertheless, be safely called in this case. 
      
                      
      
      
      :param `x`: 
      :type `x`: int
      :param `y`: 
      :type `y`: int
      :param `width`: 
      :type `width`: int
      :param `height`: 
      :type `height`: int
      
      
      
      
      :rtype: :ref:`wx.RegionContain`
      
      
      
      
      
      
      
      :returns: 
      
         One of :ref:`wx.OutRegion`, :ref:`wx.PartRegion`  or :ref:`wx.InRegion`.  
      
      
      
      
      
      
      
      .. note:: 
      
         On Windows, only :ref:`wx.OutRegion`  and :ref:`wx.InRegion`  are returned; a value :ref:`wx.InRegion`  then indicates that all or some part of the region is contained in this region.   
      
      
      
      
      
      
      
      **~~~**

      
      **Contains** `(self, rect)`
      
      Returns a value indicating whether the given rectangle is contained within the region.                  
      
      This method always returns  ``OutRegion``   for an invalid region but may, nevertheless, be safely called in this case. 
      
                      
      
      
      :param `rect`: 
      :type `rect`: wx.Rect
      
      
      
      
      :rtype: :ref:`wx.RegionContain`
      
      
      
      
      
      
      
      :returns: 
      
         One of :ref:`wx.OutRegion`, :ref:`wx.PartRegion`  or :ref:`wx.InRegion`.  
      
      
      
      
      
      
      
      .. note:: 
      
         On Windows, only :ref:`wx.OutRegion`  and :ref:`wx.InRegion`  are returned; a value :ref:`wx.InRegion`  then indicates that all or some part of the region is contained in this region.   
      
      
      
      
      
      
      
      **~~~**






   .. method:: ConvertToBitmap(self)

      Convert the region to a black and white bitmap with the white pixels being inside the region.                  

      This method can't be used for invalid region.                  

      :rtype: :ref:`wx.Bitmap`








   .. method:: GetBox(self)

      Returns the outer bounds of the region.                  

      This method returns 0-sized bounding box for invalid regions.                  

      :rtype: :ref:`wx.Rect`








   .. method:: Intersect(self, *args, **kw)



      |overload| Overloaded Implementations:

      **~~~**

      
      **Intersect** `(self, x, y, width, height)`
      
      Finds the intersection of this region and another, rectangular region, specified using position and size.                  
      
      This method always fails, i.e. returns ``False``, if this region is invalid but may nevertheless be safely used even in this case. 
      
                      
      
      
      :param `x`: 
      :type `x`: int
      :param `y`: 
      :type `y`: int
      :param `width`: 
      :type `width`: int
      :param `height`: 
      :type `height`: int
      
      
      
      
      :rtype: `bool`
      
      
      
      
      
      
      
      :returns: 
      
         ``True`` if successful, ``False`` otherwise.  
      
      
      
      
      
      
      
      .. note:: 
      
         Creates the intersection of the two regions, that is, the parts which are in both regions. The result is stored in this region.   
      
      
      
      
      
      
      
      **~~~**

      
      **Intersect** `(self, rect)`
      
      Finds the intersection of this region and another, rectangular region.                  
      
      This method always fails, i.e. returns ``False``, if this region is invalid but may nevertheless be safely used even in this case. 
      
                      
      
      
      :param `rect`: 
      :type `rect`: wx.Rect
      
      
      
      
      :rtype: `bool`
      
      
      
      
      
      
      
      :returns: 
      
         ``True`` if successful, ``False`` otherwise.  
      
      
      
      
      
      
      
      .. note:: 
      
         Creates the intersection of the two regions, that is, the parts which are in both regions. The result is stored in this region.   
      
      
      
      
      
      
      
      **~~~**

      
      **Intersect** `(self, region)`
      
      Finds the intersection of this region and another region.                  
      
      This method always fails, i.e. returns ``False``, if this region is invalid but may nevertheless be safely used even in this case. 
      
                      
      
      
      :param `region`: 
      :type `region`: wx.Region
      
      
      
      
      :rtype: `bool`
      
      
      
      
      
      
      
      :returns: 
      
         ``True`` if successful, ``False`` otherwise.  
      
      
      
      
      
      
      
      .. note:: 
      
         Creates the intersection of the two regions, that is, the parts which are in both regions. The result is stored in this region.   
      
      
      
      
      
      
      
      **~~~**






   .. method:: IsEmpty(self)

      Returns ``True`` if the region is empty, ``False`` otherwise.                  

      Always returns ``True`` if the region is invalid.                  

      :rtype: `bool`








   .. method:: IsEqual(self, region)

      Returns ``True`` if the region is equal to, i.e. covers the same area as, another one.                  

      If both this region and `region`  are both invalid, they are considered to be equal.                  


      :param `region`: 
      :type `region`: wx.Region




      :rtype: `bool`








   .. method:: Offset(self, *args, **kw)

      Moves the region by the specified offsets in horizontal and vertical directions.                  

      This method can't be called if the region is invalid as it doesn't make sense to offset it then. Attempts to do it will result in assert failure. 

                 



      :returns: 

         ``True`` if successful, ``False`` otherwise (the region is unchanged then).   





      |overload| Overloaded Implementations:

      **~~~**

      
      **Offset** `(self, x, y)`
      
      
      
      
      :param `x`: 
      :type `x`: int
      :param `y`: 
      :type `y`: int
      
      
      
      
      :rtype: `bool`
      
      
      
      
      
      
      
      **~~~**

      
      **Offset** `(self, pt)`
      
      
      
      
      :param `pt`: 
      :type `pt`: wx.Point
      
      
      
      
      :rtype: `bool`
      
      
      
      
      
      
      
      **~~~**






   .. method:: Subtract(self, *args, **kw)



      |overload| Overloaded Implementations:

      **~~~**

      
      **Subtract** `(self, rect)`
      
      Subtracts a rectangular region from this region.                  
      
      This method always fails, i.e. returns ``False``, if this region is invalid but may nevertheless be safely used even in this case. 
      
                      
      
      
      :param `rect`: 
      :type `rect`: wx.Rect
      
      
      
      
      :rtype: `bool`
      
      
      
      
      
      
      
      :returns: 
      
         ``True`` if successful, ``False`` otherwise.  
      
      
      
      
      
      
      
      .. note:: 
      
         This operation combines the parts of 'this' region that are not part of the second region. The result is stored in this region.   
      
      
      
      
      
      
      
      **~~~**

      
      **Subtract** `(self, region)`
      
      Subtracts a region from this region.                  
      
      This method always fails, i.e. returns ``False``, if this region is invalid but may nevertheless be safely used even in this case. 
      
                      
      
      
      :param `region`: 
      :type `region`: wx.Region
      
      
      
      
      :rtype: `bool`
      
      
      
      
      
      
      
      :returns: 
      
         ``True`` if successful, ``False`` otherwise.  
      
      
      
      
      
      
      
      .. note:: 
      
         This operation combines the parts of 'this' region that are not part of the second region. The result is stored in this region.   
      
      
      
      
      
      
      
      **~~~**






   .. method:: Union(self, *args, **kw)



      |overload| Overloaded Implementations:

      **~~~**

      
      **Union** `(self, x, y, width, height)`
      
      Finds the union of this region and another, rectangular region, specified using position and size.                  
      
      This method can be used even if this region is invalid and has the natural behaviour in this case, i.e. makes this region equal to the given rectangle. 
      
                      
      
      
      :param `x`: 
      :type `x`: int
      :param `y`: 
      :type `y`: int
      :param `width`: 
      :type `width`: int
      :param `height`: 
      :type `height`: int
      
      
      
      
      :rtype: `bool`
      
      
      
      
      
      
      
      :returns: 
      
         ``True`` if successful, ``False`` otherwise.  
      
      
      
      
      
      
      
      .. note:: 
      
         This operation creates a region that combines all of this region and the second region. The result is stored in this region.   
      
      
      
      
      
      
      
      **~~~**

      
      **Union** `(self, rect)`
      
      Finds the union of this region and another, rectangular region.                  
      
      This method can be used even if this region is invalid and has the natural behaviour in this case, i.e. makes this region equal to the given rectangle. 
      
                      
      
      
      :param `rect`: 
      :type `rect`: wx.Rect
      
      
      
      
      :rtype: `bool`
      
      
      
      
      
      
      
      :returns: 
      
         ``True`` if successful, ``False`` otherwise.  
      
      
      
      
      
      
      
      .. note:: 
      
         This operation creates a region that combines all of this region and the second region. The result is stored in this region.   
      
      
      
      
      
      
      
      **~~~**

      
      **Union** `(self, region)`
      
      Finds the union of this region and another region.                  
      
      This method can be used even if this region is invalid and has the natural behaviour in this case, i.e. makes this region equal to the given `region`. 
      
                      
      
      
      :param `region`: 
      :type `region`: wx.Region
      
      
      
      
      :rtype: `bool`
      
      
      
      
      
      
      
      :returns: 
      
         ``True`` if successful, ``False`` otherwise.  
      
      
      
      
      
      
      
      .. note:: 
      
         This operation creates a region that combines all of this region and the second region. The result is stored in this region.   
      
      
      
      
      
      
      
      **~~~**

      
      **Union** `(self, bmp)`
      
      Finds the union of this region and the non-transparent pixels of a bitmap.                  
      
      The bitmap's mask is used to determine transparency. If the bitmap doesn't have a mask, the bitmap's full dimensions are used. 
      
                      
      
      
      :param `bmp`: 
      :type `bmp`: wx.Bitmap
      
      
      
      
      :rtype: `bool`
      
      
      
      
      
      
      
      :returns: 
      
         ``True`` if successful, ``False`` otherwise.  
      
      
      
      
      
      
      
      .. note:: 
      
         This operation creates a region that combines all of this region and the second region. The result is stored in this region.   
      
      
      
      
      
      
      
      **~~~**

      
      **Union** `(self, bmp, transColour, tolerance=0)`
      
      Finds the union of this region and the non-transparent pixels of a bitmap.                  
      
      Colour to be treated as transparent is specified in the `transColour`  argument, along with an optional colour tolerance value. 
      
                      
      
      
      :param `bmp`: 
      :type `bmp`: wx.Bitmap
      :param `transColour`: 
      :type `transColour`: wx.Colour
      :param `tolerance`: 
      :type `tolerance`: int
      
      
      
      
      :rtype: `bool`
      
      
      
      
      
      
      
      :returns: 
      
         ``True`` if successful, ``False`` otherwise.  
      
      
      
      
      
      
      
      .. note:: 
      
         This operation creates a region that combines all of this region and the second region. The result is stored in this region.   
      
      
      
      
      
      
      
      **~~~**






   .. method:: Xor(self, *args, **kw)



      |overload| Overloaded Implementations:

      **~~~**

      
      **Xor** `(self, x, y, width, height)`
      
      Finds the Xor of this region and another, rectangular region, specified using position and size.                  
      
      This method can be used even if this region is invalid and has the natural behaviour in this case, i.e. makes this region equal to the given rectangle. 
      
                      
      
      
      :param `x`: 
      :type `x`: int
      :param `y`: 
      :type `y`: int
      :param `width`: 
      :type `width`: int
      :param `height`: 
      :type `height`: int
      
      
      
      
      :rtype: `bool`
      
      
      
      
      
      
      
      :returns: 
      
         ``True`` if successful, ``False`` otherwise.  
      
      
      
      
      
      
      
      .. note:: 
      
         This operation creates a region that combines all of this region and the second region, except for any overlapping areas. The result is stored in this region.   
      
      
      
      
      
      
      
      **~~~**

      
      **Xor** `(self, rect)`
      
      Finds the Xor of this region and another, rectangular region.                  
      
      This method can be used even if this region is invalid and has the natural behaviour in this case, i.e. makes this region equal to the given rectangle. 
      
                      
      
      
      :param `rect`: 
      :type `rect`: wx.Rect
      
      
      
      
      :rtype: `bool`
      
      
      
      
      
      
      
      :returns: 
      
         ``True`` if successful, ``False`` otherwise.  
      
      
      
      
      
      
      
      .. note:: 
      
         This operation creates a region that combines all of this region and the second region, except for any overlapping areas. The result is stored in this region.   
      
      
      
      
      
      
      
      **~~~**

      
      **Xor** `(self, region)`
      
      Finds the Xor of this region and another region.                  
      
      This method can be used even if this region is invalid and has the natural behaviour in this case, i.e. makes this region equal to the given `region`. 
      
                      
      
      
      :param `region`: 
      :type `region`: wx.Region
      
      
      
      
      :rtype: `bool`
      
      
      
      
      
      
      
      :returns: 
      
         ``True`` if successful, ``False`` otherwise.  
      
      
      
      
      
      
      
      .. note:: 
      
         This operation creates a region that combines all of this region and the second region, except for any overlapping areas. The result is stored in this region.   
      
      
      
      
      
      
      
      **~~~**






   .. method:: __iter__(self)

      Returns a rectangle interator conforming to the Python iterator
      protocol.



   .. attribute:: Box

      See :meth:`~wx.Region.GetBox`

