AUI updates

[wxWidgets.git] / wxPython / src / _dc.i

diff --git a/wxPython/src/_dc.i b/wxPython/src/_dc.i
index ab5bceb09dded80977ac0c4feebf9862f098c96c..2a590d547f4d06eca6a3ad4275ffa15e8c176ce2 100644 (file)
--- a/wxPython/src/_dc.i
+++ b/wxPython/src/_dc.i
@@ -352,6 +352,12 @@ position.", "
     :param srcPtMask:   Source position on the mask. 
 ",
         BlitPointSize);
     :param srcPtMask:   Source position on the mask. 
 ",
         BlitPointSize);

+
+
+    DocDeclStr(
+        wxBitmap , GetAsBitmap(const wxRect *subrect = NULL) const,
+        "", "");
+    

     
 
     DocStr(
     
 
     DocStr(


@@ -975,6 +981,24 @@ box doesn't contain anything.", "");
     %pythoncode { def __nonzero__(self): return self.IsOk() };
 
 
     %pythoncode { def __nonzero__(self): return self.IsOk() };
 
 

+    // RTL related functions
+    // ---------------------
+
+    DocDeclStr(
+        virtual wxLayoutDirection , GetLayoutDirection() const,
+        "Get the layout direction (LTR or RTL)_ for this dc.  On platforms
+where RTL layout is supported, the return value will either be
+``wx.Layout_LeftToRight`` or ``wx.Layout_RightToLeft``.
+``wx.Layout_Default`` is returned if layout direction is not
+supported.", "");
+    
+    DocDeclStr(
+        virtual void , SetLayoutDirection(wxLayoutDirection dir),
+        "Change the layout direction for this dc.", "");
+    
+
+    
+

 #ifdef __WXMSW__
     long GetHDC();
 #endif
 #ifdef __WXMSW__
     long GetHDC();
 #endif


@@ -1201,6 +1225,8 @@ box doesn't contain anything.", "");
     %property(TextExtent, GetTextExtent, doc="See `GetTextExtent`");
     %property(TextForeground, GetTextForeground, SetTextForeground, doc="See `GetTextForeground` and `SetTextForeground`");
     %property(UserScale, GetUserScale, SetUserScale, doc="See `GetUserScale` and `SetUserScale`");
     %property(TextExtent, GetTextExtent, doc="See `GetTextExtent`");
     %property(TextForeground, GetTextForeground, SetTextForeground, doc="See `GetTextForeground` and `SetTextForeground`");
     %property(UserScale, GetUserScale, SetUserScale, doc="See `GetUserScale` and `SetUserScale`");

+
+    %property(LayoutDirection, GetLayoutDirection, SetLayoutDirection);

 };
 
 
 };
 
 


@@ -1215,6 +1241,64 @@ static void wxDC_GetBoundingBox(wxDC* dc, int* x1, int* y1, int* x2, int* y2) {
 %}
 
 
 %}
 
 

