deprecate wxDC::SetClippingRegion(wxRegion) overload and replace it with SetDeviceCli...

[wxWidgets.git] / interface / dc.h

diff --git a/interface/dc.h b/interface/dc.h
index 9b43844acd657a8eb8b3e7e626991a5c5632ebcc..1467bff0c1930ca4d07fd1e43d42c5f45cfa5c8c 100644 (file)
--- a/interface/dc.h
+++ b/interface/dc.h
@@ -11,35 +11,37 @@
     @wxheader{dc.h}
 
     A wxDC is a @e "device context" onto which graphics and text can be drawn.
-    It is intended to represent a number of output devices in a generic way, so
-    a window can have a device context associated with it, and a printer also
-    has a device context. In this way, the same piece of code may write to a
-    number of different devices, if the device context is used as a parameter.
-
-    Notice that wxDC is an abstract base class and can't be created directly,
-    please use wxPaintDC, wxClientDC, wxWindowDC, wxScreenDC, wxMemoryDC or
+    It is intended to represent different output devices and offers a common
+    abstract API for drawing on any of them.
+    
+    wxWidgets offers an alternative drawing API based on the modern drawing
+    backends GDI+, CoreGraphics and Cairo. See wxGraphicsContext, wxGraphicsRenderer
+    and related classes. There is also a wxGCDC linking the APIs by offering
+    the wxDC API ontop of a wxGraphicsContext.
+
+    wxDC is an abstract base class and cannot be created directly.
+    Use wxPaintDC, wxClientDC, wxWindowDC, wxScreenDC, wxMemoryDC or
     wxPrinterDC.
 
-    Please note that in addition to the versions of the methods documented
-    here, there are also versions which accept single wxPoint parameter instead
-    of two wxCoord ones or wxPoint and wxSize instead of four of them.
-
-    @note Beginning with wxWidgets 2.9.0 the entire wxDC code has been
-          reorganized. All platform dependent code (actual all drawing code)
-          has been moved into backend classes which derive from a common
-          wxDCImpl class. The user-visible classes such as wxClientDC and
-          wxPaintDC merely forward all calls to the backend implementation.
+    In addition to the versions of the methods documented below, there
+    are also versions which accept single wxPoint parameter instead
+    of the two wxCoord ones or wxPoint and wxSize instead of the four
+    wxCoord parameters.
 
-    @section dc_alpha Support for Transparency / Alpha Channel
+    Beginning with wxWidgets 2.9.0 the entire wxDC code has been
+    reorganized. All platform dependent code (actually all drawing code)
+    has been moved into backend classes which derive from a common
+    wxDCImpl class. The user-visible classes such as wxClientDC and
+    wxPaintDC merely forward all calls to the backend implementation.
 
-    On Mac OS X, when using Core Graphics (wxMAC_USE_CORE_GRAPHICS set to 1),
-    colors with alpha are supported. Instances wxPen or wxBrush that are built
-    from wxColour use the color's alpha values when stroking or filling.
+    On Mac OS X colours with alpha channel are supported. Instances wxPen
+    or wxBrush that are built from wxColour use the colour's alpha values
+    when stroking or filling.
 
     @library{wxcore}
     @category{dc,gdi}
 
-    @see @ref overview_dc
+    @see @ref overview_dc, wxGraphicsContext
 
     @todo Precise definition of default/initial state.
     @todo Pixelwise definition of operations (e.g. last point of a line not
@@ -466,7 +468,7 @@ public:
         - wxFLOOD_BORDER: The area to be flooded is bounded by the given
           colour.
 
-        @returns @false if the operation failed.
+        @return @false if the operation failed.
 
         @note The present implementation for non-Windows platforms may fail to
               find colour borders if the pixels do not match the colour
@@ -579,7 +581,7 @@ public:
         @a string is the text string to measure, @e heightLine, if non @NULL,
         is where to store the height of a single line.
 
-        @returns The text extent as a wxSize object.
+        @return The text extent as a wxSize object.
 
         @note This function works with both single-line and multi-line strings.
 
@@ -867,9 +869,16 @@ public:
                            wxCoord height);
     void SetClippingRegion(const wxPoint& pt, const wxSize& sz);
     void SetClippingRegion(const wxRect& rect);
-    void SetClippingRegion(const wxRegion& region);
     //@}
 
+    /**
+        Sets the clipping region for this device context.
+
+        Unlike SetClippingRegion(), this function works with physical
+        coordinates and not with the logical ones.
+     */
+    void SetDeviceClippingRegion(const wxRegion& region);
+
     /**
         Sets the device origin (i.e., the origin in pixels after scaling has
         been applied). This function may be useful in Windows printing
@@ -1071,7 +1080,7 @@ public:
 
         See wxMemoryDC for typical usage.
 
-        @wxsince{2.9.0}
+        @since 2.9.0
 
         @see Blit(), wxMemoryDC, wxBitmap, wxMask
     */