.. wxPython Phoenix documentation

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

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

.. include:: headings.inc



.. _wx.Overlay:

==========================================================================================================================================
|phoenix_title|  **wx.Overlay**
==========================================================================================================================================

Creates an overlay over an existing window, allowing for manipulations like rubber-banding, etc. 
         

Overlay is implemented internally as a native window shown on top of the window it is used with and it is more efficient to keep the :ref:`wx.Overlay`  object around instead of recreating it every time it's needed, i.e. typically you would have a member variable of type :ref:`wx.Overlay`  in your window class. 

The overlay is initialized automatically when it is used by :ref:`wx.DCOverlay`  or `OverlayDC`       but has to be cleared manually, using its :meth:`~wx.Overlay.Reset`  function, when its contents shouldn't be shown any longer. 

Use of this class is shown in the :ref:`Drawing Sample <drawing sample>`  where pressing the left mouse button and dragging the mouse creates a rubber band effect using :ref:`wx.Overlay`. 






         



.. seealso:: :ref:`wx.DCOverlay`, `OverlayDC`         







|

|class_hierarchy| Class Hierarchy
=================================

.. raw:: html

   <div class="collabsible-wrapper">
      <input id="collapsible-inheritance" class="collapsible-checkbox" type="checkbox">
      <label for="collapsible-inheritance" tabindex="0" title="Show inheritance diagram" class="collapsible-label">Inheritance diagram for class <strong>Overlay</strong>:</label>
      <div class="collapsible-content">
         <p class="graphviz">
            <center><img src="_static/images/inheritance/wx.Overlay_inheritance.svg" alt="Inheritance diagram of Overlay" usemap="#dummy" class="inheritance invert-in-dark-mode"/></center>
            <map id="dummy" name="dummy"> <area shape="rect" id="node1" href="wx.Overlay.html" title="Creates an overlay over an existing window, allowing for manipulations like rubber-banding, etc." alt="" coords="5,5,113,34"/> </map> 
         </p>
      </div>
   </div>
   <script type="text/javascript" src="_static/inheritancetoggle.js"></script>



|


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

================================================================================ ================================================================================
:meth:`~wx.Overlay.__init__`                                                     
:meth:`~wx.Overlay.Reset`                                                        Clears the overlay without restoring the former state.
:meth:`~wx.Overlay.SetOpacity`                                                   Sets or unsets constant opacity of the overlay window.
================================================================================ ================================================================================


|


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


.. class:: wx.Overlay(object)

   **Possible constructors**::

       Overlay() -> None
       
   
   Creates an overlay over an existing window, allowing for manipulations
   like rubber-banding, etc.



   .. method:: __init__(self)



      :rtype: `None`     








   .. method:: Reset(self)

      Clears the overlay without restoring the former state. 
                 

      To be done, for example, when the window content has been changed and repainted. 
                 

      :rtype: `None`     








   .. method:: SetOpacity(self, alpha)

      Sets or unsets constant opacity of the overlay window. 
                 

      If `alpha`  is  ``-1`` , use per-pixel alpha blending, otherwise use the given alpha value for all pixels. 


                


      :param `alpha`: 
      :type `alpha`: int




      :rtype: `None`     







      .. versionadded:: 4.3/wxWidgets-3.3.0  
     







      .. note:: 

         Drawing on the overlay window is opaque by default under wxMSW. You have to call SetOpacity(-1) before initializing the overlay and use a graphics context to do the actual drawing if you want per-pixel alpha blending. Or, assuming that SetOpacity(-1) wasn't called, explicitly set the alpha value (at any time) to change the overlay window's opacity.  







      .. note:: 

         This is currently only implemented for wxMSW and does nothing in the other ports.