Document wxBK_HITTEST_XXX values.

[wxWidgets.git] / interface / wx / dc.h

diff --git a/interface/wx/dc.h b/interface/wx/dc.h
index d3e8875f607af8e9f79af3a0fb56c5fa2c127b08..4089c9e3899b68580fd14fd1ef7632370fd2107b 100644 (file)
--- a/interface/wx/dc.h
+++ b/interface/wx/dc.h
@@ -113,7 +113,7 @@ struct wxFontMetrics
     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
     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.
+    the wxDC API on top of a wxGraphicsContext.

 
     wxDC is an abstract base class and cannot be created directly.
     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


@@ -153,9 +153,25 @@ struct wxFontMetrics
 
     @section dc_alpha_support Support for Transparency / Alpha Channel
 
 
     @section dc_alpha_support Support for Transparency / Alpha Channel
 

-    On Mac OS X colours with alpha channel are supported. Instances of wxPen
-    or wxBrush that are built from wxColour use the colour's alpha values
-    when stroking or filling.
+    In general wxDC methods don't support alpha transparency and the alpha
+    component of wxColour is simply ignored and you need to use wxGraphicsContext
+    for full transparency support. There are, however, a few exceptions: first,
+    under Mac OS X colours with alpha channel are supported in all the normal
+    wxDC-derived classes as they use wxGraphicsContext internally. Second,
+    under all platforms wxSVGFileDC also fully supports alpha channel. In both
+    of these cases the instances of wxPen or wxBrush that are built from
+    wxColour use the colour's alpha values when stroking or filling.
+
+
+    @section Support for Transformation Matrix
+
+    On some platforms (currently only under MSW and only on Windows NT, i.e.
+    not Windows 9x/ME, systems) wxDC has support for applying an arbitrary
+    affine transformation matrix to its coordinate system. Call
+    CanUseTransformMatrix() to check if this support is available and then call
+    SetTransformMatrix() if it is. If the transformation matrix is not
+    supported, SetTransformMatrix() always simply returns false and doesn't do
+    anything.

 
 
     @library{wxcore}
 
 
     @library{wxcore}


@@ -364,7 +380,7 @@ public:
         character with the given index if it is != -1 and return the bounding
         rectangle if required.
     */
         character with the given index if it is != -1 and return the bounding
         rectangle if required.
     */

-    void DrawLabel(const wxString& text, const wxBitmap& image,
+    void DrawLabel(const wxString& text, const wxBitmap& bitmap,

                    const wxRect& rect,
                    int alignment = wxALIGN_LEFT | wxALIGN_TOP,
                    int indexAccel = -1, wxRect* rectBounding = NULL);
                    const wxRect& rect,
                    int alignment = wxALIGN_LEFT | wxALIGN_TOP,
                    int indexAccel = -1, wxRect* rectBounding = NULL);


@@ -545,7 +561,7 @@ public:
     /**
         @overload
     */
     /**
         @overload
     */