+//---------------------------------------------------------------------------
+%newgroup
+
+DocStr(wxDCTextColourChanger,
+"wx.DCTextColourChanger can be used to temporarily change the DC text
+colour and restore it automatically when the object goes out of scope", "");
+
+class wxDCTextColourChanger
+{
+public:
+    wxDCTextColourChanger(wxDC& dc, const wxColour& col);
+    ~wxDCTextColourChanger();
+};
+
+
+DocStr(wxDCPenChanger,
+"wx.DCPenChanger can be used to temporarily change the DC pen and
+restore it automatically when the object goes out of scope", "");
+
+class  wxDCPenChanger
+{
+public:
+    wxDCPenChanger(wxDC& dc, const wxPen& pen);
+    ~wxDCPenChanger();
+};
+
+
+
+DocStr(wxDCBrushChanger,
+"wx.DCBrushChanger can be used to temporarily change the DC brush and
+restore it automatically when the object goes out of scope", "");
+
+class wxDCBrushChanger
+{
+public:
+    wxDCBrushChanger(wxDC& dc, const wxBrush& brush);
+    ~wxDCBrushChanger();
+};
+
+
+DocStr(wxDCClipper,
+"wx.wxDCClipper sets the DC's clipping region when it is constructed,
+and then automatically destroys the clipping region when the clipper
+goes out of scope.", "");
+
+class wxDCClipper
+{
+public:
+    %nokwargs wxDCClipper;
+    wxDCClipper(wxDC& dc, const wxRegion& r);
+    wxDCClipper(wxDC& dc, const wxRect& r);
+    wxDCClipper(wxDC& dc, wxCoord x, wxCoord y, wxCoord w, wxCoord h);
+    ~wxDCClipper();
+};
+
+
+
+

 //---------------------------------------------------------------------------
 %newgroup
 
 //---------------------------------------------------------------------------
 %newgroup
 


@@ -1227,7 +1311,7 @@ be used for anything. Typical usage is as follows::
 
     dc = wx.MemoryDC()
     dc.SelectObject(bitmap)
 
     dc = wx.MemoryDC()
     dc.SelectObject(bitmap)

-    # draw on the dc usign any of the Draw methods
+    # draw on the dc using any of the Draw methods

     dc.SelectObject(wx.NullBitmap)
     # the bitmap now contains wahtever was drawn upon it
 
     dc.SelectObject(wx.NullBitmap)
     # the bitmap now contains wahtever was drawn upon it
 


@@ -1238,12 +1322,13 @@ of it) before a bitmap can be reselected into another memory DC.
 class wxMemoryDC : public wxDC {
 public:
     DocCtorStr(
 class wxMemoryDC : public wxDC {
 public:
     DocCtorStr(

-        wxMemoryDC(),
+        wxMemoryDC(wxBitmap& bitmap = wxNullBitmap),

         "Constructs a new memory device context.
 
 Use the Ok member to test whether the constructor was successful in
         "Constructs a new memory device context.
 
 Use the Ok member to test whether the constructor was successful in

-creating a usable device context. Don't forget to select a bitmap into
-the DC before drawing on it.", "
+creating a usable device context. If a bitmap is not given to this
+constructor then don't forget to select a bitmap into the DC before
+drawing on it.", "

 
 :see: `MemoryDCFromDC`");
 
 
 :see: `MemoryDCFromDC`");
 


@@ -1254,7 +1339,7 @@ the DC before drawing on it.", "
 
     
     DocDeclStr(
 
     
     DocDeclStr(

-        void , SelectObject(const wxBitmap& bitmap),
+        void , SelectObject(wxBitmap& bitmap),

         "Selects the bitmap into the device context, to use as the memory
 bitmap. Selecting the bitmap into a memory DC allows you to draw into
 the DC, and therefore the bitmap, and also to use Blit to copy the
         "Selects the bitmap into the device context, to use as the memory
 bitmap. Selecting the bitmap into a memory DC allows you to draw into
 the DC, and therefore the bitmap, and also to use Blit to copy the


@@ -1264,9 +1349,133 @@ If the argument is wx.NullBitmap (or some other uninitialised
 `wx.Bitmap`) the current bitmap is selected out of the device context,
 and the original bitmap restored, allowing the current bitmap to be
 destroyed safely.", "");
 `wx.Bitmap`) the current bitmap is selected out of the device context,
 and the original bitmap restored, allowing the current bitmap to be
 destroyed safely.", "");

+
+    
+    DocDeclStr(
+        void , SelectObjectAsSource(const wxBitmap& bmp),
+        "", "");
+    

     
 };
 
     
 };
 

+//---------------------------------------------------------------------------
+%newgroup
+
+MustHaveApp(wxScreenDC);
+
+DocStr(wxScreenDC,
+"A wxScreenDC can be used to paint anywhere on the screen. This should
+normally be constructed as a temporary stack object; don't store a
+wxScreenDC object.
+", "");
+class wxScreenDC : public wxDC {
+public:
+    wxScreenDC();
+
+    DocDeclStrName(
+        bool , StartDrawingOnTop(wxWindow* window),
+        "Specify that the area of the screen to be drawn upon coincides with
+the given window.
+
+:see: `EndDrawingOnTop`", "",
+        StartDrawingOnTopWin);
+    
+
+    DocDeclStr(
+        bool , StartDrawingOnTop(wxRect* rect = NULL),
+        "Specify that the area is the given rectangle, or the whole screen if
+``None`` is passed.
+
+:see: `EndDrawingOnTop`", "");
+    
+
+    DocDeclStr(
+        bool , EndDrawingOnTop(),
+        "Use this in conjunction with `StartDrawingOnTop` or
+`StartDrawingOnTopWin` to ensure that drawing to the screen occurs on
+top of existing windows. Without this, some window systems (such as X)
+only allow drawing to take place underneath other windows.
+
+You might use this pair of functions when implementing a drag feature,
+for example as in the `wx.SplitterWindow` implementation.
+
+These functions are probably obsolete since the X implementations
+allow drawing directly on the screen now. However, the fact that this
+function allows the screen to be refreshed afterwards may be useful
+to some applications.", "");
+    
+};
+
+//---------------------------------------------------------------------------
+%newgroup
+
+MustHaveApp(wxWindowDC);
+
+DocStr(wxWindowDC,
+       "A wx.WindowDC must be constructed if an application wishes to paint on
+the whole area of a window (client and decorations). This should
+normally be constructed as a temporary stack object; don't store a
+wx.WindowDC object.","");
+class wxWindowDC : public wxDC {
+public:
+    DocCtorStr(
+        wxWindowDC(wxWindow* win),
+        "Constructor. Pass the window on which you wish to paint.","");
+};
+
+//---------------------------------------------------------------------------
+%newgroup
+
+MustHaveApp(wxClientDC);
+
+DocStr(wxClientDC,
+"A wx.ClientDC must be constructed if an application wishes to paint on
+the client area of a window from outside an EVT_PAINT event. This should
+normally be constructed as a temporary stack object; don't store a
+wx.ClientDC object long term.
+
+To draw on a window from within an EVT_PAINT handler, construct a
+`wx.PaintDC` object.
+
+To draw on the whole window including decorations, construct a
+`wx.WindowDC` object (Windows only).
+", "");
+class wxClientDC : public wxWindowDC {
+public:
+    DocCtorStr(
+        wxClientDC(wxWindow* win),
+        "Constructor. Pass the window on which you wish to paint.", "");
+};
+
+//---------------------------------------------------------------------------
+%newgroup
+
+MustHaveApp(wxPaintDC);
+
+DocStr(wxPaintDC,
+"A wx.PaintDC must be constructed if an application wishes to paint on
+the client area of a window from within an EVT_PAINT event
+handler. This should normally be constructed as a temporary stack
+object; don't store a wx.PaintDC object. If you have an EVT_PAINT
+handler, you **must** create a wx.PaintDC object within it even if you
+don't actually use it.
+
+Using wx.PaintDC within EVT_PAINT handlers is important because it
+automatically sets the clipping area to the damaged area of the
+window. Attempts to draw outside this area do not appear.
+
+To draw on a window from outside EVT_PAINT handlers, construct a
+`wx.ClientDC` object.
+","");
+class wxPaintDC : public wxClientDC {
+public:
+    DocCtorStr(
+        wxPaintDC(wxWindow* win),
+        "Constructor. Pass the window on which you wish to paint.", "");
+};
+
+
+

 //---------------------------------------------------------------------------
 %newgroup
 
 //---------------------------------------------------------------------------
 %newgroup
 


@@ -1286,16 +1495,26 @@ DocStr(wxBufferedDC,
 "This simple class provides a simple way to avoid flicker: when drawing
 on it, everything is in fact first drawn on an in-memory buffer (a
 `wx.Bitmap`) and then copied to the screen only once, when this object
 "This simple class provides a simple way to avoid flicker: when drawing
 on it, everything is in fact first drawn on an in-memory buffer (a
 `wx.Bitmap`) and then copied to the screen only once, when this object

-is destroyed.
+is destroyed.  You can either provide a buffer bitmap yourself, and
+reuse it the next time something needs painted, or you can let the
+buffered DC create and provide a buffer bitmap itself.

 
 

-It can be used in the same way as any other device context.
+Buffered DCs can be used in the same way as any other device context.

 wx.BufferedDC itself typically replaces `wx.ClientDC`, if you want to
 use it in your EVT_PAINT handler, you should look at
 wx.BufferedDC itself typically replaces `wx.ClientDC`, if you want to
 use it in your EVT_PAINT handler, you should look at

-`wx.BufferedPaintDC`.
+`wx.BufferedPaintDC`.  You can also use a wx.BufferedDC without
+providing a target DC.  In this case the operations done on the dc
+will only be written to the buffer bitmap and *not* to any window, so
+you will want to have provided the buffer bitmap and then reuse it
+when it needs painted to the window.

 
 Please note that GTK+ 2.0 and OS X provide double buffering themselves
 
 Please note that GTK+ 2.0 and OS X provide double buffering themselves

-natively so using this class on those platforms will normally result
-in an unneeded level of buffering.
+natively.  You may want to use `wx.Window.IsDoubleBuffered` to
+determine whether you need to use buffering or not, or use
+`wx.AutoBufferedPaintDC` to avoid needless double buffering on systems
+that already do it automatically.
+
+

 ", "");
 
 class wxBufferedDC : public wxMemoryDC
 ", "");
 
 class wxBufferedDC : public wxMemoryDC


@@ -1333,11 +1552,16 @@ public:
 
 ");
     wxBufferedDC( wxDC* dc,
 
 ");
     wxBufferedDC( wxDC* dc,

-                  const wxBitmap& buffer=wxNullBitmap,
+                  wxBitmap& buffer=wxNullBitmap,

                   int style = wxBUFFER_CLIENT_AREA );
     wxBufferedDC( wxDC* dc,
                   const wxSize& area,
                   int style = wxBUFFER_CLIENT_AREA );
                   int style = wxBUFFER_CLIENT_AREA );
     wxBufferedDC( wxDC* dc,
                   const wxSize& area,
                   int style = wxBUFFER_CLIENT_AREA );

+//     wxBufferedDC(wxWindow* win,
+//                  wxDC *dc,
+//                  const wxSize &area,
+//                  int style = wxBUFFER_CLIENT_AREA);
+

 
     DocCtorStr(
         ~wxBufferedDC(),
 
     DocCtorStr(
         ~wxBufferedDC(),


@@ -1350,7 +1574,10 @@ associated with this object, if any.", "");
         "Blits the buffer to the dc, and detaches the dc from the buffer (so it
 can be effectively used once only).  This is usually only called in
 the destructor.", "");
         "Blits the buffer to the dc, and detaches the dc from the buffer (so it
 can be effectively used once only).  This is usually only called in
 the destructor.", "");

-    
+
+    // Set and get the style
+    void SetStyle(int style);
+    int GetStyle() const;    

 };
 
 
 };
 
 


@@ -1376,8 +1603,6 @@ automatically when it is destroyed.  For example::
         dc = wx.BufferedPaintDC(self, self.buffer)
 
 
         dc = wx.BufferedPaintDC(self, self.buffer)
 
 

-
-

 ", "");
 
 class wxBufferedPaintDC : public wxBufferedDC
 ", "");
 
 class wxBufferedPaintDC : public wxBufferedDC


@@ -1386,133 +1611,61 @@ public:
 
     DocCtorStr(
         wxBufferedPaintDC( wxWindow *window,
 
     DocCtorStr(
         wxBufferedPaintDC( wxWindow *window,

-                           const wxBitmap &buffer = wxNullBitmap,
+                           wxBitmap &buffer = wxNullBitmap,

                            int style = wxBUFFER_CLIENT_AREA),
         "Create a buffered paint DC.  As with `wx.BufferedDC`, you may either
 provide the bitmap to be used for buffering or let this object create
 one internally (in the latter case, the size of the client part of the
                            int style = wxBUFFER_CLIENT_AREA),
         "Create a buffered paint DC.  As with `wx.BufferedDC`, you may either
 provide the bitmap to be used for buffering or let this object create
 one internally (in the latter case, the size of the client part of the

-window is automatically used).
-
-", "");
+window is automatically used).", "");

 
 };
 
 
 };
 

-

 //---------------------------------------------------------------------------
 %newgroup
 
 //---------------------------------------------------------------------------
 %newgroup
 

-MustHaveApp(wxScreenDC);
-
-DocStr(wxScreenDC,
-"A wxScreenDC can be used to paint anywhere on the screen. This should
-normally be constructed as a temporary stack object; don't store a
-wxScreenDC object.
+// Epydoc doesn't like this for some strange reason...
+// %pythoncode {
+//     if 'wxMac' in wx.PlatformInfo or 'gtk2' in wx.PlatformInfo:
+//         _AutoBufferedPaintDCBase = PaintDC
+//     else:
+//         _AutoBufferedPaintDCBase = BufferedPaintDC
+            
+//     class AutoBufferedPaintDC(_AutoBufferedPaintDCBase):
+//         """
+//         If the current platform double buffers by default then this DC is the
+//         same as a plain `wx.PaintDC`, otherwise it is a `wx.BufferedPaintDC`.
+
+//         :see: `wx.AutoBufferedPaintDCFactory`
+//         """
+//         def __init__(self, window):
+//             _AutoBufferedPaintDCBase.__init__(self, window)
+// }
+
+
+DocStr(wxAutoBufferedPaintDC,
+"If the current platform double buffers by default then this DC is the
+same as a plain `wx.PaintDC`, otherwise it is a `wx.BufferedPaintDC`.
+
+:see: `wx.AutoBufferedPaintDCFactory`

 ", "");
 ", "");

-class wxScreenDC : public wxDC {
-public:
-    wxScreenDC();
-
-    DocDeclStrName(
-        bool , StartDrawingOnTop(wxWindow* window),
-        "Specify that the area of the screen to be drawn upon coincides with
-the given window.
-
-:see: `EndDrawingOnTop`", "",
-        StartDrawingOnTopWin);
-    
-
-    DocDeclStr(
-        bool , StartDrawingOnTop(wxRect* rect = NULL),
-        "Specify that the area is the given rectangle, or the whole screen if
-``None`` is passed.
-
-:see: `EndDrawingOnTop`", "");
-    
-
-    DocDeclStr(
-        bool , EndDrawingOnTop(),
-        "Use this in conjunction with `StartDrawingOnTop` or
-`StartDrawingOnTopWin` to ensure that drawing to the screen occurs on
-top of existing windows. Without this, some window systems (such as X)
-only allow drawing to take place underneath other windows.
-
-You might use this pair of functions when implementing a drag feature,
-for example as in the `wx.SplitterWindow` implementation.
-
-These functions are probably obsolete since the X implementations
-allow drawing directly on the screen now. However, the fact that this
-function allows the screen to be refreshed afterwards may be useful
-to some applications.", "");
-    
-};
-
-//---------------------------------------------------------------------------
-%newgroup
-
-MustHaveApp(wxWindowDC);
-
-DocStr(wxWindowDC,
-       "A wx.WindowDC must be constructed if an application wishes to paint on
-the whole area of a window (client and decorations). This should
-normally be constructed as a temporary stack object; don't store a
-wx.WindowDC object.","");
-class wxWindowDC : public wxDC {
-public:
-    DocCtorStr(
-        wxWindowDC(wxWindow* win),
-        "Constructor. Pass the window on which you wish to paint.","");
-};
-
-//---------------------------------------------------------------------------
-%newgroup
-
-MustHaveApp(wxClientDC);
-
-DocStr(wxClientDC,
-"A wx.ClientDC must be constructed if an application wishes to paint on
-the client area of a window from outside an EVT_PAINT event. This should
-normally be constructed as a temporary stack object; don't store a
-wx.ClientDC object long term.

 
 

-To draw on a window from within an EVT_PAINT handler, construct a
-`wx.PaintDC` object.
-
-To draw on the whole window including decorations, construct a
-`wx.WindowDC` object (Windows only).
-", "");
-class wxClientDC : public wxWindowDC {
+class wxAutoBufferedPaintDC: public wxDC
+{

 public:
 public:

-    DocCtorStr(
-        wxClientDC(wxWindow* win),
-        "Constructor. Pass the window on which you wish to paint.", "");
+    wxAutoBufferedPaintDC(wxWindow* win);

 };
 
 };
 

-//---------------------------------------------------------------------------
-%newgroup

 
 

-MustHaveApp(wxPaintDC);
+%newobject wxAutoBufferedPaintDCFactory;
+DocDeclStr(
+    wxDC* , wxAutoBufferedPaintDCFactory(wxWindow* window),
+    "Checks if the window is natively double buffered and will return a
+`wx.PaintDC` if it is, a `wx.BufferedPaintDC` otherwise.  The advantage of
+this function over `wx.AutoBufferedPaintDC` is that this function will check
+if the the specified window has double-buffering enabled rather than just
+going by platform defaults.", "");

 
 

-DocStr(wxPaintDC,
-"A wx.PaintDC must be constructed if an application wishes to paint on
-the client area of a window from within an EVT_PAINT event
-handler. This should normally be constructed as a temporary stack
-object; don't store a wx.PaintDC object. If you have an EVT_PAINT
-handler, you **must** create a wx.PaintDC object within it even if you
-don't actually use it.

 
 

-Using wx.PaintDC within EVT_PAINT handlers is important because it
-automatically sets the clipping area to the damaged area of the
-window. Attempts to draw outside this area do not appear.
-
-To draw on a window from outside EVT_PAINT handlers, construct a
-`wx.ClientDC` object.
-","");
-class wxPaintDC : public wxClientDC {
-public:
-    DocCtorStr(
-        wxPaintDC(wxWindow* win),
-        "Constructor. Pass the window on which you wish to paint.", "");
-};

 
 //---------------------------------------------------------------------------
 %newgroup
 
 //---------------------------------------------------------------------------
 %newgroup