try to clear the device/logical unit fog; remove unused and unsupported (an assertion fails if they are used) wxMM_ constants; better docs for the supported wxMM_ constants; use MM_ANISOTROPIC in old win16 metafile code instead of wxMM_ANISOTROPIC since it's not supported by wx code

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@59127 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

include/wx/dc.h

@@ -104,19 +104,14 @@ enum wxFloodFillStyle
     wxFLOOD_BORDER
 };
 
-//  Mapping modes (same values as used by Windows, don't change)
+//  Mapping modes
 enum wxMappingMode
 {
     wxMM_TEXT = 1,
+    wxMM_METRIC,
     wxMM_LOMETRIC,
-    wxMM_HIMETRIC,
-    wxMM_LOENGLISH,
-    wxMM_HIENGLISH,
     wxMM_TWIPS,
-    wxMM_ISOTROPIC,
+    wxMM_POINTS
-    wxMM_ANISOTROPIC,
-    wxMM_POINTS,
-    wxMM_METRIC
 };
 
 #if WXWIN_COMPATIBILITY_2_8
@@ -373,7 +368,7 @@ public:
     // logical functions
 
     virtual void SetLogicalFunction(wxRasterOperationMode function) = 0;
-    virtual wxRasterOperationMode GetLogicalFunction() const 
+    virtual wxRasterOperationMode GetLogicalFunction() const
                                       { return m_logicalFunction; }
 
     // text measurement
