How overlay works?

wxPython Users
1

Would someone please provide the details of how overlay and its methods actually work. I have found several nice examples that use overly; but, have found no documentation that actually explains the details of what happens "under the hood". If such documentation exists, then a link to it would be greatly appreciated.

Here is an example that has been posted earlier and works fine (Python 2.6, Windows Vista).

import wx
print wx.version()

class TestPanel(wx.Panel):
     def __init__(self, *args, **kw):
         wx.Panel.__init__(self, *args, **kw)

         self.Bind(wx.EVT_PAINT, self.OnPaint)
         self.Bind(wx.EVT_LEFT_DOWN, self.OnLeftDown)
         self.Bind(wx.EVT_LEFT_UP, self.OnLeftUp)
         self.Bind(wx.EVT_MOTION, self.OnMouseMove)

         self.startPos = None
         self.overlay = wx.Overlay()

     def OnPaint(self, evt):
         # Just some simple stuff to paint in the window for an example
         dc = wx.PaintDC(self)
         coords = ((40,40),(200,220),(210,120),(120,300))
         dc.SetBackground(wx.Brush("sky blue"))
         dc.Clear()
         dc.SetPen(wx.Pen("red", 2))
         dc.SetBrush(wx.CYAN_BRUSH)
         dc.DrawPolygon(coords)
         dc.DrawLabel("Drag the mouse across this window to see \n"
                     "a rubber-band effect using wx.Overlay",
                     (140, 50, -1, -1))

     def OnLeftDown(self, evt):
         # Capture the mouse and save the starting posiiton for the
         # rubber-band
         self.CaptureMouse()
         self.startPos = evt.GetPosition()

     def OnMouseMove(self, evt):
         if evt.Dragging() and evt.LeftIsDown():
             rect = wx.RectPP(self.startPos, evt.GetPosition())

             # Draw the rubber-band rectangle using an overlay so it
             # will manage keeping the rectangle and the former window
             # contents separate.
             dc = wx.ClientDC(self)

             #*** This won't work because wx.GCDC is not a wx.WindowDC
             #dc = wx.GCDC(dc)

             odc = wx.DCOverlay(self.overlay, dc)
             odc.Clear()

             #*** This crashes on wxMac

             #dc = wx.GCDC(dc)

             dc.SetPen(wx.Pen("black", 2))
             if 'wxMac' in wx.PlatformInfo:
                 dc.SetBrush(wx.Brush(wx.Colour(0xC0, 0xC0, 0xC0, 0x80)))
             else:
                 dc.SetBrush(wx.TRANSPARENT_BRUSH)
             dc.DrawRectangleRect(rect)

             del odc # work around a bug in the Python wrappers to make
                     # sure the odc is destroyed before the dc is.

     def OnLeftUp(self, evt):
         if self.HasCapture():
             self.ReleaseMouse()
         self.startPos = None

         # When the mouse is released we reset the overlay and it
         # restores the former content to the window.
         dc = wx.ClientDC(self)
         odc = wx.DCOverlay(self.overlay, dc)
         odc.Clear()
         del odc
         self.overlay.Reset()

app = wx.App(redirect=False)
frm = wx.Frame(None, title="wx.Overlay Test", size=(450,450))
pnl = TestPanel(frm)
frm.Show()
app.MainLoop()

The comments help somewhat; but, they don't explain what is really happening in some of the code. For example,
if I comment out the self.overlay.Reset() in OnLeftUp(self, evt), I can see no difference in the execution of the program.

Some basic questions (in reference to the above code):
1) What happens in odc.wx.DCOverlay(self.overlay,dc)? (note there are two instances)
2) What happens in odc.Clear()? (note there are two instances)
3) What happens in self.overlay.Reset() ? and Why is it used in this code?

2

Virgil Stokes wrote:

Would someone please provide the details of how overlay and its methods actually
work. I have found several nice examples that use overly; but, have found no
documentation that actually explains the details of what happens "under the
hood". If such documentation exists, then a link to it would be greatly
appreciated.

It's fairly simple. The overlay object holds a copy of the window in a
bitmap. You can then draw on the window itself to your heart's
content. When you call Clear, it restores the saved copy back to the
visible window. Reset clears the saved copy.

The comments help somewhat; but, they don't explain what is really happening in
some of the code. For example,
if I comment out the self.overlay.Reset() in OnLeftUp(self, evt), I can see no
difference in the execution of the program.

Some basic questions (in reference to the above code):
1) What happens in odc.wx.DCOverlay(self.overlay,dc)? (note there are two instances)

The wx.Overlay object is the one that owns the snapshot bitmap. The
wx.DCOverlay object is essentially a helper object that makes the state
management a little more automatic. The first time you create the
DCOverlay, it causes the Overlay to grab a snapshot of the window.
Calling ods.Clear() copies than snapshot back to the window, thereby
erasing any drawing that had been done to the window in the meantime.

