More interface header reviews by Azriel Fasten, and added skeleton docs for wxBookCtr...

[wxWidgets.git] / interface / dc.h

diff --git a/interface/dc.h b/interface/dc.h
index 4def17d77f4bd88edcc845c7ba3b95177b5c4c4b..9a3b4dac48f6f46032f685259bbef459f09579c7 100644 (file)
--- a/interface/dc.h
+++ b/interface/dc.h
@@ -11,38 +11,37 @@
     @wxheader{dc.h}
 
     A wxDC is a @e "device context" onto which graphics and text can be drawn.
     @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.
+    It is intended to represent different output devices and offers a common
+    abstract API for drawing on any of them.

     
     

-    wxWidgets offers alternative drawing classes based on the modern drawing
+    wxWidgets offers an alternative drawing API based on the modern drawing

     backends GDI+, CoreGraphics and Cairo. See wxGraphicsContext, wxGraphicsRenderer
     backends GDI+, CoreGraphics and Cairo. See wxGraphicsContext, wxGraphicsRenderer

-    and related classes.
+    and related classes. There is also a wxGCDC linking the APIs by offering
+    the wxDC API ontop of a wxGraphicsContext.

 
 

-    Notice that wxDC is an abstract base class and can't be created directly,
-    please use wxPaintDC, wxClientDC, wxWindowDC, wxScreenDC, wxMemoryDC or
+    wxDC is an abstract base class and cannot be created directly.
+    Use wxPaintDC, wxClientDC, wxWindowDC, wxScreenDC, wxMemoryDC or

     wxPrinterDC.
 
     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.
+    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.

 
 

-    @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.
+    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.

 
 

-    @section dc_alpha Support for Transparency / Alpha Channel
-
-    On Mac OS X 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}
 
 
     @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
 
     @todo Precise definition of default/initial state.
     @todo Pixelwise definition of operations (e.g. last point of a line not


@@ -469,7 +468,7 @@ public:
         - wxFLOOD_BORDER: The area to be flooded is bounded by the given
           colour.
 
         - 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
 
         @note The present implementation for non-Windows platforms may fail to
               find colour borders if the pixels do not match the colour


@@ -582,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.
 
         @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.
 
 
         @note This function works with both single-line and multi-line strings.