@@ -1134,7 +1129,7 @@ public:
 
     bool Blit(wxCoord xdest, wxCoord ydest, wxCoord width, wxCoord height,
               wxDC *source, wxCoord xsrc, wxCoord ysrc,
-              wxRasterOperationMode rop = wxCOPY, bool useMask = false, 
+              wxRasterOperationMode rop = wxCOPY, bool useMask = false,
               wxCoord xsrcMask = wxDefaultCoord, wxCoord ysrcMask = wxDefaultCoord)
     {
         return m_pimpl->DoBlit(xdest, ydest, width, height,
@@ -1142,7 +1137,7 @@ public:
     }
     bool Blit(const wxPoint& destPt, const wxSize& sz,
               wxDC *source, const wxPoint& srcPt,
-              wxRasterOperationMode rop = wxCOPY, bool useMask = false, 
+              wxRasterOperationMode rop = wxCOPY, bool useMask = false,
               const wxPoint& srcPtMask = wxDefaultPosition)
     {
         return m_pimpl->DoBlit(destPt.x, destPt.y, sz.x, sz.y,
@@ -1162,7 +1157,7 @@ public:
     }
     bool StretchBlit(const wxPoint& dstPt, const wxSize& dstSize,
                      wxDC *source, const wxPoint& srcPt, const wxSize& srcSize,
-                     wxRasterOperationMode rop = wxCOPY, bool useMask = false, 
+                     wxRasterOperationMode rop = wxCOPY, bool useMask = false,
                      const wxPoint& srcMaskPt = wxDefaultPosition)
     {
         return m_pimpl->DoStretchBlit(dstPt.x, dstPt.y, dstSize.x, dstSize.y,

interface/wx/dc.h

@@ -49,34 +49,38 @@ enum wxFloodFillStyle
 };
 
 /**
-    The mapping mode which can be used with wxDC::SetMapMode.
+    The mapping used to transform @e logical units to @e device units.
+    See wxDC::SetMapMode.
 */
 enum wxMappingMode
 {
-    /** Each logical unit is 1 device pixel. */
+    /**
+        Each logical unit is 1 device pixel.
+        This is the default mapping mode for all wxDC-derived classes.
+    */
     wxMM_TEXT = 1,
 
+    /** Each logical unit is 1 millimeter. */
+    wxMM_METRIC,
+
+    /** Each logical unit is 1/10 of a millimeter. */
     wxMM_LOMETRIC,
-    wxMM_HIMETRIC,
 
-    /** Each logical unit is 1/10 of a mm. */
+    /**
-    wxMM_LOENGLISH,
+        Each logical unit is 1/20 of a @e "printer point", or 1/1440 of an inch
-
+        (also known as "twip"). Equivalent to about 17.64 micrometers.
-    wxMM_HIENGLISH,
+    */
-
-    /** Each logical unit is 1/20 of a point, or 1/1440 of an inch. */
     wxMM_TWIPS,
 
-    wxMM_ISOTROPIC,
+    /**
-    wxMM_ANISOTROPIC,
+        Each logical unit is a @e "printer point" i.e. 1/72 of an inch.
-
+        Equivalent to about 353 micrometers.
-    /** Each logical unit is a point, or 1/72 of an inch. */
+    */
-    wxMM_POINTS,
+    wxMM_POINTS
-
-    /** Each logical unit is 1 mm. */
-    wxMM_METRIC
 };
 
+
+
 /**
     @class wxDC
 
@@ -112,6 +116,23 @@ enum wxMappingMode
     or wxBrush that are built from wxColour use the colour's alpha values
     when stroking or filling.
 
+
+    @section dc_units Device and logical units
+
+    In the wxDC context there is a distinction between @e logical units and @e device units.
+
+    @b Device units are the units native to the particular device; e.g. for a screen,
+    a device unit is a @e pixel. For a printer, the device unit is defined by the
+    resolution of the printer (usually given in @c DPI: dot-per-inch).
+
+    All wxDC functions use instead @b logical units, unless where explicitely
+    stated. Logical units are arbitrary units mapped to device units using
+    the current mapping mode (see wxDC::SetMapMode).
+
+    This mechanism allows to reuse the same code which prints on e.g. a window
+    on the screen to print on e.g. a paper.
+
+
     @library{wxcore}
     @category{dc,gdi}
 
@@ -121,9 +142,6 @@ enum wxMappingMode
     @todo Precise definition of default/initial state.
     @todo Pixelwise definition of operations (e.g. last point of a line not
           drawn).
-    @todo Coordinates: state clearly which type of coordinates are returned by
-          the various Get*Point() or similar functions - often they are client
-          coordinates but not always.
 */
 class wxDC : public wxObject
 {
@@ -223,26 +241,26 @@ public:
     void DestroyClippingRegion();
 
     /**
-        Convert device X coordinate to logical coordinate, using the current
+        Convert @e device X coordinate to logical coordinate, using the current
         mapping mode, user scale factor, device origin and axis orientation.
     */
     wxCoord DeviceToLogicalX(wxCoord x) const;
 
     /**
-        Convert device X coordinate to relative logical coordinate, using the
+        Convert @e device X coordinate to relative logical coordinate, using the
         current mapping mode and user scale factor but ignoring the
         axis orientation. Use this for converting a width, for example.
     */
     wxCoord DeviceToLogicalXRel(wxCoord x) const;
 
     /**
-        Converts device Y coordinate to logical coordinate, using the current
+        Converts @e device Y coordinate to logical coordinate, using the current
         mapping mode, user scale factor, device origin and axis orientation.
     */
     wxCoord DeviceToLogicalY(wxCoord y) const;
 
     /**
-        Convert device Y coordinate to relative logical coordinate, using the
+        Convert @e device Y coordinate to relative logical coordinate, using the
         current mapping mode and user scale factor but ignoring the
         axis orientation. Use this for converting a height, for example.
     */
@@ -618,7 +636,7 @@ public:
     wxRasterOperationMode GetLogicalFunction() const;
 
     /**
-        Gets the mapping mode for the device context.
+        Gets the current mapping mode for the device context.
 
         @see SetMapMode()
     */
@@ -700,8 +718,8 @@ public:
 
     //@{
     /**
-        This gets the horizontal and vertical resolution in device units. It
+        Gets the horizontal and vertical extent of this device context in @e device units.
-        can be used to scale graphics to fit the page.
+        It can be used to scale graphics to fit the page.
 
         For example, if @e maxX and @e maxY represent the maximum horizontal
         and vertical 'pixel' values used in your application, the following
@@ -987,7 +1005,7 @@ public:
 
     /**
         The mapping mode of the device context defines the unit of measurement
-        used to convert logical units to device units.
+        used to convert @e logical units to @e device units.
 
         Note that in X, text drawing isn't handled consistently with the mapping mode;
         a font is always specified in point size. However, setting the user scale (see

src/msw/metafile.cpp

@@ -64,7 +64,7 @@ IMPLEMENT_ABSTRACT_CLASS(wxMetafileDC, wxDC)
 wxMetafileRefData::wxMetafileRefData()
 {
     m_metafile = 0;
-    m_windowsMappingMode = wxMM_ANISOTROPIC;
+    m_windowsMappingMode = MM_ANISOTROPIC;
     m_width = m_height = 0;
 }
 
@@ -85,7 +85,7 @@ wxMetafile::wxMetafile(const wxString& file)
 {
     m_refData = new wxMetafileRefData;
 
-    M_METAFILEDATA->m_windowsMappingMode = wxMM_ANISOTROPIC;
+    M_METAFILEDATA->m_windowsMappingMode = MM_ANISOTROPIC;
     M_METAFILEDATA->m_metafile = 0;
     if (!file.empty())
         M_METAFILEDATA->m_metafile = (WXHANDLE) GetMetaFile(file);
@@ -213,7 +213,7 @@ wxMetafileDCImpl::wxMetafileDCImpl(wxDC *owner, const wxString& file,
     ::SetWindowExtEx((HDC) m_hDC,xext,yext, NULL);
 
     // Actual Windows mapping mode, for future reference.
-    m_windowsMappingMode = wxMM_ANISOTROPIC;
+    m_windowsMappingMode = MM_ANISOTROPIC;
 
     SetMapMode(wxMM_TEXT); // NOTE: does not set HDC mapmode (this is correct)
 }

src/os2/metafile.cpp

@@ -40,7 +40,7 @@ IMPLEMENT_ABSTRACT_CLASS(wxMetafileDC, wxDC)
 wxMetafileRefData::wxMetafileRefData(void)
 {
     m_metafile = 0;
-    m_windowsMappingMode = wxMM_ANISOTROPIC;
+    m_windowsMappingMode = MM_ANISOTROPIC;
 }
 
 wxMetafileRefData::~wxMetafileRefData(void)
@@ -56,7 +56,7 @@ wxMetafile::wxMetafile(const wxString& file)
 {
     m_refData = new wxMetafileRefData;
 
-    M_METAFILEDATA->m_windowsMappingMode = wxMM_ANISOTROPIC;
+    M_METAFILEDATA->m_windowsMappingMode = MM_ANISOTROPIC;
     M_METAFILEDATA->m_metafile = 0;
     if (!file.empty())
         M_METAFILEDATA->m_metafile = (WXHANDLE)0; // TODO: GetMetaFile(file);
@@ -185,7 +185,7 @@ wxMetafileDCImpl::wxMetafileDCImpl( wxDC *owner, const wxString& file,
 //  ::SetWindowExtEx((HDC) m_hDC,xext,yext, NULL);
 
     // Actual Windows mapping mode, for future reference.
-    m_windowsMappingMode = wxMM_ANISOTROPIC;
+    m_windowsMappingMode = MM_ANISOTROPIC;
 
     SetMapMode(wxMM_TEXT); // NOTE: does not set HDC mapmode (this is correct)
 }