-    void DrawRotatedText(const wxString& text, const wxPoint&,
+    void DrawRotatedText(const wxString& text, const wxPoint& point,

                          double angle);
 
     /**
                          double angle);
 
     /**


@@ -691,6 +707,13 @@ public:
         @note The present implementation for non-Windows platforms may fail to
               find colour borders if the pixels do not match the colour
               exactly. However the function will still return @true.
         @note The present implementation for non-Windows platforms may fail to
               find colour borders if the pixels do not match the colour
               exactly. However the function will still return @true.

+
+        @note This method shouldn't be used with wxPaintDC under non-Windows
+              platforms as it uses GetPixel() internally and this may give
+              wrong results, notably in wxGTK. If you need to flood fill
+              wxPaintDC, create a temporary wxMemoryDC, flood fill it and then
+              blit it to, or draw as a bitmap on, wxPaintDC. See the example of
+              doing this in the drawing sample and wxBufferedPaintDC class.

     */
     bool FloodFill(wxCoord x, wxCoord y, const wxColour& colour,
                    wxFloodFillStyle style = wxFLOOD_SURFACE);
     */
     bool FloodFill(wxCoord x, wxCoord y, const wxColour& colour,
                    wxFloodFillStyle style = wxFLOOD_SURFACE);


@@ -699,7 +722,7 @@ public:
         @overload
     */
     bool FloodFill(const wxPoint& pt, const wxColour& col,
         @overload
     */
     bool FloodFill(const wxPoint& pt, const wxColour& col,

-                   int style = wxFLOOD_SURFACE);
+                   wxFloodFillStyle style = wxFLOOD_SURFACE);

 
     /**
         Displays a cross hair using the current pen. This is a vertical and
 
     /**
         Displays a cross hair using the current pen. This is a vertical and


@@ -1350,6 +1373,9 @@ public:
 
         @note Setting a pixel can be done using DrawPoint().
 
 
         @note Setting a pixel can be done using DrawPoint().
 

+        @note This method shouldn't be used with wxPaintDC as accessing the DC
+        while drawing can result in unexpected results, notably in wxGTK.
+

         @beginWxPythonOnly
         The wxColour value is returned and is not required as a parameter.
         @endWxPythonOnly
         @beginWxPythonOnly
         The wxColour value is returned and is not required as a parameter.
         @endWxPythonOnly


@@ -1494,6 +1520,66 @@ public:
         'zooming'.
     */
     void SetUserScale(double xScale, double yScale);
         'zooming'.
     */
     void SetUserScale(double xScale, double yScale);

+
+
+    /**
+        @name Transformation matrix
+
+        See the notes about the availability of these functions in the class
+        documentation.
+    */
+    //@{
+
+    /**
+        Check if the use of transformation matrix is supported by the current
+        system.
+
+        Currently this function always returns @false for non-MSW platforms and
+        may return @false for old (Windows 9x/ME) Windows systems. Normally
+        support for the transformation matrix is always available in any
+        relatively recent Windows versions.
+
+        @since 2.9.2
+    */
+    bool CanUseTransformMatrix() const;
+
+    /**
+        Set the transformation matrix.
+
+        If transformation matrix is supported on the current system, the
+        specified @a matrix will be used to transform between wxDC and physical
+        coordinates. Otherwise the function returns @false and doesn't change
+        the coordinate mapping.
+
+        @since 2.9.2
+    */
+    bool SetTransformMatrix(const wxAffineMatrix2D& matrix);
+
+    /**
+        Return the transformation matrix used by this device context.
+
+        By default the transformation matrix is the identity matrix.
+
+        @since 2.9.2
+    */
+    wxAffineMatrix2D GetTransformMatrix() const;
+
+    /**
+        Revert the transformation matrix to identity matrix.
+
+        @since 2.9.2
+    */
+    void ResetTransformMatrix();
+
+    //@}
+
+
+    void SetLogicalScale(double x, double y);
+    void GetLogicalScale(double *x, double *y) const;
+    void SetLogicalOrigin(wxCoord x, wxCoord y);
+    void GetLogicalOrigin(wxCoord *x, wxCoord *y) const;
+    wxPoint GetLogicalOrigin() const;
+    

 };
 
 
 };
 
 


@@ -1536,7 +1622,7 @@ public:
 
         The clipping region is automatically unset when this object is destroyed.
     */
 
         The clipping region is automatically unset when this object is destroyed.
     */

-    wxDCClipper(wxDC& dc, const wxRegion& r);
+    wxDCClipper(wxDC& dc, const wxRegion& region);

     wxDCClipper(wxDC& dc, const wxRect& rect);
     wxDCClipper(wxDC& dc, wxCoord x, wxCoord y, wxCoord w, wxCoord h);
     //@}
     wxDCClipper(wxDC& dc, const wxRect& rect);
     wxDCClipper(wxDC& dc, wxCoord x, wxCoord y, wxCoord w, wxCoord h);
     //@}