DCOverlay is intended to be transient, like a DC. It is providing
access to the global Overlay.

2) What happens in odc.Clear()? (note there are two instances)

ods.Clear() causes the saved bitmap to be blitted back to the window,
erasing any drawing that had been done since the last snapshot.

3) What happens in self.overlay.Reset() ? and Why is it used in this code?

Reset() creates a new empty bitmap in the overlay, thereby deleting
whatever snapshot had previously been captured. The next time you
create a DCOverlay, it will grab a new snapshot. Since you don't do any
additional drawing, you won't see a difference.

···

--
Tim Roberts, timr@probo.com
Providenza & Boekelheide, Inc.

3

Ok Tim,
I will go through your response in detail and test it more thoroughly; but, for now thanks very much for your prompt and complete reply.
Best regards :slight_smile:

--V

···

On 07-Feb-2012 18:48, Tim Roberts wrote:

Virgil Stokes wrote:

Would someone please provide the details of how overlay and its methods actually
work. I have found several nice examples that use overly; but, have found no
documentation that actually explains the details of what happens "under the
hood". If such documentation exists, then a link to it would be greatly
appreciated.

It's fairly simple. The overlay object holds a copy of the window in a
bitmap. You can then draw on the window itself to your heart's
content. When you call Clear, it restores the saved copy back to the
visible window. Reset clears the saved copy.

The comments help somewhat; but, they don't explain what is really happening in
some of the code. For example,
if I comment out the self.overlay.Reset() in OnLeftUp(self, evt), I can see no
difference in the execution of the program.

Some basic questions (in reference to the above code):
1) What happens in odc.wx.DCOverlay(self.overlay,dc)? (note there are two instances)

The wx.Overlay object is the one that owns the snapshot bitmap. The
wx.DCOverlay object is essentially a helper object that makes the state
management a little more automatic. The first time you create the
DCOverlay, it causes the Overlay to grab a snapshot of the window.
Calling ods.Clear() copies than snapshot back to the window, thereby
erasing any drawing that had been done to the window in the meantime.

DCOverlay is intended to be transient, like a DC. It is providing
access to the global Overlay.

2) What happens in odc.Clear()? (note there are two instances)

ods.Clear() causes the saved bitmap to be blitted back to the window,
erasing any drawing that had been done since the last snapshot.

3) What happens in self.overlay.Reset() ? and Why is it used in this code?

Reset() creates a new empty bitmap in the overlay, thereby deleting
whatever snapshot had previously been captured. The next time you
create a DCOverlay, it will grab a new snapshot. Since you don't do any
additional drawing, you won't see a difference.

4

It should also be noted that on Mac the Overlay is part of the native API, while on the other platforms it is a generic implementation using regular DCs. So some things that may seem odd about how wx.Overlay works are likely there in order to satisfy the needs of the native API on Mac.

···

On 2/7/12 9:48 AM, Tim Roberts wrote:

Virgil Stokes wrote:

Would someone please provide the details of how overlay and its methods actually
work. I have found several nice examples that use overly; but, have found no
documentation that actually explains the details of what happens "under the
hood". If such documentation exists, then a link to it would be greatly
appreciated.

It's fairly simple. The overlay object holds a copy of the window in a
bitmap. You can then draw on the window itself to your heart's
content. When you call Clear, it restores the saved copy back to the
visible window. Reset clears the saved copy.

The comments help somewhat; but, they don't explain what is really happening in
some of the code. For example,
if I comment out the self.overlay.Reset() in OnLeftUp(self, evt), I can see no
difference in the execution of the program.

Some basic questions (in reference to the above code):
1) What happens in odc.wx.DCOverlay(self.overlay,dc)? (note there are two instances)

The wx.Overlay object is the one that owns the snapshot bitmap. The
wx.DCOverlay object is essentially a helper object that makes the state
management a little more automatic. The first time you create the
DCOverlay, it causes the Overlay to grab a snapshot of the window.
Calling ods.Clear() copies than snapshot back to the window, thereby
erasing any drawing that had been done to the window in the meantime.

DCOverlay is intended to be transient, like a DC. It is providing
access to the global Overlay.

2) What happens in odc.Clear()? (note there are two instances)

ods.Clear() causes the saved bitmap to be blitted back to the window,
erasing any drawing that had been done since the last snapshot.

3) What happens in self.overlay.Reset() ? and Why is it used in this code?

Reset() creates a new empty bitmap in the overlay, thereby deleting
whatever snapshot had previously been captured. The next time you
create a DCOverlay, it will grab a new snapshot. Since you don't do any
additional drawing, you won't see a difference.

--
Robin Dunn
Software Craftsman