Implement auto-completion support for wxTextEntry in wxOSX/Cocoa.

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

diff --git a/interface/wx/dc.h b/interface/wx/dc.h
index e637dfb4490e2f35f21f0c323cd2900b9f90efe0..32b986bd1e97bc77b092c79a7196af42a92e9674 100644 (file)
--- a/interface/wx/dc.h
+++ b/interface/wx/dc.h
@@ -3,7 +3,7 @@
 // Purpose:     interface of wxDC
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
-// Licence:     wxWindows license
+// Licence:     wxWindows licence
 /////////////////////////////////////////////////////////////////////////////
 
 
@@ -79,6 +79,28 @@ enum wxMappingMode
     wxMM_POINTS
 };
 
+/**
+    Simple collection of various font metrics.
+
+    This object is returned by wxDC::GetFontMetrics().
+
+    @since 2.9.2
+
+    @library{wxcore}
+    @category{dc,gdi}
+ */
+struct wxFontMetrics
+{
+    /// Constructor initializes all fields to 0.
+    wxFontMetrics();
+
+    int height,             ///< Total character height.
+        ascent,             ///< Part of the height above the baseline.
+        descent,            ///< Part of the height below the baseline.
+        internalLeading,    ///< Intra-line spacing.
+        externalLeading,    ///< Inter-line spacing.
+        averageWidth;       ///< Average font width, a.k.a. "x-width".
+};
 
 
 /**
@@ -91,7 +113,7 @@ enum wxMappingMode
     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
@@ -121,7 +143,7 @@ enum wxMappingMode
     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
+    All wxDC functions use instead @b logical units, unless where explicitly
     stated. Logical units are arbitrary units mapped to device units using
     the current mapping mode (see wxDC::SetMapMode).
 
@@ -131,9 +153,14 @@ enum wxMappingMode
 
     @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.
 
 
     @library{wxcore}
@@ -596,7 +623,12 @@ public:
 
         The coordinates refer to the top-left corner of the rectangle bounding
         the string. See GetTextExtent() for how to get the dimensions of a text
-        string, which can be used to position the text more precisely.
+        string, which can be used to position the text more precisely and
+        DrawLabel() if you need to align the string differently.
+
+        Starting from wxWidgets 2.9.2 @a text parameter can be a multi-line
+        string, i.e. contain new line characters, and will be rendered
+        correctly.
 
         @note The current @ref GetLogicalFunction() "logical function" is
               ignored by this function.
@@ -768,6 +800,21 @@ public:
     */
     wxCoord GetCharWidth() const;
 
+    /**
+        Returns the various font characteristics.
+
+        This method allows to retrieve some of the font characteristics not
+        returned by GetTextExtent(), notably internal leading and average
+        character width.
+
+        Currently this method returns correct results only under wxMSW, in the
+        other ports the internal leading will always be 0 and the average
+        character width will be computed as the width of the character 'x'.
+
+        @since 2.9.2
+     */
+    wxFontMetrics GetFontMetrics() const;
+
     /**
         Gets the dimensions of the string using the currently selected font.
         @a string is the text string to measure, @e heightLine, if non @NULL,
@@ -1097,7 +1144,7 @@ public:
             This sequence of operations ensures that the source's transparent
             area need not be black, and logical functions are supported.
             @n @b Note: on Windows, blitting with masks can be speeded up
-            considerably by compiling wxWidgets with the wxUSE_DC_CACHE option
+            considerably by compiling wxWidgets with the wxUSE_DC_CACHEING option
             enabled. You can also influence whether MaskBlt or the explicit
             mask blitting code above is used, by using wxSystemOptions and
             setting the @c no-maskblt option to 1.
@@ -1168,7 +1215,7 @@ public:
             This sequence of operations ensures that the source's transparent
             area need not be black, and logical functions are supported.
             @n @b Note: on Windows, blitting with masks can be speeded up
-            considerably by compiling wxWidgets with the wxUSE_DC_CACHE option
+            considerably by compiling wxWidgets with the wxUSE_DC_CACHEING option
             enabled. You can also influence whether MaskBlt or the explicit
             mask blitting code above is used, by using wxSystemOptions and
             setting the @c no-maskblt option to 1.